[www-releases] r257950 - Add 3.7.1 docs
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Fri Jan 15 15:13:20 PST 2016
Added: www-releases/trunk/3.7.1/docs/SystemLibrary.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/SystemLibrary.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/SystemLibrary.html (added)
+++ www-releases/trunk/3.7.1/docs/SystemLibrary.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,311 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>System Library — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="index.html" />
+ <link rel="next" title="Source Level Debugging with LLVM" href="SourceLevelDebugging.html" />
+ <link rel="prev" title="LLVMâs Optional Rich Disassembly Output" href="MarkedUpDisassembly.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="system-library">
+<h1>System Library<a class="headerlink" href="#system-library" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="abstract">
+<h2>Abstract<a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>This document provides some details on LLVM’s System Library, located in the
+source at <tt class="docutils literal"><span class="pre">lib/System</span></tt> and <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt>. The library’s purpose is
+to shield LLVM from the differences between operating systems for the few
+services LLVM needs from the operating system. Much of LLVM is written using
+portability features of standard C++. However, in a few areas, system dependent
+facilities are needed and the System Library is the wrapper around those system
+calls.</p>
+<p>By centralizing LLVM’s use of operating system interfaces, we make it possible
+for the LLVM tool chain and runtime libraries to be more easily ported to new
+platforms since (theoretically) only <tt class="docutils literal"><span class="pre">lib/System</span></tt> needs to be ported. This
+library also unclutters the rest of LLVM from #ifdef use and special cases for
+specific operating systems. Such uses are replaced with simple calls to the
+interfaces provided in <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt>.</p>
+<p>Note that the System Library is not intended to be a complete operating system
+wrapper (such as the Adaptive Communications Environment (ACE) or Apache
+Portable Runtime (APR)), but only provides the functionality necessary to
+support LLVM.</p>
+<p>The System Library was written by Reid Spencer who formulated the design based
+on similar work originating from the eXtensible Programming System (XPS).
+Several people helped with the effort; especially, Jeff Cohen and Henrik Bach
+on the Win32 port.</p>
+</div>
+<div class="section" id="keeping-llvm-portable">
+<h2>Keeping LLVM Portable<a class="headerlink" href="#keeping-llvm-portable" title="Permalink to this headline">¶</a></h2>
+<p>In order to keep LLVM portable, LLVM developers should adhere to a set of
+portability rules associated with the System Library. Adherence to these rules
+should help the System Library achieve its goal of shielding LLVM from the
+variations in operating system interfaces and doing so efficiently. The
+following sections define the rules needed to fulfill this objective.</p>
+<div class="section" id="don-t-include-system-headers">
+<h3>Don’t Include System Headers<a class="headerlink" href="#don-t-include-system-headers" title="Permalink to this headline">¶</a></h3>
+<p>Except in <tt class="docutils literal"><span class="pre">lib/System</span></tt>, no LLVM source code should directly <tt class="docutils literal"><span class="pre">#include</span></tt> a
+system header. Care has been taken to remove all such <tt class="docutils literal"><span class="pre">#includes</span></tt> from LLVM
+while <tt class="docutils literal"><span class="pre">lib/System</span></tt> was being developed. Specifically this means that header
+files like “<tt class="docutils literal"><span class="pre">unistd.h</span></tt>”, “<tt class="docutils literal"><span class="pre">windows.h</span></tt>”, “<tt class="docutils literal"><span class="pre">stdio.h</span></tt>”, and “<tt class="docutils literal"><span class="pre">string.h</span></tt>”
+are forbidden to be included by LLVM source code outside the implementation of
+<tt class="docutils literal"><span class="pre">lib/System</span></tt>.</p>
+<p>To obtain system-dependent functionality, existing interfaces to the system
+found in <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt> should be used. If an appropriate interface is
+not available, it should be added to <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt> and implemented in
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> for all supported platforms.</p>
+</div>
+<div class="section" id="don-t-expose-system-headers">
+<h3>Don’t Expose System Headers<a class="headerlink" href="#don-t-expose-system-headers" title="Permalink to this headline">¶</a></h3>
+<p>The System Library must shield LLVM from <strong>all</strong> system headers. To obtain
+system level functionality, LLVM source must <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/System/Thing.h"</span></tt>
+and nothing else. This means that <tt class="docutils literal"><span class="pre">Thing.h</span></tt> cannot expose any system header
+files. This protects LLVM from accidentally using system specific functionality
+and only allows it via the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface.</p>
+</div>
+<div class="section" id="use-standard-c-headers">
+<h3>Use Standard C Headers<a class="headerlink" href="#use-standard-c-headers" title="Permalink to this headline">¶</a></h3>
+<p>The <strong>standard</strong> C headers (the ones beginning with “c”) are allowed to be
+exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface. These headers and the things they
+declare are considered to be platform agnostic. LLVM source files may include
+them directly or obtain their inclusion through <tt class="docutils literal"><span class="pre">lib/System</span></tt> interfaces.</p>
+</div>
+<div class="section" id="id1">
+<h3>Use Standard C++ Headers<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>The <strong>standard</strong> C++ headers from the standard C++ library and standard
+template library may be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface. These
+headers and the things they declare are considered to be platform agnostic.
+LLVM source files may include them or obtain their inclusion through
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> interfaces.</p>
+</div>
+<div class="section" id="high-level-interface">
+<h3>High Level Interface<a class="headerlink" href="#high-level-interface" title="Permalink to this headline">¶</a></h3>
+<p>The entry points specified in the interface of <tt class="docutils literal"><span class="pre">lib/System</span></tt> must be aimed at
+completing some reasonably high level task needed by LLVM. We do not want to
+simply wrap each operating system call. It would be preferable to wrap several
+operating system calls that are always used in conjunction with one another by
+LLVM.</p>
+<p>For example, consider what is needed to execute a program, wait for it to
+complete, and return its result code. On Unix, this involves the following
+operating system calls: <tt class="docutils literal"><span class="pre">getenv</span></tt>, <tt class="docutils literal"><span class="pre">fork</span></tt>, <tt class="docutils literal"><span class="pre">execve</span></tt>, and <tt class="docutils literal"><span class="pre">wait</span></tt>. The
+correct thing for <tt class="docutils literal"><span class="pre">lib/System</span></tt> to provide is a function, say
+<tt class="docutils literal"><span class="pre">ExecuteProgramAndWait</span></tt>, that implements the functionality completely. what
+we don’t want is wrappers for the operating system calls involved.</p>
+<p>There must <strong>not</strong> be a one-to-one relationship between operating system
+calls and the System library’s interface. Any such interface function will be
+suspicious.</p>
+</div>
+<div class="section" id="no-unused-functionality">
+<h3>No Unused Functionality<a class="headerlink" href="#no-unused-functionality" title="Permalink to this headline">¶</a></h3>
+<p>There must be no functionality specified in the interface of <tt class="docutils literal"><span class="pre">lib/System</span></tt>
+that isn’t actually used by LLVM. We’re not writing a general purpose operating
+system wrapper here, just enough to satisfy LLVM’s needs. And, LLVM doesn’t
+need much. This design goal aims to keep the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface small and
+understandable which should foster its actual use and adoption.</p>
+</div>
+<div class="section" id="no-duplicate-implementations">
+<h3>No Duplicate Implementations<a class="headerlink" href="#no-duplicate-implementations" title="Permalink to this headline">¶</a></h3>
+<p>The implementation of a function for a given platform must be written exactly
+once. This implies that it must be possible to apply a function’s
+implementation to multiple operating systems if those operating systems can
+share the same implementation. This rule applies to the set of operating
+systems supported for a given class of operating system (e.g. Unix, Win32).</p>
+</div>
+<div class="section" id="no-virtual-methods">
+<h3>No Virtual Methods<a class="headerlink" href="#no-virtual-methods" title="Permalink to this headline">¶</a></h3>
+<p>The System Library interfaces can be called quite frequently by LLVM. In order
+to make those calls as efficient as possible, we discourage the use of virtual
+methods. There is no need to use inheritance for implementation differences, it
+just adds complexity. The <tt class="docutils literal"><span class="pre">#include</span></tt> mechanism works just fine.</p>
+</div>
+<div class="section" id="no-exposed-functions">
+<h3>No Exposed Functions<a class="headerlink" href="#no-exposed-functions" title="Permalink to this headline">¶</a></h3>
+<p>Any functions defined by system libraries (i.e. not defined by <tt class="docutils literal"><span class="pre">lib/System</span></tt>)
+must not be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface, even if the header
+file for that function is not exposed. This prevents inadvertent use of system
+specific functionality.</p>
+<p>For example, the <tt class="docutils literal"><span class="pre">stat</span></tt> system call is notorious for having variations in the
+data it provides. <tt class="docutils literal"><span class="pre">lib/System</span></tt> must not declare <tt class="docutils literal"><span class="pre">stat</span></tt> nor allow it to be
+declared. Instead it should provide its own interface to discovering
+information about files and directories. Those interfaces may be implemented in
+terms of <tt class="docutils literal"><span class="pre">stat</span></tt> but that is strictly an implementation detail. The interface
+provided by the System Library must be implemented on all platforms (even those
+without <tt class="docutils literal"><span class="pre">stat</span></tt>).</p>
+</div>
+<div class="section" id="no-exposed-data">
+<h3>No Exposed Data<a class="headerlink" href="#no-exposed-data" title="Permalink to this headline">¶</a></h3>
+<p>Any data defined by system libraries (i.e. not defined by <tt class="docutils literal"><span class="pre">lib/System</span></tt>) must
+not be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface, even if the header file
+for that function is not exposed. As with functions, this prevents inadvertent
+use of data that might not exist on all platforms.</p>
+</div>
+<div class="section" id="minimize-soft-errors">
+<h3>Minimize Soft Errors<a class="headerlink" href="#minimize-soft-errors" title="Permalink to this headline">¶</a></h3>
+<p>Operating system interfaces will generally provide error results for every
+little thing that could go wrong. In almost all cases, you can divide these
+error results into two groups: normal/good/soft and abnormal/bad/hard. That is,
+some of the errors are simply information like “file not found”, “insufficient
+privileges”, etc. while other errors are much harder like “out of space”, “bad
+disk sector”, or “system call interrupted”. We’ll call the first group “<em>soft</em>”
+errors and the second group “<em>hard</em>” errors.</p>
+<p><tt class="docutils literal"><span class="pre">lib/System</span></tt> must always attempt to minimize soft errors. This is a design
+requirement because the minimization of soft errors can affect the granularity
+and the nature of the interface. In general, if you find that you’re wanting to
+throw soft errors, you must review the granularity of the interface because it
+is likely you’re trying to implement something that is too low level. The rule
+of thumb is to provide interface functions that <strong>can’t</strong> fail, except when
+faced with hard errors.</p>
+<p>For a trivial example, suppose we wanted to add an “<tt class="docutils literal"><span class="pre">OpenFileForWriting</span></tt>”
+function. For many operating systems, if the file doesn’t exist, attempting to
+open the file will produce an error. However, <tt class="docutils literal"><span class="pre">lib/System</span></tt> should not simply
+throw that error if it occurs because its a soft error. The problem is that the
+interface function, <tt class="docutils literal"><span class="pre">OpenFileForWriting</span></tt> is too low level. It should be
+<tt class="docutils literal"><span class="pre">OpenOrCreateFileForWriting</span></tt>. In the case of the soft “doesn’t exist” error,
+this function would just create it and then open it for writing.</p>
+<p>This design principle needs to be maintained in <tt class="docutils literal"><span class="pre">lib/System</span></tt> because it
+avoids the propagation of soft error handling throughout the rest of LLVM.
+Hard errors will generally just cause a termination for an LLVM tool so don’t
+be bashful about throwing them.</p>
+<p>Rules of thumb:</p>
+<ol class="arabic simple">
+<li>Don’t throw soft errors, only hard errors.</li>
+<li>If you’re tempted to throw a soft error, re-think the interface.</li>
+<li>Handle internally the most common normal/good/soft error conditions
+so the rest of LLVM doesn’t have to.</li>
+</ol>
+</div>
+<div class="section" id="no-throw-specifications">
+<h3>No throw Specifications<a class="headerlink" href="#no-throw-specifications" title="Permalink to this headline">¶</a></h3>
+<p>None of the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface functions may be declared with C++
+<tt class="docutils literal"><span class="pre">throw()</span></tt> specifications on them. This requirement makes sure that the
+compiler does not insert additional exception handling code into the interface
+functions. This is a performance consideration: <tt class="docutils literal"><span class="pre">lib/System</span></tt> functions are at
+the bottom of many call chains and as such can be frequently called. We need
+them to be as efficient as possible. However, no routines in the system
+library should actually throw exceptions.</p>
+</div>
+<div class="section" id="code-organization">
+<h3>Code Organization<a class="headerlink" href="#code-organization" title="Permalink to this headline">¶</a></h3>
+<p>Implementations of the System Library interface are separated by their general
+class of operating system. Currently only Unix and Win32 classes are defined
+but more could be added for other operating system classifications. To
+distinguish which implementation to compile, the code in <tt class="docutils literal"><span class="pre">lib/System</span></tt> uses
+the <tt class="docutils literal"><span class="pre">LLVM_ON_UNIX</span></tt> and <tt class="docutils literal"><span class="pre">LLVM_ON_WIN32</span></tt> <tt class="docutils literal"><span class="pre">#defines</span></tt> provided via configure
+through the <tt class="docutils literal"><span class="pre">llvm/Config/config.h</span></tt> file. Each source file in <tt class="docutils literal"><span class="pre">lib/System</span></tt>,
+after implementing the generic (operating system independent) functionality
+needs to include the correct implementation using a set of
+<tt class="docutils literal"><span class="pre">#if</span> <span class="pre">defined(LLVM_ON_XYZ)</span></tt> directives. For example, if we had
+<tt class="docutils literal"><span class="pre">lib/System/File.cpp</span></tt>, we’d expect to see in that file:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if defined(LLVM_ON_UNIX)</span>
+<span class="cp">#include "Unix/File.cpp"</span>
+<span class="cp">#endif</span>
+<span class="cp">#if defined(LLVM_ON_WIN32)</span>
+<span class="cp">#include "Win32/File.cpp"</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>The implementation in <tt class="docutils literal"><span class="pre">lib/System/Unix/File.cpp</span></tt> should handle all Unix
+variants. The implementation in <tt class="docutils literal"><span class="pre">lib/System/Win32/File.cpp</span></tt> should handle all
+Win32 variants. What this does is quickly differentiate the basic class of
+operating system that will provide the implementation. The specific details for
+a given platform must still be determined through the use of <tt class="docutils literal"><span class="pre">#ifdef</span></tt>.</p>
+</div>
+<div class="section" id="consistent-semantics">
+<h3>Consistent Semantics<a class="headerlink" href="#consistent-semantics" title="Permalink to this headline">¶</a></h3>
+<p>The implementation of a <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface can vary drastically between
+platforms. That’s okay as long as the end result of the interface function is
+the same. For example, a function to create a directory is pretty straight
+forward on all operating system. System V IPC on the other hand isn’t even
+supported on all platforms. Instead of “supporting” System V IPC,
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> should provide an interface to the basic concept of
+inter-process communications. The implementations might use System V IPC if
+that was available or named pipes, or whatever gets the job done effectively
+for a given operating system. In all cases, the interface and the
+implementation must be semantically consistent.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/TableGen/BackEnds.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/TableGen/BackEnds.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/TableGen/BackEnds.html (added)
+++ www-releases/trunk/3.7.1/docs/TableGen/BackEnds.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,496 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen BackEnds — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="../index.html" />
+ <link rel="up" title="TableGen" href="index.html" />
+ <link rel="next" title="TableGen Language Reference" href="LangRef.html" />
+ <link rel="prev" title="TableGen" 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">
+ <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="LangRef.html" title="TableGen Language Reference"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="TableGen"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">TableGen</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-backends">
+<h1>TableGen BackEnds<a class="headerlink" href="#tablegen-backends" 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="#llvm-backends" id="id2">LLVM BackEnds</a><ul>
+<li><a class="reference internal" href="#codeemitter" id="id3">CodeEmitter</a></li>
+<li><a class="reference internal" href="#registerinfo" id="id4">RegisterInfo</a></li>
+<li><a class="reference internal" href="#instrinfo" id="id5">InstrInfo</a></li>
+<li><a class="reference internal" href="#asmwriter" id="id6">AsmWriter</a></li>
+<li><a class="reference internal" href="#asmmatcher" id="id7">AsmMatcher</a></li>
+<li><a class="reference internal" href="#disassembler" id="id8">Disassembler</a></li>
+<li><a class="reference internal" href="#pseudolowering" id="id9">PseudoLowering</a></li>
+<li><a class="reference internal" href="#callingconv" id="id10">CallingConv</a></li>
+<li><a class="reference internal" href="#dagisel" id="id11">DAGISel</a></li>
+<li><a class="reference internal" href="#dfapacketizer" id="id12">DFAPacketizer</a></li>
+<li><a class="reference internal" href="#fastisel" id="id13">FastISel</a></li>
+<li><a class="reference internal" href="#subtarget" id="id14">Subtarget</a></li>
+<li><a class="reference internal" href="#intrinsic" id="id15">Intrinsic</a></li>
+<li><a class="reference internal" href="#optparserdefs" id="id16">OptParserDefs</a></li>
+<li><a class="reference internal" href="#ctags" id="id17">CTags</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-backends" id="id18">Clang BackEnds</a><ul>
+<li><a class="reference internal" href="#clangattrclasses" id="id19">ClangAttrClasses</a></li>
+<li><a class="reference internal" href="#clangattrparserstringswitches" id="id20">ClangAttrParserStringSwitches</a></li>
+<li><a class="reference internal" href="#clangattrimpl" id="id21">ClangAttrImpl</a></li>
+<li><a class="reference internal" href="#clangattrlist" id="id22">ClangAttrList</a></li>
+<li><a class="reference internal" href="#clangattrpchread" id="id23">ClangAttrPCHRead</a></li>
+<li><a class="reference internal" href="#clangattrpchwrite" id="id24">ClangAttrPCHWrite</a></li>
+<li><a class="reference internal" href="#clangattrspellings" id="id25">ClangAttrSpellings</a></li>
+<li><a class="reference internal" href="#clangattrspellinglistindex" id="id26">ClangAttrSpellingListIndex</a></li>
+<li><a class="reference internal" href="#clangattrvisitor" id="id27">ClangAttrVisitor</a></li>
+<li><a class="reference internal" href="#clangattrtemplateinstantiate" id="id28">ClangAttrTemplateInstantiate</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrlist" id="id29">ClangAttrParsedAttrList</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrimpl" id="id30">ClangAttrParsedAttrImpl</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrkinds" id="id31">ClangAttrParsedAttrKinds</a></li>
+<li><a class="reference internal" href="#clangattrdump" id="id32">ClangAttrDump</a></li>
+<li><a class="reference internal" href="#clangdiagsdefs" id="id33">ClangDiagsDefs</a></li>
+<li><a class="reference internal" href="#clangdiaggroups" id="id34">ClangDiagGroups</a></li>
+<li><a class="reference internal" href="#clangdiagsindexname" id="id35">ClangDiagsIndexName</a></li>
+<li><a class="reference internal" href="#clangcommentnodes" id="id36">ClangCommentNodes</a></li>
+<li><a class="reference internal" href="#clangdeclnodes" id="id37">ClangDeclNodes</a></li>
+<li><a class="reference internal" href="#clangstmtnodes" id="id38">ClangStmtNodes</a></li>
+<li><a class="reference internal" href="#clangsacheckers" id="id39">ClangSACheckers</a></li>
+<li><a class="reference internal" href="#clangcommenthtmltags" id="id40">ClangCommentHTMLTags</a></li>
+<li><a class="reference internal" href="#clangcommenthtmltagsproperties" id="id41">ClangCommentHTMLTagsProperties</a></li>
+<li><a class="reference internal" href="#clangcommenthtmlnamedcharacterreferences" id="id42">ClangCommentHTMLNamedCharacterReferences</a></li>
+<li><a class="reference internal" href="#clangcommentcommandinfo" id="id43">ClangCommentCommandInfo</a></li>
+<li><a class="reference internal" href="#clangcommentcommandlist" id="id44">ClangCommentCommandList</a></li>
+<li><a class="reference internal" href="#armneon" id="id45">ArmNeon</a></li>
+<li><a class="reference internal" href="#armneonsema" id="id46">ArmNeonSema</a></li>
+<li><a class="reference internal" href="#armneontest" id="id47">ArmNeonTest</a></li>
+<li><a class="reference internal" href="#attrdocs" id="id48">AttrDocs</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-write-a-back-end" id="id49">How to write a back-end</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>TableGen backends are at the core of TableGen’s functionality. The source files
+provide the semantics to a generated (in memory) structure, but it’s up to the
+backend to print this out in a way that is meaningful to the user (normally a
+C program including a file or a textual list of warnings, options and error
+messages).</p>
+<p>TableGen is used by both LLVM and Clang with very different goals. LLVM uses it
+as a way to automate the generation of massive amounts of information regarding
+instructions, schedules, cores and architecture features. Some backends generate
+output that is consumed by more than one source file, so they need to be created
+in a way that is easy to use pre-processor tricks. Some backends can also print
+C code structures, so that they can be directly included as-is.</p>
+<p>Clang, on the other hand, uses it mainly for diagnostic messages (errors,
+warnings, tips) and attributes, so more on the textual end of the scale.</p>
+</div>
+<div class="section" id="llvm-backends">
+<h2><a class="toc-backref" href="#id2">LLVM BackEnds</a><a class="headerlink" href="#llvm-backends" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is raw. Each section below needs three sub-sections: description
+of its purpose with a list of users, output generated from generic input, and
+finally why it needed a new backend (in case there’s something similar).</p>
+</div>
+<p>Overall, each backend will take the same TableGen file type and transform into
+similar output for different targets/uses. There is an implicit contract between
+the TableGen files, the back-ends and their users.</p>
+<p>For instance, a global contract is that each back-end produces macro-guarded
+sections. Based on whether the file is included by a header or a source file,
+or even in which context of each file the include is being used, you have
+todefine a macro just before including it, to get the right output:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_REGINFO_TARGET_DESC</span>
+<span class="cp">#include "ARMGenRegisterInfo.inc"</span>
+</pre></div>
+</div>
+<p>And just part of the generated file would be included. This is useful if
+you need the same information in multiple formats (instantiation, initialization,
+getter/setter functions, etc) from the same source TableGen file without having
+to re-compile the TableGen file multiple times.</p>
+<p>Sometimes, multiple macros might be defined before the same include file to
+output multiple blocks:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_REGISTER_MATCHER</span>
+<span class="cp">#define GET_SUBTARGET_FEATURE_NAME</span>
+<span class="cp">#define GET_MATCHER_IMPLEMENTATION</span>
+<span class="cp">#include "ARMGenAsmMatcher.inc"</span>
+</pre></div>
+</div>
+<p>The macros will be undef’d automatically as they’re used, in the include file.</p>
+<p>On all LLVM back-ends, the <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt> binary will be executed on the root
+TableGen file <tt class="docutils literal"><span class="pre"><Target>.td</span></tt>, which should include all others. This guarantees
+that all information needed is accessible, and that no duplication is needed
+in the TbleGen files.</p>
+<div class="section" id="codeemitter">
+<h3><a class="toc-backref" href="#id3">CodeEmitter</a><a class="headerlink" href="#codeemitter" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: CodeEmitterGen uses the descriptions of instructions and their fields to
+construct an automated code emitter: a function that, given a MachineInstr,
+returns the (currently, 32-bit unsigned) value of the instruction.</p>
+<p><strong>Output</strong>: C++ code, implementing the target’s CodeEmitter
+class by overriding the virtual functions as <tt class="docutils literal"><span class="pre"><Target>CodeEmitter::function()</span></tt>.</p>
+<p><strong>Usage</strong>: Used to include directly at the end of <tt class="docutils literal"><span class="pre"><Target>MCCodeEmitter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="registerinfo">
+<h3><a class="toc-backref" href="#id4">RegisterInfo</a><a class="headerlink" href="#registerinfo" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend is responsible for emitting a description of a target
+register file for a code generator. It uses instances of the Register,
+RegisterAliases, and RegisterClass classes to gather this information.</p>
+<p><strong>Output</strong>: C++ code with enums and structures representing the register mappings,
+properties, masks, etc.</p>
+<p><strong>Usage</strong>: Both on <tt class="docutils literal"><span class="pre"><Target>BaseRegisterInfo</span></tt> and <tt class="docutils literal"><span class="pre"><Target>MCTargetDesc</span></tt> (headers
+and source files) with macros defining in which they are for declaration vs.
+initialization issues.</p>
+</div>
+<div class="section" id="instrinfo">
+<h3><a class="toc-backref" href="#id5">InstrInfo</a><a class="headerlink" href="#instrinfo" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend is responsible for emitting a description of the target
+instruction set for the code generator. (what are the differences from CodeEmitter?)</p>
+<p><strong>Output</strong>: C++ code with enums and structures representing the register mappings,
+properties, masks, etc.</p>
+<p><strong>Usage</strong>: Both on <tt class="docutils literal"><span class="pre"><Target>BaseInstrInfo</span></tt> and <tt class="docutils literal"><span class="pre"><Target>MCTargetDesc</span></tt> (headers
+and source files) with macros defining in which they are for declaration vs.</p>
+</div>
+<div class="section" id="asmwriter">
+<h3><a class="toc-backref" href="#id6">AsmWriter</a><a class="headerlink" href="#asmwriter" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Emits an assembly printer for the current target.</p>
+<p><strong>Output</strong>: Implementation of <tt class="docutils literal"><span class="pre"><Target>InstPrinter::printInstruction()</span></tt>, among
+other things.</p>
+<p><strong>Usage</strong>: Included directly into <tt class="docutils literal"><span class="pre">InstPrinter/<Target>InstPrinter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="asmmatcher">
+<h3><a class="toc-backref" href="#id7">AsmMatcher</a><a class="headerlink" href="#asmmatcher" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Emits a target specifier matcher for
+converting parsed assembly operands in the MCInst structures. It also
+emits a matcher for custom operand parsing. Extensive documentation is
+written on the <tt class="docutils literal"><span class="pre">AsmMatcherEmitter.cpp</span></tt> file.</p>
+<p><strong>Output</strong>: Assembler parsers’ matcher functions, declarations, etc.</p>
+<p><strong>Usage</strong>: Used in back-ends’ <tt class="docutils literal"><span class="pre">AsmParser/<Target>AsmParser.cpp</span></tt> for
+building the AsmParser class.</p>
+</div>
+<div class="section" id="disassembler">
+<h3><a class="toc-backref" href="#id8">Disassembler</a><a class="headerlink" href="#disassembler" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Contains disassembler table emitters for various
+architectures. Extensive documentation is written on the
+<tt class="docutils literal"><span class="pre">DisassemblerEmitter.cpp</span></tt> file.</p>
+<p><strong>Output</strong>: Decoding tables, static decoding functions, etc.</p>
+<p><strong>Usage</strong>: Directly included in <tt class="docutils literal"><span class="pre">Disassembler/<Target>Disassembler.cpp</span></tt>
+to cater for all default decodings, after all hand-made ones.</p>
+</div>
+<div class="section" id="pseudolowering">
+<h3><a class="toc-backref" href="#id9">PseudoLowering</a><a class="headerlink" href="#pseudolowering" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate pseudo instruction lowering.</p>
+<p><strong>Output</strong>: Implements <tt class="docutils literal"><span class="pre">ARMAsmPrinter::emitPseudoExpansionLowering()</span></tt>.</p>
+<p><strong>Usage</strong>: Included directly into <tt class="docutils literal"><span class="pre"><Target>AsmPrinter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="callingconv">
+<h3><a class="toc-backref" href="#id10">CallingConv</a><a class="headerlink" href="#callingconv" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Responsible for emitting descriptions of the calling
+conventions supported by this target.</p>
+<p><strong>Output</strong>: Implement static functions to deal with calling conventions
+chained by matching styles, returning false on no match.</p>
+<p><strong>Usage</strong>: Used in ISelLowering and FastIsel as function pointers to
+implementation returned by a CC sellection function.</p>
+</div>
+<div class="section" id="dagisel">
+<h3><a class="toc-backref" href="#id11">DAGISel</a><a class="headerlink" href="#dagisel" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate a DAG instruction selector.</p>
+<p><strong>Output</strong>: Creates huge functions for automating DAG selection.</p>
+<p><strong>Usage</strong>: Included in <tt class="docutils literal"><span class="pre"><Target>ISelDAGToDAG.cpp</span></tt> inside the target’s
+implementation of <tt class="docutils literal"><span class="pre">SelectionDAGISel</span></tt>.</p>
+</div>
+<div class="section" id="dfapacketizer">
+<h3><a class="toc-backref" href="#id12">DFAPacketizer</a><a class="headerlink" href="#dfapacketizer" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This class parses the Schedule.td file and produces an API that
+can be used to reason about whether an instruction can be added to a packet
+on a VLIW architecture. The class internally generates a deterministic finite
+automaton (DFA) that models all possible mappings of machine instructions
+to functional units as instructions are added to a packet.</p>
+<p><strong>Output</strong>: Scheduling tables for GPU back-ends (Hexagon, AMD).</p>
+<p><strong>Usage</strong>: Included directly on <tt class="docutils literal"><span class="pre"><Target>InstrInfo.cpp</span></tt>.</p>
+</div>
+<div class="section" id="fastisel">
+<h3><a class="toc-backref" href="#id13">FastISel</a><a class="headerlink" href="#fastisel" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend emits code for use by the “fast”
+instruction selection algorithm. See the comments at the top of
+lib/CodeGen/SelectionDAG/FastISel.cpp for background. This file
+scans through the target’s tablegen instruction-info files
+and extracts instructions with obvious-looking patterns, and it emits
+code to look up these instructions by type and operator.</p>
+<p><strong>Output</strong>: Generates <tt class="docutils literal"><span class="pre">Predicate</span></tt> and <tt class="docutils literal"><span class="pre">FastEmit</span></tt> methods.</p>
+<p><strong>Usage</strong>: Implements private methods of the targets’ implementation
+of <tt class="docutils literal"><span class="pre">FastISel</span></tt> class.</p>
+</div>
+<div class="section" id="subtarget">
+<h3><a class="toc-backref" href="#id14">Subtarget</a><a class="headerlink" href="#subtarget" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate subtarget enumerations.</p>
+<p><strong>Output</strong>: Enums, globals, local tables for sub-target information.</p>
+<p><strong>Usage</strong>: Populates <tt class="docutils literal"><span class="pre"><Target>Subtarget</span></tt> and
+<tt class="docutils literal"><span class="pre">MCTargetDesc/<Target>MCTargetDesc</span></tt> files (both headers and source).</p>
+</div>
+<div class="section" id="intrinsic">
+<h3><a class="toc-backref" href="#id15">Intrinsic</a><a class="headerlink" href="#intrinsic" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate (target) intrinsic information.</p>
+</div>
+<div class="section" id="optparserdefs">
+<h3><a class="toc-backref" href="#id16">OptParserDefs</a><a class="headerlink" href="#optparserdefs" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Print enum values for a class.</p>
+</div>
+<div class="section" id="ctags">
+<h3><a class="toc-backref" href="#id17">CTags</a><a class="headerlink" href="#ctags" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend emits an index of definitions in ctags(1)
+format. A helper script, utils/TableGen/tdtags, provides an easier-to-use
+interface; run ‘tdtags -H’ for documentation.</p>
+</div>
+</div>
+<div class="section" id="clang-backends">
+<h2><a class="toc-backref" href="#id18">Clang BackEnds</a><a class="headerlink" href="#clang-backends" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="clangattrclasses">
+<h3><a class="toc-backref" href="#id19">ClangAttrClasses</a><a class="headerlink" href="#clangattrclasses" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates Attrs.inc, which contains semantic attribute class
+declarations for any attribute in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> that has not set <tt class="docutils literal"><span class="pre">ASTNode</span> <span class="pre">=</span> <span class="pre">0</span></tt>.
+This file is included as part of <tt class="docutils literal"><span class="pre">Attr.h</span></tt>.</p>
+</div>
+<div class="section" id="clangattrparserstringswitches">
+<h3><a class="toc-backref" href="#id20">ClangAttrParserStringSwitches</a><a class="headerlink" href="#clangattrparserstringswitches" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParserStringSwitches.inc, which contains
+StringSwitch::Case statements for parser-related string switches. Each switch
+is given its own macro (such as <tt class="docutils literal"><span class="pre">CLANG_ATTR_ARG_CONTEXT_LIST</span></tt>, or
+<tt class="docutils literal"><span class="pre">CLANG_ATTR_IDENTIFIER_ARG_LIST</span></tt>), which is expected to be defined before
+including AttrParserStringSwitches.inc, and undefined after.</p>
+</div>
+<div class="section" id="clangattrimpl">
+<h3><a class="toc-backref" href="#id21">ClangAttrImpl</a><a class="headerlink" href="#clangattrimpl" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrImpl.inc, which contains semantic attribute class
+definitions for any attribute in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> that has not set <tt class="docutils literal"><span class="pre">ASTNode</span> <span class="pre">=</span> <span class="pre">0</span></tt>.
+This file is included as part of <tt class="docutils literal"><span class="pre">AttrImpl.cpp</span></tt>.</p>
+</div>
+<div class="section" id="clangattrlist">
+<h3><a class="toc-backref" href="#id22">ClangAttrList</a><a class="headerlink" href="#clangattrlist" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrList.inc, which is used when a list of semantic
+attribute identifiers is required. For instance, <tt class="docutils literal"><span class="pre">AttrKinds.h</span></tt> includes this
+file to generate the list of <tt class="docutils literal"><span class="pre">attr::Kind</span></tt> enumeration values. This list is
+separated out into multiple categories: attributes, inheritable attributes, and
+inheritable parameter attributes. This categorization happens automatically
+based on information in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> and is used to implement the <tt class="docutils literal"><span class="pre">classof</span></tt>
+functionality required for <tt class="docutils literal"><span class="pre">dyn_cast</span></tt> and similar APIs.</p>
+</div>
+<div class="section" id="clangattrpchread">
+<h3><a class="toc-backref" href="#id23">ClangAttrPCHRead</a><a class="headerlink" href="#clangattrpchread" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrPCHRead.inc, which is used to deserialize attributes
+in the <tt class="docutils literal"><span class="pre">ASTReader::ReadAttributes</span></tt> function.</p>
+</div>
+<div class="section" id="clangattrpchwrite">
+<h3><a class="toc-backref" href="#id24">ClangAttrPCHWrite</a><a class="headerlink" href="#clangattrpchwrite" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrPCHWrite.inc, which is used to serialize attributes in
+the <tt class="docutils literal"><span class="pre">ASTWriter::WriteAttributes</span></tt> function.</p>
+</div>
+<div class="section" id="clangattrspellings">
+<h3><a class="toc-backref" href="#id25">ClangAttrSpellings</a><a class="headerlink" href="#clangattrspellings" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrSpellings.inc, which is used to implement the
+<tt class="docutils literal"><span class="pre">__has_attribute</span></tt> feature test macro.</p>
+</div>
+<div class="section" id="clangattrspellinglistindex">
+<h3><a class="toc-backref" href="#id26">ClangAttrSpellingListIndex</a><a class="headerlink" href="#clangattrspellinglistindex" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrSpellingListIndex.inc, which is used to map parsed
+attribute spellings (including which syntax or scope was used) to an attribute
+spelling list index. These spelling list index values are internal
+implementation details exposed via
+<tt class="docutils literal"><span class="pre">AttributeList::getAttributeSpellingListIndex</span></tt>.</p>
+</div>
+<div class="section" id="clangattrvisitor">
+<h3><a class="toc-backref" href="#id27">ClangAttrVisitor</a><a class="headerlink" href="#clangattrvisitor" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrVisitor.inc, which is used when implementing
+recursive AST visitors.</p>
+</div>
+<div class="section" id="clangattrtemplateinstantiate">
+<h3><a class="toc-backref" href="#id28">ClangAttrTemplateInstantiate</a><a class="headerlink" href="#clangattrtemplateinstantiate" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrTemplateInstantiate.inc, which implements the
+<tt class="docutils literal"><span class="pre">instantiateTemplateAttribute</span></tt> function, used when instantiating a template
+that requires an attribute to be cloned.</p>
+</div>
+<div class="section" id="clangattrparsedattrlist">
+<h3><a class="toc-backref" href="#id29">ClangAttrParsedAttrList</a><a class="headerlink" href="#clangattrparsedattrlist" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrList.inc, which is used to generate the
+<tt class="docutils literal"><span class="pre">AttributeList::Kind</span></tt> parsed attribute enumeration.</p>
+</div>
+<div class="section" id="clangattrparsedattrimpl">
+<h3><a class="toc-backref" href="#id30">ClangAttrParsedAttrImpl</a><a class="headerlink" href="#clangattrparsedattrimpl" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrImpl.inc, which is used by
+<tt class="docutils literal"><span class="pre">AttributeList.cpp</span></tt> to implement several functions on the <tt class="docutils literal"><span class="pre">AttributeList</span></tt>
+class. This functionality is implemented via the <tt class="docutils literal"><span class="pre">AttrInfoMap</span> <span class="pre">ParsedAttrInfo</span></tt>
+array, which contains one element per parsed attribute object.</p>
+</div>
+<div class="section" id="clangattrparsedattrkinds">
+<h3><a class="toc-backref" href="#id31">ClangAttrParsedAttrKinds</a><a class="headerlink" href="#clangattrparsedattrkinds" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrKinds.inc, which is used to implement the
+<tt class="docutils literal"><span class="pre">AttributeList::getKind</span></tt> function, mapping a string (and syntax) to a parsed
+attribute <tt class="docutils literal"><span class="pre">AttributeList::Kind</span></tt> enumeration.</p>
+</div>
+<div class="section" id="clangattrdump">
+<h3><a class="toc-backref" href="#id32">ClangAttrDump</a><a class="headerlink" href="#clangattrdump" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrDump.inc, which dumps information about an attribute.
+It is used to implement <tt class="docutils literal"><span class="pre">ASTDumper::dumpAttr</span></tt>.</p>
+</div>
+<div class="section" id="clangdiagsdefs">
+<h3><a class="toc-backref" href="#id33">ClangDiagsDefs</a><a class="headerlink" href="#clangdiagsdefs" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostics definitions.</p>
+</div>
+<div class="section" id="clangdiaggroups">
+<h3><a class="toc-backref" href="#id34">ClangDiagGroups</a><a class="headerlink" href="#clangdiaggroups" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostic groups.</p>
+</div>
+<div class="section" id="clangdiagsindexname">
+<h3><a class="toc-backref" href="#id35">ClangDiagsIndexName</a><a class="headerlink" href="#clangdiagsindexname" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostic name index.</p>
+</div>
+<div class="section" id="clangcommentnodes">
+<h3><a class="toc-backref" href="#id36">ClangCommentNodes</a><a class="headerlink" href="#clangcommentnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST comment nodes.</p>
+</div>
+<div class="section" id="clangdeclnodes">
+<h3><a class="toc-backref" href="#id37">ClangDeclNodes</a><a class="headerlink" href="#clangdeclnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST declaration nodes.</p>
+</div>
+<div class="section" id="clangstmtnodes">
+<h3><a class="toc-backref" href="#id38">ClangStmtNodes</a><a class="headerlink" href="#clangstmtnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST statement nodes.</p>
+</div>
+<div class="section" id="clangsacheckers">
+<h3><a class="toc-backref" href="#id39">ClangSACheckers</a><a class="headerlink" href="#clangsacheckers" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang Static Analyzer checkers.</p>
+</div>
+<div class="section" id="clangcommenthtmltags">
+<h3><a class="toc-backref" href="#id40">ClangCommentHTMLTags</a><a class="headerlink" href="#clangcommenthtmltags" title="Permalink to this headline">¶</a></h3>
+<p>Generate efficient matchers for HTML tag names that are used in documentation comments.</p>
+</div>
+<div class="section" id="clangcommenthtmltagsproperties">
+<h3><a class="toc-backref" href="#id41">ClangCommentHTMLTagsProperties</a><a class="headerlink" href="#clangcommenthtmltagsproperties" title="Permalink to this headline">¶</a></h3>
+<p>Generate efficient matchers for HTML tag properties.</p>
+</div>
+<div class="section" id="clangcommenthtmlnamedcharacterreferences">
+<h3><a class="toc-backref" href="#id42">ClangCommentHTMLNamedCharacterReferences</a><a class="headerlink" href="#clangcommenthtmlnamedcharacterreferences" title="Permalink to this headline">¶</a></h3>
+<p>Generate function to translate named character references to UTF-8 sequences.</p>
+</div>
+<div class="section" id="clangcommentcommandinfo">
+<h3><a class="toc-backref" href="#id43">ClangCommentCommandInfo</a><a class="headerlink" href="#clangcommentcommandinfo" title="Permalink to this headline">¶</a></h3>
+<p>Generate command properties for commands that are used in documentation comments.</p>
+</div>
+<div class="section" id="clangcommentcommandlist">
+<h3><a class="toc-backref" href="#id44">ClangCommentCommandList</a><a class="headerlink" href="#clangcommentcommandlist" title="Permalink to this headline">¶</a></h3>
+<p>Generate list of commands that are used in documentation comments.</p>
+</div>
+<div class="section" id="armneon">
+<h3><a class="toc-backref" href="#id45">ArmNeon</a><a class="headerlink" href="#armneon" title="Permalink to this headline">¶</a></h3>
+<p>Generate arm_neon.h for clang.</p>
+</div>
+<div class="section" id="armneonsema">
+<h3><a class="toc-backref" href="#id46">ArmNeonSema</a><a class="headerlink" href="#armneonsema" title="Permalink to this headline">¶</a></h3>
+<p>Generate ARM NEON sema support for clang.</p>
+</div>
+<div class="section" id="armneontest">
+<h3><a class="toc-backref" href="#id47">ArmNeonTest</a><a class="headerlink" href="#armneontest" title="Permalink to this headline">¶</a></h3>
+<p>Generate ARM NEON tests for clang.</p>
+</div>
+<div class="section" id="attrdocs">
+<h3><a class="toc-backref" href="#id48">AttrDocs</a><a class="headerlink" href="#attrdocs" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates <tt class="docutils literal"><span class="pre">AttributeReference.rst</span></tt> from <tt class="docutils literal"><span class="pre">AttrDocs.td</span></tt>, and is
+used for documenting user-facing attributes.</p>
+</div>
+</div>
+<div class="section" id="how-to-write-a-back-end">
+<h2><a class="toc-backref" href="#id49">How to write a back-end</a><a class="headerlink" href="#how-to-write-a-back-end" title="Permalink to this headline">¶</a></h2>
+<p>TODO.</p>
+<p>Until we get a step-by-step HowTo for writing TableGen backends, you can at
+least grab the boilerplate (build system, new files, etc.) from Clang’s
+r173931.</p>
+<p>TODO: How they work, how to write one. This section should not contain details
+about any particular backend, except maybe <tt class="docutils literal"><span class="pre">-print-enums</span></tt> as an example. This
+should highlight the APIs in <tt class="docutils literal"><span class="pre">TableGen/Record.h</span></tt>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LangRef.html" title="TableGen Language Reference"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="TableGen"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >TableGen</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/TableGen/Deficiencies.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/TableGen/Deficiencies.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/TableGen/Deficiencies.html (added)
+++ www-releases/trunk/3.7.1/docs/TableGen/Deficiencies.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,128 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Deficiencies — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="../index.html" />
+ <link rel="up" title="TableGen" href="index.html" />
+ <link rel="next" title="Debugging JIT-ed Code With GDB" href="../DebuggingJITedCode.html" />
+ <link rel="prev" title="TableGen Language Introduction" href="LangIntro.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LangIntro.html" title="TableGen Language Introduction"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">TableGen</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-deficiencies">
+<h1>TableGen Deficiencies<a class="headerlink" href="#tablegen-deficiencies" 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="#known-problems" id="id2">Known Problems</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>Despite being very generic, TableGen has some deficiencies that have been
+pointed out numerous times. The common theme is that, while TableGen allows
+you to build Domain-Specific-Languages, the final languages that you create
+lack the power of other DSLs, which in turn increase considerably the size
+and complexity of TableGen files.</p>
+<p>At the same time, TableGen allows you to create virtually any meaning of
+the basic concepts via custom-made back-ends, which can pervert the original
+design and make it very hard for newcomers to understand it.</p>
+<p>There are some in favour of extending the semantics even more, but making sure
+back-ends adhere to strict rules. Others suggesting we should move to more
+powerful DSLs designed with specific purposes, or even re-using existing
+DSLs.</p>
+</div>
+<div class="section" id="known-problems">
+<h2><a class="toc-backref" href="#id2">Known Problems</a><a class="headerlink" href="#known-problems" title="Permalink to this headline">¶</a></h2>
+<p>TODO: Add here frequently asked questions about why TableGen doesn’t do
+what you want, how it might, and how we could extend/restrict it to
+be more use friendly.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LangIntro.html" title="TableGen Language Introduction"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >TableGen</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/TableGen/LangIntro.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/TableGen/LangIntro.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/TableGen/LangIntro.html (added)
+++ www-releases/trunk/3.7.1/docs/TableGen/LangIntro.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,647 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Language Introduction — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="../index.html" />
+ <link rel="up" title="TableGen" href="index.html" />
+ <link rel="next" title="TableGen Deficiencies" href="Deficiencies.html" />
+ <link rel="prev" title="TableGen Language Reference" href="LangRef.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Deficiencies.html" title="TableGen Deficiencies"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LangRef.html" title="TableGen Language Reference"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">TableGen</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-language-introduction">
+<h1>TableGen Language Introduction<a class="headerlink" href="#tablegen-language-introduction" 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="id4">Introduction</a></li>
+<li><a class="reference internal" href="#tablegen-syntax" id="id5">TableGen syntax</a><ul>
+<li><a class="reference internal" href="#tablegen-primitives" id="id6">TableGen primitives</a><ul>
+<li><a class="reference internal" href="#tablegen-comments" id="id7">TableGen comments</a></li>
+<li><a class="reference internal" href="#the-tablegen-type-system" id="id8">The TableGen type system</a></li>
+<li><a class="reference internal" href="#tablegen-values-and-expressions" id="id9">TableGen values and expressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#classes-and-definitions" id="id10">Classes and definitions</a><ul>
+<li><a class="reference internal" href="#value-definitions" id="id11">Value definitions</a></li>
+<li><a class="reference internal" href="#let-expressions-within-a-record" id="id12">‘let’ expressions</a></li>
+<li><a class="reference internal" href="#class-template-arguments" id="id13">Class template arguments</a></li>
+<li><a class="reference internal" href="#multiclass-definitions-and-instances" id="id14">Multiclass definitions and instances</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#file-scope-entities" id="id15">File scope entities</a><ul>
+<li><a class="reference internal" href="#file-inclusion" id="id16">File inclusion</a></li>
+<li><a class="reference internal" href="#id3" id="id17">‘let’ expressions</a></li>
+<li><a class="reference internal" href="#looping" id="id18">Looping</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#code-generator-backend-info" id="id19">Code Generator backend info</a></li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is extremely rough. If you find something lacking, please
+fix it, file a documentation bug, or ask about it on llvm-dev.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id4">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is not meant to be a normative spec about the TableGen language
+in and of itself (i.e. how to understand a given construct in terms of how
+it affects the final set of records represented by the TableGen file). For
+the formal language specification, see <a class="reference internal" href="LangRef.html"><em>TableGen Language Reference</em></a>.</p>
+</div>
+<div class="section" id="tablegen-syntax">
+<h2><a class="toc-backref" href="#id5">TableGen syntax</a><a class="headerlink" href="#tablegen-syntax" title="Permalink to this headline">¶</a></h2>
+<p>TableGen doesn’t care about the meaning of data (that is up to the backend to
+define), but it does care about syntax, and it enforces a simple type system.
+This section describes the syntax and the constructs allowed in a TableGen file.</p>
+<div class="section" id="tablegen-primitives">
+<h3><a class="toc-backref" href="#id6">TableGen primitives</a><a class="headerlink" href="#tablegen-primitives" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="tablegen-comments">
+<h4><a class="toc-backref" href="#id7">TableGen comments</a><a class="headerlink" href="#tablegen-comments" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports C++ style “<tt class="docutils literal"><span class="pre">//</span></tt>” comments, which run to the end of the
+line, and it also supports <strong>nestable</strong> “<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">*/</span></tt>” comments.</p>
+</div>
+<div class="section" id="the-tablegen-type-system">
+<span id="tablegen-type"></span><h4><a class="toc-backref" href="#id8">The TableGen type system</a><a class="headerlink" href="#the-tablegen-type-system" title="Permalink to this headline">¶</a></h4>
+<p>TableGen files are strongly typed, in a simple (but complete) type-system.
+These types are used to perform automatic conversions, check for errors, and to
+help interface designers constrain the input that they allow. Every <a class="reference internal" href="#value-definition">value
+definition</a> is required to have an associated type.</p>
+<p>TableGen supports a mixture of very low-level types (such as <tt class="docutils literal"><span class="pre">bit</span></tt>) and very
+high-level types (such as <tt class="docutils literal"><span class="pre">dag</span></tt>). This flexibility is what allows it to
+describe a wide range of information conveniently and compactly. The TableGen
+types are:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">bit</span></tt></dt>
+<dd>A ‘bit’ is a boolean value that can hold either 0 or 1.</dd>
+<dt><tt class="docutils literal"><span class="pre">int</span></tt></dt>
+<dd>The ‘int’ type represents a simple 32-bit integer value, such as 5.</dd>
+<dt><tt class="docutils literal"><span class="pre">string</span></tt></dt>
+<dd>The ‘string’ type represents an ordered sequence of characters of arbitrary
+length.</dd>
+<dt><tt class="docutils literal"><span class="pre">bits<n></span></tt></dt>
+<dd>A ‘bits’ type is an arbitrary, but fixed, size integer that is broken up
+into individual bits. This type is useful because it can handle some bits
+being defined while others are undefined.</dd>
+<dt><tt class="docutils literal"><span class="pre">list<ty></span></tt></dt>
+<dd>This type represents a list whose elements are some other type. The
+contained type is arbitrary: it can even be another list type.</dd>
+<dt>Class type</dt>
+<dd>Specifying a class name in a type context means that the defined value must
+be a subclass of the specified class. This is useful in conjunction with
+the <tt class="docutils literal"><span class="pre">list</span></tt> type, for example, to constrain the elements of the list to a
+common base class (e.g., a <tt class="docutils literal"><span class="pre">list<Register></span></tt> can only contain definitions
+derived from the “<tt class="docutils literal"><span class="pre">Register</span></tt>” class).</dd>
+<dt><tt class="docutils literal"><span class="pre">dag</span></tt></dt>
+<dd>This type represents a nestable directed graph of elements.</dd>
+</dl>
+<p>To date, these types have been sufficient for describing things that TableGen
+has been used for, but it is straight-forward to extend this list if needed.</p>
+</div>
+<div class="section" id="tablegen-values-and-expressions">
+<span id="tablegen-expressions"></span><h4><a class="toc-backref" href="#id9">TableGen values and expressions</a><a class="headerlink" href="#tablegen-values-and-expressions" title="Permalink to this headline">¶</a></h4>
+<p>TableGen allows for a pretty reasonable number of different expression forms
+when building up values. These forms allow the TableGen file to be written in a
+natural syntax and flavor for the application. The current expression forms
+supported include:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">?</span></tt></dt>
+<dd>uninitialized field</dd>
+<dt><tt class="docutils literal"><span class="pre">0b1001011</span></tt></dt>
+<dd>binary integer value.
+Note that this is sized by the number of bits given and will not be
+silently extended/truncated.</dd>
+<dt><tt class="docutils literal"><span class="pre">07654321</span></tt></dt>
+<dd>octal integer value (indicated by a leading 0)</dd>
+<dt><tt class="docutils literal"><span class="pre">7</span></tt></dt>
+<dd>decimal integer value</dd>
+<dt><tt class="docutils literal"><span class="pre">0x7F</span></tt></dt>
+<dd>hexadecimal integer value</dd>
+<dt><tt class="docutils literal"><span class="pre">"foo"</span></tt></dt>
+<dd>string value</dd>
+<dt><tt class="docutils literal"><span class="pre">[{</span> <span class="pre">...</span> <span class="pre">}]</span></tt></dt>
+<dd>usually called a “code fragment”, but is just a multiline string literal</dd>
+<dt><tt class="docutils literal"><span class="pre">[</span> <span class="pre">X,</span> <span class="pre">Y,</span> <span class="pre">Z</span> <span class="pre">]<type></span></tt></dt>
+<dd>list value. <type> is the type of the list element and is usually optional.
+In rare cases, TableGen is unable to deduce the element type in which case
+the user must specify it explicitly.</dd>
+<dt><tt class="docutils literal"><span class="pre">{</span> <span class="pre">a,</span> <span class="pre">b,</span> <span class="pre">0b10</span> <span class="pre">}</span></tt></dt>
+<dd>initializer for a “bits<4>” value.
+1-bit from “a”, 1-bit from “b”, 2-bits from 0b10.</dd>
+<dt><tt class="docutils literal"><span class="pre">value</span></tt></dt>
+<dd>value reference</dd>
+<dt><tt class="docutils literal"><span class="pre">value{17}</span></tt></dt>
+<dd>access to one bit of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">value{15-17}</span></tt></dt>
+<dd>access to multiple bits of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">DEF</span></tt></dt>
+<dd>reference to a record definition</dd>
+<dt><tt class="docutils literal"><span class="pre">CLASS<val</span> <span class="pre">list></span></tt></dt>
+<dd>reference to a new anonymous definition of CLASS with the specified template
+arguments.</dd>
+<dt><tt class="docutils literal"><span class="pre">X.Y</span></tt></dt>
+<dd>reference to the subfield of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">list[4-7,17,2-3]</span></tt></dt>
+<dd>A slice of the ‘list’ list, including elements 4,5,6,7,17,2, and 3 from it.
+Elements may be included multiple times.</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">[</span> <span class="pre"><list></span> <span class="pre">]</span> <span class="pre">in</span> <span class="pre">{</span> <span class="pre"><body></span> <span class="pre">}</span></tt></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">[</span> <span class="pre"><list></span> <span class="pre">]</span> <span class="pre">in</span> <span class="pre"><def></span></tt></dt>
+<dd>Replicate <body> or <def>, replacing instances of <var> with each value
+in <list>. <var> is scoped at the level of the <tt class="docutils literal"><span class="pre">foreach</span></tt> loop and must
+not conflict with any other object introduced in <body> or <def>. Currently
+only <tt class="docutils literal"><span class="pre">def</span></tt>s are expanded within <body>.</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">0-15</span> <span class="pre">in</span> <span class="pre">...</span></tt></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">{0-15,32-47}</span> <span class="pre">in</span> <span class="pre">...</span></tt></dt>
+<dd>Loop over ranges of integers. The braces are required for multiple ranges.</dd>
+<dt><tt class="docutils literal"><span class="pre">(DEF</span> <span class="pre">a,</span> <span class="pre">b)</span></tt></dt>
+<dd>a dag value. The first element is required to be a record definition, the
+remaining elements in the list may be arbitrary other values, including
+nested <tt class="docutils literal"><span class="pre">`dag</span></tt>‘ values.</dd>
+<dt><tt class="docutils literal"><span class="pre">!listconcat(a,</span> <span class="pre">b,</span> <span class="pre">...)</span></tt></dt>
+<dd>A list value that is the result of concatenating the ‘a’ and ‘b’ lists.
+The lists must have the same element type.
+More than two arguments are accepted with the result being the concatenation
+of all the lists given.</dd>
+<dt><tt class="docutils literal"><span class="pre">!strconcat(a,</span> <span class="pre">b,</span> <span class="pre">...)</span></tt></dt>
+<dd>A string value that is the result of concatenating the ‘a’ and ‘b’ strings.
+More than two arguments are accepted with the result being the concatenation
+of all the strings given.</dd>
+<dt><tt class="docutils literal"><span class="pre">str1#str2</span></tt></dt>
+<dd>“#” (paste) is a shorthand for !strconcat. It may concatenate things that
+are not quoted strings, in which case an implicit !cast<string> is done on
+the operand of the paste.</dd>
+<dt><tt class="docutils literal"><span class="pre">!cast<type>(a)</span></tt></dt>
+<dd>A symbol of type <em>type</em> obtained by looking up the string ‘a’ in the symbol
+table. If the type of ‘a’ does not match <em>type</em>, TableGen aborts with an
+error. !cast<string> is a special case in that the argument must be an
+object defined by a ‘def’ construct.</dd>
+<dt><tt class="docutils literal"><span class="pre">!subst(a,</span> <span class="pre">b,</span> <span class="pre">c)</span></tt></dt>
+<dd>If ‘a’ and ‘b’ are of string type or are symbol references, substitute ‘b’
+for ‘a’ in ‘c.’ This operation is analogous to $(subst) in GNU make.</dd>
+<dt><tt class="docutils literal"><span class="pre">!foreach(a,</span> <span class="pre">b,</span> <span class="pre">c)</span></tt></dt>
+<dd>For each member of dag or list ‘b’ apply operator ‘c.’ ‘a’ is a dummy
+variable that should be declared as a member variable of an instantiated
+class. This operation is analogous to $(foreach) in GNU make.</dd>
+<dt><tt class="docutils literal"><span class="pre">!head(a)</span></tt></dt>
+<dd>The first element of list ‘a.’</dd>
+<dt><tt class="docutils literal"><span class="pre">!tail(a)</span></tt></dt>
+<dd>The 2nd-N elements of list ‘a.’</dd>
+<dt><tt class="docutils literal"><span class="pre">!empty(a)</span></tt></dt>
+<dd>An integer {0,1} indicating whether list ‘a’ is empty.</dd>
+<dt><tt class="docutils literal"><span class="pre">!if(a,b,c)</span></tt></dt>
+<dd>‘b’ if the result of ‘int’ or ‘bit’ operator ‘a’ is nonzero, ‘c’ otherwise.</dd>
+<dt><tt class="docutils literal"><span class="pre">!eq(a,b)</span></tt></dt>
+<dd>‘bit 1’ if string a is equal to string b, 0 otherwise. This only operates
+on string, int and bit objects. Use !cast<string> to compare other types of
+objects.</dd>
+<dt><tt class="docutils literal"><span class="pre">!shl(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!srl(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!sra(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!add(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!and(a,b)</span></tt></dt>
+<dd>The usual binary and arithmetic operators.</dd>
+</dl>
+<p>Note that all of the values have rules specifying how they convert to values
+for different types. These rules allow you to assign a value like “<tt class="docutils literal"><span class="pre">7</span></tt>”
+to a “<tt class="docutils literal"><span class="pre">bits<4></span></tt>” value, for example.</p>
+</div>
+</div>
+<div class="section" id="classes-and-definitions">
+<h3><a class="toc-backref" href="#id10">Classes and definitions</a><a class="headerlink" href="#classes-and-definitions" title="Permalink to this headline">¶</a></h3>
+<p>As mentioned in the <a class="reference internal" href="index.html"><em>introduction</em></a>, classes and definitions (collectively known as
+‘records’) in TableGen are the main high-level unit of information that TableGen
+collects. Records are defined with a <tt class="docutils literal"><span class="pre">def</span></tt> or <tt class="docutils literal"><span class="pre">class</span></tt> keyword, the record
+name, and an optional list of “<a class="reference internal" href="#template-arguments">template arguments</a>”. If the record has
+superclasses, they are specified as a comma separated list that starts with a
+colon character (“<tt class="docutils literal"><span class="pre">:</span></tt>”). If <a class="reference internal" href="#value-definitions">value definitions</a> or <a class="reference internal" href="#let-expressions">let expressions</a> are
+needed for the class, they are enclosed in curly braces (“<tt class="docutils literal"><span class="pre">{}</span></tt>”); otherwise,
+the record ends with a semicolon.</p>
+<p>Here is a simple TableGen file:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class C { bit V = 1; }
+def X : C;
+def Y : C {
+ string Greeting = "hello";
+}
+</pre></div>
+</div>
+<p>This example defines two definitions, <tt class="docutils literal"><span class="pre">X</span></tt> and <tt class="docutils literal"><span class="pre">Y</span></tt>, both of which derive from
+the <tt class="docutils literal"><span class="pre">C</span></tt> class. Because of this, they both get the <tt class="docutils literal"><span class="pre">V</span></tt> bit value. The <tt class="docutils literal"><span class="pre">Y</span></tt>
+definition also gets the Greeting member as well.</p>
+<p>In general, classes are useful for collecting together the commonality between a
+group of records and isolating it in a single place. Also, classes permit the
+specification of default values for their subclasses, allowing the subclasses to
+override them as they wish.</p>
+<div class="section" id="value-definitions">
+<span id="value-definition"></span><span id="id1"></span><h4><a class="toc-backref" href="#id11">Value definitions</a><a class="headerlink" href="#value-definitions" title="Permalink to this headline">¶</a></h4>
+<p>Value definitions define named entries in records. A value must be defined
+before it can be referred to as the operand for another value definition or
+before the value is reset with a <a class="reference internal" href="#let-expression">let expression</a>. A value is defined by
+specifying a <a class="reference internal" href="#tablegen-type">TableGen type</a> and a name. If an initial value is available, it
+may be specified after the type with an equal sign. Value definitions require
+terminating semicolons.</p>
+</div>
+<div class="section" id="let-expressions-within-a-record">
+<span id="let-expressions"></span><span id="let-expression"></span><span id="id2"></span><h4><a class="toc-backref" href="#id12">‘let’ expressions</a><a class="headerlink" href="#let-expressions-within-a-record" title="Permalink to this headline">¶</a></h4>
+<p>A record-level let expression is used to change the value of a value definition
+in a record. This is primarily useful when a superclass defines a value that a
+derived class or definition wants to override. Let expressions consist of the
+‘<tt class="docutils literal"><span class="pre">let</span></tt>‘ keyword followed by a value name, an equal sign (“<tt class="docutils literal"><span class="pre">=</span></tt>”), and a new
+value. For example, a new class could be added to the example above, redefining
+the <tt class="docutils literal"><span class="pre">V</span></tt> field for all of its subclasses:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class D : C { let V = 0; }
+def Z : D;
+</pre></div>
+</div>
+<p>In this case, the <tt class="docutils literal"><span class="pre">Z</span></tt> definition will have a zero value for its <tt class="docutils literal"><span class="pre">V</span></tt> value,
+despite the fact that it derives (indirectly) from the <tt class="docutils literal"><span class="pre">C</span></tt> class, because the
+<tt class="docutils literal"><span class="pre">D</span></tt> class overrode its value.</p>
+</div>
+<div class="section" id="class-template-arguments">
+<span id="template-arguments"></span><h4><a class="toc-backref" href="#id13">Class template arguments</a><a class="headerlink" href="#class-template-arguments" title="Permalink to this headline">¶</a></h4>
+<p>TableGen permits the definition of parameterized classes as well as normal
+concrete classes. Parameterized TableGen classes specify a list of variable
+bindings (which may optionally have defaults) that are bound when used. Here is
+a simple example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class FPFormat<bits<3> val> {
+ bits<3> Value = val;
+}
+def NotFP : FPFormat<0>;
+def ZeroArgFP : FPFormat<1>;
+def OneArgFP : FPFormat<2>;
+def OneArgFPRW : FPFormat<3>;
+def TwoArgFP : FPFormat<4>;
+def CompareFP : FPFormat<5>;
+def CondMovFP : FPFormat<6>;
+def SpecialFP : FPFormat<7>;
+</pre></div>
+</div>
+<p>In this case, template arguments are used as a space efficient way to specify a
+list of “enumeration values”, each with a “<tt class="docutils literal"><span class="pre">Value</span></tt>” field set to the specified
+integer.</p>
+<p>The more esoteric forms of <a class="reference internal" href="#tablegen-expressions">TableGen expressions</a> are useful in conjunction
+with template arguments. As an example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class ModRefVal<bits<2> val> {
+ bits<2> Value = val;
+}
+
+def None : ModRefVal<0>;
+def Mod : ModRefVal<1>;
+def Ref : ModRefVal<2>;
+def ModRef : ModRefVal<3>;
+
+class Value<ModRefVal MR> {
+ // Decode some information into a more convenient format, while providing
+ // a nice interface to the user of the "Value" class.
+ bit isMod = MR.Value{0};
+ bit isRef = MR.Value{1};
+
+ // other stuff...
+}
+
+// Example uses
+def bork : Value<Mod>;
+def zork : Value<Ref>;
+def hork : Value<ModRef>;
+</pre></div>
+</div>
+<p>This is obviously a contrived example, but it shows how template arguments can
+be used to decouple the interface provided to the user of the class from the
+actual internal data representation expected by the class. In this case,
+running <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt> on the example prints the following definitions:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def bork { // Value
+ bit isMod = 1;
+ bit isRef = 0;
+}
+def hork { // Value
+ bit isMod = 1;
+ bit isRef = 1;
+}
+def zork { // Value
+ bit isMod = 0;
+ bit isRef = 1;
+}
+</pre></div>
+</div>
+<p>This shows that TableGen was able to dig into the argument and extract a piece
+of information that was requested by the designer of the “Value” class. For
+more realistic examples, please see existing users of TableGen, such as the X86
+backend.</p>
+</div>
+<div class="section" id="multiclass-definitions-and-instances">
+<h4><a class="toc-backref" href="#id14">Multiclass definitions and instances</a><a class="headerlink" href="#multiclass-definitions-and-instances" title="Permalink to this headline">¶</a></h4>
+<p>While classes with template arguments are a good way to factor commonality
+between two instances of a definition, multiclasses allow a convenient notation
+for defining multiple definitions at once (instances of implicitly constructed
+classes). For example, consider an 3-address instruction set whose instructions
+come in two forms: “<tt class="docutils literal"><span class="pre">reg</span> <span class="pre">=</span> <span class="pre">reg</span> <span class="pre">op</span> <span class="pre">reg</span></tt>” and “<tt class="docutils literal"><span class="pre">reg</span> <span class="pre">=</span> <span class="pre">reg</span> <span class="pre">op</span> <span class="pre">imm</span></tt>”
+(e.g. SPARC). In this case, you’d like to specify in one place that this
+commonality exists, then in a separate place indicate what all the ops are.</p>
+<p>Here is an example TableGen fragment that shows this idea:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def ops;
+def GPR;
+def Imm;
+class inst<int opc, string asmstr, dag operandlist>;
+
+multiclass ri_inst<int opc, string asmstr> {
+ def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+ def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+}
+
+// Instantiations of the ri_inst multiclass.
+defm ADD : ri_inst<0b111, "add">;
+defm SUB : ri_inst<0b101, "sub">;
+defm MUL : ri_inst<0b100, "mul">;
+...
+</pre></div>
+</div>
+<p>The name of the resultant definitions has the multidef fragment names appended
+to them, so this defines <tt class="docutils literal"><span class="pre">ADD_rr</span></tt>, <tt class="docutils literal"><span class="pre">ADD_ri</span></tt>, <tt class="docutils literal"><span class="pre">SUB_rr</span></tt>, etc. A defm may
+inherit from multiple multiclasses, instantiating definitions from each
+multiclass. Using a multiclass this way is exactly equivalent to instantiating
+the classes multiple times yourself, e.g. by writing:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def ops;
+def GPR;
+def Imm;
+class inst<int opc, string asmstr, dag operandlist>;
+
+class rrinst<int opc, string asmstr>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+
+class riinst<int opc, string asmstr>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+
+// Instantiations of the ri_inst multiclass.
+def ADD_rr : rrinst<0b111, "add">;
+def ADD_ri : riinst<0b111, "add">;
+def SUB_rr : rrinst<0b101, "sub">;
+def SUB_ri : riinst<0b101, "sub">;
+def MUL_rr : rrinst<0b100, "mul">;
+def MUL_ri : riinst<0b100, "mul">;
+...
+</pre></div>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">defm</span></tt> can also be used inside a multiclass providing several levels of
+multiclass instantiations.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class Instruction<bits<4> opc, string Name> {
+ bits<4> opcode = opc;
+ string name = Name;
+}
+
+multiclass basic_r<bits<4> opc> {
+ def rr : Instruction<opc, "rr">;
+ def rm : Instruction<opc, "rm">;
+}
+
+multiclass basic_s<bits<4> opc> {
+ defm SS : basic_r<opc>;
+ defm SD : basic_r<opc>;
+ def X : Instruction<opc, "x">;
+}
+
+multiclass basic_p<bits<4> opc> {
+ defm PS : basic_r<opc>;
+ defm PD : basic_r<opc>;
+ def Y : Instruction<opc, "y">;
+}
+
+defm ADD : basic_s<0xf>, basic_p<0xf>;
+...
+
+// Results
+def ADDPDrm { ...
+def ADDPDrr { ...
+def ADDPSrm { ...
+def ADDPSrr { ...
+def ADDSDrm { ...
+def ADDSDrr { ...
+def ADDY { ...
+def ADDX { ...
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">defm</span></tt> declarations can inherit from classes too, the rule to follow is that
+the class list must start after the last multiclass, and there must be at least
+one multiclass before them.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class XD { bits<4> Prefix = 11; }
+class XS { bits<4> Prefix = 12; }
+
+class I<bits<4> op> {
+ bits<4> opcode = op;
+}
+
+multiclass R {
+ def rr : I<4>;
+ def rm : I<2>;
+}
+
+multiclass Y {
+ defm SS : R, XD;
+ defm SD : R, XS;
+}
+
+defm Instr : Y;
+
+// Results
+def InstrSDrm {
+ bits<4> opcode = { 0, 0, 1, 0 };
+ bits<4> Prefix = { 1, 1, 0, 0 };
+}
+...
+def InstrSSrr {
+ bits<4> opcode = { 0, 1, 0, 0 };
+ bits<4> Prefix = { 1, 0, 1, 1 };
+}
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="file-scope-entities">
+<h3><a class="toc-backref" href="#id15">File scope entities</a><a class="headerlink" href="#file-scope-entities" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="file-inclusion">
+<h4><a class="toc-backref" href="#id16">File inclusion</a><a class="headerlink" href="#file-inclusion" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports the ‘<tt class="docutils literal"><span class="pre">include</span></tt>‘ token, which textually substitutes the
+specified file in place of the include directive. The filename should be
+specified as a double quoted string immediately after the ‘<tt class="docutils literal"><span class="pre">include</span></tt>‘ keyword.
+Example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>include "foo.td"
+</pre></div>
+</div>
+</div>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id17">‘let’ expressions</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>“Let” expressions at file scope are similar to <a class="reference internal" href="#let-expressions-within-a-record">“let” expressions within a
+record</a>, except they can specify a value binding for multiple records at a
+time, and may be useful in certain other cases. File-scope let expressions are
+really just another way that TableGen allows the end-user to factor out
+commonality from the records.</p>
+<p>File-scope “let” expressions take a comma-separated list of bindings to apply,
+and one or more records to bind the values in. Here are some examples:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
+ def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
+
+let isCall = 1 in
+ // All calls clobber the non-callee saved registers...
+ let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
+ MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
+ XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
+ def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
+ "call\t${dst:call}", []>;
+ def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
+ "call\t{*}$dst", [(X86call GR32:$dst)]>;
+ def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
+ "call\t{*}$dst", []>;
+ }
+</pre></div>
+</div>
+<p>File-scope “let” expressions are often useful when a couple of definitions need
+to be added to several records, and the records do not otherwise need to be
+opened, as in the case with the <tt class="docutils literal"><span class="pre">CALL*</span></tt> instructions above.</p>
+<p>It’s also possible to use “let” expressions inside multiclasses, providing more
+ways to factor out commonality from the records, specially if using several
+levels of multiclass instantiations. This also avoids the need of using “let”
+expressions within subsequent records inside a multiclass.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>multiclass basic_r<bits<4> opc> {
+ let Predicates = [HasSSE2] in {
+ def rr : Instruction<opc, "rr">;
+ def rm : Instruction<opc, "rm">;
+ }
+ let Predicates = [HasSSE3] in
+ def rx : Instruction<opc, "rx">;
+}
+
+multiclass basic_ss<bits<4> opc> {
+ let IsDouble = 0 in
+ defm SS : basic_r<opc>;
+
+ let IsDouble = 1 in
+ defm SD : basic_r<opc>;
+}
+
+defm ADD : basic_ss<0xf>;
+</pre></div>
+</div>
+</div>
+<div class="section" id="looping">
+<h4><a class="toc-backref" href="#id18">Looping</a><a class="headerlink" href="#looping" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports the ‘<tt class="docutils literal"><span class="pre">foreach</span></tt>‘ block, which textually replicates the loop
+body, substituting iterator values for iterator references in the body.
+Example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>foreach i = [0, 1, 2, 3] in {
+ def R#i : Register<...>;
+ def F#i : Register<...>;
+}
+</pre></div>
+</div>
+<p>This will create objects <tt class="docutils literal"><span class="pre">R0</span></tt>, <tt class="docutils literal"><span class="pre">R1</span></tt>, <tt class="docutils literal"><span class="pre">R2</span></tt> and <tt class="docutils literal"><span class="pre">R3</span></tt>. <tt class="docutils literal"><span class="pre">foreach</span></tt> blocks
+may be nested. If there is only one item in the body the braces may be
+elided:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>foreach i = [0, 1, 2, 3] in
+ def R#i : Register<...>;
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="code-generator-backend-info">
+<h2><a class="toc-backref" href="#id19">Code Generator backend info</a><a class="headerlink" href="#code-generator-backend-info" title="Permalink to this headline">¶</a></h2>
+<p>Expressions used by code generator to describe instructions and isel patterns:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">(implicit</span> <span class="pre">a)</span></tt></dt>
+<dd>an implicitly defined physical register. This tells the dag instruction
+selection emitter the input pattern’s extra definitions matches implicit
+physical register definitions.</dd>
+</dl>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Deficiencies.html" title="TableGen Deficiencies"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LangRef.html" title="TableGen Language Reference"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >TableGen</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/TableGen/LangRef.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/TableGen/LangRef.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/TableGen/LangRef.html (added)
+++ www-releases/trunk/3.7.1/docs/TableGen/LangRef.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,447 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Language Reference — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="../index.html" />
+ <link rel="up" title="TableGen" href="index.html" />
+ <link rel="next" title="TableGen Language Introduction" href="LangIntro.html" />
+ <link rel="prev" title="TableGen BackEnds" href="BackEnds.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LangIntro.html" title="TableGen Language Introduction"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="BackEnds.html" title="TableGen BackEnds"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">TableGen</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-language-reference">
+<h1>TableGen Language Reference<a class="headerlink" href="#tablegen-language-reference" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id10">Introduction</a></li>
+<li><a class="reference internal" href="#notation" id="id11">Notation</a></li>
+<li><a class="reference internal" href="#lexical-analysis" id="id12">Lexical Analysis</a></li>
+<li><a class="reference internal" href="#syntax" id="id13">Syntax</a><ul>
+<li><a class="reference internal" href="#classes" id="id14"><tt class="docutils literal"><span class="pre">class</span></tt>es</a></li>
+<li><a class="reference internal" href="#declarations" id="id15">Declarations</a></li>
+<li><a class="reference internal" href="#types" id="id16">Types</a></li>
+<li><a class="reference internal" href="#values" id="id17">Values</a></li>
+<li><a class="reference internal" href="#bodies" id="id18">Bodies</a></li>
+<li><a class="reference internal" href="#def" id="id19"><tt class="docutils literal"><span class="pre">def</span></tt></a></li>
+<li><a class="reference internal" href="#defm" id="id20"><tt class="docutils literal"><span class="pre">defm</span></tt></a></li>
+<li><a class="reference internal" href="#foreach" id="id21"><tt class="docutils literal"><span class="pre">foreach</span></tt></a></li>
+<li><a class="reference internal" href="#top-level-let" id="id22">Top-Level <tt class="docutils literal"><span class="pre">let</span></tt></a></li>
+<li><a class="reference internal" href="#multiclass" id="id23"><tt class="docutils literal"><span class="pre">multiclass</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is extremely rough. If you find something lacking, please
+fix it, file a documentation bug, or ask about it on llvm-dev.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id10">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is meant to be a normative spec about the TableGen language
+in and of itself (i.e. how to understand a given construct in terms of how
+it affects the final set of records represented by the TableGen file). If
+you are unsure if this document is really what you are looking for, please
+read the <a class="reference internal" href="index.html"><em>introduction to TableGen</em></a> first.</p>
+</div>
+<div class="section" id="notation">
+<h2><a class="toc-backref" href="#id11">Notation</a><a class="headerlink" href="#notation" title="Permalink to this headline">¶</a></h2>
+<p>The lexical and syntax notation used here is intended to imitate
+<a class="reference external" href="http://docs.python.org/py3k/reference/introduction.html#notation">Python’s</a>. In particular, for lexical definitions, the productions
+operate at the character level and there is no implied whitespace between
+elements. The syntax definitions operate at the token level, so there is
+implied whitespace between tokens.</p>
+</div>
+<div class="section" id="lexical-analysis">
+<h2><a class="toc-backref" href="#id12">Lexical Analysis</a><a class="headerlink" href="#lexical-analysis" title="Permalink to this headline">¶</a></h2>
+<p>TableGen supports BCPL (<tt class="docutils literal"><span class="pre">//</span> <span class="pre">...</span></tt>) and nestable C-style (<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">...</span> <span class="pre">*/</span></tt>)
+comments.</p>
+<p>The following is a listing of the basic punctuation tokens:</p>
+<div class="highlight-python"><div class="highlight"><pre>- + [ ] { } ( ) < > : ; . = ? #
+</pre></div>
+</div>
+<p>Numeric literals take one of the following forms:</p>
+<pre>
+<strong id="grammar-token-TokInteger">TokInteger </strong> ::= <a class="reference internal" href="#grammar-token-DecimalInteger"><tt class="xref docutils literal"><span class="pre">DecimalInteger</span></tt></a> | <a class="reference internal" href="#grammar-token-HexInteger"><tt class="xref docutils literal"><span class="pre">HexInteger</span></tt></a> | <a class="reference internal" href="#grammar-token-BinInteger"><tt class="xref docutils literal"><span class="pre">BinInteger</span></tt></a>
+<strong id="grammar-token-DecimalInteger">DecimalInteger</strong> ::= ["+" | "-"] ("0"..."9")+
+<strong id="grammar-token-HexInteger">HexInteger </strong> ::= "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
+<strong id="grammar-token-BinInteger">BinInteger </strong> ::= "0b" ("0" | "1")+
+</pre>
+<p>One aspect to note is that the <a class="reference internal" href="#grammar-token-DecimalInteger"><tt class="xref std std-token docutils literal"><span class="pre">DecimalInteger</span></tt></a> token <em>includes</em> the
+<tt class="docutils literal"><span class="pre">+</span></tt> or <tt class="docutils literal"><span class="pre">-</span></tt>, as opposed to having <tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">-</span></tt> be unary operators as
+most languages do.</p>
+<p>Also note that <a class="reference internal" href="#grammar-token-BinInteger"><tt class="xref std std-token docutils literal"><span class="pre">BinInteger</span></tt></a> creates a value of type <tt class="docutils literal"><span class="pre">bits<n></span></tt>
+(where <tt class="docutils literal"><span class="pre">n</span></tt> is the number of bits). This will implicitly convert to
+integers when needed.</p>
+<p>TableGen has identifier-like tokens:</p>
+<pre>
+<strong id="grammar-token-ualpha">ualpha </strong> ::= "a"..."z" | "A"..."Z" | "_"
+<strong id="grammar-token-TokIdentifier">TokIdentifier</strong> ::= ("0"..."9")* <a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> (<a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> | "0"..."9")*
+<strong id="grammar-token-TokVarName">TokVarName </strong> ::= "$" <a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> (<a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> | "0"..."9")*
+</pre>
+<p>Note that unlike most languages, TableGen allows <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref std std-token docutils literal"><span class="pre">TokIdentifier</span></tt></a> to
+begin with a number. In case of ambiguity, a token will be interpreted as a
+numeric literal rather than an identifier.</p>
+<p>TableGen also has two string-like literals:</p>
+<pre>
+<strong id="grammar-token-TokString">TokString </strong> ::= '"' <non-'"' characters and C-like escapes> '"'
+<strong id="grammar-token-TokCodeFragment">TokCodeFragment</strong> ::= "[{" <shortest text not containing "}]"> "}]"
+</pre>
+<p><a class="reference internal" href="#grammar-token-TokCodeFragment"><tt class="xref std std-token docutils literal"><span class="pre">TokCodeFragment</span></tt></a> is essentially a multiline string literal
+delimited by <tt class="docutils literal"><span class="pre">[{</span></tt> and <tt class="docutils literal"><span class="pre">}]</span></tt>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>The current implementation accepts the following C-like escapes:</p>
+<div class="last highlight-python"><div class="highlight"><pre>\\ \' \" \t \n
+</pre></div>
+</div>
+</div>
+<p>TableGen also has the following keywords:</p>
+<div class="highlight-python"><div class="highlight"><pre>bit bits class code dag
+def foreach defm field in
+int let list multiclass string
+</pre></div>
+</div>
+<p>TableGen also has “bang operators” which have a
+wide variety of meanings:</p>
+<pre>
+<strong id="grammar-token-BangOperator">BangOperator</strong> ::= one of
+ !eq !if !head !tail !con
+ !add !shl !sra !srl !and
+ !cast !empty !subst !foreach !listconcat !strconcat
+</pre>
+</div>
+<div class="section" id="syntax">
+<h2><a class="toc-backref" href="#id13">Syntax</a><a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
+<p>TableGen has an <tt class="docutils literal"><span class="pre">include</span></tt> mechanism. It does not play a role in the
+syntax per se, since it is lexically replaced with the contents of the
+included file.</p>
+<pre>
+<strong id="grammar-token-IncludeDirective">IncludeDirective</strong> ::= "include" <a class="reference internal" href="#grammar-token-TokString"><tt class="xref docutils literal"><span class="pre">TokString</span></tt></a>
+</pre>
+<p>TableGen’s top-level production consists of “objects”.</p>
+<pre>
+<strong id="grammar-token-TableGenFile">TableGenFile</strong> ::= <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>*
+<strong id="grammar-token-Object">Object </strong> ::= <a class="reference internal" href="#grammar-token-Class"><tt class="xref docutils literal"><span class="pre">Class</span></tt></a> | <a class="reference internal" href="#grammar-token-Def"><tt class="xref docutils literal"><span class="pre">Def</span></tt></a> | <a class="reference internal" href="#grammar-token-Defm"><tt class="xref docutils literal"><span class="pre">Defm</span></tt></a> | <a class="reference internal" href="#grammar-token-Let"><tt class="xref docutils literal"><span class="pre">Let</span></tt></a> | <a class="reference internal" href="#grammar-token-MultiClass"><tt class="xref docutils literal"><span class="pre">MultiClass</span></tt></a> | <a class="reference internal" href="#grammar-token-Foreach"><tt class="xref docutils literal"><span class="pre">Foreach</span></tt></a>
+</pre>
+<div class="section" id="classes">
+<h3><a class="toc-backref" href="#id14"><tt class="docutils literal"><span class="pre">class</span></tt>es</a><a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Class">Class</strong> ::= "class" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref docutils literal"><span class="pre">TemplateArgList</span></tt></a>] <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref docutils literal"><span class="pre">ObjectBody</span></tt></a>
+</pre>
+<p>A <tt class="docutils literal"><span class="pre">class</span></tt> declaration creates a record which other records can inherit
+from. A class can be parametrized by a list of “template arguments”, whose
+values can be used in the class body.</p>
+<p>A given class can only be defined once. A <tt class="docutils literal"><span class="pre">class</span></tt> declaration is
+considered to define the class if any of the following is true:</p>
+<ol class="arabic simple">
+<li>The <a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref std std-token docutils literal"><span class="pre">TemplateArgList</span></tt></a> is present.</li>
+<li>The <a class="reference internal" href="#grammar-token-Body"><tt class="xref std std-token docutils literal"><span class="pre">Body</span></tt></a> in the <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a> is present and is not empty.</li>
+<li>The <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a> in the <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a> is present.</li>
+</ol>
+<p>You can declare an empty class by giving and empty <a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref std std-token docutils literal"><span class="pre">TemplateArgList</span></tt></a>
+and an empty <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a>. This can serve as a restricted form of
+forward declaration: note that records deriving from the forward-declared
+class will inherit no fields from it since the record expansion is done
+when the record is parsed.</p>
+<pre>
+<strong id="grammar-token-TemplateArgList">TemplateArgList</strong> ::= "<" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> ("," <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a>)* ">"
+</pre>
+</div>
+<div class="section" id="declarations">
+<h3><a class="toc-backref" href="#id15">Declarations</a><a class="headerlink" href="#declarations" title="Permalink to this headline">¶</a></h3>
+<p>The declaration syntax is pretty much what you would expect as a C++
+programmer.</p>
+<pre>
+<strong id="grammar-token-Declaration">Declaration</strong> ::= <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> ["=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>]
+</pre>
+<p>It assigns the value to the identifer.</p>
+</div>
+<div class="section" id="types">
+<h3><a class="toc-backref" href="#id16">Types</a><a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Type">Type </strong> ::= "string" | "code" | "bit" | "int" | "dag"
+ | "bits" "<" <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> ">"
+ | "list" "<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"
+ | <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a>
+<strong id="grammar-token-ClassID">ClassID</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>Both <tt class="docutils literal"><span class="pre">string</span></tt> and <tt class="docutils literal"><span class="pre">code</span></tt> correspond to the string type; the difference
+is purely to indicate programmer intention.</p>
+<p>The <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref std std-token docutils literal"><span class="pre">ClassID</span></tt></a> must identify a class that has been previously
+declared or defined.</p>
+</div>
+<div class="section" id="values">
+<h3><a class="toc-backref" href="#id17">Values</a><a class="headerlink" href="#values" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Value">Value </strong> ::= <a class="reference internal" href="#grammar-token-SimpleValue"><tt class="xref docutils literal"><span class="pre">SimpleValue</span></tt></a> <a class="reference internal" href="#grammar-token-ValueSuffix"><tt class="xref docutils literal"><span class="pre">ValueSuffix</span></tt></a>*
+<strong id="grammar-token-ValueSuffix">ValueSuffix</strong> ::= "{" <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a> "}"
+ | "[" <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a> "]"
+ | "." <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+<strong id="grammar-token-RangeList">RangeList </strong> ::= <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref docutils literal"><span class="pre">RangePiece</span></tt></a> ("," <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref docutils literal"><span class="pre">RangePiece</span></tt></a>)*
+<strong id="grammar-token-RangePiece">RangePiece </strong> ::= <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+ | <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> "-" <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+ | <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+</pre>
+<p>The peculiar last form of <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref std std-token docutils literal"><span class="pre">RangePiece</span></tt></a> is due to the fact that the
+“<tt class="docutils literal"><span class="pre">-</span></tt>” is included in the <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref std std-token docutils literal"><span class="pre">TokInteger</span></tt></a>, hence <tt class="docutils literal"><span class="pre">1-5</span></tt> gets lexed as
+two consecutive <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref std std-token docutils literal"><span class="pre">TokInteger</span></tt></a>‘s, with values <tt class="docutils literal"><span class="pre">1</span></tt> and <tt class="docutils literal"><span class="pre">-5</span></tt>,
+instead of “1”, “-”, and “5”.
+The <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref std std-token docutils literal"><span class="pre">RangeList</span></tt></a> can be thought of as specifying “list slice” in some
+contexts.</p>
+<p><a class="reference internal" href="#grammar-token-SimpleValue"><tt class="xref std std-token docutils literal"><span class="pre">SimpleValue</span></tt></a> has a number of forms:</p>
+<pre>
+<strong id="grammar-token-SimpleValue">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>The value will be the variable referenced by the identifier. It can be one
+of:</p>
+<ul>
+<li><p class="first">name of a <tt class="docutils literal"><span class="pre">def</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>def Bar : SomeClass {
+ int X = 5;
+}
+
+def Foo {
+ SomeClass Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+<li><p class="first">value local to a <tt class="docutils literal"><span class="pre">def</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>def Foo {
+ int Bar = 5;
+ int Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+<li><p class="first">a template arg of a <tt class="docutils literal"><span class="pre">class</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>class Foo<int Bar> {
+ int Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+<li><p class="first">value local to a <tt class="docutils literal"><span class="pre">multiclass</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>multiclass Foo {
+ int Bar = 5;
+ int Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+<li><p class="first">a template arg to a <tt class="docutils literal"><span class="pre">multiclass</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>multiclass Foo<int Bar> {
+ int Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+</ul>
+<pre>
+<strong id="id1">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+</pre>
+<p>This represents the numeric value of the integer.</p>
+<pre>
+<strong id="id2">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokString"><tt class="xref docutils literal"><span class="pre">TokString</span></tt></a>+
+</pre>
+<p>Multiple adjacent string literals are concatenated like in C/C++. The value
+is the concatenation of the strings.</p>
+<pre>
+<strong id="id3">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokCodeFragment"><tt class="xref docutils literal"><span class="pre">TokCodeFragment</span></tt></a>
+</pre>
+<p>The value is the string value of the code fragment.</p>
+<pre>
+<strong id="id4">SimpleValue</strong> ::= "?"
+</pre>
+<p><tt class="docutils literal"><span class="pre">?</span></tt> represents an “unset” initializer.</p>
+<pre>
+<strong id="id5">SimpleValue</strong> ::= "{" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> "}"
+<strong id="grammar-token-ValueList">ValueList </strong> ::= [<a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a>]
+<strong id="grammar-token-ValueListNE">ValueListNE</strong> ::= <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> ("," <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>)*
+</pre>
+<p>This represents a sequence of bits, as would be used to initialize a
+<tt class="docutils literal"><span class="pre">bits<n></span></tt> field (where <tt class="docutils literal"><span class="pre">n</span></tt> is the number of bits).</p>
+<pre>
+<strong id="id6">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a> "<" <a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a> ">"
+</pre>
+<p>This generates a new anonymous record definition (as would be created by an
+unnamed <tt class="docutils literal"><span class="pre">def</span></tt> inheriting from the given class with the given template
+arguments) and the value is the value of that record definition.</p>
+<pre>
+<strong id="id7">SimpleValue</strong> ::= "[" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> "]" ["<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"]
+</pre>
+<p>A list initializer. The optional <a class="reference internal" href="#grammar-token-Type"><tt class="xref std std-token docutils literal"><span class="pre">Type</span></tt></a> can be used to indicate a
+specific element type, otherwise the element type will be deduced from the
+given values.</p>
+<pre>
+<strong id="id8">SimpleValue</strong> ::= "(" <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a> <a class="reference internal" href="#grammar-token-DagArgList"><tt class="xref docutils literal"><span class="pre">DagArgList</span></tt></a> ")"
+<strong id="grammar-token-DagArgList">DagArgList </strong> ::= <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a> ("," <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a>)*
+<strong id="grammar-token-DagArg">DagArg </strong> ::= <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> [":" <a class="reference internal" href="#grammar-token-TokVarName"><tt class="xref docutils literal"><span class="pre">TokVarName</span></tt></a>] | <a class="reference internal" href="#grammar-token-TokVarName"><tt class="xref docutils literal"><span class="pre">TokVarName</span></tt></a>
+</pre>
+<p>The initial <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref std std-token docutils literal"><span class="pre">DagArg</span></tt></a> is called the “operator” of the dag.</p>
+<pre>
+<strong id="id9">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-BangOperator"><tt class="xref docutils literal"><span class="pre">BangOperator</span></tt></a> ["<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"] "(" <a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a> ")"
+</pre>
+</div>
+<div class="section" id="bodies">
+<h3><a class="toc-backref" href="#id18">Bodies</a><a class="headerlink" href="#bodies" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-ObjectBody">ObjectBody </strong> ::= <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref docutils literal"><span class="pre">BaseClassList</span></tt></a> <a class="reference internal" href="#grammar-token-Body"><tt class="xref docutils literal"><span class="pre">Body</span></tt></a>
+<strong id="grammar-token-BaseClassList">BaseClassList </strong> ::= [":" <a class="reference internal" href="#grammar-token-BaseClassListNE"><tt class="xref docutils literal"><span class="pre">BaseClassListNE</span></tt></a>]
+<strong id="grammar-token-BaseClassListNE">BaseClassListNE</strong> ::= <a class="reference internal" href="#grammar-token-SubClassRef"><tt class="xref docutils literal"><span class="pre">SubClassRef</span></tt></a> ("," <a class="reference internal" href="#grammar-token-SubClassRef"><tt class="xref docutils literal"><span class="pre">SubClassRef</span></tt></a>)*
+<strong id="grammar-token-SubClassRef">SubClassRef </strong> ::= (<a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a> | <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a>) ["<" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> ">"]
+<strong id="grammar-token-DefmID">DefmID </strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>The version with the <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref std std-token docutils literal"><span class="pre">MultiClassID</span></tt></a> is only valid in the
+<a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a> of a <tt class="docutils literal"><span class="pre">defm</span></tt>.
+The <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref std std-token docutils literal"><span class="pre">MultiClassID</span></tt></a> should be the name of a <tt class="docutils literal"><span class="pre">multiclass</span></tt>.</p>
+<p>It is after parsing the base class list that the “let stack” is applied.</p>
+<pre>
+<strong id="grammar-token-Body">Body </strong> ::= ";" | "{" BodyList "}"
+<strong id="grammar-token-BodyList">BodyList</strong> ::= BodyItem*
+<strong id="grammar-token-BodyItem">BodyItem</strong> ::= <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> ";"
+ | "let" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a>] "=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> ";"
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">let</span></tt> form allows overriding the value of an inherited field.</p>
+</div>
+<div class="section" id="def">
+<h3><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">def</span></tt></a><a class="headerlink" href="#def" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Def">Def</strong> ::= "def" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref docutils literal"><span class="pre">ObjectBody</span></tt></a>
+</pre>
+<p>Defines a record whose name is given by the <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref std std-token docutils literal"><span class="pre">TokIdentifier</span></tt></a>. The
+fields of the record are inherited from the base classes and defined in the
+body.</p>
+<p>Special handling occurs if this <tt class="docutils literal"><span class="pre">def</span></tt> appears inside a <tt class="docutils literal"><span class="pre">multiclass</span></tt> or
+a <tt class="docutils literal"><span class="pre">foreach</span></tt>.</p>
+</div>
+<div class="section" id="defm">
+<h3><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">defm</span></tt></a><a class="headerlink" href="#defm" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Defm">Defm</strong> ::= "defm" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> ":" <a class="reference internal" href="#grammar-token-BaseClassListNE"><tt class="xref docutils literal"><span class="pre">BaseClassListNE</span></tt></a> ";"
+</pre>
+<p>Note that in the <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a>, all of the <tt class="docutils literal"><span class="pre">multiclass</span></tt>‘s must
+precede any <tt class="docutils literal"><span class="pre">class</span></tt>‘s that appear.</p>
+</div>
+<div class="section" id="foreach">
+<h3><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">foreach</span></tt></a><a class="headerlink" href="#foreach" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Foreach">Foreach</strong> ::= "foreach" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> "in" "{" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>* "}"
+ | "foreach" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> "in" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>
+</pre>
+<p>The value assigned to the variable in the declaration is iterated over and
+the object or object list is reevaluated with the variable set at each
+iterated value.</p>
+</div>
+<div class="section" id="top-level-let">
+<h3><a class="toc-backref" href="#id22">Top-Level <tt class="docutils literal"><span class="pre">let</span></tt></a><a class="headerlink" href="#top-level-let" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Let">Let </strong> ::= "let" <a class="reference internal" href="#grammar-token-LetList"><tt class="xref docutils literal"><span class="pre">LetList</span></tt></a> "in" "{" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>* "}"
+ | "let" <a class="reference internal" href="#grammar-token-LetList"><tt class="xref docutils literal"><span class="pre">LetList</span></tt></a> "in" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>
+<strong id="grammar-token-LetList">LetList</strong> ::= <a class="reference internal" href="#grammar-token-LetItem"><tt class="xref docutils literal"><span class="pre">LetItem</span></tt></a> ("," <a class="reference internal" href="#grammar-token-LetItem"><tt class="xref docutils literal"><span class="pre">LetItem</span></tt></a>)*
+<strong id="grammar-token-LetItem">LetItem</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a>] "=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>
+</pre>
+<p>This is effectively equivalent to <tt class="docutils literal"><span class="pre">let</span></tt> inside the body of a record
+except that it applies to multiple records at a time. The bindings are
+applied at the end of parsing the base classes of a record.</p>
+</div>
+<div class="section" id="multiclass">
+<h3><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">multiclass</span></tt></a><a class="headerlink" href="#multiclass" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-MultiClass">MultiClass </strong> ::= "multiclass" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref docutils literal"><span class="pre">TemplateArgList</span></tt></a>]
+ [":" <a class="reference internal" href="#grammar-token-BaseMultiClassList"><tt class="xref docutils literal"><span class="pre">BaseMultiClassList</span></tt></a>] "{" <a class="reference internal" href="#grammar-token-MultiClassObject"><tt class="xref docutils literal"><span class="pre">MultiClassObject</span></tt></a>+ "}"
+<strong id="grammar-token-BaseMultiClassList">BaseMultiClassList</strong> ::= <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a> ("," <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a>)*
+<strong id="grammar-token-MultiClassID">MultiClassID </strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+<strong id="grammar-token-MultiClassObject">MultiClassObject </strong> ::= <a class="reference internal" href="#grammar-token-Def"><tt class="xref docutils literal"><span class="pre">Def</span></tt></a> | <a class="reference internal" href="#grammar-token-Defm"><tt class="xref docutils literal"><span class="pre">Defm</span></tt></a> | <a class="reference internal" href="#grammar-token-Let"><tt class="xref docutils literal"><span class="pre">Let</span></tt></a> | <a class="reference internal" href="#grammar-token-Foreach"><tt class="xref docutils literal"><span class="pre">Foreach</span></tt></a>
+</pre>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LangIntro.html" title="TableGen Language Introduction"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="BackEnds.html" title="TableGen BackEnds"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >TableGen</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/TableGen/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/TableGen/index.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/TableGen/index.html (added)
+++ www-releases/trunk/3.7.1/docs/TableGen/index.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,365 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="../index.html" />
+ <link rel="next" title="TableGen BackEnds" href="BackEnds.html" />
+ <link rel="prev" title="TableGen Fundamentals" href="../TableGenFundamentals.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="BackEnds.html" title="TableGen BackEnds"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../TableGenFundamentals.html" title="TableGen Fundamentals"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen">
+<h1>TableGen<a class="headerlink" href="#tablegen" 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="id3">Introduction</a></li>
+<li><a class="reference internal" href="#the-tablegen-program" id="id4">The TableGen program</a><ul>
+<li><a class="reference internal" href="#running-tablegen" id="id5">Running TableGen</a></li>
+<li><a class="reference internal" href="#example" id="id6">Example</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#syntax" id="id7">Syntax</a><ul>
+<li><a class="reference internal" href="#basic-concepts" id="id8">Basic concepts</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tablegen-backends" id="id9">TableGen backends</a></li>
+<li><a class="reference internal" href="#tablegen-deficiencies" id="id10">TableGen Deficiencies</a></li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>TableGen’s purpose is to help a human develop and maintain records of
+domain-specific information. Because there may be a large number of these
+records, it is specifically designed to allow writing flexible descriptions and
+for common features of these records to be factored out. This reduces the
+amount of duplication in the description, reduces the chance of error, and makes
+it easier to structure domain specific information.</p>
+<p>The core part of TableGen parses a file, instantiates the declarations, and
+hands the result off to a domain-specific <a class="reference internal" href="#backend">backend</a> for processing.</p>
+<p>The current major users of TableGen are <a class="reference internal" href="../CodeGenerator.html"><em>The LLVM Target-Independent Code Generator</em></a>
+and the
+<a class="reference external" href="http://clang.llvm.org/docs/UsersManual.html#controlling-errors-and-warnings">Clang diagnostics and attributes</a>.</p>
+<p>Note that if you work on TableGen much, and use emacs or vim, that you can find
+an emacs “TableGen mode” and a vim language file in the <tt class="docutils literal"><span class="pre">llvm/utils/emacs</span></tt> and
+<tt class="docutils literal"><span class="pre">llvm/utils/vim</span></tt> directories of your LLVM distribution, respectively.</p>
+</div>
+<div class="section" id="the-tablegen-program">
+<span id="intro"></span><h2><a class="toc-backref" href="#id4">The TableGen program</a><a class="headerlink" href="#the-tablegen-program" title="Permalink to this headline">¶</a></h2>
+<p>TableGen files are interpreted by the TableGen program: <cite>llvm-tblgen</cite> available
+on your build directory under <cite>bin</cite>. It is not installed in the system (or where
+your sysroot is set to), since it has no use beyond LLVM’s build process.</p>
+<div class="section" id="running-tablegen">
+<h3><a class="toc-backref" href="#id5">Running TableGen</a><a class="headerlink" href="#running-tablegen" title="Permalink to this headline">¶</a></h3>
+<p>TableGen runs just like any other LLVM tool. The first (optional) argument
+specifies the file to read. If a filename is not specified, <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt>
+reads from standard input.</p>
+<p>To be useful, one of the <a class="reference internal" href="#backends">backends</a> must be used. These backends are
+selectable on the command line (type ‘<tt class="docutils literal"><span class="pre">llvm-tblgen</span> <span class="pre">-help</span></tt>‘ for a list). For
+example, to get a list of all of the definitions that subclass a particular type
+(which can be useful for building up an enum list of these records), use the
+<tt class="docutils literal"><span class="pre">-print-enums</span></tt> option:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>llvm-tblgen X86.td -print-enums -class<span class="o">=</span>Register
+AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
+ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
+MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
+R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
+R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
+RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
+XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
+XMM6, XMM7, XMM8, XMM9,
+
+<span class="nv">$ </span>llvm-tblgen X86.td -print-enums -class<span class="o">=</span>Instruction
+ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
+ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
+ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
+ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
+ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
+</pre></div>
+</div>
+<p>The default backend prints out all of the records.</p>
+<p>If you plan to use TableGen, you will most likely have to write a <a class="reference internal" href="#backend">backend</a>
+that extracts the information specific to what you need and formats it in the
+appropriate way.</p>
+</div>
+<div class="section" id="example">
+<h3><a class="toc-backref" href="#id6">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>With no other arguments, <cite>llvm-tblgen</cite> parses the specified file and prints out all
+of the classes, then all of the definitions. This is a good way to see what the
+various definitions expand to fully. Running this on the <tt class="docutils literal"><span class="pre">X86.td</span></tt> file prints
+this (at the time of this writing):</p>
+<div class="highlight-llvm"><div class="highlight"><pre>...
+def ADD32rr { // Instruction X86Inst I
+ string Namespace = "X86";
+ dag OutOperandList = (outs GR32:$dst);
+ dag InOperandList = (ins GR32:$src1, GR32:$src2);
+ string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
+ list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
+ list<Register> Uses = [];
+ list<Register> Defs = [EFLAGS];
+ list<Predicate> Predicates = [];
+ int CodeSize = 3;
+ int AddedComplexity = 0;
+ bit isReturn = 0;
+ bit isBranch = 0;
+ bit isIndirectBranch = 0;
+ bit isBarrier = 0;
+ bit isCall = 0;
+ bit canFoldAsLoad = 0;
+ bit mayLoad = 0;
+ bit mayStore = 0;
+ bit isImplicitDef = 0;
+ bit isConvertibleToThreeAddress = 1;
+ bit isCommutable = 1;
+ bit isTerminator = 0;
+ bit isReMaterializable = 0;
+ bit isPredicable = 0;
+ bit hasDelaySlot = 0;
+ bit usesCustomInserter = 0;
+ bit hasCtrlDep = 0;
+ bit isNotDuplicable = 0;
+ bit hasSideEffects = 0;
+ InstrItinClass Itinerary = NoItinerary;
+ string Constraints = "";
+ string DisableEncoding = "";
+ bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
+ Format Form = MRMDestReg;
+ bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
+ ImmType ImmT = NoImm;
+ bits<3> ImmTypeBits = { 0, 0, 0 };
+ bit hasOpSizePrefix = 0;
+ bit hasAdSizePrefix = 0;
+ bits<4> Prefix = { 0, 0, 0, 0 };
+ bit hasREX_WPrefix = 0;
+ FPFormat FPForm = ?;
+ bits<3> FPFormBits = { 0, 0, 0 };
+}
+...
+</pre></div>
+</div>
+<p>This definition corresponds to the 32-bit register-register <tt class="docutils literal"><span class="pre">add</span></tt> instruction
+of the x86 architecture. <tt class="docutils literal"><span class="pre">def</span> <span class="pre">ADD32rr</span></tt> defines a record named
+<tt class="docutils literal"><span class="pre">ADD32rr</span></tt>, and the comment at the end of the line indicates the superclasses
+of the definition. The body of the record contains all of the data that
+TableGen assembled for the record, indicating that the instruction is part of
+the “X86” namespace, the pattern indicating how the instruction is selected by
+the code generator, that it is a two-address instruction, has a particular
+encoding, etc. The contents and semantics of the information in the record are
+specific to the needs of the X86 backend, and are only shown as an example.</p>
+<p>As you can see, a lot of information is needed for every instruction supported
+by the code generator, and specifying it all manually would be unmaintainable,
+prone to bugs, and tiring to do in the first place. Because we are using
+TableGen, all of the information was derived from the following definition:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>let Defs = [EFLAGS],
+ isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
+ isConvertibleToThreeAddress = 1 in // Can transform into LEA.
+def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
+ (ins GR32:$src1, GR32:$src2),
+ "add{l}\t{$src2, $dst|$dst, $src2}",
+ [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
+</pre></div>
+</div>
+<p>This definition makes use of the custom class <tt class="docutils literal"><span class="pre">I</span></tt> (extended from the custom
+class <tt class="docutils literal"><span class="pre">X86Inst</span></tt>), which is defined in the X86-specific TableGen file, to
+factor out the common features that instructions of its class share. A key
+feature of TableGen is that it allows the end-user to define the abstractions
+they prefer to use when describing their information.</p>
+<p>Each <tt class="docutils literal"><span class="pre">def</span></tt> record has a special entry called “NAME”. This is the name of the
+record (“<tt class="docutils literal"><span class="pre">ADD32rr</span></tt>” above). In the general case <tt class="docutils literal"><span class="pre">def</span></tt> names can be formed
+from various kinds of string processing expressions and <tt class="docutils literal"><span class="pre">NAME</span></tt> resolves to the
+final value obtained after resolving all of those expressions. The user may
+refer to <tt class="docutils literal"><span class="pre">NAME</span></tt> anywhere she desires to use the ultimate name of the <tt class="docutils literal"><span class="pre">def</span></tt>.
+<tt class="docutils literal"><span class="pre">NAME</span></tt> should not be defined anywhere else in user code to avoid conflicts.</p>
+</div>
+</div>
+<div class="section" id="syntax">
+<h2><a class="toc-backref" href="#id7">Syntax</a><a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
+<p>TableGen has a syntax that is loosely based on C++ templates, with built-in
+types and specification. In addition, TableGen’s syntax introduces some
+automation concepts like multiclass, foreach, let, etc.</p>
+<div class="section" id="basic-concepts">
+<h3><a class="toc-backref" href="#id8">Basic concepts</a><a class="headerlink" href="#basic-concepts" title="Permalink to this headline">¶</a></h3>
+<p>TableGen files consist of two key parts: ‘classes’ and ‘definitions’, both of
+which are considered ‘records’.</p>
+<p><strong>TableGen records</strong> have a unique name, a list of values, and a list of
+superclasses. The list of values is the main data that TableGen builds for each
+record; it is this that holds the domain specific information for the
+application. The interpretation of this data is left to a specific <a class="reference internal" href="#backend">backend</a>,
+but the structure and format rules are taken care of and are fixed by
+TableGen.</p>
+<p><strong>TableGen definitions</strong> are the concrete form of ‘records’. These generally do
+not have any undefined values, and are marked with the ‘<tt class="docutils literal"><span class="pre">def</span></tt>‘ keyword.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true",
+ "Enable ARMv8 FP">;
+</pre></div>
+</div>
+<p>In this example, FeatureFPARMv8 is <tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> record initialised
+with some values. The names of the classes are defined via the
+keyword <cite>class</cite> either on the same file or some other included. Most target
+TableGen files include the generic ones in <tt class="docutils literal"><span class="pre">include/llvm/Target</span></tt>.</p>
+<p><strong>TableGen classes</strong> are abstract records that are used to build and describe
+other records. These classes allow the end-user to build abstractions for
+either the domain they are targeting (such as “Register”, “RegisterClass”, and
+“Instruction” in the LLVM code generator) or for the implementor to help factor
+out common properties of records (such as “FPInst”, which is used to represent
+floating point instructions in the X86 backend). TableGen keeps track of all of
+the classes that are used to build up a definition, so the backend can find all
+definitions of a particular class, such as “Instruction”.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class ProcNoItin<string Name, list<SubtargetFeature> Features>
+ : Processor<Name, NoItineraries, Features>;
+</pre></div>
+</div>
+<p>Here, the class ProcNoItin, receiving parameters <cite>Name</cite> of type <cite>string</cite> and
+a list of target features is specializing the class Processor by passing the
+arguments down as well as hard-coding NoItineraries.</p>
+<p><strong>TableGen multiclasses</strong> are groups of abstract records that are instantiated
+all at once. Each instantiation can result in multiple TableGen definitions.
+If a multiclass inherits from another multiclass, the definitions in the
+sub-multiclass become part of the current multiclass, as if they were declared
+in the current multiclass.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>multiclass ro_signed_pats<string T, string Rm, dag Base, dag Offset, dag Extend,
+ dag address, ValueType sty> {
+def : Pat<(i32 (!cast<SDNode>("sextload" # sty) address)),
+ (!cast<Instruction>("LDRS" # T # "w_" # Rm # "_RegOffset")
+ Base, Offset, Extend)>;
+
+def : Pat<(i64 (!cast<SDNode>("sextload" # sty) address)),
+ (!cast<Instruction>("LDRS" # T # "x_" # Rm # "_RegOffset")
+ Base, Offset, Extend)>;
+}
+
+defm : ro_signed_pats<"B", Rm, Base, Offset, Extend,
+ !foreach(decls.pattern, address,
+ !subst(SHIFT, imm_eq0, decls.pattern)),
+ i8>;
+</pre></div>
+</div>
+<p>See the <a class="reference internal" href="LangIntro.html"><em>TableGen Language Introduction</em></a> for more generic
+information on the usage of the language, and the
+<a class="reference internal" href="LangRef.html"><em>TableGen Language Reference</em></a> for more in-depth description
+of the formal language specification.</p>
+</div>
+</div>
+<div class="section" id="tablegen-backends">
+<span id="backends"></span><span id="backend"></span><h2><a class="toc-backref" href="#id9">TableGen backends</a><a class="headerlink" href="#tablegen-backends" title="Permalink to this headline">¶</a></h2>
+<p>TableGen files have no real meaning without a back-end. The default operation
+of running <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt> is to print the information in a textual format, but
+that’s only useful for debugging of the TableGen files themselves. The power
+in TableGen is, however, to interpret the source files into an internal
+representation that can be generated into anything you want.</p>
+<p>Current usage of TableGen is to create huge include files with tables that you
+can either include directly (if the output is in the language you’re coding),
+or be used in pre-processing via macros surrounding the include of the file.</p>
+<p>Direct output can be used if the back-end already prints a table in C format
+or if the output is just a list of strings (for error and warning messages).
+Pre-processed output should be used if the same information needs to be used
+in different contexts (like Instruction names), so your back-end should print
+a meta-information list that can be shaped into different compile-time formats.</p>
+<p>See the <a class="reference external" href="BackEnds.html">TableGen BackEnds</a> for more information.</p>
+</div>
+<div class="section" id="tablegen-deficiencies">
+<h2><a class="toc-backref" href="#id10">TableGen Deficiencies</a><a class="headerlink" href="#tablegen-deficiencies" title="Permalink to this headline">¶</a></h2>
+<p>Despite being very generic, TableGen has some deficiencies that have been
+pointed out numerous times. The common theme is that, while TableGen allows
+you to build Domain-Specific-Languages, the final languages that you create
+lack the power of other DSLs, which in turn increase considerably the size
+and complexity of TableGen files.</p>
+<p>At the same time, TableGen allows you to create virtually any meaning of
+the basic concepts via custom-made back-ends, which can pervert the original
+design and make it very hard for newcomers to understand the evil TableGen
+file.</p>
+<p>There are some in favour of extending the semantics even more, but making sure
+back-ends adhere to strict rules. Others are suggesting we should move to less,
+more powerful DSLs designed with specific purposes, or even re-using existing
+DSLs.</p>
+<p>Either way, this is a discussion that will likely span across several years,
+if not decades. You can read more in the <a class="reference external" href="Deficiencies.html">TableGen Deficiencies</a>
+document.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="BackEnds.html" title="TableGen BackEnds"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../TableGenFundamentals.html" title="TableGen Fundamentals"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/TableGenFundamentals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/TableGenFundamentals.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/TableGenFundamentals.html (added)
+++ www-releases/trunk/3.7.1/docs/TableGenFundamentals.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,104 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Fundamentals — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="index.html" />
+ <link rel="next" title="TableGen" href="TableGen/index.html" />
+ <link rel="prev" title="Segmented Stacks in LLVM" href="SegmentedStacks.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="TableGen/index.html" title="TableGen"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SegmentedStacks.html" title="Segmented Stacks in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-fundamentals">
+<h1>TableGen Fundamentals<a class="headerlink" href="#tablegen-fundamentals" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="moved">
+<h2>Moved<a class="headerlink" href="#moved" title="Permalink to this headline">¶</a></h2>
+<p>The TableGen fundamentals documentation has moved to a directory on its own
+and is now available at <a class="reference internal" href="TableGen/index.html"><em>TableGen</em></a>. Please, change your links to
+that page.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="TableGen/index.html" title="TableGen"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SegmentedStacks.html" title="Segmented Stacks in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/TestSuiteMakefileGuide.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/TestSuiteMakefileGuide.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/TestSuiteMakefileGuide.html (added)
+++ www-releases/trunk/3.7.1/docs/TestSuiteMakefileGuide.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,347 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM test-suite Makefile Guide — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="index.html" />
+ <link rel="up" title="LLVM Testing Infrastructure Guide" href="TestingGuide.html" />
+ <link rel="next" title="LLVM Tutorial: Table of Contents" href="tutorial/index.html" />
+ <link rel="prev" title="LLVM Testing Infrastructure Guide" href="TestingGuide.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="tutorial/index.html" title="LLVM Tutorial: Table of Contents"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TestingGuide.html" title="LLVM Testing Infrastructure 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><a href="TestingGuide.html" accesskey="U">LLVM Testing Infrastructure Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-test-suite-makefile-guide">
+<h1>LLVM test-suite Makefile Guide<a class="headerlink" href="#llvm-test-suite-makefile-guide" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
+<li><a class="reference internal" href="#test-suite-structure" id="id2">Test suite Structure</a></li>
+<li><a class="reference internal" href="#running-the-test-suite" id="id3">Running the test suite</a><ul>
+<li><a class="reference internal" href="#configuring-external-tests" id="id4">Configuring External Tests</a></li>
+<li><a class="reference internal" href="#running-different-tests" id="id5">Running different tests</a></li>
+<li><a class="reference internal" href="#generating-test-output" id="id6">Generating test output</a></li>
+<li><a class="reference internal" href="#writing-custom-tests-for-the-test-suite" id="id7">Writing custom tests for the test suite</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id1">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the features of the Makefile-based LLVM
+test-suite. This way of interacting with the test-suite is deprecated in
+favor of running the test-suite using LNT, but may continue to prove
+useful for some users. See the Testing Guide’s <a class="reference internal" href="TestingGuide.html#test-suite-quickstart"><em>test-suite Quickstart</em></a> section for more information.</p>
+</div>
+<div class="section" id="test-suite-structure">
+<h2><a class="toc-backref" href="#id2">Test suite Structure</a><a class="headerlink" href="#test-suite-structure" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">test-suite</span></tt> module contains a number of programs that can be
+compiled with LLVM and executed. These programs are compiled using the
+native compiler and various LLVM backends. The output from the program
+compiled with the native compiler is assumed correct; the results from
+the other programs are compared to the native program output and pass if
+they match.</p>
+<p>When executing tests, it is usually a good idea to start out with a
+subset of the available tests or programs. This makes test run times
+smaller at first and later on this is useful to investigate individual
+test failures. To run some test only on a subset of programs, simply
+change directory to the programs you want tested and run <tt class="docutils literal"><span class="pre">gmake</span></tt>
+there. Alternatively, you can run a different test using the <tt class="docutils literal"><span class="pre">TEST</span></tt>
+variable to change what tests or run on the selected programs (see below
+for more info).</p>
+<p>In addition for testing correctness, the <tt class="docutils literal"><span class="pre">test-suite</span></tt> directory also
+performs timing tests of various LLVM optimizations. It also records
+compilation times for the compilers and the JIT. This information can be
+used to compare the effectiveness of LLVM’s optimizations and code
+generation.</p>
+<p><tt class="docutils literal"><span class="pre">test-suite</span></tt> tests are divided into three types of tests: MultiSource,
+SingleSource, and External.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/SingleSource</span></tt></p>
+<p>The SingleSource directory contains test programs that are only a
+single source file in size. These are usually small benchmark
+programs or small programs that calculate a particular value. Several
+such programs are grouped together in each directory.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/MultiSource</span></tt></p>
+<p>The MultiSource directory contains subdirectories which contain
+entire programs with multiple source files. Large benchmarks and
+whole applications go here.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/External</span></tt></p>
+<p>The External directory contains Makefiles for building code that is
+external to (i.e., not distributed with) LLVM. The most prominent
+members of this directory are the SPEC 95 and SPEC 2000 benchmark
+suites. The <tt class="docutils literal"><span class="pre">External</span></tt> directory does not contain these actual
+tests, but only the Makefiles that know how to properly compile these
+programs from somewhere else. The presence and location of these
+external programs is configured by the test-suite <tt class="docutils literal"><span class="pre">configure</span></tt>
+script.</p>
+</li>
+</ul>
+<p>Each tree is then subdivided into several categories, including
+applications, benchmarks, regression tests, code that is strange
+grammatically, etc. These organizations should be relatively self
+explanatory.</p>
+<p>Some tests are known to fail. Some are bugs that we have not fixed yet;
+others are features that we haven’t added yet (or may never add). In the
+regression tests, the result for such tests will be XFAIL (eXpected
+FAILure). In this way, you can tell the difference between an expected
+and unexpected failure.</p>
+<p>The tests in the test suite have no such feature at this time. If the
+test passes, only warnings and other miscellaneous output will be
+generated. If a test fails, a large <program> FAILED message will be
+displayed. This will help you separate benign warnings from actual test
+failures.</p>
+</div>
+<div class="section" id="running-the-test-suite">
+<h2><a class="toc-backref" href="#id3">Running the test suite</a><a class="headerlink" href="#running-the-test-suite" title="Permalink to this headline">¶</a></h2>
+<p>First, all tests are executed within the LLVM object directory tree.
+They <em>are not</em> executed inside of the LLVM source tree. This is because
+the test suite creates temporary files during execution.</p>
+<p>To run the test suite, you need to use the following steps:</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">cd</span></tt> into the <tt class="docutils literal"><span class="pre">llvm/projects</span></tt> directory in your source tree.</p>
+</li>
+<li><p class="first">Check out the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module with:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% svn co http://llvm.org/svn/llvm-project/test-suite/trunk <span class="nb">test</span>-suite
+</pre></div>
+</div>
+<p>This will get the test suite into <tt class="docutils literal"><span class="pre">llvm/projects/test-suite</span></tt>.</p>
+</li>
+<li><p class="first">Configure and build <tt class="docutils literal"><span class="pre">llvm</span></tt>.</p>
+</li>
+<li><p class="first">Configure and build <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>.</p>
+</li>
+<li><p class="first">Install <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> somewhere.</p>
+</li>
+<li><p class="first"><em>Re-configure</em> <tt class="docutils literal"><span class="pre">llvm</span></tt> from the top level of each build tree (LLVM
+object directory tree) in which you want to run the test suite, just
+as you do before building LLVM.</p>
+<p>During the <em>re-configuration</em>, you must either: (1) have <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>
+you just built in your path, or (2) specify the directory where your
+just-built <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> is installed using
+<tt class="docutils literal"><span class="pre">--with-llvmgccdir=$LLVM_GCC_DIR</span></tt>.</p>
+<p>You must also tell the configure machinery that the test suite is
+available so it can be configured for your build tree:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd</span> <span class="nv">$LLVM_OBJ_ROOT</span> ; <span class="nv">$LLVM_SRC_ROOT</span>/configure <span class="o">[</span>--with-llvmgccdir<span class="o">=</span><span class="nv">$LLVM_GCC_DIR</span><span class="o">]</span>
+</pre></div>
+</div>
+<p>[Remember that <tt class="docutils literal"><span class="pre">$LLVM_GCC_DIR</span></tt> is the directory where you
+<em>installed</em> llvm-gcc, not its src or obj directory.]</p>
+</li>
+<li><p class="first">You can now run the test suite from your build tree as follows:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd</span> <span class="nv">$LLVM_OBJ_ROOT</span>/projects/test-suite
+% make
+</pre></div>
+</div>
+</li>
+</ol>
+<p>Note that the second and third steps only need to be done once. After
+you have the suite checked out and configured, you don’t need to do it
+again (unless the test code or configure script changes).</p>
+<div class="section" id="configuring-external-tests">
+<h3><a class="toc-backref" href="#id4">Configuring External Tests</a><a class="headerlink" href="#configuring-external-tests" title="Permalink to this headline">¶</a></h3>
+<p>In order to run the External tests in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module, you
+must specify <em>–with-externals</em>. This must be done during the
+<em>re-configuration</em> step (see above), and the <tt class="docutils literal"><span class="pre">llvm</span></tt> re-configuration
+must recognize the previously-built <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>. If any of these is
+missing or neglected, the External tests won’t work.</p>
+<ul class="simple">
+<li><em>–with-externals</em></li>
+<li><em>–with-externals=<directory></em></li>
+</ul>
+<p>This tells LLVM where to find any external tests. They are expected to
+be in specifically named subdirectories of <<tt class="docutils literal"><span class="pre">directory</span></tt>>. If
+<tt class="docutils literal"><span class="pre">directory</span></tt> is left unspecified, <tt class="docutils literal"><span class="pre">configure</span></tt> uses the default value
+<tt class="docutils literal"><span class="pre">/home/vadve/shared/benchmarks/speccpu2000/benchspec</span></tt>. Subdirectory
+names known to LLVM include:</p>
+<ul class="simple">
+<li>spec95</li>
+<li>speccpu2000</li>
+<li>speccpu2006</li>
+<li>povray31</li>
+</ul>
+<p>Others are added from time to time, and can be determined from
+<tt class="docutils literal"><span class="pre">configure</span></tt>.</p>
+</div>
+<div class="section" id="running-different-tests">
+<h3><a class="toc-backref" href="#id5">Running different tests</a><a class="headerlink" href="#running-different-tests" title="Permalink to this headline">¶</a></h3>
+<p>In addition to the regular “whole program” tests, the <tt class="docutils literal"><span class="pre">test-suite</span></tt>
+module also provides a mechanism for compiling the programs in different
+ways. If the variable TEST is defined on the <tt class="docutils literal"><span class="pre">gmake</span></tt> command line, the
+test system will include a Makefile named
+<tt class="docutils literal"><span class="pre">TEST.<value</span> <span class="pre">of</span> <span class="pre">TEST</span> <span class="pre">variable>.Makefile</span></tt>. This Makefile can modify
+build rules to yield different results.</p>
+<p>For example, the LLVM nightly tester uses <tt class="docutils literal"><span class="pre">TEST.nightly.Makefile</span></tt> to
+create the nightly test reports. To run the nightly tests, run
+<tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=nightly</span></tt>.</p>
+<p>There are several TEST Makefiles available in the tree. Some of them are
+designed for internal LLVM research and will not work outside of the
+LLVM research group. They may still be valuable, however, as a guide to
+writing your own TEST Makefile for any optimization or analysis passes
+that you develop with LLVM.</p>
+</div>
+<div class="section" id="generating-test-output">
+<h3><a class="toc-backref" href="#id6">Generating test output</a><a class="headerlink" href="#generating-test-output" title="Permalink to this headline">¶</a></h3>
+<p>There are a number of ways to run the tests and generate output. The
+most simple one is simply running <tt class="docutils literal"><span class="pre">gmake</span></tt> with no arguments. This will
+compile and run all programs in the tree using a number of different
+methods and compare results. Any failures are reported in the output,
+but are likely drowned in the other output. Passes are not reported
+explicitly.</p>
+<p>Somewhat better is running <tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=sometest</span> <span class="pre">test</span></tt>, which runs the
+specified test and usually adds per-program summaries to the output
+(depending on which sometest you use). For example, the <tt class="docutils literal"><span class="pre">nightly</span></tt> test
+explicitly outputs TEST-PASS or TEST-FAIL for every test after each
+program. Though these lines are still drowned in the output, it’s easy
+to grep the output logs in the Output directories.</p>
+<p>Even better are the <tt class="docutils literal"><span class="pre">report</span></tt> and <tt class="docutils literal"><span class="pre">report.format</span></tt> targets (where
+<tt class="docutils literal"><span class="pre">format</span></tt> is one of <tt class="docutils literal"><span class="pre">html</span></tt>, <tt class="docutils literal"><span class="pre">csv</span></tt>, <tt class="docutils literal"><span class="pre">text</span></tt> or <tt class="docutils literal"><span class="pre">graphs</span></tt>). The
+exact contents of the report are dependent on which <tt class="docutils literal"><span class="pre">TEST</span></tt> you are
+running, but the text results are always shown at the end of the run and
+the results are always stored in the <tt class="docutils literal"><span class="pre">report.<type>.format</span></tt> file (when
+running with <tt class="docutils literal"><span class="pre">TEST=<type></span></tt>). The <tt class="docutils literal"><span class="pre">report</span></tt> also generate a file
+called <tt class="docutils literal"><span class="pre">report.<type>.raw.out</span></tt> containing the output of the entire
+test run.</p>
+</div>
+<div class="section" id="writing-custom-tests-for-the-test-suite">
+<h3><a class="toc-backref" href="#id7">Writing custom tests for the test suite</a><a class="headerlink" href="#writing-custom-tests-for-the-test-suite" title="Permalink to this headline">¶</a></h3>
+<p>Assuming you can run the test suite, (e.g.
+“<tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=nightly</span> <span class="pre">report</span></tt>” should work), it is really easy to run
+optimizations or code generator components against every program in the
+tree, collecting statistics or running custom checks for correctness. At
+base, this is how the nightly tester works, it’s just one example of a
+general framework.</p>
+<p>Lets say that you have an LLVM optimization pass, and you want to see
+how many times it triggers. First thing you should do is add an LLVM
+<a class="reference external" href="ProgrammersManual.html#Statistic">statistic</a> to your pass, which will
+tally counts of things you care about.</p>
+<p>Following this, you can set up a test and a report that collects these
+and formats them for easy viewing. This consists of two files, a
+“<tt class="docutils literal"><span class="pre">test-suite/TEST.XXX.Makefile</span></tt>” fragment (where XXX is the name of
+your test) and a “<tt class="docutils literal"><span class="pre">test-suite/TEST.XXX.report</span></tt>” file that indicates
+how to format the output into a table. There are many example reports of
+various levels of sophistication included with the test suite, and the
+framework is very general.</p>
+<p>If you are interested in testing an optimization pass, check out the
+“libcalls” test as an example. It can be run like this:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>llvm/projects/test-suite/MultiSource/Benchmarks <span class="c"># or some other level</span>
+% make <span class="nv">TEST</span><span class="o">=</span>libcalls report
+</pre></div>
+</div>
+<p>This will do a bunch of stuff, then eventually print a table like this:</p>
+<div class="highlight-python"><div class="highlight"><pre>Name | total | #exit |
+...
+FreeBench/analyzer/analyzer | 51 | 6 |
+FreeBench/fourinarow/fourinarow | 1 | 1 |
+FreeBench/neural/neural | 19 | 9 |
+FreeBench/pifft/pifft | 5 | 3 |
+MallocBench/cfrac/cfrac | 1 | * |
+MallocBench/espresso/espresso | 52 | 12 |
+MallocBench/gs/gs | 4 | * |
+Prolangs-C/TimberWolfMC/timberwolfmc | 302 | * |
+Prolangs-C/agrep/agrep | 33 | 12 |
+Prolangs-C/allroots/allroots | * | * |
+Prolangs-C/assembler/assembler | 47 | * |
+Prolangs-C/bison/mybison | 74 | * |
+...
+</pre></div>
+</div>
+<p>This basically is grepping the -stats output and displaying it in a
+table. You can also use the “TEST=libcalls report.html” target to get
+the table in HTML form, similarly for report.csv and report.tex.</p>
+<p>The source for this is in <tt class="docutils literal"><span class="pre">test-suite/TEST.libcalls.*</span></tt>. The format is
+pretty simple: the Makefile indicates how to run the test (in this case,
+“<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-simplify-libcalls</span> <span class="pre">-stats</span></tt>”), and the report contains one line
+for each column of the output. The first value is the header for the
+column and the second is the regex to grep the output of the command
+for. There are lots of example reports that can do fancy stuff.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="tutorial/index.html" title="LLVM Tutorial: Table of Contents"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TestingGuide.html" title="LLVM Testing Infrastructure Guide"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ <li><a href="TestingGuide.html" >LLVM Testing Infrastructure Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/TestingGuide.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/TestingGuide.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/TestingGuide.html (added)
+++ www-releases/trunk/3.7.1/docs/TestingGuide.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,623 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Testing Infrastructure Guide — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="index.html" />
+ <link rel="next" title="LLVM test-suite Makefile Guide" href="TestSuiteMakefileGuide.html" />
+ <link rel="prev" title="Code Reviews with Phabricator" href="Phabricator.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="TestSuiteMakefileGuide.html" title="LLVM test-suite Makefile Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Phabricator.html" title="Code Reviews with Phabricator"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-testing-infrastructure-guide">
+<h1>LLVM Testing Infrastructure Guide<a class="headerlink" href="#llvm-testing-infrastructure-guide" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id4">Overview</a></li>
+<li><a class="reference internal" href="#requirements" id="id5">Requirements</a></li>
+<li><a class="reference internal" href="#llvm-testing-infrastructure-organization" id="id6">LLVM testing infrastructure organization</a><ul>
+<li><a class="reference internal" href="#regression-tests" id="id7">Regression tests</a></li>
+<li><a class="reference internal" href="#test-suite" id="id8"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a></li>
+<li><a class="reference internal" href="#debugging-information-tests" id="id9">Debugging Information tests</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#quick-start" id="id10">Quick start</a><ul>
+<li><a class="reference internal" href="#id1" id="id11">Regression tests</a></li>
+<li><a class="reference internal" href="#id2" id="id12">Debugging Information tests</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#regression-test-structure" id="id13">Regression test structure</a><ul>
+<li><a class="reference internal" href="#writing-new-regression-tests" id="id14">Writing new regression tests</a></li>
+<li><a class="reference internal" href="#extra-files" id="id15">Extra files</a></li>
+<li><a class="reference internal" href="#fragile-tests" id="id16">Fragile tests</a></li>
+<li><a class="reference internal" href="#platform-specific-tests" id="id17">Platform-Specific Tests</a></li>
+<li><a class="reference internal" href="#substitutions" id="id18">Substitutions</a></li>
+<li><a class="reference internal" href="#options" id="id19">Options</a></li>
+<li><a class="reference internal" href="#other-features" id="id20">Other Features</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#test-suite-overview" id="id21"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Overview</a><ul>
+<li><a class="reference internal" href="#test-suite-quickstart" id="id22"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Quickstart</a></li>
+<li><a class="reference internal" href="#test-suite-makefiles" id="id23"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefiles</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id4">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>This document is the reference manual for the LLVM testing
+infrastructure. It documents the structure of the LLVM testing
+infrastructure, the tools needed to use it, and how to add and run
+tests.</p>
+</div>
+<div class="section" id="requirements">
+<h2><a class="toc-backref" href="#id5">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
+<p>In order to use the LLVM testing infrastructure, you will need all of the
+software required to build LLVM, as well as <a class="reference external" href="http://python.org">Python</a> 2.7 or
+later.</p>
+</div>
+<div class="section" id="llvm-testing-infrastructure-organization">
+<h2><a class="toc-backref" href="#id6">LLVM testing infrastructure organization</a><a class="headerlink" href="#llvm-testing-infrastructure-organization" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM testing infrastructure contains two major categories of tests:
+regression tests and whole programs. The regression tests are contained
+inside the LLVM repository itself under <tt class="docutils literal"><span class="pre">llvm/test</span></tt> and are expected
+to always pass – they should be run before every commit.</p>
+<p>The whole programs tests are referred to as the “LLVM test suite” (or
+“test-suite”) and are in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module in subversion. For
+historical reasons, these tests are also referred to as the “nightly
+tests” in places, which is less ambiguous than “test-suite” and remains
+in use although we run them much more often than nightly.</p>
+<div class="section" id="regression-tests">
+<h3><a class="toc-backref" href="#id7">Regression tests</a><a class="headerlink" href="#regression-tests" title="Permalink to this headline">¶</a></h3>
+<p>The regression tests are small pieces of code that test a specific
+feature of LLVM or trigger a specific bug in LLVM. The language they are
+written in depends on the part of LLVM being tested. These tests are driven by
+the <a class="reference internal" href="CommandGuide/lit.html"><em>Lit</em></a> testing tool (which is part of LLVM), and
+are located in the <tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory.</p>
+<p>Typically when a bug is found in LLVM, a regression test containing just
+enough code to reproduce the problem should be written and placed
+somewhere underneath this directory. For example, it can be a small
+piece of LLVM IR distilled from an actual application or benchmark.</p>
+</div>
+<div class="section" id="test-suite">
+<h3><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a><a class="headerlink" href="#test-suite" title="Permalink to this headline">¶</a></h3>
+<p>The test suite contains whole programs, which are pieces of code which
+can be compiled and linked into a stand-alone program that can be
+executed. These programs are generally written in high level languages
+such as C or C++.</p>
+<p>These programs are compiled using a user specified compiler and set of
+flags, and then executed to capture the program output and timing
+information. The output of these programs is compared to a reference
+output to ensure that the program is being compiled correctly.</p>
+<p>In addition to compiling and executing programs, whole program tests
+serve as a way of benchmarking LLVM performance, both in terms of the
+efficiency of the programs generated as well as the speed with which
+LLVM compiles, optimizes, and generates code.</p>
+<p>The test-suite is located in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> Subversion module.</p>
+</div>
+<div class="section" id="debugging-information-tests">
+<h3><a class="toc-backref" href="#id9">Debugging Information tests</a><a class="headerlink" href="#debugging-information-tests" title="Permalink to this headline">¶</a></h3>
+<p>The test suite contains tests to check quality of debugging information.
+The test are written in C based languages or in LLVM assembly language.</p>
+<p>These tests are compiled and run under a debugger. The debugger output
+is checked to validate of debugging information. See README.txt in the
+test suite for more information . This test suite is located in the
+<tt class="docutils literal"><span class="pre">debuginfo-tests</span></tt> Subversion module.</p>
+</div>
+</div>
+<div class="section" id="quick-start">
+<h2><a class="toc-backref" href="#id10">Quick start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
+<p>The tests are located in two separate Subversion modules. The
+regressions tests are in the main “llvm” module under the directory
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> (so you get these tests for free with the main LLVM tree).
+Use <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt> to run the regression tests after building LLVM.</p>
+<p>The more comprehensive test suite that includes whole programs in C and C++
+is in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module. See <a class="reference internal" href="#test-suite-quickstart"><em>test-suite Quickstart</em></a> for more information on running these tests.</p>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id11">Regression tests</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>To run all of the LLVM regression tests, use the master Makefile in the
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory. LLVM Makefiles require GNU Make (read the <a class="reference internal" href="MakefileGuide.html"><em>LLVM
+Makefile Guide</em></a> for more details):</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make -C llvm/test
+</pre></div>
+</div>
+<p>or:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check
+</pre></div>
+</div>
+<p>If you have <a class="reference external" href="http://clang.llvm.org/">Clang</a> checked out and built, you
+can run the LLVM and Clang tests simultaneously using:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check-all
+</pre></div>
+</div>
+<p>To run the tests with Valgrind (Memcheck by default), use the <tt class="docutils literal"><span class="pre">LIT_ARGS</span></tt> make
+variable to pass the required options to lit. For example, you can use:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check <span class="nv">LIT_ARGS</span><span class="o">=</span><span class="s2">"-v --vg --vg-leak"</span>
+</pre></div>
+</div>
+<p>to enable testing with valgrind and with leak checking enabled.</p>
+<p>To run individual tests or subsets of tests, you can use the <tt class="docutils literal"><span class="pre">llvm-lit</span></tt>
+script which is built as part of LLVM. For example, to run the
+<tt class="docutils literal"><span class="pre">Integer/BitPacked.ll</span></tt> test by itself you can run:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% llvm-lit ~/llvm/test/Integer/BitPacked.ll
+</pre></div>
+</div>
+<p>or to run all of the ARM CodeGen tests:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% llvm-lit ~/llvm/test/CodeGen/ARM
+</pre></div>
+</div>
+<p>For more information on using the <strong class="program">lit</strong> tool, see <tt class="docutils literal"><span class="pre">llvm-lit</span> <span class="pre">--help</span></tt>
+or the <a class="reference internal" href="CommandGuide/lit.html"><em>lit man page</em></a>.</p>
+</div>
+<div class="section" id="id2">
+<h3><a class="toc-backref" href="#id12">Debugging Information tests</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<p>To run debugging information tests simply checkout the tests inside
+clang/test directory.</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>clang/test
+% svn co http://llvm.org/svn/llvm-project/debuginfo-tests/trunk debuginfo-tests
+</pre></div>
+</div>
+<p>These tests are already set up to run as part of clang regression tests.</p>
+</div>
+</div>
+<div class="section" id="regression-test-structure">
+<h2><a class="toc-backref" href="#id13">Regression test structure</a><a class="headerlink" href="#regression-test-structure" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM regression tests are driven by <strong class="program">lit</strong> and are located in the
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory.</p>
+<p>This directory contains a large array of small tests that exercise
+various features of LLVM and to ensure that regressions do not occur.
+The directory is broken into several sub-directories, each focused on a
+particular area of LLVM.</p>
+<div class="section" id="writing-new-regression-tests">
+<h3><a class="toc-backref" href="#id14">Writing new regression tests</a><a class="headerlink" href="#writing-new-regression-tests" title="Permalink to this headline">¶</a></h3>
+<p>The regression test structure is very simple, but does require some
+information to be set. This information is gathered via <tt class="docutils literal"><span class="pre">configure</span></tt>
+and is written to a file, <tt class="docutils literal"><span class="pre">test/lit.site.cfg</span></tt> in the build directory.
+The <tt class="docutils literal"><span class="pre">llvm/test</span></tt> Makefile does this work for you.</p>
+<p>In order for the regression tests to work, each directory of tests must
+have a <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> file. <strong class="program">lit</strong> looks for this file to determine
+how to run the tests. This file is just Python code and thus is very
+flexible, but we’ve standardized it for the LLVM regression tests. If
+you’re adding a directory of tests, just copy <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> from
+another directory to get running. The standard <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> simply
+specifies which files to look in for tests. Any directory that contains
+only directories does not need the <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> file. Read the <a class="reference internal" href="CommandGuide/lit.html"><em>Lit
+documentation</em></a> for more information.</p>
+<p>Each test file must contain lines starting with “RUN:” that tell <strong class="program">lit</strong>
+how to run it. If there are no RUN lines, <strong class="program">lit</strong> will issue an error
+while running a test.</p>
+<p>RUN lines are specified in the comments of the test program using the
+keyword <tt class="docutils literal"><span class="pre">RUN</span></tt> followed by a colon, and lastly the command (pipeline)
+to execute. Together, these lines form the “script” that <strong class="program">lit</strong>
+executes to run the test case. The syntax of the RUN lines is similar to a
+shell’s syntax for pipelines including I/O redirection and variable
+substitution. However, even though these lines may <em>look</em> like a shell
+script, they are not. RUN lines are interpreted by <strong class="program">lit</strong>.
+Consequently, the syntax differs from shell in a few ways. You can specify
+as many RUN lines as needed.</p>
+<p><strong class="program">lit</strong> performs substitution on each RUN line to replace LLVM tool names
+with the full paths to the executable built for each tool (in
+<tt class="docutils literal"><span class="pre">$(LLVM_OBJ_ROOT)/$(BuildMode)/bin)</span></tt>. This ensures that <strong class="program">lit</strong> does
+not invoke any stray LLVM tools in the user’s path during testing.</p>
+<p>Each RUN line is executed on its own, distinct from other lines unless
+its last character is <tt class="docutils literal"><span class="pre">\</span></tt>. This continuation character causes the RUN
+line to be concatenated with the next one. In this way you can build up
+long pipelines of commands without making huge line lengths. The lines
+ending in <tt class="docutils literal"><span class="pre">\</span></tt> are concatenated until a RUN line that doesn’t end in
+<tt class="docutils literal"><span class="pre">\</span></tt> is found. This concatenated set of RUN lines then constitutes one
+execution. <strong class="program">lit</strong> will substitute variables and arrange for the pipeline
+to be executed. If any process in the pipeline fails, the entire line (and
+test case) fails too.</p>
+<p>Below is an example of legal RUN lines in a <tt class="docutils literal"><span class="pre">.ll</span></tt> file:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: llvm-as < %s | llvm-dis > %t1</span>
+<span class="c">; RUN: llvm-dis < %s.bc-13 > %t2</span>
+<span class="c">; RUN: diff %t1 %t2</span>
+</pre></div>
+</div>
+<p>As with a Unix shell, the RUN lines permit pipelines and I/O
+redirection to be used.</p>
+<p>There are some quoting rules that you must pay attention to when writing
+your RUN lines. In general nothing needs to be quoted. <strong class="program">lit</strong> won’t
+strip off any quote characters so they will get passed to the invoked program.
+To avoid this use curly braces to tell <strong class="program">lit</strong> that it should treat
+everything enclosed as one value.</p>
+<p>In general, you should strive to keep your RUN lines as simple as possible,
+using them only to run tools that generate textual output you can then examine.
+The recommended way to examine output to figure out if the test passes is using
+the <a class="reference internal" href="CommandGuide/FileCheck.html"><em>FileCheck tool</em></a>. <em>[The usage of grep in RUN
+lines is deprecated - please do not send or commit patches that use it.]</em></p>
+</div>
+<div class="section" id="extra-files">
+<h3><a class="toc-backref" href="#id15">Extra files</a><a class="headerlink" href="#extra-files" title="Permalink to this headline">¶</a></h3>
+<p>If your test requires extra files besides the file containing the <tt class="docutils literal"><span class="pre">RUN:</span></tt>
+lines, the idiomatic place to put them is in a subdirectory <tt class="docutils literal"><span class="pre">Inputs</span></tt>.
+You can then refer to the extra files as <tt class="docutils literal"><span class="pre">%S/Inputs/foo.bar</span></tt>.</p>
+<p>For example, consider <tt class="docutils literal"><span class="pre">test/Linker/ident.ll</span></tt>. The directory structure is
+as follows:</p>
+<div class="highlight-python"><div class="highlight"><pre>test/
+ Linker/
+ ident.ll
+ Inputs/
+ ident.a.ll
+ ident.b.ll
+</pre></div>
+</div>
+<p>For convenience, these are the contents:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">;;;;; ident.ll:</span>
+
+<span class="c">; RUN: llvm-link %S/Inputs/ident.a.ll %S/Inputs/ident.b.ll -S | FileCheck %s</span>
+
+<span class="c">; Verify that multiple input llvm.ident metadata are linked together.</span>
+
+<span class="c">; CHECK-DAG: !llvm.ident = !{!0, !1, !2}</span>
+<span class="c">; CHECK-DAG: "Compiler V1"</span>
+<span class="c">; CHECK-DAG: "Compiler V2"</span>
+<span class="c">; CHECK-DAG: "Compiler V3"</span>
+
+<span class="c">;;;;; Inputs/ident.a.ll:</span>
+
+<span class="nv">!llvm.ident</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">,</span> <span class="nv-Anonymous">!1</span><span class="p">}</span>
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv">!"Compiler V1"</span><span class="p">}</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv">!"Compiler V2"</span><span class="p">}</span>
+
+<span class="c">;;;;; Inputs/ident.b.ll:</span>
+
+<span class="nv">!llvm.ident</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv">!"Compiler V3"</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>For symmetry reasons, <tt class="docutils literal"><span class="pre">ident.ll</span></tt> is just a dummy file that doesn’t
+actually participate in the test besides holding the <tt class="docutils literal"><span class="pre">RUN:</span></tt> lines.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Some existing tests use <tt class="docutils literal"><span class="pre">RUN:</span> <span class="pre">true</span></tt> in extra files instead of just
+putting the extra files in an <tt class="docutils literal"><span class="pre">Inputs/</span></tt> directory. This pattern is
+deprecated.</p>
+</div>
+</div>
+<div class="section" id="fragile-tests">
+<h3><a class="toc-backref" href="#id16">Fragile tests</a><a class="headerlink" href="#fragile-tests" title="Permalink to this headline">¶</a></h3>
+<p>It is easy to write a fragile test that would fail spuriously if the tool being
+tested outputs a full path to the input file. For example, <strong class="program">opt</strong> by
+default outputs a <tt class="docutils literal"><span class="pre">ModuleID</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat example.ll
+<span class="go">define i32 @main() nounwind {</span>
+<span class="go"> ret i32 0</span>
+<span class="go">}</span>
+
+<span class="gp">$</span> opt -S /path/to/example.ll
+<span class="go">; ModuleID = '/path/to/example.ll'</span>
+
+<span class="go">define i32 @main() nounwind {</span>
+<span class="go"> ret i32 0</span>
+<span class="go">}</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">ModuleID</span></tt> can unexpetedly match against <tt class="docutils literal"><span class="pre">CHECK</span></tt> lines. For example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: opt -S %s | FileCheck</span>
+
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="k">nounwind</span> <span class="p">{</span>
+ <span class="c">; CHECK-NOT: load</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This test will fail if placed into a <tt class="docutils literal"><span class="pre">download</span></tt> directory.</p>
+<p>To make your tests robust, always use <tt class="docutils literal"><span class="pre">opt</span> <span class="pre">...</span> <span class="pre"><</span> <span class="pre">%s</span></tt> in the RUN line.
+<strong class="program">opt</strong> does not output a <tt class="docutils literal"><span class="pre">ModuleID</span></tt> when input comes from stdin.</p>
+</div>
+<div class="section" id="platform-specific-tests">
+<h3><a class="toc-backref" href="#id17">Platform-Specific Tests</a><a class="headerlink" href="#platform-specific-tests" title="Permalink to this headline">¶</a></h3>
+<p>Whenever adding tests that require the knowledge of a specific platform,
+either related to code generated, specific output or back-end features,
+you must make sure to isolate the features, so that buildbots that
+run on different architectures (and don’t even compile all back-ends),
+don’t fail.</p>
+<p>The first problem is to check for target-specific output, for example sizes
+of structures, paths and architecture names, for example:</p>
+<ul class="simple">
+<li>Tests containing Windows paths will fail on Linux and vice-versa.</li>
+<li>Tests that check for <tt class="docutils literal"><span class="pre">x86_64</span></tt> somewhere in the text will fail anywhere else.</li>
+<li>Tests where the debug information calculates the size of types and structures.</li>
+</ul>
+<p>Also, if the test rely on any behaviour that is coded in any back-end, it must
+go in its own directory. So, for instance, code generator tests for ARM go
+into <tt class="docutils literal"><span class="pre">test/CodeGen/ARM</span></tt> and so on. Those directories contain a special
+<tt class="docutils literal"><span class="pre">lit</span></tt> configuration file that ensure all tests in that directory will
+only run if a specific back-end is compiled and available.</p>
+<p>For instance, on <tt class="docutils literal"><span class="pre">test/CodeGen/ARM</span></tt>, the <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> is:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">config</span><span class="o">.</span><span class="n">suffixes</span> <span class="o">=</span> <span class="p">[</span><span class="s">'.ll'</span><span class="p">,</span> <span class="s">'.c'</span><span class="p">,</span> <span class="s">'.cpp'</span><span class="p">,</span> <span class="s">'.test'</span><span class="p">]</span>
+<span class="k">if</span> <span class="ow">not</span> <span class="s">'ARM'</span> <span class="ow">in</span> <span class="n">config</span><span class="o">.</span><span class="n">root</span><span class="o">.</span><span class="n">targets</span><span class="p">:</span>
+ <span class="n">config</span><span class="o">.</span><span class="n">unsupported</span> <span class="o">=</span> <span class="bp">True</span>
+</pre></div>
+</div>
+<p>Other platform-specific tests are those that depend on a specific feature
+of a specific sub-architecture, for example only to Intel chips that support <tt class="docutils literal"><span class="pre">AVX2</span></tt>.</p>
+<p>For instance, <tt class="docutils literal"><span class="pre">test/CodeGen/X86/psubus.ll</span></tt> tests three sub-architecture
+variants:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: llc -mcpu=core2 < %s | FileCheck %s -check-prefix=SSE2</span>
+<span class="c">; RUN: llc -mcpu=corei7-avx < %s | FileCheck %s -check-prefix=AVX1</span>
+<span class="c">; RUN: llc -mcpu=core-avx2 < %s | FileCheck %s -check-prefix=AVX2</span>
+</pre></div>
+</div>
+<p>And the checks are different:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; SSE2: @test1</span>
+<span class="c">; SSE2: psubusw LCPI0_0(%rip), %xmm0</span>
+<span class="c">; AVX1: @test1</span>
+<span class="c">; AVX1: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0</span>
+<span class="c">; AVX2: @test1</span>
+<span class="c">; AVX2: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0</span>
+</pre></div>
+</div>
+<p>So, if you’re testing for a behaviour that you know is platform-specific or
+depends on special features of sub-architectures, you must add the specific
+triple, test with the specific FileCheck and put it into the specific
+directory that will filter out all other architectures.</p>
+</div>
+<div class="section" id="substitutions">
+<h3><a class="toc-backref" href="#id18">Substitutions</a><a class="headerlink" href="#substitutions" title="Permalink to this headline">¶</a></h3>
+<p>Besides replacing LLVM tool names the following substitutions are performed in
+RUN lines:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">%%</span></tt></dt>
+<dd>Replaced by a single <tt class="docutils literal"><span class="pre">%</span></tt>. This allows escaping other substitutions.</dd>
+<dt><tt class="docutils literal"><span class="pre">%s</span></tt></dt>
+<dd><p class="first">File path to the test case’s source. This is suitable for passing on the
+command line as the input to an LLVM tool.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">/home/user/llvm/test/MC/ELF/foo_test.s</span></tt></p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%S</span></tt></dt>
+<dd><p class="first">Directory path to the test case’s source.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">/home/user/llvm/test/MC/ELF</span></tt></p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%t</span></tt></dt>
+<dd><p class="first">File path to a temporary file name that could be used for this test case.
+The file name won’t conflict with other test cases. You can append to it
+if you need multiple temporaries. This is useful as the destination of
+some redirected output.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">/home/user/llvm.build/test/MC/ELF/Output/foo_test.s.tmp</span></tt></p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%T</span></tt></dt>
+<dd><p class="first">Directory of <tt class="docutils literal"><span class="pre">%t</span></tt>.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">/home/user/llvm.build/test/MC/ELF/Output</span></tt></p>
+</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">%{pathsep}</span></tt></p>
+<blockquote>
+<div>Expands to the path separator, i.e. <tt class="docutils literal"><span class="pre">:</span></tt> (or <tt class="docutils literal"><span class="pre">;</span></tt> on Windows).</div></blockquote>
+<p><strong>LLVM-specific substitutions:</strong></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">%shlibext</span></tt></dt>
+<dd><p class="first">The suffix for the host platforms shared library files. This includes the
+period as the first character.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">.so</span></tt> (Linux), <tt class="docutils literal"><span class="pre">.dylib</span></tt> (OS X), <tt class="docutils literal"><span class="pre">.dll</span></tt> (Windows)</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%exeext</span></tt></dt>
+<dd><p class="first">The suffix for the host platforms executable files. This includes the
+period as the first character.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">.exe</span></tt> (Windows), empty on Linux.</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%(line)</span></tt>, <tt class="docutils literal"><span class="pre">%(line+<number>)</span></tt>, <tt class="docutils literal"><span class="pre">%(line-<number>)</span></tt></dt>
+<dd>The number of the line where this substitution is used, with an optional
+integer offset. This can be used in tests with multiple RUN lines, which
+reference test file’s line numbers.</dd>
+</dl>
+<p><strong>Clang-specific substitutions:</strong></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">%clang</span></tt></dt>
+<dd>Invokes the Clang driver.</dd>
+<dt><tt class="docutils literal"><span class="pre">%clang_cpp</span></tt></dt>
+<dd>Invokes the Clang driver for C++.</dd>
+<dt><tt class="docutils literal"><span class="pre">%clang_cl</span></tt></dt>
+<dd>Invokes the CL-compatible Clang driver.</dd>
+<dt><tt class="docutils literal"><span class="pre">%clangxx</span></tt></dt>
+<dd>Invokes the G++-compatible Clang driver.</dd>
+<dt><tt class="docutils literal"><span class="pre">%clang_cc1</span></tt></dt>
+<dd>Invokes the Clang frontend.</dd>
+<dt><tt class="docutils literal"><span class="pre">%itanium_abi_triple</span></tt>, <tt class="docutils literal"><span class="pre">%ms_abi_triple</span></tt></dt>
+<dd>These substitutions can be used to get the current target triple adjusted to
+the desired ABI. For example, if the test suite is running with the
+<tt class="docutils literal"><span class="pre">i686-pc-win32</span></tt> target, <tt class="docutils literal"><span class="pre">%itanium_abi_triple</span></tt> will expand to
+<tt class="docutils literal"><span class="pre">i686-pc-mingw32</span></tt>. This allows a test to run with a specific ABI without
+constraining it to a specific triple.</dd>
+</dl>
+<p>To add more substituations, look at <tt class="docutils literal"><span class="pre">test/lit.cfg</span></tt> or <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt>.</p>
+</div>
+<div class="section" id="options">
+<h3><a class="toc-backref" href="#id19">Options</a><a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
+<p>The llvm lit configuration allows to customize some things with user options:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">llc</span></tt>, <tt class="docutils literal"><span class="pre">opt</span></tt>, ...</dt>
+<dd><p class="first">Substitute the respective llvm tool name with a custom command line. This
+allows to specify custom paths and default arguments for these tools.
+Example:</p>
+<p class="last">% llvm-lit “-Dllc=llc -verify-machineinstrs”</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">run_long_tests</span></tt></dt>
+<dd>Enable the execution of long running tests.</dd>
+<dt><tt class="docutils literal"><span class="pre">llvm_site_config</span></tt></dt>
+<dd>Load the specified lit configuration instead of the default one.</dd>
+</dl>
+</div>
+<div class="section" id="other-features">
+<h3><a class="toc-backref" href="#id20">Other Features</a><a class="headerlink" href="#other-features" title="Permalink to this headline">¶</a></h3>
+<p>To make RUN line writing easier, there are several helper programs. These
+helpers are in the PATH when running tests, so you can just call them using
+their name. For example:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">not</span></tt></dt>
+<dd>This program runs its arguments and then inverts the result code from it.
+Zero result codes become 1. Non-zero result codes become 0.</dd>
+</dl>
+<p>Sometimes it is necessary to mark a test case as “expected fail” or
+XFAIL. You can easily mark a test as XFAIL just by including <tt class="docutils literal"><span class="pre">XFAIL:</span></tt>
+on a line near the top of the file. This signals that the test case
+should succeed if the test fails. Such test cases are counted separately
+by the testing tool. To specify an expected fail, use the XFAIL keyword
+in the comments of the test program followed by a colon and one or more
+failure patterns. Each failure pattern can be either <tt class="docutils literal"><span class="pre">*</span></tt> (to specify
+fail everywhere), or a part of a target triple (indicating the test
+should fail on that platform), or the name of a configurable feature
+(for example, <tt class="docutils literal"><span class="pre">loadable_module</span></tt>). If there is a match, the test is
+expected to fail. If not, the test is expected to succeed. To XFAIL
+everywhere just specify <tt class="docutils literal"><span class="pre">XFAIL:</span> <span class="pre">*</span></tt>. Here is an example of an <tt class="docutils literal"><span class="pre">XFAIL</span></tt>
+line:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; XFAIL: darwin,sun</span>
+</pre></div>
+</div>
+<p>To make the output more useful, <strong class="program">lit</strong> will scan
+the lines of the test case for ones that contain a pattern that matches
+<tt class="docutils literal"><span class="pre">PR[0-9]+</span></tt>. This is the syntax for specifying a PR (Problem Report) number
+that is related to the test case. The number after “PR” specifies the
+LLVM bugzilla number. When a PR number is specified, it will be used in
+the pass/fail reporting. This is useful to quickly get some context when
+a test fails.</p>
+<p>Finally, any line that contains “END.” will cause the special
+interpretation of lines to terminate. This is generally done right after
+the last RUN: line. This has two side effects:</p>
+<ol class="loweralpha simple">
+<li>it prevents special interpretation of lines that are part of the test
+program, not the instructions to the test case, and</li>
+<li>it speeds things up for really big test cases by avoiding
+interpretation of the remainder of the file.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="test-suite-overview">
+<h2><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Overview</a><a class="headerlink" href="#test-suite-overview" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">test-suite</span></tt> module contains a number of programs that can be
+compiled and executed. The <tt class="docutils literal"><span class="pre">test-suite</span></tt> includes reference outputs for
+all of the programs, so that the output of the executed program can be
+checked for correctness.</p>
+<p><tt class="docutils literal"><span class="pre">test-suite</span></tt> tests are divided into three types of tests: MultiSource,
+SingleSource, and External.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/SingleSource</span></tt></p>
+<p>The SingleSource directory contains test programs that are only a
+single source file in size. These are usually small benchmark
+programs or small programs that calculate a particular value. Several
+such programs are grouped together in each directory.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/MultiSource</span></tt></p>
+<p>The MultiSource directory contains subdirectories which contain
+entire programs with multiple source files. Large benchmarks and
+whole applications go here.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/External</span></tt></p>
+<p>The External directory contains Makefiles for building code that is
+external to (i.e., not distributed with) LLVM. The most prominent
+members of this directory are the SPEC 95 and SPEC 2000 benchmark
+suites. The <tt class="docutils literal"><span class="pre">External</span></tt> directory does not contain these actual
+tests, but only the Makefiles that know how to properly compile these
+programs from somewhere else. When using <tt class="docutils literal"><span class="pre">LNT</span></tt>, use the
+<tt class="docutils literal"><span class="pre">--test-externals</span></tt> option to include these tests in the results.</p>
+</li>
+</ul>
+<div class="section" id="test-suite-quickstart">
+<span id="id3"></span><h3><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Quickstart</a><a class="headerlink" href="#test-suite-quickstart" title="Permalink to this headline">¶</a></h3>
+<p>The modern way of running the <tt class="docutils literal"><span class="pre">test-suite</span></tt> is focused on testing and
+benchmarking complete compilers using the
+<a class="reference external" href="http://llvm.org/docs/lnt">LNT</a> testing infrastructure.</p>
+<p>For more information on using LNT to execute the <tt class="docutils literal"><span class="pre">test-suite</span></tt>, please
+see the <a class="reference external" href="http://llvm.org/docs/lnt/quickstart.html">LNT Quickstart</a>
+documentation.</p>
+</div>
+<div class="section" id="test-suite-makefiles">
+<h3><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefiles</a><a class="headerlink" href="#test-suite-makefiles" title="Permalink to this headline">¶</a></h3>
+<p>Historically, the <tt class="docutils literal"><span class="pre">test-suite</span></tt> was executed using a complicated setup
+of Makefiles. The LNT based approach above is recommended for most
+users, but there are some testing scenarios which are not supported by
+the LNT approach. In addition, LNT currently uses the Makefile setup
+under the covers and so developers who are interested in how LNT works
+under the hood may want to understand the Makefile based setup.</p>
+<p>For more information on the <tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefile setup, please see
+the <a class="reference internal" href="TestSuiteMakefileGuide.html"><em>Test Suite Makefile Guide</em></a>.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="TestSuiteMakefileGuide.html" title="LLVM test-suite Makefile Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Phabricator.html" title="Code Reviews with Phabricator"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/Vectorizers.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/Vectorizers.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/Vectorizers.html (added)
+++ www-releases/trunk/3.7.1/docs/Vectorizers.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,491 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Auto-Vectorization in LLVM — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="index.html" />
+ <link rel="next" title="Writing an LLVM Backend" href="WritingAnLLVMBackend.html" />
+ <link rel="prev" title="Source Level Debugging with LLVM" href="SourceLevelDebugging.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="auto-vectorization-in-llvm">
+<h1>Auto-Vectorization in LLVM<a class="headerlink" href="#auto-vectorization-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="#the-loop-vectorizer" id="id2">The Loop Vectorizer</a><ul>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a><ul>
+<li><a class="reference internal" href="#command-line-flags" id="id4">Command line flags</a></li>
+<li><a class="reference internal" href="#pragma-loop-hint-directives" id="id5">Pragma loop hint directives</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#diagnostics" id="id6">Diagnostics</a></li>
+<li><a class="reference internal" href="#features" id="id7">Features</a><ul>
+<li><a class="reference internal" href="#loops-with-unknown-trip-count" id="id8">Loops with unknown trip count</a></li>
+<li><a class="reference internal" href="#runtime-checks-of-pointers" id="id9">Runtime Checks of Pointers</a></li>
+<li><a class="reference internal" href="#reductions" id="id10">Reductions</a></li>
+<li><a class="reference internal" href="#inductions" id="id11">Inductions</a></li>
+<li><a class="reference internal" href="#if-conversion" id="id12">If Conversion</a></li>
+<li><a class="reference internal" href="#pointer-induction-variables" id="id13">Pointer Induction Variables</a></li>
+<li><a class="reference internal" href="#reverse-iterators" id="id14">Reverse Iterators</a></li>
+<li><a class="reference internal" href="#scatter-gather" id="id15">Scatter / Gather</a></li>
+<li><a class="reference internal" href="#vectorization-of-mixed-types" id="id16">Vectorization of Mixed Types</a></li>
+<li><a class="reference internal" href="#global-structures-alias-analysis" id="id17">Global Structures Alias Analysis</a></li>
+<li><a class="reference internal" href="#vectorization-of-function-calls" id="id18">Vectorization of function calls</a></li>
+<li><a class="reference internal" href="#partial-unrolling-during-vectorization" id="id19">Partial unrolling during vectorization</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#performance" id="id20">Performance</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-slp-vectorizer" id="id21">The SLP Vectorizer</a><ul>
+<li><a class="reference internal" href="#details" id="id22">Details</a></li>
+<li><a class="reference internal" href="#id1" id="id23">Usage</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<p>LLVM has two vectorizers: The <a class="reference internal" href="#loop-vectorizer"><em>Loop Vectorizer</em></a>,
+which operates on Loops, and the <a class="reference internal" href="#slp-vectorizer"><em>SLP Vectorizer</em></a>. These vectorizers
+focus on different optimization opportunities and use different techniques.
+The SLP vectorizer merges multiple scalars that are found in the code into
+vectors while the Loop Vectorizer widens instructions in loops
+to operate on multiple consecutive iterations.</p>
+<p>Both the Loop Vectorizer and the SLP Vectorizer are enabled by default.</p>
+<div class="section" id="the-loop-vectorizer">
+<span id="loop-vectorizer"></span><h2><a class="toc-backref" href="#id2">The Loop Vectorizer</a><a class="headerlink" href="#the-loop-vectorizer" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="usage">
+<h3><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h3>
+<p>The Loop Vectorizer is enabled by default, but it can be disabled
+through clang using the command line flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang ... -fno-vectorize file.c
+</pre></div>
+</div>
+<div class="section" id="command-line-flags">
+<h4><a class="toc-backref" href="#id4">Command line flags</a><a class="headerlink" href="#command-line-flags" title="Permalink to this headline">¶</a></h4>
+<p>The loop vectorizer uses a cost model to decide on the optimal vectorization factor
+and unroll factor. However, users of the vectorizer can force the vectorizer to use
+specific values. Both ‘clang’ and ‘opt’ support the flags below.</p>
+<p>Users can control the vectorization SIMD width using the command line flag “-force-vector-width”.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -mllvm -force-vector-width<span class="o">=</span>8 ...
+<span class="gp">$</span> opt -loop-vectorize -force-vector-width<span class="o">=</span>8 ...
+</pre></div>
+</div>
+<p>Users can control the unroll factor using the command line flag “-force-vector-unroll”</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -mllvm -force-vector-unroll<span class="o">=</span>2 ...
+<span class="gp">$</span> opt -loop-vectorize -force-vector-unroll<span class="o">=</span>2 ...
+</pre></div>
+</div>
+</div>
+<div class="section" id="pragma-loop-hint-directives">
+<h4><a class="toc-backref" href="#id5">Pragma loop hint directives</a><a class="headerlink" href="#pragma-loop-hint-directives" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span></tt> directive allows loop vectorization hints to be
+specified for the subsequent for, while, do-while, or c++11 range-based for
+loop. The directive allows vectorization and interleaving to be enabled or
+disabled. Vector width as well as interleave count can also be manually
+specified. The following example explicitly enables vectorization and
+interleaving:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma clang loop vectorize(enable) interleave(enable)</span>
+<span class="k">while</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The following example implicitly enables vectorization and interleaving by
+specifying a vector width and interleaving count:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma clang loop vectorize_width(2) interleave_count(2)</span>
+<span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>See the Clang
+<a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations">language extensions</a>
+for details.</p>
+</div>
+</div>
+<div class="section" id="diagnostics">
+<h3><a class="toc-backref" href="#id6">Diagnostics</a><a class="headerlink" href="#diagnostics" title="Permalink to this headline">¶</a></h3>
+<p>Many loops cannot be vectorized including loops with complicated control flow,
+unvectorizable types, and unvectorizable calls. The loop vectorizer generates
+optimization remarks which can be queried using command line options to identify
+and diagnose loops that are skipped by the loop-vectorizer.</p>
+<p>Optimization remarks are enabled using:</p>
+<p><tt class="docutils literal"><span class="pre">-Rpass=loop-vectorize</span></tt> identifies loops that were successfully vectorized.</p>
+<p><tt class="docutils literal"><span class="pre">-Rpass-missed=loop-vectorize</span></tt> identifies loops that failed vectorization and
+indicates if vectorization was specified.</p>
+<p><tt class="docutils literal"><span class="pre">-Rpass-analysis=loop-vectorize</span></tt> identifies the statements that caused
+vectorization to fail.</p>
+<p>Consider the following loop:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma clang loop vectorize(enable)</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">Length</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">switch</span><span class="p">(</span><span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">])</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="mi">0</span>: <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="o">*</span><span class="mi">2</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="mi">1</span>: <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="nl">default:</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The command line <tt class="docutils literal"><span class="pre">-Rpass-missed=loop-vectorized</span></tt> prints the remark:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">no_switch.cpp:4:5: remark: loop not vectorized: vectorization is explicitly enabled [-Rpass-missed=loop-vectorize]</span>
+</pre></div>
+</div>
+<p>And the command line <tt class="docutils literal"><span class="pre">-Rpass-analysis=loop-vectorize</span></tt> indicates that the
+switch statement cannot be vectorized.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">no_switch.cpp:4:5: remark: loop not vectorized: loop contains a switch statement [-Rpass-analysis=loop-vectorize]</span>
+<span class="go"> switch(A[i]) {</span>
+<span class="go"> ^</span>
+</pre></div>
+</div>
+<p>To ensure line and column numbers are produced include the command line options
+<tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> and <tt class="docutils literal"><span class="pre">-gcolumn-info</span></tt>. See the Clang <a class="reference external" href="http://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports">user manual</a>
+for details</p>
+</div>
+<div class="section" id="features">
+<h3><a class="toc-backref" href="#id7">Features</a><a class="headerlink" href="#features" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM Loop Vectorizer has a number of features that allow it to vectorize
+complex loops.</p>
+<div class="section" id="loops-with-unknown-trip-count">
+<h4><a class="toc-backref" href="#id8">Loops with unknown trip count</a><a class="headerlink" href="#loops-with-unknown-trip-count" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer supports loops with an unknown trip count.
+In the loop below, the iteration <tt class="docutils literal"><span class="pre">start</span></tt> and <tt class="docutils literal"><span class="pre">finish</span></tt> points are unknown,
+and the Loop Vectorizer has a mechanism to vectorize loops that do not start
+at zero. In this example, ‘n’ may not be a multiple of the vector width, and
+the vectorizer has to execute the last few iterations as scalar code. Keeping
+a scalar copy of the loop increases the code size.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</span><span class="p">,</span> <span class="kt">int</span> <span class="n">start</span><span class="p">,</span> <span class="kt">int</span> <span class="n">end</span><span class="p">)</span> <span class="p">{</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="n">start</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">end</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="n">K</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="runtime-checks-of-pointers">
+<h4><a class="toc-backref" href="#id9">Runtime Checks of Pointers</a><a class="headerlink" href="#runtime-checks-of-pointers" title="Permalink to this headline">¶</a></h4>
+<p>In the example below, if the pointers A and B point to consecutive addresses,
+then it is illegal to vectorize the code because some elements of A will be
+written before they are read from array B.</p>
+<p>Some programmers use the ‘restrict’ keyword to notify the compiler that the
+pointers are disjointed, but in our example, the Loop Vectorizer has no way of
+knowing that the pointers A and B are unique. The Loop Vectorizer handles this
+loop by placing code that checks, at runtime, if the arrays A and B point to
+disjointed memory locations. If arrays A and B overlap, then the scalar version
+of the loop is executed.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</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="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="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="n">K</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="reductions">
+<h4><a class="toc-backref" href="#id10">Reductions</a><a class="headerlink" href="#reductions" title="Permalink to this headline">¶</a></h4>
+<p>In this example the <tt class="docutils literal"><span class="pre">sum</span></tt> variable is used by consecutive iterations of
+the loop. Normally, this would prevent vectorization, but the vectorizer can
+detect that ‘sum’ is a reduction variable. The variable ‘sum’ becomes a vector
+of integers, and at the end of the loop the elements of the array are added
+together to create the correct result. We support a number of different
+reduction operations, such as addition, multiplication, XOR, AND and OR.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</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">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</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="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">5</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>We support floating point reduction operations when <cite>-ffast-math</cite> is used.</p>
+</div>
+<div class="section" id="inductions">
+<h4><a class="toc-backref" href="#id11">Inductions</a><a class="headerlink" href="#inductions" title="Permalink to this headline">¶</a></h4>
+<p>In this example the value of the induction variable <tt class="docutils literal"><span class="pre">i</span></tt> is saved into an
+array. The Loop Vectorizer knows to vectorize induction variables.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</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="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="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="if-conversion">
+<h4><a class="toc-backref" href="#id12">If Conversion</a><a class="headerlink" href="#if-conversion" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer is able to “flatten” the IF statement in the code and
+generate a single stream of instructions. The Loop Vectorizer supports any
+control flow in the innermost loop. The innermost loop may contain complex
+nesting of IFs, ELSEs and even GOTOs.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</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">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</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="k">if</span> <span class="p">(</span><span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">></span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
+ <span class="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">5</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pointer-induction-variables">
+<h4><a class="toc-backref" href="#id13">Pointer Induction Variables</a><a class="headerlink" href="#pointer-induction-variables" title="Permalink to this headline">¶</a></h4>
+<p>This example uses the “accumulate” function of the standard c++ library. This
+loop uses C++ iterators, which are pointers, and not integer indices.
+The Loop Vectorizer detects pointer induction variables and can vectorize
+this loop. This feature is important because many C++ programs use iterators.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">baz</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</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">return</span> <span class="n">std</span><span class="o">::</span><span class="n">accumulate</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="n">n</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="reverse-iterators">
+<h4><a class="toc-backref" href="#id14">Reverse Iterators</a><a class="headerlink" href="#reverse-iterators" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize loops that count backwards.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</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="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">n</span><span class="p">;</span> <span class="n">i</span> <span class="o">></span> <span class="mi">0</span><span class="p">;</span> <span class="o">--</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span><span class="mi">1</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="scatter-gather">
+<h4><a class="toc-backref" href="#id15">Scatter / Gather</a><a class="headerlink" href="#scatter-gather" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize code that becomes a sequence of scalar instructions
+that scatter/gathers memory.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span> <span class="n">B</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="kt">intptr_t</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="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span> <span class="o">*</span> <span class="mi">4</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In many situations the cost model will inform LLVM that this is not beneficial
+and LLVM will only vectorize such code if forced with “-mllvm -force-vector-width=#”.</p>
+</div>
+<div class="section" id="vectorization-of-mixed-types">
+<h4><a class="toc-backref" href="#id16">Vectorization of Mixed Types</a><a class="headerlink" href="#vectorization-of-mixed-types" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize programs with mixed types. The Vectorizer
+cost model can estimate the cost of the type conversion and decide if
+vectorization is profitable.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">,</span> <span class="kt">int</span> <span class="n">k</span><span class="p">)</span> <span class="p">{</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="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span> <span class="mi">4</span> <span class="o">*</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="global-structures-alias-analysis">
+<h4><a class="toc-backref" href="#id17">Global Structures Alias Analysis</a><a class="headerlink" href="#global-structures-alias-analysis" title="Permalink to this headline">¶</a></h4>
+<p>Access to global structures can also be vectorized, with alias analysis being
+used to make sure accesses don’t alias. Run-time checks can also be added on
+pointer access to structure members.</p>
+<p>Many variations are supported, but some that rely on undefined behaviour being
+ignored (as other compilers do) are still being left un-vectorized.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">A</span><span class="p">[</span><span class="mi">100</span><span class="p">],</span> <span class="n">K</span><span class="p">,</span> <span class="n">B</span><span class="p">[</span><span class="mi">100</span><span class="p">];</span> <span class="p">}</span> <span class="n">Foo</span><span class="p">;</span>
+
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">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="mi">100</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Foo</span><span class="p">.</span><span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">Foo</span><span class="p">.</span><span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">100</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="vectorization-of-function-calls">
+<h4><a class="toc-backref" href="#id18">Vectorization of function calls</a><a class="headerlink" href="#vectorization-of-function-calls" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorize can vectorize intrinsic math functions.
+See the table below for a list of these functions.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="26%" />
+<col width="26%" />
+<col width="47%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>pow</td>
+<td>exp</td>
+<td>exp2</td>
+</tr>
+<tr class="row-even"><td>sin</td>
+<td>cos</td>
+<td>sqrt</td>
+</tr>
+<tr class="row-odd"><td>log</td>
+<td>log2</td>
+<td>log10</td>
+</tr>
+<tr class="row-even"><td>fabs</td>
+<td>floor</td>
+<td>ceil</td>
+</tr>
+<tr class="row-odd"><td>fma</td>
+<td>trunc</td>
+<td>nearbyint</td>
+</tr>
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>fmuladd</td>
+</tr>
+</tbody>
+</table>
+<p>The loop vectorizer knows about special instructions on the target and will
+vectorize a loop containing a function call that maps to the instructions. For
+example, the loop below will be vectorized on Intel x86 if the SSE4.1 roundps
+instruction is available.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">f</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="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="mi">1024</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">f</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">floorf</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="partial-unrolling-during-vectorization">
+<h4><a class="toc-backref" href="#id19">Partial unrolling during vectorization</a><a class="headerlink" href="#partial-unrolling-during-vectorization" title="Permalink to this headline">¶</a></h4>
+<p>Modern processors feature multiple execution units, and only programs that contain a
+high degree of parallelism can fully utilize the entire width of the machine.
+The Loop Vectorizer increases the instruction level parallelism (ILP) by
+performing partial-unrolling of loops.</p>
+<p>In the example below the entire array is accumulated into the variable ‘sum’.
+This is inefficient because only a single execution port can be used by the processor.
+By unrolling the code the Loop Vectorizer allows two or more execution ports
+to be used simultaneously.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</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">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</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="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The Loop Vectorizer uses a cost model to decide when it is profitable to unroll loops.
+The decision to unroll the loop depends on the register pressure and the generated code size.</p>
+</div>
+</div>
+<div class="section" id="performance">
+<h3><a class="toc-backref" href="#id20">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h3>
+<p>This section shows the execution time of Clang on a simple benchmark:
+<a class="reference external" href="http://llvm.org/viewvc/llvm-project/test-suite/trunk/SingleSource/UnitTests/Vectorizer/">gcc-loops</a>.
+This benchmarks is a collection of loops from the GCC autovectorization
+<a class="reference external" href="http://gcc.gnu.org/projects/tree-ssa/vectorization.html">page</a> by Dorit Nuzman.</p>
+<p>The chart below compares GCC-4.7, ICC-13, and Clang-SVN with and without loop vectorization at -O3, tuned for “corei7-avx”, running on a Sandybridge iMac.
+The Y-axis shows the time in msec. Lower is better. The last column shows the geomean of all the kernels.</p>
+<img alt="_images/gcc-loops.png" src="_images/gcc-loops.png" />
+<p>And Linpack-pc with the same configuration. Result is Mflops, higher is better.</p>
+<img alt="_images/linpack-pc.png" src="_images/linpack-pc.png" />
+</div>
+</div>
+<div class="section" id="the-slp-vectorizer">
+<span id="slp-vectorizer"></span><h2><a class="toc-backref" href="#id21">The SLP Vectorizer</a><a class="headerlink" href="#the-slp-vectorizer" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="details">
+<h3><a class="toc-backref" href="#id22">Details</a><a class="headerlink" href="#details" title="Permalink to this headline">¶</a></h3>
+<p>The goal of SLP vectorization (a.k.a. superword-level parallelism) is
+to combine similar independent instructions
+into vector instructions. Memory accesses, arithmetic operations, comparison
+operations, PHI-nodes, can all be vectorized using this technique.</p>
+<p>For example, the following function performs very similar operations on its
+inputs (a1, b1) and (a2, b2). The basic-block vectorizer may combine these
+into vector operations.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">a1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">a2</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b2</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">A</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">a1</span><span class="o">*</span><span class="p">(</span><span class="n">a1</span> <span class="o">+</span> <span class="n">b1</span><span class="p">)</span><span class="o">/</span><span class="n">b1</span> <span class="o">+</span> <span class="mi">50</span><span class="o">*</span><span class="n">b1</span><span class="o">/</span><span class="n">a1</span><span class="p">;</span>
+ <span class="n">A</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">a2</span><span class="o">*</span><span class="p">(</span><span class="n">a2</span> <span class="o">+</span> <span class="n">b2</span><span class="p">)</span><span class="o">/</span><span class="n">b2</span> <span class="o">+</span> <span class="mi">50</span><span class="o">*</span><span class="n">b2</span><span class="o">/</span><span class="n">a2</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The SLP-vectorizer processes the code bottom-up, across basic blocks, in search of scalars to combine.</p>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id23">Usage</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>The SLP Vectorizer is enabled by default, but it can be disabled
+through clang using the command line flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -fno-slp-vectorize file.c
+</pre></div>
+</div>
+<p>LLVM has a second basic block vectorization phase
+which is more compile-time intensive (The BB vectorizer). This optimization
+can be enabled through clang using the command line flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -fslp-vectorize-aggressive file.c
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/WritingAnLLVMBackend.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/WritingAnLLVMBackend.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/WritingAnLLVMBackend.html (added)
+++ www-releases/trunk/3.7.1/docs/WritingAnLLVMBackend.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,1825 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Writing an LLVM Backend — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="index.html" />
+ <link rel="next" title="How To Use Instruction Mappings" href="HowToUseInstrMappings.html" />
+ <link rel="prev" title="Auto-Vectorization in LLVM" href="Vectorizers.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <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="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="writing-an-llvm-backend">
+<h1>Writing an LLVM Backend<a class="headerlink" href="#writing-an-llvm-backend" title="Permalink to this headline">¶</a></h1>
+<div class="toctree-wrapper compound">
+</div>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a><ul>
+<li><a class="reference internal" href="#audience" id="id4">Audience</a></li>
+<li><a class="reference internal" href="#prerequisite-reading" id="id5">Prerequisite Reading</a></li>
+<li><a class="reference internal" href="#basic-steps" id="id6">Basic Steps</a></li>
+<li><a class="reference internal" href="#preliminaries" id="id7">Preliminaries</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-machine" id="id8">Target Machine</a></li>
+<li><a class="reference internal" href="#target-registration" id="id9">Target Registration</a></li>
+<li><a class="reference internal" href="#register-set-and-register-classes" id="id10">Register Set and Register Classes</a><ul>
+<li><a class="reference internal" href="#defining-a-register" id="id11">Defining a Register</a></li>
+<li><a class="reference internal" href="#defining-a-register-class" id="id12">Defining a Register Class</a></li>
+<li><a class="reference internal" href="#implement-a-subclass-of-targetregisterinfo" id="id13">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instruction-set" id="id14">Instruction Set</a><ul>
+<li><a class="reference internal" href="#instruction-operand-mapping" id="id15">Instruction Operand Mapping</a><ul>
+<li><a class="reference internal" href="#instruction-operand-name-mapping" id="id16">Instruction Operand Name Mapping</a></li>
+<li><a class="reference internal" href="#instruction-operand-types" id="id17">Instruction Operand Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instruction-scheduling" id="id18">Instruction Scheduling</a></li>
+<li><a class="reference internal" href="#instruction-relation-mapping" id="id19">Instruction Relation Mapping</a></li>
+<li><a class="reference internal" href="#implement-a-subclass-of-targetinstrinfo" id="id20">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt></a></li>
+<li><a class="reference internal" href="#branch-folding-and-if-conversion" id="id21">Branch Folding and If Conversion</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instruction-selector" id="id22">Instruction Selector</a><ul>
+<li><a class="reference internal" href="#the-selectiondag-legalize-phase" id="id23">The SelectionDAG Legalize Phase</a><ul>
+<li><a class="reference internal" href="#promote" id="id24">Promote</a></li>
+<li><a class="reference internal" href="#expand" id="id25">Expand</a></li>
+<li><a class="reference internal" href="#custom" id="id26">Custom</a></li>
+<li><a class="reference internal" href="#legal" id="id27">Legal</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#calling-conventions" id="id28">Calling Conventions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#assembly-printer" id="id29">Assembly Printer</a></li>
+<li><a class="reference internal" href="#subtarget-support" id="id30">Subtarget Support</a></li>
+<li><a class="reference internal" href="#jit-support" id="id31">JIT Support</a><ul>
+<li><a class="reference internal" href="#machine-code-emitter" id="id32">Machine Code Emitter</a></li>
+<li><a class="reference internal" href="#target-jit-info" id="id33">Target JIT Info</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes techniques for writing compiler backends that convert
+the LLVM Intermediate Representation (IR) to code for a specified machine or
+other languages. Code intended for a specific machine can take the form of
+either assembly code or binary code (usable for a JIT compiler).</p>
+<p>The backend of LLVM features a target-independent code generator that may
+create output for several types of target CPUs — including X86, PowerPC,
+ARM, and SPARC. The backend may also be used to generate code targeted at SPUs
+of the Cell processor or GPUs to support the execution of compute kernels.</p>
+<p>The document focuses on existing examples found in subdirectories of
+<tt class="docutils literal"><span class="pre">llvm/lib/Target</span></tt> in a downloaded LLVM release. In particular, this document
+focuses on the example of creating a static compiler (one that emits text
+assembly) for a SPARC target, because SPARC has fairly standard
+characteristics, such as a RISC instruction set and straightforward calling
+conventions.</p>
+<div class="section" id="audience">
+<h3><a class="toc-backref" href="#id4">Audience</a><a class="headerlink" href="#audience" title="Permalink to this headline">¶</a></h3>
+<p>The audience for this document is anyone who needs to write an LLVM backend to
+generate code for a specific hardware or software target.</p>
+</div>
+<div class="section" id="prerequisite-reading">
+<h3><a class="toc-backref" href="#id5">Prerequisite Reading</a><a class="headerlink" href="#prerequisite-reading" title="Permalink to this headline">¶</a></h3>
+<p>These essential documents must be read before reading this document:</p>
+<ul class="simple">
+<li><a class="reference external" href="LangRef.html">LLVM Language Reference Manual</a> — a reference manual for
+the LLVM assembly language.</li>
+<li><a class="reference internal" href="CodeGenerator.html"><em>The LLVM Target-Independent Code Generator</em></a> — a guide to the components (classes and code
+generation algorithms) for translating the LLVM internal representation into
+machine code for a specified target. Pay particular attention to the
+descriptions of code generation stages: Instruction Selection, Scheduling and
+Formation, SSA-based Optimization, Register Allocation, Prolog/Epilog Code
+Insertion, Late Machine Code Optimizations, and Code Emission.</li>
+<li><a class="reference internal" href="TableGen/index.html"><em>TableGen</em></a> — a document that describes the TableGen
+(<tt class="docutils literal"><span class="pre">tblgen</span></tt>) application that manages domain-specific information to support
+LLVM code generation. TableGen processes input from a target description
+file (<tt class="docutils literal"><span class="pre">.td</span></tt> suffix) and generates C++ code that can be used for code
+generation.</li>
+<li><a class="reference internal" href="WritingAnLLVMPass.html"><em>Writing an LLVM Pass</em></a> — The assembly printer is a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, as
+are several <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> processing steps.</li>
+</ul>
+<p>To follow the SPARC examples in this document, have a copy of <a class="reference external" href="http://www.sparc.org/standards/V8.pdf">The SPARC
+Architecture Manual, Version 8</a> for
+reference. For details about the ARM instruction set, refer to the <a class="reference external" href="http://infocenter.arm.com/">ARM
+Architecture Reference Manual</a>. For more about
+the GNU Assembler format (<tt class="docutils literal"><span class="pre">GAS</span></tt>), see <a class="reference external" href="http://sourceware.org/binutils/docs/as/index.html">Using As</a>, especially for the
+assembly printer. “Using As” contains a list of target machine dependent
+features.</p>
+</div>
+<div class="section" id="basic-steps">
+<h3><a class="toc-backref" href="#id6">Basic Steps</a><a class="headerlink" href="#basic-steps" title="Permalink to this headline">¶</a></h3>
+<p>To write a compiler backend for LLVM that converts the LLVM IR to code for a
+specified target (machine or other language), follow these steps:</p>
+<ul class="simple">
+<li>Create a subclass of the <tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class that describes
+characteristics of your target machine. Copy existing examples of specific
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class and header files; for example, start with
+<tt class="docutils literal"><span class="pre">SparcTargetMachine.cpp</span></tt> and <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt>, but change the file
+names for your target. Similarly, change code that references “<tt class="docutils literal"><span class="pre">Sparc</span></tt>” to
+reference your target.</li>
+<li>Describe the register set of the target. Use TableGen to generate code for
+register definition, register aliases, and register classes from a
+target-specific <tt class="docutils literal"><span class="pre">RegisterInfo.td</span></tt> input file. You should also write
+additional code for a subclass of the <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt> class that
+represents the class register file data used for register allocation and also
+describes the interactions between registers.</li>
+<li>Describe the instruction set of the target. Use TableGen to generate code
+for target-specific instructions from target-specific versions of
+<tt class="docutils literal"><span class="pre">TargetInstrFormats.td</span></tt> and <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. You should write
+additional code for a subclass of the <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt> class to represent
+machine instructions supported by the target machine.</li>
+<li>Describe the selection and conversion of the LLVM IR from a Directed Acyclic
+Graph (DAG) representation of instructions to native target-specific
+instructions. Use TableGen to generate code that matches patterns and
+selects instructions based on additional information in a target-specific
+version of <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. Write code for <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt>,
+where <tt class="docutils literal"><span class="pre">XXX</span></tt> identifies the specific target, to perform pattern matching and
+DAG-to-DAG instruction selection. Also write code in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>
+to replace or remove operations and data types that are not supported
+natively in a SelectionDAG.</li>
+<li>Write code for an assembly printer that converts LLVM IR to a GAS format for
+your target machine. You should add assembly strings to the instructions
+defined in your target-specific version of <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. You
+should also write code for a subclass of <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> that performs the
+LLVM-to-assembly conversion and a trivial subclass of <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt>.</li>
+<li>Optionally, add support for subtargets (i.e., variants with different
+capabilities). You should also write code for a subclass of the
+<tt class="docutils literal"><span class="pre">TargetSubtarget</span></tt> class, which allows you to use the <tt class="docutils literal"><span class="pre">-mcpu=</span></tt> and
+<tt class="docutils literal"><span class="pre">-mattr=</span></tt> command-line options.</li>
+<li>Optionally, add JIT support and create a machine code emitter (subclass of
+<tt class="docutils literal"><span class="pre">TargetJITInfo</span></tt>) that is used to emit binary code directly into memory.</li>
+</ul>
+<p>In the <tt class="docutils literal"><span class="pre">.cpp</span></tt> and <tt class="docutils literal"><span class="pre">.h</span></tt>. files, initially stub up these methods and then
+implement them later. Initially, you may not know which private members that
+the class will need and which components will need to be subclassed.</p>
+</div>
+<div class="section" id="preliminaries">
+<h3><a class="toc-backref" href="#id7">Preliminaries</a><a class="headerlink" href="#preliminaries" title="Permalink to this headline">¶</a></h3>
+<p>To actually create your compiler backend, you need to create and modify a few
+files. The absolute minimum is discussed here. But to actually use the LLVM
+target-independent code generator, you must perform the steps described in the
+<a class="reference internal" href="CodeGenerator.html"><em>LLVM Target-Independent Code Generator</em></a> document.</p>
+<p>First, you should create a subdirectory under <tt class="docutils literal"><span class="pre">lib/Target</span></tt> to hold all the
+files related to your target. If your target is called “Dummy”, create the
+directory <tt class="docutils literal"><span class="pre">lib/Target/Dummy</span></tt>.</p>
+<p>In this new directory, create a <tt class="docutils literal"><span class="pre">Makefile</span></tt>. It is easiest to copy a
+<tt class="docutils literal"><span class="pre">Makefile</span></tt> of another target and modify it. It should at least contain the
+<tt class="docutils literal"><span class="pre">LEVEL</span></tt>, <tt class="docutils literal"><span class="pre">LIBRARYNAME</span></tt> and <tt class="docutils literal"><span class="pre">TARGET</span></tt> variables, and then include
+<tt class="docutils literal"><span class="pre">$(LEVEL)/Makefile.common</span></tt>. The library can be named <tt class="docutils literal"><span class="pre">LLVMDummy</span></tt> (for
+example, see the MIPS target). Alternatively, you can split the library into
+<tt class="docutils literal"><span class="pre">LLVMDummyCodeGen</span></tt> and <tt class="docutils literal"><span class="pre">LLVMDummyAsmPrinter</span></tt>, the latter of which should be
+implemented in a subdirectory below <tt class="docutils literal"><span class="pre">lib/Target/Dummy</span></tt> (for example, see the
+PowerPC target).</p>
+<p>Note that these two naming schemes are hardcoded into <tt class="docutils literal"><span class="pre">llvm-config</span></tt>. Using
+any other naming scheme will confuse <tt class="docutils literal"><span class="pre">llvm-config</span></tt> and produce a lot of
+(seemingly unrelated) linker errors when linking <tt class="docutils literal"><span class="pre">llc</span></tt>.</p>
+<p>To make your target actually do something, you need to implement a subclass of
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt>. This implementation should typically be in the file
+<tt class="docutils literal"><span class="pre">lib/Target/DummyTargetMachine.cpp</span></tt>, but any file in the <tt class="docutils literal"><span class="pre">lib/Target</span></tt>
+directory will be built and should work. To use LLVM’s target independent code
+generator, you should do what all current machine backends do: create a
+subclass of <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt>. (To create a target from scratch, create a
+subclass of <tt class="docutils literal"><span class="pre">TargetMachine</span></tt>.)</p>
+<p>To get LLVM to actually build and link your target, you need to add it to the
+<tt class="docutils literal"><span class="pre">TARGETS_TO_BUILD</span></tt> variable. To do this, you modify the configure script to
+know about your target when parsing the <tt class="docutils literal"><span class="pre">--enable-targets</span></tt> option. Search
+the configure script for <tt class="docutils literal"><span class="pre">TARGETS_TO_BUILD</span></tt>, add your target to the lists
+there (some creativity required), and then reconfigure. Alternatively, you can
+change <tt class="docutils literal"><span class="pre">autoconf/configure.ac</span></tt> and regenerate configure by running
+<tt class="docutils literal"><span class="pre">./autoconf/AutoRegen.sh</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="target-machine">
+<h2><a class="toc-backref" href="#id8">Target Machine</a><a class="headerlink" href="#target-machine" title="Permalink to this headline">¶</a></h2>
+<p><tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> is designed as a base class for targets implemented with
+the LLVM target-independent code generator. The <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> class
+should be specialized by a concrete target class that implements the various
+virtual methods. <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> is defined as a subclass of
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> in <tt class="docutils literal"><span class="pre">include/llvm/Target/TargetMachine.h</span></tt>. The
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class implementation (<tt class="docutils literal"><span class="pre">TargetMachine.cpp</span></tt>) also processes
+numerous command-line options.</p>
+<p>To create a concrete target-specific subclass of <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt>, start
+by copying an existing <tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class and header. You should name the
+files that you create to reflect your specific target. For instance, for the
+SPARC target, name the files <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt> and
+<tt class="docutils literal"><span class="pre">SparcTargetMachine.cpp</span></tt>.</p>
+<p>For a target machine <tt class="docutils literal"><span class="pre">XXX</span></tt>, the implementation of <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> must
+have access methods to obtain objects that represent target components. These
+methods are named <tt class="docutils literal"><span class="pre">get*Info</span></tt>, and are intended to obtain the instruction set
+(<tt class="docutils literal"><span class="pre">getInstrInfo</span></tt>), register set (<tt class="docutils literal"><span class="pre">getRegisterInfo</span></tt>), stack frame layout
+(<tt class="docutils literal"><span class="pre">getFrameInfo</span></tt>), and similar information. <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> must also
+implement the <tt class="docutils literal"><span class="pre">getDataLayout</span></tt> method to access an object with target-specific
+data characteristics, such as data type size and alignment requirements.</p>
+<p>For instance, for the SPARC target, the header file <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt>
+declares prototypes for several <tt class="docutils literal"><span class="pre">get*Info</span></tt> and <tt class="docutils literal"><span class="pre">getDataLayout</span></tt> methods that
+simply return a class member.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
+
+<span class="k">class</span> <span class="nc">Module</span><span class="p">;</span>
+
+<span class="k">class</span> <span class="nc">SparcTargetMachine</span> <span class="o">:</span> <span class="k">public</span> <span class="n">LLVMTargetMachine</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="n">DataLayout</span> <span class="n">DataLayout</span><span class="p">;</span> <span class="c1">// Calculates type size & alignment</span>
+ <span class="n">SparcSubtarget</span> <span class="n">Subtarget</span><span class="p">;</span>
+ <span class="n">SparcInstrInfo</span> <span class="n">InstrInfo</span><span class="p">;</span>
+ <span class="n">TargetFrameInfo</span> <span class="n">FrameInfo</span><span class="p">;</span>
+
+<span class="nl">protected:</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetAsmInfo</span> <span class="o">*</span><span class="n">createTargetAsmInfo</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+ <span class="n">SparcTargetMachine</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</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">FS</span><span class="p">);</span>
+
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">SparcInstrInfo</span> <span class="o">*</span><span class="n">getInstrInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">InstrInfo</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetFrameInfo</span> <span class="o">*</span><span class="n">getFrameInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">FrameInfo</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetSubtarget</span> <span class="o">*</span><span class="n">getSubtargetImpl</span><span class="p">()</span> <span class="k">const</span><span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">Subtarget</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetRegisterInfo</span> <span class="o">*</span><span class="n">getRegisterInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="o">&</span><span class="n">InstrInfo</span><span class="p">.</span><span class="n">getRegisterInfo</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">DataLayout</span> <span class="o">*</span><span class="n">getDataLayout</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&</span><span class="n">DataLayout</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="kt">unsigned</span> <span class="n">getModuleMatchQuality</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+
+ <span class="c1">// Pass Pipeline Configuration</span>
+ <span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">addInstSelector</span><span class="p">(</span><span class="n">PassManagerBase</span> <span class="o">&</span><span class="n">PM</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">Fast</span><span class="p">);</span>
+ <span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">addPreEmitPass</span><span class="p">(</span><span class="n">PassManagerBase</span> <span class="o">&</span><span class="n">PM</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">Fast</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="p">}</span> <span class="c1">// end namespace llvm</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getInstrInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getRegisterInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getFrameInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getDataLayout()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getSubtargetImpl()</span></tt></li>
+</ul>
+<p>For some targets, you also need to support the following methods:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getTargetLowering()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getJITInfo()</span></tt></li>
+</ul>
+<p>Some architectures, such as GPUs, do not support jumping to an arbitrary
+program location and implement branching using masked execution and loop using
+special instructions around the loop body. In order to avoid CFG modifications
+that introduce irreducible control flow not handled by such hardware, a target
+must call <cite>setRequiresStructuredCFG(true)</cite> when being initialized.</p>
+<p>In addition, the <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> constructor should specify a
+<tt class="docutils literal"><span class="pre">TargetDescription</span></tt> string that determines the data layout for the target
+machine, including characteristics such as pointer size, alignment, and
+endianness. For example, the constructor for <tt class="docutils literal"><span class="pre">SparcTargetMachine</span></tt> contains
+the following:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SparcTargetMachine</span><span class="o">::</span><span class="n">SparcTargetMachine</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</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">FS</span><span class="p">)</span>
+ <span class="o">:</span> <span class="n">DataLayout</span><span class="p">(</span><span class="s">"E-p:32:32-f128:128:128"</span><span class="p">),</span>
+ <span class="n">Subtarget</span><span class="p">(</span><span class="n">M</span><span class="p">,</span> <span class="n">FS</span><span class="p">),</span> <span class="n">InstrInfo</span><span class="p">(</span><span class="n">Subtarget</span><span class="p">),</span>
+ <span class="n">FrameInfo</span><span class="p">(</span><span class="n">TargetFrameInfo</span><span class="o">::</span><span class="n">StackGrowsDown</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Hyphens separate portions of the <tt class="docutils literal"><span class="pre">TargetDescription</span></tt> string.</p>
+<ul class="simple">
+<li>An upper-case “<tt class="docutils literal"><span class="pre">E</span></tt>” in the string indicates a big-endian target data model.
+A lower-case “<tt class="docutils literal"><span class="pre">e</span></tt>” indicates little-endian.</li>
+<li>“<tt class="docutils literal"><span class="pre">p:</span></tt>” is followed by pointer information: size, ABI alignment, and
+preferred alignment. If only two figures follow “<tt class="docutils literal"><span class="pre">p:</span></tt>”, then the first
+value is pointer size, and the second value is both ABI and preferred
+alignment.</li>
+<li>Then a letter for numeric type alignment: “<tt class="docutils literal"><span class="pre">i</span></tt>”, “<tt class="docutils literal"><span class="pre">f</span></tt>”, “<tt class="docutils literal"><span class="pre">v</span></tt>”, or
+“<tt class="docutils literal"><span class="pre">a</span></tt>” (corresponding to integer, floating point, vector, or aggregate).
+“<tt class="docutils literal"><span class="pre">i</span></tt>”, “<tt class="docutils literal"><span class="pre">v</span></tt>”, or “<tt class="docutils literal"><span class="pre">a</span></tt>” are followed by ABI alignment and preferred
+alignment. “<tt class="docutils literal"><span class="pre">f</span></tt>” is followed by three values: the first indicates the size
+of a long double, then ABI alignment, and then ABI preferred alignment.</li>
+</ul>
+</div>
+<div class="section" id="target-registration">
+<h2><a class="toc-backref" href="#id9">Target Registration</a><a class="headerlink" href="#target-registration" title="Permalink to this headline">¶</a></h2>
+<p>You must also register your target with the <tt class="docutils literal"><span class="pre">TargetRegistry</span></tt>, which is what
+other LLVM tools use to be able to lookup and use your target at runtime. The
+<tt class="docutils literal"><span class="pre">TargetRegistry</span></tt> can be used directly, but for most targets there are helper
+templates which should take care of the work for you.</p>
+<p>All targets should declare a global <tt class="docutils literal"><span class="pre">Target</span></tt> object which is used to
+represent the target during registration. Then, in the target’s <tt class="docutils literal"><span class="pre">TargetInfo</span></tt>
+library, the target should define that object and use the <tt class="docutils literal"><span class="pre">RegisterTarget</span></tt>
+template to register the target. For example, the Sparc registration code
+looks like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Target</span> <span class="n">llvm</span><span class="o">::</span><span class="n">TheSparcTarget</span><span class="p">;</span>
+
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">LLVMInitializeSparcTargetInfo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">RegisterTarget</span><span class="o"><</span><span class="n">Triple</span><span class="o">::</span><span class="n">sparc</span><span class="p">,</span> <span class="cm">/*HasJIT=*/</span><span class="nb">false</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="n">TheSparcTarget</span><span class="p">,</span> <span class="s">"sparc"</span><span class="p">,</span> <span class="s">"Sparc"</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This allows the <tt class="docutils literal"><span class="pre">TargetRegistry</span></tt> to look up the target by name or by target
+triple. In addition, most targets will also register additional features which
+are available in separate libraries. These registration steps are separate,
+because some clients may wish to only link in some parts of the target — the
+JIT code generator does not require the use of the assembler printer, for
+example. Here is an example of registering the Sparc assembly printer:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">LLVMInitializeSparcAsmPrinter</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">RegisterAsmPrinter</span><span class="o"><</span><span class="n">SparcAsmPrinter</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="n">TheSparcTarget</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For more information, see “<a class="reference external" href="/doxygen/TargetRegistry_8h-source.html">llvm/Target/TargetRegistry.h</a>”.</p>
+</div>
+<div class="section" id="register-set-and-register-classes">
+<h2><a class="toc-backref" href="#id10">Register Set and Register Classes</a><a class="headerlink" href="#register-set-and-register-classes" title="Permalink to this headline">¶</a></h2>
+<p>You should describe a concrete target-specific class that represents the
+register file of a target machine. This class is called <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt>
+(where <tt class="docutils literal"><span class="pre">XXX</span></tt> identifies the target) and represents the class register file
+data that is used for register allocation. It also describes the interactions
+between registers.</p>
+<p>You also need to define register classes to categorize related registers. A
+register class should be added for groups of registers that are all treated the
+same way for some instruction. Typical examples are register classes for
+integer, floating-point, or vector registers. A register allocator allows an
+instruction to use any register in a specified register class to perform the
+instruction in a similar manner. Register classes allocate virtual registers
+to instructions from these sets, and register classes let the
+target-independent register allocator automatically choose the actual
+registers.</p>
+<p>Much of the code for registers, including register definition, register
+aliases, and register classes, is generated by TableGen from
+<tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> input files and placed in <tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.h.inc</span></tt>
+and <tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.inc</span></tt> output files. Some of the code in the
+implementation of <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt> requires hand-coding.</p>
+<div class="section" id="defining-a-register">
+<h3><a class="toc-backref" href="#id11">Defining a Register</a><a class="headerlink" href="#defining-a-register" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> file typically starts with register definitions for
+a target machine. The <tt class="docutils literal"><span class="pre">Register</span></tt> class (specified in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is used
+to define an object for each register. The specified string <tt class="docutils literal"><span class="pre">n</span></tt> becomes the
+<tt class="docutils literal"><span class="pre">Name</span></tt> of the register. The basic <tt class="docutils literal"><span class="pre">Register</span></tt> object does not have any
+subregisters and does not specify any aliases.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class Register<string n> {
+ string Namespace = "";
+ string AsmName = n;
+ string Name = n;
+ int SpillSize = 0;
+ int SpillAlignment = 0;
+ list<Register> Aliases = [];
+ list<Register> SubRegs = [];
+ list<int> DwarfNumbers = [];
+}
+</pre></div>
+</div>
+<p>For example, in the <tt class="docutils literal"><span class="pre">X86RegisterInfo.td</span></tt> file, there are register definitions
+that utilize the <tt class="docutils literal"><span class="pre">Register</span></tt> class, such as:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def AL : Register<"AL">, DwarfRegNum<[0, 0, 0]>;
+</pre></div>
+</div>
+<p>This defines the register <tt class="docutils literal"><span class="pre">AL</span></tt> and assigns it values (with <tt class="docutils literal"><span class="pre">DwarfRegNum</span></tt>)
+that are used by <tt class="docutils literal"><span class="pre">gcc</span></tt>, <tt class="docutils literal"><span class="pre">gdb</span></tt>, or a debug information writer to identify a
+register. For register <tt class="docutils literal"><span class="pre">AL</span></tt>, <tt class="docutils literal"><span class="pre">DwarfRegNum</span></tt> takes an array of 3 values
+representing 3 different modes: the first element is for X86-64, the second for
+exception handling (EH) on X86-32, and the third is generic. -1 is a special
+Dwarf number that indicates the gcc number is undefined, and -2 indicates the
+register number is invalid for this mode.</p>
+<p>From the previously described line in the <tt class="docutils literal"><span class="pre">X86RegisterInfo.td</span></tt> file, TableGen
+generates this code in the <tt class="docutils literal"><span class="pre">X86GenRegisterInfo.inc</span></tt> file:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="k">const</span> <span class="kt">unsigned</span> <span class="n">GR8</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="n">X86</span><span class="o">::</span><span class="n">AL</span><span class="p">,</span> <span class="p">...</span> <span class="p">};</span>
+
+<span class="k">const</span> <span class="kt">unsigned</span> <span class="n">AL_AliasSet</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="n">X86</span><span class="o">::</span><span class="n">AX</span><span class="p">,</span> <span class="n">X86</span><span class="o">::</span><span class="n">EAX</span><span class="p">,</span> <span class="n">X86</span><span class="o">::</span><span class="n">RAX</span><span class="p">,</span> <span class="mi">0</span> <span class="p">};</span>
+
+<span class="k">const</span> <span class="n">TargetRegisterDesc</span> <span class="n">RegisterDescriptors</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">{</span> <span class="s">"AL"</span><span class="p">,</span> <span class="s">"AL"</span><span class="p">,</span> <span class="n">AL_AliasSet</span><span class="p">,</span> <span class="n">Empty_SubRegsSet</span><span class="p">,</span> <span class="n">Empty_SubRegsSet</span><span class="p">,</span> <span class="n">AL_SuperRegsSet</span> <span class="p">},</span> <span class="p">...</span>
+</pre></div>
+</div>
+<p>From the register info file, TableGen generates a <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> object
+for each register. <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> is defined in
+<tt class="docutils literal"><span class="pre">include/llvm/Target/TargetRegisterInfo.h</span></tt> with the following fields:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">TargetRegisterDesc</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">AsmName</span><span class="p">;</span> <span class="c1">// Assembly language name for the register</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">Name</span><span class="p">;</span> <span class="c1">// Printable name for the reg (for debugging)</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">AliasSet</span><span class="p">;</span> <span class="c1">// Register Alias Set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">SubRegs</span><span class="p">;</span> <span class="c1">// Sub-register set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">ImmSubRegs</span><span class="p">;</span> <span class="c1">// Immediate sub-register set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">SuperRegs</span><span class="p">;</span> <span class="c1">// Super-register set</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>TableGen uses the entire target description file (<tt class="docutils literal"><span class="pre">.td</span></tt>) to determine text
+names for the register (in the <tt class="docutils literal"><span class="pre">AsmName</span></tt> and <tt class="docutils literal"><span class="pre">Name</span></tt> fields of
+<tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt>) and the relationships of other registers to the defined
+register (in the other <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> fields). In this example, other
+definitions establish the registers “<tt class="docutils literal"><span class="pre">AX</span></tt>”, “<tt class="docutils literal"><span class="pre">EAX</span></tt>”, and “<tt class="docutils literal"><span class="pre">RAX</span></tt>” as
+aliases for one another, so TableGen generates a null-terminated array
+(<tt class="docutils literal"><span class="pre">AL_AliasSet</span></tt>) for this register alias set.</p>
+<p>The <tt class="docutils literal"><span class="pre">Register</span></tt> class is commonly used as a base class for more complex
+classes. In <tt class="docutils literal"><span class="pre">Target.td</span></tt>, the <tt class="docutils literal"><span class="pre">Register</span></tt> class is the base for the
+<tt class="docutils literal"><span class="pre">RegisterWithSubRegs</span></tt> class that is used to define registers that need to
+specify subregisters in the <tt class="docutils literal"><span class="pre">SubRegs</span></tt> list, as shown here:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class RegisterWithSubRegs<string n, list<Register> subregs> : Register<n> {
+ let SubRegs = subregs;
+}
+</pre></div>
+</div>
+<p>In <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt>, additional register classes are defined for SPARC:
+a <tt class="docutils literal"><span class="pre">Register</span></tt> subclass, <tt class="docutils literal"><span class="pre">SparcReg</span></tt>, and further subclasses: <tt class="docutils literal"><span class="pre">Ri</span></tt>, <tt class="docutils literal"><span class="pre">Rf</span></tt>,
+and <tt class="docutils literal"><span class="pre">Rd</span></tt>. SPARC registers are identified by 5-bit ID numbers, which is a
+feature common to these subclasses. Note the use of “<tt class="docutils literal"><span class="pre">let</span></tt>” expressions to
+override values that are initially defined in a superclass (such as <tt class="docutils literal"><span class="pre">SubRegs</span></tt>
+field in the <tt class="docutils literal"><span class="pre">Rd</span></tt> class).</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class SparcReg<string n> : Register<n> {
+ field bits<5> Num;
+ let Namespace = "SP";
+}
+// Ri - 32-bit integer registers
+class Ri<bits<5> num, string n> :
+SparcReg<n> {
+ let Num = num;
+}
+// Rf - 32-bit floating-point registers
+class Rf<bits<5> num, string n> :
+SparcReg<n> {
+ let Num = num;
+}
+// Rd - Slots in the FP register file for 64-bit floating-point values.
+class Rd<bits<5> num, string n, list<Register> subregs> : SparcReg<n> {
+ let Num = num;
+ let SubRegs = subregs;
+}
+</pre></div>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> file, there are register definitions that
+utilize these subclasses of <tt class="docutils literal"><span class="pre">Register</span></tt>, such as:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def G0 : Ri< 0, "G0">, DwarfRegNum<[0]>;
+def G1 : Ri< 1, "G1">, DwarfRegNum<[1]>;
+...
+def F0 : Rf< 0, "F0">, DwarfRegNum<[32]>;
+def F1 : Rf< 1, "F1">, DwarfRegNum<[33]>;
+...
+def D0 : Rd< 0, "F0", [F0, F1]>, DwarfRegNum<[32]>;
+def D1 : Rd< 2, "F2", [F2, F3]>, DwarfRegNum<[34]>;
+</pre></div>
+</div>
+<p>The last two registers shown above (<tt class="docutils literal"><span class="pre">D0</span></tt> and <tt class="docutils literal"><span class="pre">D1</span></tt>) are double-precision
+floating-point registers that are aliases for pairs of single-precision
+floating-point sub-registers. In addition to aliases, the sub-register and
+super-register relationships of the defined register are in fields of a
+register’s <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt>.</p>
+</div>
+<div class="section" id="defining-a-register-class">
+<h3><a class="toc-backref" href="#id12">Defining a Register Class</a><a class="headerlink" href="#defining-a-register-class" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> class (specified in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is used to define an
+object that represents a group of related registers and also defines the
+default allocation order of the registers. A target description file
+<tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> that uses <tt class="docutils literal"><span class="pre">Target.td</span></tt> can construct register classes
+using the following class:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class RegisterClass<string namespace,
+list<ValueType> regTypes, int alignment, dag regList> {
+ string Namespace = namespace;
+ list<ValueType> RegTypes = regTypes;
+ int Size = 0; // spill size, in bits; zero lets tblgen pick the size
+ int Alignment = alignment;
+
+ // CopyCost is the cost of copying a value between two registers
+ // default value 1 means a single instruction
+ // A negative value means copying is extremely expensive or impossible
+ int CopyCost = 1;
+ dag MemberList = regList;
+
+ // for register classes that are subregisters of this class
+ list<RegisterClass> SubRegClassList = [];
+
+ code MethodProtos = [{}]; // to insert arbitrary code
+ code MethodBodies = [{}];
+}
+</pre></div>
+</div>
+<p>To define a <tt class="docutils literal"><span class="pre">RegisterClass</span></tt>, use the following 4 arguments:</p>
+<ul class="simple">
+<li>The first argument of the definition is the name of the namespace.</li>
+<li>The second argument is a list of <tt class="docutils literal"><span class="pre">ValueType</span></tt> register type values that are
+defined in <tt class="docutils literal"><span class="pre">include/llvm/CodeGen/ValueTypes.td</span></tt>. Defined values include
+integer types (such as <tt class="docutils literal"><span class="pre">i16</span></tt>, <tt class="docutils literal"><span class="pre">i32</span></tt>, and <tt class="docutils literal"><span class="pre">i1</span></tt> for Boolean),
+floating-point types (<tt class="docutils literal"><span class="pre">f32</span></tt>, <tt class="docutils literal"><span class="pre">f64</span></tt>), and vector types (for example,
+<tt class="docutils literal"><span class="pre">v8i16</span></tt> for an <tt class="docutils literal"><span class="pre">8</span> <span class="pre">x</span> <span class="pre">i16</span></tt> vector). All registers in a <tt class="docutils literal"><span class="pre">RegisterClass</span></tt>
+must have the same <tt class="docutils literal"><span class="pre">ValueType</span></tt>, but some registers may store vector data in
+different configurations. For example a register that can process a 128-bit
+vector may be able to handle 16 8-bit integer elements, 8 16-bit integers, 4
+32-bit integers, and so on.</li>
+<li>The third argument of the <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> definition specifies the
+alignment required of the registers when they are stored or loaded to
+memory.</li>
+<li>The final argument, <tt class="docutils literal"><span class="pre">regList</span></tt>, specifies which registers are in this class.
+If an alternative allocation order method is not specified, then <tt class="docutils literal"><span class="pre">regList</span></tt>
+also defines the order of allocation used by the register allocator. Besides
+simply listing registers with <tt class="docutils literal"><span class="pre">(add</span> <span class="pre">R0,</span> <span class="pre">R1,</span> <span class="pre">...)</span></tt>, more advanced set
+operators are available. See <tt class="docutils literal"><span class="pre">include/llvm/Target/Target.td</span></tt> for more
+information.</li>
+</ul>
+<p>In <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt>, three <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> objects are defined:
+<tt class="docutils literal"><span class="pre">FPRegs</span></tt>, <tt class="docutils literal"><span class="pre">DFPRegs</span></tt>, and <tt class="docutils literal"><span class="pre">IntRegs</span></tt>. For all three register classes, the
+first argument defines the namespace with the string “<tt class="docutils literal"><span class="pre">SP</span></tt>”. <tt class="docutils literal"><span class="pre">FPRegs</span></tt>
+defines a group of 32 single-precision floating-point registers (<tt class="docutils literal"><span class="pre">F0</span></tt> to
+<tt class="docutils literal"><span class="pre">F31</span></tt>); <tt class="docutils literal"><span class="pre">DFPRegs</span></tt> defines a group of 16 double-precision registers
+(<tt class="docutils literal"><span class="pre">D0-D15</span></tt>).</p>
+<div class="highlight-llvm"><div class="highlight"><pre>// F0, F1, F2, ..., F31
+def FPRegs : RegisterClass<"SP", [f32], 32, (sequence "F%u", 0, 31)>;
+
+def DFPRegs : RegisterClass<"SP", [f64], 64,
+ (add D0, D1, D2, D3, D4, D5, D6, D7, D8,
+ D9, D10, D11, D12, D13, D14, D15)>;
+
+def IntRegs : RegisterClass<"SP", [i32], 32,
+ (add L0, L1, L2, L3, L4, L5, L6, L7,
+ I0, I1, I2, I3, I4, I5,
+ O0, O1, O2, O3, O4, O5, O7,
+ G1,
+ // Non-allocatable regs:
+ G2, G3, G4,
+ O6, // stack ptr
+ I6, // frame ptr
+ I7, // return address
+ G0, // constant zero
+ G5, G6, G7 // reserved for kernel
+ )>;
+</pre></div>
+</div>
+<p>Using <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> with TableGen generates several output files
+that are intended for inclusion in other source code that you write.
+<tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> generates <tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.h.inc</span></tt>, which should
+be included in the header file for the implementation of the SPARC register
+implementation that you write (<tt class="docutils literal"><span class="pre">SparcRegisterInfo.h</span></tt>). In
+<tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.h.inc</span></tt> a new structure is defined called
+<tt class="docutils literal"><span class="pre">SparcGenRegisterInfo</span></tt> that uses <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt> as its base. It also
+specifies types, based upon the defined register classes: <tt class="docutils literal"><span class="pre">DFPRegsClass</span></tt>,
+<tt class="docutils literal"><span class="pre">FPRegsClass</span></tt>, and <tt class="docutils literal"><span class="pre">IntRegsClass</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> also generates <tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.inc</span></tt>, which is
+included at the bottom of <tt class="docutils literal"><span class="pre">SparcRegisterInfo.cpp</span></tt>, the SPARC register
+implementation. The code below shows only the generated integer registers and
+associated register classes. The order of registers in <tt class="docutils literal"><span class="pre">IntRegs</span></tt> reflects
+the order in the definition of <tt class="docutils literal"><span class="pre">IntRegs</span></tt> in the target description file.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// IntRegs Register Class...</span>
+<span class="k">static</span> <span class="k">const</span> <span class="kt">unsigned</span> <span class="n">IntRegs</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">L0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L3</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L5</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">L6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">I4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I5</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">O4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O5</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">G4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G5</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">G6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G7</span><span class="p">,</span>
+<span class="p">};</span>
+
+<span class="c1">// IntRegsVTs Register Class Value Types...</span>
+<span class="k">static</span> <span class="k">const</span> <span class="n">MVT</span><span class="o">::</span><span class="n">ValueType</span> <span class="n">IntRegsVTs</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">Other</span>
+<span class="p">};</span>
+
+<span class="k">namespace</span> <span class="n">SP</span> <span class="p">{</span> <span class="c1">// Register class instances</span>
+ <span class="n">DFPRegsClass</span> <span class="n">DFPRegsRegClass</span><span class="p">;</span>
+ <span class="n">FPRegsClass</span> <span class="n">FPRegsRegClass</span><span class="p">;</span>
+ <span class="n">IntRegsClass</span> <span class="n">IntRegsRegClass</span><span class="p">;</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Sub-register Classess...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSubRegClasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Super-register Classess...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSuperRegClasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Register Class sub-classes...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSubclasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Register Class super-classes...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSuperclasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+
+ <span class="n">IntRegsClass</span><span class="o">::</span><span class="n">IntRegsClass</span><span class="p">()</span> <span class="o">:</span> <span class="n">TargetRegisterClass</span><span class="p">(</span><span class="n">IntRegsRegClassID</span><span class="p">,</span>
+ <span class="n">IntRegsVTs</span><span class="p">,</span> <span class="n">IntRegsSubclasses</span><span class="p">,</span> <span class="n">IntRegsSuperclasses</span><span class="p">,</span> <span class="n">IntRegsSubRegClasses</span><span class="p">,</span>
+ <span class="n">IntRegsSuperRegClasses</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">IntRegs</span><span class="p">,</span> <span class="n">IntRegs</span> <span class="o">+</span> <span class="mi">32</span><span class="p">)</span> <span class="p">{}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The register allocators will avoid using reserved registers, and callee saved
+registers are not used until all the volatile registers have been used. That
+is usually good enough, but in some cases it may be necessary to provide custom
+allocation orders.</p>
+</div>
+<div class="section" id="implement-a-subclass-of-targetregisterinfo">
+<h3><a class="toc-backref" href="#id13">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt></a><a class="headerlink" href="#implement-a-subclass-of-targetregisterinfo" title="Permalink to this headline">¶</a></h3>
+<p>The final step is to hand code portions of <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt>, which
+implements the interface described in <tt class="docutils literal"><span class="pre">TargetRegisterInfo.h</span></tt> (see
+<a class="reference internal" href="CodeGenerator.html#targetregisterinfo"><em>The TargetRegisterInfo class</em></a>). These functions return <tt class="docutils literal"><span class="pre">0</span></tt>, <tt class="docutils literal"><span class="pre">NULL</span></tt>, or
+<tt class="docutils literal"><span class="pre">false</span></tt>, unless overridden. Here is a list of functions that are overridden
+for the SPARC implementation in <tt class="docutils literal"><span class="pre">SparcRegisterInfo.cpp</span></tt>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getCalleeSavedRegs</span></tt> — Returns a list of callee-saved registers in the
+order of the desired callee-save stack frame offset.</li>
+<li><tt class="docutils literal"><span class="pre">getReservedRegs</span></tt> — Returns a bitset indexed by physical register
+numbers, indicating if a particular register is unavailable.</li>
+<li><tt class="docutils literal"><span class="pre">hasFP</span></tt> — Return a Boolean indicating if a function should have a
+dedicated frame pointer register.</li>
+<li><tt class="docutils literal"><span class="pre">eliminateCallFramePseudoInstr</span></tt> — If call frame setup or destroy pseudo
+instructions are used, this can be called to eliminate them.</li>
+<li><tt class="docutils literal"><span class="pre">eliminateFrameIndex</span></tt> — Eliminate abstract frame indices from
+instructions that may use them.</li>
+<li><tt class="docutils literal"><span class="pre">emitPrologue</span></tt> — Insert prologue code into the function.</li>
+<li><tt class="docutils literal"><span class="pre">emitEpilogue</span></tt> — Insert epilogue code into the function.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="instruction-set">
+<span id="id1"></span><h2><a class="toc-backref" href="#id14">Instruction Set</a><a class="headerlink" href="#instruction-set" title="Permalink to this headline">¶</a></h2>
+<p>During the early stages of code generation, the LLVM IR code is converted to a
+<tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> with nodes that are instances of the <tt class="docutils literal"><span class="pre">SDNode</span></tt> class
+containing target instructions. An <tt class="docutils literal"><span class="pre">SDNode</span></tt> has an opcode, operands, type
+requirements, and operation properties. For example, is an operation
+commutative, does an operation load from memory. The various operation node
+types are described in the <tt class="docutils literal"><span class="pre">include/llvm/CodeGen/SelectionDAGNodes.h</span></tt> file
+(values of the <tt class="docutils literal"><span class="pre">NodeType</span></tt> enum in the <tt class="docutils literal"><span class="pre">ISD</span></tt> namespace).</p>
+<p>TableGen uses the following target description (<tt class="docutils literal"><span class="pre">.td</span></tt>) input files to
+generate much of the code for instruction definition:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">Target.td</span></tt> — Where the <tt class="docutils literal"><span class="pre">Instruction</span></tt>, <tt class="docutils literal"><span class="pre">Operand</span></tt>, <tt class="docutils literal"><span class="pre">InstrInfo</span></tt>, and
+other fundamental classes are defined.</li>
+<li><tt class="docutils literal"><span class="pre">TargetSelectionDAG.td</span></tt> — Used by <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> instruction selection
+generators, contains <tt class="docutils literal"><span class="pre">SDTC*</span></tt> classes (selection DAG type constraint),
+definitions of <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> nodes (such as <tt class="docutils literal"><span class="pre">imm</span></tt>, <tt class="docutils literal"><span class="pre">cond</span></tt>, <tt class="docutils literal"><span class="pre">bb</span></tt>,
+<tt class="docutils literal"><span class="pre">add</span></tt>, <tt class="docutils literal"><span class="pre">fadd</span></tt>, <tt class="docutils literal"><span class="pre">sub</span></tt>), and pattern support (<tt class="docutils literal"><span class="pre">Pattern</span></tt>, <tt class="docutils literal"><span class="pre">Pat</span></tt>,
+<tt class="docutils literal"><span class="pre">PatFrag</span></tt>, <tt class="docutils literal"><span class="pre">PatLeaf</span></tt>, <tt class="docutils literal"><span class="pre">ComplexPattern</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">XXXInstrFormats.td</span></tt> — Patterns for definitions of target-specific
+instructions.</li>
+<li><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> — Target-specific definitions of instruction templates,
+condition codes, and instructions of an instruction set. For architecture
+modifications, a different file name may be used. For example, for Pentium
+with SSE instruction, this file is <tt class="docutils literal"><span class="pre">X86InstrSSE.td</span></tt>, and for Pentium with
+MMX, this file is <tt class="docutils literal"><span class="pre">X86InstrMMX.td</span></tt>.</li>
+</ul>
+<p>There is also a target-specific <tt class="docutils literal"><span class="pre">XXX.td</span></tt> file, where <tt class="docutils literal"><span class="pre">XXX</span></tt> is the name of
+the target. The <tt class="docutils literal"><span class="pre">XXX.td</span></tt> file includes the other <tt class="docutils literal"><span class="pre">.td</span></tt> input files, but
+its contents are only directly important for subtargets.</p>
+<p>You should describe a concrete target-specific class <tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> that
+represents machine instructions supported by a target machine.
+<tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> contains an array of <tt class="docutils literal"><span class="pre">XXXInstrDescriptor</span></tt> objects, each of
+which describes one instruction. An instruction descriptor defines:</p>
+<ul class="simple">
+<li>Opcode mnemonic</li>
+<li>Number of operands</li>
+<li>List of implicit register definitions and uses</li>
+<li>Target-independent properties (such as memory access, is commutable)</li>
+<li>Target-specific flags</li>
+</ul>
+<p>The Instruction class (defined in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is mostly used as a base for
+more complex instruction classes.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class Instruction {
+ string Namespace = "";
+ dag OutOperandList; // A dag containing the MI def operand list.
+ dag InOperandList; // A dag containing the MI use operand list.
+ string AsmString = ""; // The .s format to print the instruction with.
+ list<dag> Pattern; // Set to the DAG pattern for this instruction.
+ list<Register> Uses = [];
+ list<Register> Defs = [];
+ list<Predicate> Predicates = []; // predicates turned into isel match code
+ ... remainder not shown for space ...
+}
+</pre></div>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> node (<tt class="docutils literal"><span class="pre">SDNode</span></tt>) should contain an object representing a
+target-specific instruction that is defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt>. The
+instruction objects should represent instructions from the architecture manual
+of the target machine (such as the SPARC Architecture Manual for the SPARC
+target).</p>
+<p>A single instruction from the architecture manual is often modeled as multiple
+target instructions, depending upon its operands. For example, a manual might
+describe an add instruction that takes a register or an immediate operand. An
+LLVM target could model this with two instructions named <tt class="docutils literal"><span class="pre">ADDri</span></tt> and
+<tt class="docutils literal"><span class="pre">ADDrr</span></tt>.</p>
+<p>You should define a class for each instruction category and define each opcode
+as a subclass of the category with appropriate parameters such as the fixed
+binary encoding of opcodes and extended opcodes. You should map the register
+bits to the bits of the instruction in which they are encoded (for the JIT).
+Also you should specify how the instruction should be printed when the
+automatic assembly printer is used.</p>
+<p>As is described in the SPARC Architecture Manual, Version 8, there are three
+major 32-bit formats for instructions. Format 1 is only for the <tt class="docutils literal"><span class="pre">CALL</span></tt>
+instruction. Format 2 is for branch on condition codes and <tt class="docutils literal"><span class="pre">SETHI</span></tt> (set high
+bits of a register) instructions. Format 3 is for other instructions.</p>
+<p>Each of these formats has corresponding classes in <tt class="docutils literal"><span class="pre">SparcInstrFormat.td</span></tt>.
+<tt class="docutils literal"><span class="pre">InstSP</span></tt> is a base class for other instruction classes. Additional base
+classes are specified for more precise formats: for example in
+<tt class="docutils literal"><span class="pre">SparcInstrFormat.td</span></tt>, <tt class="docutils literal"><span class="pre">F2_1</span></tt> is for <tt class="docutils literal"><span class="pre">SETHI</span></tt>, and <tt class="docutils literal"><span class="pre">F2_2</span></tt> is for
+branches. There are three other base classes: <tt class="docutils literal"><span class="pre">F3_1</span></tt> for register/register
+operations, <tt class="docutils literal"><span class="pre">F3_2</span></tt> for register/immediate operations, and <tt class="docutils literal"><span class="pre">F3_3</span></tt> for
+floating-point operations. <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> also adds the base class
+<tt class="docutils literal"><span class="pre">Pseudo</span></tt> for synthetic SPARC instructions.</p>
+<p><tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> largely consists of operand and instruction definitions
+for the SPARC target. In <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>, the following target
+description file entry, <tt class="docutils literal"><span class="pre">LDrr</span></tt>, defines the Load Integer instruction for a
+Word (the <tt class="docutils literal"><span class="pre">LD</span></tt> SPARC opcode) from a memory address to a register. The first
+parameter, the value 3 (<tt class="docutils literal"><span class="pre">11</span></tt><sub>2</sub>), is the operation value for this
+category of operation. The second parameter (<tt class="docutils literal"><span class="pre">000000</span></tt><sub>2</sub>) is the
+specific operation value for <tt class="docutils literal"><span class="pre">LD</span></tt>/Load Word. The third parameter is the
+output destination, which is a register operand and defined in the <tt class="docutils literal"><span class="pre">Register</span></tt>
+target description file (<tt class="docutils literal"><span class="pre">IntRegs</span></tt>).</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def LDrr : F3_1 <3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr),
+ "ld [$addr], $dst",
+ [(set i32:$dst, (load ADDRrr:$addr))]>;
+</pre></div>
+</div>
+<p>The fourth parameter is the input source, which uses the address operand
+<tt class="docutils literal"><span class="pre">MEMrr</span></tt> that is defined earlier in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def MEMrr : Operand<i32> {
+ let PrintMethod = "printMemOperand";
+ let MIOperandInfo = (ops IntRegs, IntRegs);
+}
+</pre></div>
+</div>
+<p>The fifth parameter is a string that is used by the assembly printer and can be
+left as an empty string until the assembly printer interface is implemented.
+The sixth and final parameter is the pattern used to match the instruction
+during the SelectionDAG Select Phase described in <a class="reference internal" href="CodeGenerator.html"><em>The LLVM Target-Independent Code Generator</em></a>.
+This parameter is detailed in the next section, <a class="reference internal" href="#instruction-selector"><em>Instruction Selector</em></a>.</p>
+<p>Instruction class definitions are not overloaded for different operand types,
+so separate versions of instructions are needed for register, memory, or
+immediate value operands. For example, to perform a Load Integer instruction
+for a Word from an immediate operand to a register, the following instruction
+class is defined:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def LDri : F3_2 <3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr),
+ "ld [$addr], $dst",
+ [(set i32:$dst, (load ADDRri:$addr))]>;
+</pre></div>
+</div>
+<p>Writing these definitions for so many similar instructions can involve a lot of
+cut and paste. In <tt class="docutils literal"><span class="pre">.td</span></tt> files, the <tt class="docutils literal"><span class="pre">multiclass</span></tt> directive enables the
+creation of templates to define several instruction classes at once (using the
+<tt class="docutils literal"><span class="pre">defm</span></tt> directive). For example in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>, the <tt class="docutils literal"><span class="pre">multiclass</span></tt>
+pattern <tt class="docutils literal"><span class="pre">F3_12</span></tt> is defined to create 2 instruction classes each time
+<tt class="docutils literal"><span class="pre">F3_12</span></tt> is invoked:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>multiclass F3_12 <string OpcStr, bits<6> Op3Val, SDNode OpNode> {
+ def rr : F3_1 <2, Op3Val,
+ (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
+ !strconcat(OpcStr, " $b, $c, $dst"),
+ [(set i32:$dst, (OpNode i32:$b, i32:$c))]>;
+ def ri : F3_2 <2, Op3Val,
+ (outs IntRegs:$dst), (ins IntRegs:$b, i32imm:$c),
+ !strconcat(OpcStr, " $b, $c, $dst"),
+ [(set i32:$dst, (OpNode i32:$b, simm13:$c))]>;
+}
+</pre></div>
+</div>
+<p>So when the <tt class="docutils literal"><span class="pre">defm</span></tt> directive is used for the <tt class="docutils literal"><span class="pre">XOR</span></tt> and <tt class="docutils literal"><span class="pre">ADD</span></tt>
+instructions, as seen below, it creates four instruction objects: <tt class="docutils literal"><span class="pre">XORrr</span></tt>,
+<tt class="docutils literal"><span class="pre">XORri</span></tt>, <tt class="docutils literal"><span class="pre">ADDrr</span></tt>, and <tt class="docutils literal"><span class="pre">ADDri</span></tt>.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>defm XOR : F3_12<"xor", 0b000011, xor>;
+defm ADD : F3_12<"add", 0b000000, add>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> also includes definitions for condition codes that are
+referenced by branch instructions. The following definitions in
+<tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> indicate the bit location of the SPARC condition code.
+For example, the 10<sup>th</sup> bit represents the “greater than” condition for
+integers, and the 22<sup>nd</sup> bit represents the “greater than” condition for
+floats.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def ICC_NE : ICC_VAL< 9>; // Not Equal
+def ICC_E : ICC_VAL< 1>; // Equal
+def ICC_G : ICC_VAL<10>; // Greater
+...
+def FCC_U : FCC_VAL<23>; // Unordered
+def FCC_G : FCC_VAL<22>; // Greater
+def FCC_UG : FCC_VAL<21>; // Unordered or Greater
+...
+</pre></div>
+</div>
+<p>(Note that <tt class="docutils literal"><span class="pre">Sparc.h</span></tt> also defines enums that correspond to the same SPARC
+condition codes. Care must be taken to ensure the values in <tt class="docutils literal"><span class="pre">Sparc.h</span></tt>
+correspond to the values in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>. I.e., <tt class="docutils literal"><span class="pre">SPCC::ICC_NE</span> <span class="pre">=</span> <span class="pre">9</span></tt>,
+<tt class="docutils literal"><span class="pre">SPCC::FCC_U</span> <span class="pre">=</span> <span class="pre">23</span></tt> and so on.)</p>
+<div class="section" id="instruction-operand-mapping">
+<h3><a class="toc-backref" href="#id15">Instruction Operand Mapping</a><a class="headerlink" href="#instruction-operand-mapping" title="Permalink to this headline">¶</a></h3>
+<p>The code generator backend maps instruction operands to fields in the
+instruction. Operands are assigned to unbound fields in the instruction in the
+order they are defined. Fields are bound when they are assigned a value. For
+example, the Sparc target defines the <tt class="docutils literal"><span class="pre">XNORrr</span></tt> instruction as a <tt class="docutils literal"><span class="pre">F3_1</span></tt>
+format instruction having three operands.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def XNORrr : F3_1<2, 0b000111,
+ (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
+ "xnor $b, $c, $dst",
+ [(set i32:$dst, (not (xor i32:$b, i32:$c)))]>;
+</pre></div>
+</div>
+<p>The instruction templates in <tt class="docutils literal"><span class="pre">SparcInstrFormats.td</span></tt> show the base class for
+<tt class="docutils literal"><span class="pre">F3_1</span></tt> is <tt class="docutils literal"><span class="pre">InstSP</span></tt>.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class InstSP<dag outs, dag ins, string asmstr, list<dag> pattern> : Instruction {
+ field bits<32> Inst;
+ let Namespace = "SP";
+ bits<2> op;
+ let Inst{31-30} = op;
+ dag OutOperandList = outs;
+ dag InOperandList = ins;
+ let AsmString = asmstr;
+ let Pattern = pattern;
+}
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">InstSP</span></tt> leaves the <tt class="docutils literal"><span class="pre">op</span></tt> field unbound.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class F3<dag outs, dag ins, string asmstr, list<dag> pattern>
+ : InstSP<outs, ins, asmstr, pattern> {
+ bits<5> rd;
+ bits<6> op3;
+ bits<5> rs1;
+ let op{1} = 1; // Op = 2 or 3
+ let Inst{29-25} = rd;
+ let Inst{24-19} = op3;
+ let Inst{18-14} = rs1;
+}
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">F3</span></tt> binds the <tt class="docutils literal"><span class="pre">op</span></tt> field and defines the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">op3</span></tt>, and <tt class="docutils literal"><span class="pre">rs1</span></tt>
+fields. <tt class="docutils literal"><span class="pre">F3</span></tt> format instructions will bind the operands <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">op3</span></tt>, and
+<tt class="docutils literal"><span class="pre">rs1</span></tt> fields.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class F3_1<bits<2> opVal, bits<6> op3val, dag outs, dag ins,
+ string asmstr, list<dag> pattern> : F3<outs, ins, asmstr, pattern> {
+ bits<8> asi = 0; // asi not currently used
+ bits<5> rs2;
+ let op = opVal;
+ let op3 = op3val;
+ let Inst{13} = 0; // i field = 0
+ let Inst{12-5} = asi; // address space identifier
+ let Inst{4-0} = rs2;
+}
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">F3_1</span></tt> binds the <tt class="docutils literal"><span class="pre">op3</span></tt> field and defines the <tt class="docutils literal"><span class="pre">rs2</span></tt> fields. <tt class="docutils literal"><span class="pre">F3_1</span></tt>
+format instructions will bind the operands to the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">rs1</span></tt>, and <tt class="docutils literal"><span class="pre">rs2</span></tt>
+fields. This results in the <tt class="docutils literal"><span class="pre">XNORrr</span></tt> instruction binding <tt class="docutils literal"><span class="pre">$dst</span></tt>, <tt class="docutils literal"><span class="pre">$b</span></tt>,
+and <tt class="docutils literal"><span class="pre">$c</span></tt> operands to the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">rs1</span></tt>, and <tt class="docutils literal"><span class="pre">rs2</span></tt> fields respectively.</p>
+<div class="section" id="instruction-operand-name-mapping">
+<h4><a class="toc-backref" href="#id16">Instruction Operand Name Mapping</a><a class="headerlink" href="#instruction-operand-name-mapping" title="Permalink to this headline">¶</a></h4>
+<p>TableGen will also generate a function called getNamedOperandIdx() which
+can be used to look up an operand’s index in a MachineInstr based on its
+TableGen name. Setting the UseNamedOperandTable bit in an instruction’s
+TableGen definition will add all of its operands to an enumeration in the
+llvm::XXX:OpName namespace and also add an entry for it into the OperandMap
+table, which can be queried using getNamedOperandIdx()</p>
+<div class="highlight-llvm"><div class="highlight"><pre>int DstIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::dst); // => 0
+int BIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::b); // => 1
+int CIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::c); // => 2
+int DIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::d); // => -1
+
+...
+</pre></div>
+</div>
+<p>The entries in the OpName enum are taken verbatim from the TableGen definitions,
+so operands with lowercase names will have lower case entries in the enum.</p>
+<p>To include the getNamedOperandIdx() function in your backend, you will need
+to define a few preprocessor macros in XXXInstrInfo.cpp and XXXInstrInfo.h.
+For example:</p>
+<p>XXXInstrInfo.cpp:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_INSTRINFO_NAMED_OPS </span><span class="c1">// For getNamedOperandIdx() function</span>
+<span class="cp">#include "XXXGenInstrInfo.inc"</span>
+</pre></div>
+</div>
+<p>XXXInstrInfo.h:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_INSTRINFO_OPERAND_ENUM </span><span class="c1">// For OpName enum</span>
+<span class="cp">#include "XXXGenInstrInfo.inc"</span>
+
+<span class="k">namespace</span> <span class="n">XXX</span> <span class="p">{</span>
+ <span class="kt">int16_t</span> <span class="n">getNamedOperandIdx</span><span class="p">(</span><span class="kt">uint16_t</span> <span class="n">Opcode</span><span class="p">,</span> <span class="kt">uint16_t</span> <span class="n">NamedIndex</span><span class="p">);</span>
+<span class="p">}</span> <span class="c1">// End namespace XXX</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="instruction-operand-types">
+<h4><a class="toc-backref" href="#id17">Instruction Operand Types</a><a class="headerlink" href="#instruction-operand-types" title="Permalink to this headline">¶</a></h4>
+<p>TableGen will also generate an enumeration consisting of all named Operand
+types defined in the backend, in the llvm::XXX::OpTypes namespace.
+Some common immediate Operand types (for instance i8, i32, i64, f32, f64)
+are defined for all targets in <tt class="docutils literal"><span class="pre">include/llvm/Target/Target.td</span></tt>, and are
+available in each Target’s OpTypes enum. Also, only named Operand types appear
+in the enumeration: anonymous types are ignored.
+For example, the X86 backend defines <tt class="docutils literal"><span class="pre">brtarget</span></tt> and <tt class="docutils literal"><span class="pre">brtarget8</span></tt>, both
+instances of the TableGen <tt class="docutils literal"><span class="pre">Operand</span></tt> class, which represent branch target
+operands:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def brtarget : Operand<OtherVT>;
+def brtarget8 : Operand<OtherVT>;
+</pre></div>
+</div>
+<p>This results in:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">X86</span> <span class="p">{</span>
+<span class="k">namespace</span> <span class="n">OpTypes</span> <span class="p">{</span>
+<span class="k">enum</span> <span class="n">OperandType</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="n">brtarget</span><span class="p">,</span>
+ <span class="n">brtarget8</span><span class="p">,</span>
+ <span class="p">...</span>
+ <span class="n">i32imm</span><span class="p">,</span>
+ <span class="n">i64imm</span><span class="p">,</span>
+ <span class="p">...</span>
+ <span class="n">OPERAND_TYPE_LIST_END</span>
+<span class="p">}</span> <span class="c1">// End namespace OpTypes</span>
+<span class="p">}</span> <span class="c1">// End namespace X86</span>
+</pre></div>
+</div>
+<p>In typical TableGen fashion, to use the enum, you will need to define a
+preprocessor macro:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_INSTRINFO_OPERAND_TYPES_ENUM </span><span class="c1">// For OpTypes enum</span>
+<span class="cp">#include "XXXGenInstrInfo.inc"</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="instruction-scheduling">
+<h3><a class="toc-backref" href="#id18">Instruction Scheduling</a><a class="headerlink" href="#instruction-scheduling" title="Permalink to this headline">¶</a></h3>
+<p>Instruction itineraries can be queried using MCDesc::getSchedClass(). The
+value can be named by an enumemation in llvm::XXX::Sched namespace generated
+by TableGen in XXXGenInstrInfo.inc. The name of the schedule classes are
+the same as provided in XXXSchedule.td plus a default NoItinerary class.</p>
+</div>
+<div class="section" id="instruction-relation-mapping">
+<h3><a class="toc-backref" href="#id19">Instruction Relation Mapping</a><a class="headerlink" href="#instruction-relation-mapping" title="Permalink to this headline">¶</a></h3>
+<p>This TableGen feature is used to relate instructions with each other. It is
+particularly useful when you have multiple instruction formats and need to
+switch between them after instruction selection. This entire feature is driven
+by relation models which can be defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> files
+according to the target-specific instruction set. Relation models are defined
+using <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> class as a base. TableGen parses all the models
+and generates instruction relation maps using the specified information.
+Relation maps are emitted as tables in the <tt class="docutils literal"><span class="pre">XXXGenInstrInfo.inc</span></tt> file
+along with the functions to query them. For the detailed information on how to
+use this feature, please refer to <a class="reference internal" href="HowToUseInstrMappings.html"><em>How To Use Instruction Mappings</em></a>.</p>
+</div>
+<div class="section" id="implement-a-subclass-of-targetinstrinfo">
+<h3><a class="toc-backref" href="#id20">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt></a><a class="headerlink" href="#implement-a-subclass-of-targetinstrinfo" title="Permalink to this headline">¶</a></h3>
+<p>The final step is to hand code portions of <tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt>, which implements
+the interface described in <tt class="docutils literal"><span class="pre">TargetInstrInfo.h</span></tt> (see <a class="reference internal" href="CodeGenerator.html#targetinstrinfo"><em>The TargetInstrInfo class</em></a>).
+These functions return <tt class="docutils literal"><span class="pre">0</span></tt> or a Boolean or they assert, unless overridden.
+Here’s a list of functions that are overridden for the SPARC implementation in
+<tt class="docutils literal"><span class="pre">SparcInstrInfo.cpp</span></tt>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">isLoadFromStackSlot</span></tt> — If the specified machine instruction is a direct
+load from a stack slot, return the register number of the destination and the
+<tt class="docutils literal"><span class="pre">FrameIndex</span></tt> of the stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">isStoreToStackSlot</span></tt> — If the specified machine instruction is a direct
+store to a stack slot, return the register number of the destination and the
+<tt class="docutils literal"><span class="pre">FrameIndex</span></tt> of the stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">copyPhysReg</span></tt> — Copy values between a pair of physical registers.</li>
+<li><tt class="docutils literal"><span class="pre">storeRegToStackSlot</span></tt> — Store a register value to a stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">loadRegFromStackSlot</span></tt> — Load a register value from a stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">storeRegToAddr</span></tt> — Store a register value to memory.</li>
+<li><tt class="docutils literal"><span class="pre">loadRegFromAddr</span></tt> — Load a register value from memory.</li>
+<li><tt class="docutils literal"><span class="pre">foldMemoryOperand</span></tt> — Attempt to combine instructions of any load or
+store instruction for the specified operand(s).</li>
+</ul>
+</div>
+<div class="section" id="branch-folding-and-if-conversion">
+<h3><a class="toc-backref" href="#id21">Branch Folding and If Conversion</a><a class="headerlink" href="#branch-folding-and-if-conversion" title="Permalink to this headline">¶</a></h3>
+<p>Performance can be improved by combining instructions or by eliminating
+instructions that are never reached. The <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> method in
+<tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> may be implemented to examine conditional instructions and
+remove unnecessary instructions. <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> looks at the end of a
+machine basic block (MBB) for opportunities for improvement, such as branch
+folding and if conversion. The <tt class="docutils literal"><span class="pre">BranchFolder</span></tt> and <tt class="docutils literal"><span class="pre">IfConverter</span></tt> machine
+function passes (see the source files <tt class="docutils literal"><span class="pre">BranchFolding.cpp</span></tt> and
+<tt class="docutils literal"><span class="pre">IfConversion.cpp</span></tt> in the <tt class="docutils literal"><span class="pre">lib/CodeGen</span></tt> directory) call <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>
+to improve the control flow graph that represents the instructions.</p>
+<p>Several implementations of <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (for ARM, Alpha, and X86) can be
+examined as models for your own <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> implementation. Since SPARC
+does not implement a useful <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>, the ARM target implementation is
+shown below.</p>
+<p><tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> returns a Boolean value and takes four parameters:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">&MBB</span></tt> — The incoming block to be examined.</li>
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">*&TBB</span></tt> — A destination block that is returned. For a
+conditional branch that evaluates to true, <tt class="docutils literal"><span class="pre">TBB</span></tt> is the destination.</li>
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">*&FBB</span></tt> — For a conditional branch that evaluates to
+false, <tt class="docutils literal"><span class="pre">FBB</span></tt> is returned as the destination.</li>
+<li><tt class="docutils literal"><span class="pre">std::vector<MachineOperand></span> <span class="pre">&Cond</span></tt> — List of operands to evaluate a
+condition for a conditional branch.</li>
+</ul>
+<p>In the simplest case, if a block ends without a branch, then it falls through
+to the successor block. No destination blocks are specified for either <tt class="docutils literal"><span class="pre">TBB</span></tt>
+or <tt class="docutils literal"><span class="pre">FBB</span></tt>, so both parameters return <tt class="docutils literal"><span class="pre">NULL</span></tt>. The start of the
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (see code below for the ARM target) shows the function
+parameters and the code for the simplest case.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">ARMInstrInfo</span><span class="o">::</span><span class="n">AnalyzeBranch</span><span class="p">(</span><span class="n">MachineBasicBlock</span> <span class="o">&</span><span class="n">MBB</span><span class="p">,</span>
+ <span class="n">MachineBasicBlock</span> <span class="o">*&</span><span class="n">TBB</span><span class="p">,</span>
+ <span class="n">MachineBasicBlock</span> <span class="o">*&</span><span class="n">FBB</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">MachineOperand</span><span class="o">></span> <span class="o">&</span><span class="n">Cond</span><span class="p">)</span> <span class="k">const</span>
+<span class="p">{</span>
+ <span class="n">MachineBasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">MBB</span><span class="p">.</span><span class="n">end</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">I</span> <span class="o">==</span> <span class="n">MBB</span><span class="p">.</span><span class="n">begin</span><span class="p">()</span> <span class="o">||</span> <span class="o">!</span><span class="n">isUnpredicatedTerminator</span><span class="p">(</span><span class="o">--</span><span class="n">I</span><span class="p">))</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>If a block ends with a single unconditional branch instruction, then
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the destination of that branch in
+the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If a block ends with two unconditional branches, then the second branch is
+never reached. In that situation, as shown below, remove the last branch
+instruction and return the penultimate branch in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">((</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">I</span> <span class="o">=</span> <span class="n">LastInst</span><span class="p">;</span>
+ <span class="n">I</span><span class="o">-></span><span class="n">eraseFromParent</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A block may end with a single conditional branch instruction that falls through
+to successor block if the condition evaluates to false. In that case,
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the destination of that
+conditional branch in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter and a list of operands in the
+<tt class="docutils literal"><span class="pre">Cond</span></tt> parameter to evaluate the condition.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">Bcc</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tBcc</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Block ends with fall-through condbranch.</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If a block ends with both a conditional branch and an ensuing unconditional
+branch, then <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the conditional
+branch destination (assuming it corresponds to a conditional evaluation of
+“<tt class="docutils literal"><span class="pre">true</span></tt>”) in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter and the unconditional branch destination
+in the <tt class="docutils literal"><span class="pre">FBB</span></tt> (corresponding to a conditional evaluation of “<tt class="docutils literal"><span class="pre">false</span></tt>”). A
+list of operands to evaluate the condition should be returned in the <tt class="docutils literal"><span class="pre">Cond</span></tt>
+parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">unsigned</span> <span class="n">SecondLastOpc</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOpcode</span><span class="p">();</span>
+
+<span class="k">if</span> <span class="p">((</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">Bcc</span> <span class="o">&&</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span><span class="p">)</span> <span class="o">||</span>
+ <span class="p">(</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tBcc</span> <span class="o">&&</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
+ <span class="n">FBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For the last two cases (ending with a single conditional branch or ending with
+one conditional and one unconditional branch), the operands returned in the
+<tt class="docutils literal"><span class="pre">Cond</span></tt> parameter can be passed to methods of other instructions to create new
+branches or perform other operations. An implementation of <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>
+requires the helper methods <tt class="docutils literal"><span class="pre">RemoveBranch</span></tt> and <tt class="docutils literal"><span class="pre">InsertBranch</span></tt> to manage
+subsequent operations.</p>
+<p><tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> should return false indicating success in most circumstances.
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> should only return true when the method is stumped about what
+to do, for example, if a block has three terminating branches.
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> may return true if it encounters a terminator it cannot
+handle, such as an indirect branch.</p>
+</div>
+</div>
+<div class="section" id="instruction-selector">
+<span id="id2"></span><h2><a class="toc-backref" href="#id22">Instruction Selector</a><a class="headerlink" href="#instruction-selector" title="Permalink to this headline">¶</a></h2>
+<p>LLVM uses a <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> to represent LLVM IR instructions, and nodes of
+the <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> ideally represent native target instructions. During code
+generation, instruction selection passes are performed to convert non-native
+DAG instructions into native target-specific instructions. The pass described
+in <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt> is used to match patterns and perform DAG-to-DAG
+instruction selection. Optionally, a pass may be defined (in
+<tt class="docutils literal"><span class="pre">XXXBranchSelector.cpp</span></tt>) to perform similar DAG-to-DAG operations for branch
+instructions. Later, the code in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt> replaces or removes
+operations and data types not supported natively (legalizes) in a
+<tt class="docutils literal"><span class="pre">SelectionDAG</span></tt>.</p>
+<p>TableGen generates code for instruction selection using the following target
+description input files:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> — Contains definitions of instructions in a
+target-specific instruction set, generates <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>, which is
+included in <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">XXXCallingConv.td</span></tt> — Contains the calling and return value conventions
+for the target architecture, and it generates <tt class="docutils literal"><span class="pre">XXXGenCallingConv.inc</span></tt>,
+which is included in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>.</li>
+</ul>
+<p>The implementation of an instruction selection pass must include a header that
+declares the <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> class or a subclass of <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>. In
+<tt class="docutils literal"><span class="pre">XXXTargetMachine.cpp</span></tt>, a Pass Manager (PM) should add each instruction
+selection pass into the queue of passes to run.</p>
+<p>The LLVM static compiler (<tt class="docutils literal"><span class="pre">llc</span></tt>) is an excellent tool for visualizing the
+contents of DAGs. To display the <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> before or after specific
+processing phases, use the command line options for <tt class="docutils literal"><span class="pre">llc</span></tt>, described at
+<a class="reference internal" href="CodeGenerator.html#selectiondag-process"><em>SelectionDAG Instruction Selection Process</em></a>.</p>
+<p>To describe instruction selector behavior, you should add patterns for lowering
+LLVM code into a <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> as the last parameter of the instruction
+definitions in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt>. For example, in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>,
+this entry defines a register store operation, and the last parameter describes
+a pattern with the store DAG operator.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def STrr : F3_1< 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src),
+ "st $src, [$addr]", [(store i32:$src, ADDRrr:$addr)]>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">ADDRrr</span></tt> is a memory mode that is also defined in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def ADDRrr : ComplexPattern<i32, 2, "SelectADDRrr", [], []>;
+</pre></div>
+</div>
+<p>The definition of <tt class="docutils literal"><span class="pre">ADDRrr</span></tt> refers to <tt class="docutils literal"><span class="pre">SelectADDRrr</span></tt>, which is a function
+defined in an implementation of the Instructor Selector (such as
+<tt class="docutils literal"><span class="pre">SparcISelDAGToDAG.cpp</span></tt>).</p>
+<p>In <tt class="docutils literal"><span class="pre">lib/Target/TargetSelectionDAG.td</span></tt>, the DAG operator for store is defined
+below:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def store : PatFrag<(ops node:$val, node:$ptr),
+ (st node:$val, node:$ptr), [{
+ if (StoreSDNode *ST = dyn_cast<StoreSDNode>(N))
+ return !ST->isTruncatingStore() &&
+ ST->getAddressingMode() == ISD::UNINDEXED;
+ return false;
+}]>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> also generates (in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>) the
+<tt class="docutils literal"><span class="pre">SelectCode</span></tt> method that is used to call the appropriate processing method
+for an instruction. In this example, <tt class="docutils literal"><span class="pre">SelectCode</span></tt> calls <tt class="docutils literal"><span class="pre">Select_ISD_STORE</span></tt>
+for the <tt class="docutils literal"><span class="pre">ISD::STORE</span></tt> opcode.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDNode</span> <span class="o">*</span><span class="nf">SelectCode</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">N</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="n">MVT</span><span class="o">::</span><span class="n">ValueType</span> <span class="n">NVT</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">N</span><span class="p">.</span><span class="n">getOpcode</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">ISD</span>:<span class="o">:</span><span class="n">STORE</span><span class="o">:</span> <span class="p">{</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">NVT</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nl">default:</span>
+ <span class="k">return</span> <span class="n">Select_ISD_STORE</span><span class="p">(</span><span class="n">N</span><span class="p">);</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+<p>The pattern for <tt class="docutils literal"><span class="pre">STrr</span></tt> is matched, so elsewhere in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>,
+code for <tt class="docutils literal"><span class="pre">STrr</span></tt> is created for <tt class="docutils literal"><span class="pre">Select_ISD_STORE</span></tt>. The <tt class="docutils literal"><span class="pre">Emit_22</span></tt> method
+is also generated in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt> to complete the processing of this
+instruction.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDNode</span> <span class="o">*</span><span class="nf">Select_ISD_STORE</span><span class="p">(</span><span class="k">const</span> <span class="n">SDValue</span> <span class="o">&</span><span class="n">N</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">SDValue</span> <span class="n">Chain</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Predicate_store</span><span class="p">(</span><span class="n">N</span><span class="p">.</span><span class="n">getNode</span><span class="p">()))</span> <span class="p">{</span>
+ <span class="n">SDValue</span> <span class="n">N1</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+ <span class="n">SDValue</span> <span class="n">N2</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span>
+ <span class="n">SDValue</span> <span class="n">CPTmp0</span><span class="p">;</span>
+ <span class="n">SDValue</span> <span class="n">CPTmp1</span><span class="p">;</span>
+
+ <span class="c1">// Pattern: (st:void i32:i32:$src,</span>
+ <span class="c1">// ADDRrr:i32:$addr)<<P:Predicate_store>></span>
+ <span class="c1">// Emits: (STrr:void ADDRrr:i32:$addr, IntRegs:i32:$src)</span>
+ <span class="c1">// Pattern complexity = 13 cost = 1 size = 0</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">SelectADDRrr</span><span class="p">(</span><span class="n">N</span><span class="p">,</span> <span class="n">N2</span><span class="p">,</span> <span class="n">CPTmp0</span><span class="p">,</span> <span class="n">CPTmp1</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="n">N1</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span> <span class="o">&&</span>
+ <span class="n">N2</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">Emit_22</span><span class="p">(</span><span class="n">N</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">STrr</span><span class="p">,</span> <span class="n">CPTmp0</span><span class="p">,</span> <span class="n">CPTmp1</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<div class="section" id="the-selectiondag-legalize-phase">
+<h3><a class="toc-backref" href="#id23">The SelectionDAG Legalize Phase</a><a class="headerlink" href="#the-selectiondag-legalize-phase" title="Permalink to this headline">¶</a></h3>
+<p>The Legalize phase converts a DAG to use types and operations that are natively
+supported by the target. For natively unsupported types and operations, you
+need to add code to the target-specific <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> implementation to
+convert unsupported types and operations to supported ones.</p>
+<p>In the constructor for the <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> class, first use the
+<tt class="docutils literal"><span class="pre">addRegisterClass</span></tt> method to specify which types are supported and which
+register classes are associated with them. The code for the register classes
+are generated by TableGen from <tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> and placed in
+<tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.h.inc</span></tt>. For example, the implementation of the
+constructor for the SparcTargetLowering class (in <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt>)
+starts with the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">IntRegsRegisterClass</span><span class="p">);</span>
+<span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">FPRegsRegisterClass</span><span class="p">);</span>
+<span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">f64</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">DFPRegsRegisterClass</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>You should examine the node types in the <tt class="docutils literal"><span class="pre">ISD</span></tt> namespace
+(<tt class="docutils literal"><span class="pre">include/llvm/CodeGen/SelectionDAGNodes.h</span></tt>) and determine which operations
+the target natively supports. For operations that do <strong>not</strong> have native
+support, add a callback to the constructor for the <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> class,
+so the instruction selection process knows what to do. The <tt class="docutils literal"><span class="pre">TargetLowering</span></tt>
+class callback methods (declared in <tt class="docutils literal"><span class="pre">llvm/Target/TargetLowering.h</span></tt>) are:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">setOperationAction</span></tt> — General operation.</li>
+<li><tt class="docutils literal"><span class="pre">setLoadExtAction</span></tt> — Load with extension.</li>
+<li><tt class="docutils literal"><span class="pre">setTruncStoreAction</span></tt> — Truncating store.</li>
+<li><tt class="docutils literal"><span class="pre">setIndexedLoadAction</span></tt> — Indexed load.</li>
+<li><tt class="docutils literal"><span class="pre">setIndexedStoreAction</span></tt> — Indexed store.</li>
+<li><tt class="docutils literal"><span class="pre">setConvertAction</span></tt> — Type conversion.</li>
+<li><tt class="docutils literal"><span class="pre">setCondCodeAction</span></tt> — Support for a given condition code.</li>
+</ul>
+<p>Note: on older releases, <tt class="docutils literal"><span class="pre">setLoadXAction</span></tt> is used instead of
+<tt class="docutils literal"><span class="pre">setLoadExtAction</span></tt>. Also, on older releases, <tt class="docutils literal"><span class="pre">setCondCodeAction</span></tt> may not
+be supported. Examine your release to see what methods are specifically
+supported.</p>
+<p>These callbacks are used to determine that an operation does or does not work
+with a specified type (or types). And in all cases, the third parameter is a
+<tt class="docutils literal"><span class="pre">LegalAction</span></tt> type enum value: <tt class="docutils literal"><span class="pre">Promote</span></tt>, <tt class="docutils literal"><span class="pre">Expand</span></tt>, <tt class="docutils literal"><span class="pre">Custom</span></tt>, or
+<tt class="docutils literal"><span class="pre">Legal</span></tt>. <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> contains examples of all four
+<tt class="docutils literal"><span class="pre">LegalAction</span></tt> values.</p>
+<div class="section" id="promote">
+<h4><a class="toc-backref" href="#id24">Promote</a><a class="headerlink" href="#promote" title="Permalink to this headline">¶</a></h4>
+<p>For an operation without native support for a given type, the specified type
+may be promoted to a larger type that is supported. For example, SPARC does
+not support a sign-extending load for Boolean values (<tt class="docutils literal"><span class="pre">i1</span></tt> type), so in
+<tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> the third parameter below, <tt class="docutils literal"><span class="pre">Promote</span></tt>, changes
+<tt class="docutils literal"><span class="pre">i1</span></tt> type values to a large type before loading.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setLoadExtAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">SEXTLOAD</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i1</span><span class="p">,</span> <span class="n">Promote</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="expand">
+<h4><a class="toc-backref" href="#id25">Expand</a><a class="headerlink" href="#expand" title="Permalink to this headline">¶</a></h4>
+<p>For a type without native support, a value may need to be broken down further,
+rather than promoted. For an operation without native support, a combination
+of other operations may be used to similar effect. In SPARC, the
+floating-point sine and cosine trig operations are supported by expansion to
+other operations, as indicated by the third parameter, <tt class="docutils literal"><span class="pre">Expand</span></tt>, to
+<tt class="docutils literal"><span class="pre">setOperationAction</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FSIN</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+<span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FCOS</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="custom">
+<h4><a class="toc-backref" href="#id26">Custom</a><a class="headerlink" href="#custom" title="Permalink to this headline">¶</a></h4>
+<p>For some operations, simple type promotion or operation expansion may be
+insufficient. In some cases, a special intrinsic function must be implemented.</p>
+<p>For example, a constant value may require special treatment, or an operation
+may require spilling and restoring registers in the stack and working with
+register allocators.</p>
+<p>As seen in <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> code below, to perform a type conversion
+from a floating point value to a signed integer, first the
+<tt class="docutils literal"><span class="pre">setOperationAction</span></tt> should be called with <tt class="docutils literal"><span class="pre">Custom</span></tt> as the third parameter:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FP_TO_SINT</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Custom</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">LowerOperation</span></tt> method, for each <tt class="docutils literal"><span class="pre">Custom</span></tt> operation, a case
+statement should be added to indicate what function to call. In the following
+code, an <tt class="docutils literal"><span class="pre">FP_TO_SINT</span></tt> opcode will call the <tt class="docutils literal"><span class="pre">LowerFP_TO_SINT</span></tt> method:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDValue</span> <span class="n">SparcTargetLowering</span><span class="o">::</span><span class="n">LowerOperation</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">Op</span><span class="p">,</span> <span class="n">SelectionDAG</span> <span class="o">&</span><span class="n">DAG</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">Op</span><span class="p">.</span><span class="n">getOpcode</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">ISD</span>:<span class="o">:</span><span class="n">FP_TO_SINT</span><span class="o">:</span> <span class="k">return</span> <span class="n">LowerFP_TO_SINT</span><span class="p">(</span><span class="n">Op</span><span class="p">,</span> <span class="n">DAG</span><span class="p">);</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Finally, the <tt class="docutils literal"><span class="pre">LowerFP_TO_SINT</span></tt> method is implemented, using an FP register to
+convert the floating-point value to an integer.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">SDValue</span> <span class="nf">LowerFP_TO_SINT</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">Op</span><span class="p">,</span> <span class="n">SelectionDAG</span> <span class="o">&</span><span class="n">DAG</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Op</span><span class="p">.</span><span class="n">getValueType</span><span class="p">()</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">);</span>
+ <span class="n">Op</span> <span class="o">=</span> <span class="n">DAG</span><span class="p">.</span><span class="n">getNode</span><span class="p">(</span><span class="n">SPISD</span><span class="o">::</span><span class="n">FTOI</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Op</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span>
+ <span class="k">return</span> <span class="n">DAG</span><span class="p">.</span><span class="n">getNode</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">BITCAST</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Op</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="legal">
+<h4><a class="toc-backref" href="#id27">Legal</a><a class="headerlink" href="#legal" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">Legal</span></tt> <tt class="docutils literal"><span class="pre">LegalizeAction</span></tt> enum value simply indicates that an operation
+<strong>is</strong> natively supported. <tt class="docutils literal"><span class="pre">Legal</span></tt> represents the default condition, so it
+is rarely used. In <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt>, the action for <tt class="docutils literal"><span class="pre">CTPOP</span></tt> (an
+operation to count the bits set in an integer) is natively supported only for
+SPARC v9. The following code enables the <tt class="docutils literal"><span class="pre">Expand</span></tt> conversion technique for
+non-v9 SPARC implementations.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">CTPOP</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+<span class="p">...</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">TM</span><span class="p">.</span><span class="n">getSubtarget</span><span class="o"><</span><span class="n">SparcSubtarget</span><span class="o">></span><span class="p">().</span><span class="n">isV9</span><span class="p">())</span>
+ <span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">CTPOP</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Legal</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="calling-conventions">
+<h3><a class="toc-backref" href="#id28">Calling Conventions</a><a class="headerlink" href="#calling-conventions" title="Permalink to this headline">¶</a></h3>
+<p>To support target-specific calling conventions, <tt class="docutils literal"><span class="pre">XXXGenCallingConv.td</span></tt> uses
+interfaces (such as <tt class="docutils literal"><span class="pre">CCIfType</span></tt> and <tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt>) that are defined in
+<tt class="docutils literal"><span class="pre">lib/Target/TargetCallingConv.td</span></tt>. TableGen can take the target descriptor
+file <tt class="docutils literal"><span class="pre">XXXGenCallingConv.td</span></tt> and generate the header file
+<tt class="docutils literal"><span class="pre">XXXGenCallingConv.inc</span></tt>, which is typically included in
+<tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>. You can use the interfaces in
+<tt class="docutils literal"><span class="pre">TargetCallingConv.td</span></tt> to specify:</p>
+<ul class="simple">
+<li>The order of parameter allocation.</li>
+<li>Where parameters and return values are placed (that is, on the stack or in
+registers).</li>
+<li>Which registers may be used.</li>
+<li>Whether the caller or callee unwinds the stack.</li>
+</ul>
+<p>The following example demonstrates the use of the <tt class="docutils literal"><span class="pre">CCIfType</span></tt> and
+<tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt> interfaces. If the <tt class="docutils literal"><span class="pre">CCIfType</span></tt> predicate is true (that is,
+if the current argument is of type <tt class="docutils literal"><span class="pre">f32</span></tt> or <tt class="docutils literal"><span class="pre">f64</span></tt>), then the action is
+performed. In this case, the <tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt> action assigns the argument
+value to the first available register: either <tt class="docutils literal"><span class="pre">R0</span></tt> or <tt class="docutils literal"><span class="pre">R1</span></tt>.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>CCIfType<[f32,f64], CCAssignToReg<[R0, R1]>>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">SparcCallingConv.td</span></tt> contains definitions for a target-specific return-value
+calling convention (<tt class="docutils literal"><span class="pre">RetCC_Sparc32</span></tt>) and a basic 32-bit C calling convention
+(<tt class="docutils literal"><span class="pre">CC_Sparc32</span></tt>). The definition of <tt class="docutils literal"><span class="pre">RetCC_Sparc32</span></tt> (shown below) indicates
+which registers are used for specified scalar return types. A single-precision
+float is returned to register <tt class="docutils literal"><span class="pre">F0</span></tt>, and a double-precision float goes to
+register <tt class="docutils literal"><span class="pre">D0</span></tt>. A 32-bit integer is returned in register <tt class="docutils literal"><span class="pre">I0</span></tt> or <tt class="docutils literal"><span class="pre">I1</span></tt>.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def RetCC_Sparc32 : CallingConv<[
+ CCIfType<[i32], CCAssignToReg<[I0, I1]>>,
+ CCIfType<[f32], CCAssignToReg<[F0]>>,
+ CCIfType<[f64], CCAssignToReg<[D0]>>
+]>;
+</pre></div>
+</div>
+<p>The definition of <tt class="docutils literal"><span class="pre">CC_Sparc32</span></tt> in <tt class="docutils literal"><span class="pre">SparcCallingConv.td</span></tt> introduces
+<tt class="docutils literal"><span class="pre">CCAssignToStack</span></tt>, which assigns the value to a stack slot with the specified
+size and alignment. In the example below, the first parameter, 4, indicates
+the size of the slot, and the second parameter, also 4, indicates the stack
+alignment along 4-byte units. (Special cases: if size is zero, then the ABI
+size is used; if alignment is zero, then the ABI alignment is used.)</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def CC_Sparc32 : CallingConv<[
+ // All arguments get passed in integer registers if there is space.
+ CCIfType<[i32, f32, f64], CCAssignToReg<[I0, I1, I2, I3, I4, I5]>>,
+ CCAssignToStack<4, 4>
+]>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">CCDelegateTo</span></tt> is another commonly used interface, which tries to find a
+specified sub-calling convention, and, if a match is found, it is invoked. In
+the following example (in <tt class="docutils literal"><span class="pre">X86CallingConv.td</span></tt>), the definition of
+<tt class="docutils literal"><span class="pre">RetCC_X86_32_C</span></tt> ends with <tt class="docutils literal"><span class="pre">CCDelegateTo</span></tt>. After the current value is
+assigned to the register <tt class="docutils literal"><span class="pre">ST0</span></tt> or <tt class="docutils literal"><span class="pre">ST1</span></tt>, the <tt class="docutils literal"><span class="pre">RetCC_X86Common</span></tt> is
+invoked.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def RetCC_X86_32_C : CallingConv<[
+ CCIfType<[f32], CCAssignToReg<[ST0, ST1]>>,
+ CCIfType<[f64], CCAssignToReg<[ST0, ST1]>>,
+ CCDelegateTo<RetCC_X86Common>
+]>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">CCIfCC</span></tt> is an interface that attempts to match the given name to the current
+calling convention. If the name identifies the current calling convention,
+then a specified action is invoked. In the following example (in
+<tt class="docutils literal"><span class="pre">X86CallingConv.td</span></tt>), if the <tt class="docutils literal"><span class="pre">Fast</span></tt> calling convention is in use, then
+<tt class="docutils literal"><span class="pre">RetCC_X86_32_Fast</span></tt> is invoked. If the <tt class="docutils literal"><span class="pre">SSECall</span></tt> calling convention is in
+use, then <tt class="docutils literal"><span class="pre">RetCC_X86_32_SSE</span></tt> is invoked.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def RetCC_X86_32 : CallingConv<[
+ CCIfCC<"CallingConv::Fast", CCDelegateTo<RetCC_X86_32_Fast>>,
+ CCIfCC<"CallingConv::X86_SSECall", CCDelegateTo<RetCC_X86_32_SSE>>,
+ CCDelegateTo<RetCC_X86_32_C>
+]>;
+</pre></div>
+</div>
+<p>Other calling convention interfaces include:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">CCIf</span> <span class="pre"><predicate,</span> <span class="pre">action></span></tt> — If the predicate matches, apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfInReg</span> <span class="pre"><action></span></tt> — If the argument is marked with the “<tt class="docutils literal"><span class="pre">inreg</span></tt>”
+attribute, then apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfNest</span> <span class="pre"><action></span></tt> — If the argument is marked with the “<tt class="docutils literal"><span class="pre">nest</span></tt>”
+attribute, then apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfNotVarArg</span> <span class="pre"><action></span></tt> — If the current function does not take a
+variable number of arguments, apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCAssignToRegWithShadow</span> <span class="pre"><registerList,</span> <span class="pre">shadowList></span></tt> — similar to
+<tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt>, but with a shadow list of registers.</li>
+<li><tt class="docutils literal"><span class="pre">CCPassByVal</span> <span class="pre"><size,</span> <span class="pre">align></span></tt> — Assign value to a stack slot with the
+minimum specified size and alignment.</li>
+<li><tt class="docutils literal"><span class="pre">CCPromoteToType</span> <span class="pre"><type></span></tt> — Promote the current value to the specified
+type.</li>
+<li><tt class="docutils literal"><span class="pre">CallingConv</span> <span class="pre"><[actions]></span></tt> — Define each calling convention that is
+supported.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="assembly-printer">
+<h2><a class="toc-backref" href="#id29">Assembly Printer</a><a class="headerlink" href="#assembly-printer" title="Permalink to this headline">¶</a></h2>
+<p>During the code emission stage, the code generator may utilize an LLVM pass to
+produce assembly output. To do this, you want to implement the code for a
+printer that converts LLVM IR to a GAS-format assembly language for your target
+machine, using the following steps:</p>
+<ul class="simple">
+<li>Define all the assembly strings for your target, adding them to the
+instructions defined in the <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> file. (See
+<a class="reference internal" href="#instruction-set"><em>Instruction Set</em></a>.) TableGen will produce an output file
+(<tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt>) with an implementation of the <tt class="docutils literal"><span class="pre">printInstruction</span></tt>
+method for the <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt> class.</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.h</span></tt>, which contains the bare-bones declaration of
+the <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt> class (a subclass of <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt>).</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt>, which contains target-specific values for
+<tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt> properties and sometimes new implementations for methods.</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, which implements the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> class that
+performs the LLVM-to-assembly conversion.</li>
+</ul>
+<p>The code in <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.h</span></tt> is usually a trivial declaration of the
+<tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt> class for use in <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt>. Similarly,
+<tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt> usually has a few declarations of <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt>
+replacement values that override the default values in <tt class="docutils literal"><span class="pre">TargetAsmInfo.cpp</span></tt>.
+For example in <tt class="docutils literal"><span class="pre">SparcTargetAsmInfo.cpp</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SparcTargetAsmInfo</span><span class="o">::</span><span class="n">SparcTargetAsmInfo</span><span class="p">(</span><span class="k">const</span> <span class="n">SparcTargetMachine</span> <span class="o">&</span><span class="n">TM</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Data16bitsDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.half</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">Data32bitsDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.word</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">Data64bitsDirective</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// .xword is only supported by V9.</span>
+ <span class="n">ZeroDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.skip</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">CommentString</span> <span class="o">=</span> <span class="s">"!"</span><span class="p">;</span>
+ <span class="n">ConstantPoolSection</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.section </span><span class="se">\"</span><span class="s">.rodata</span><span class="se">\"</span><span class="s">,#alloc</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The X86 assembly printer implementation (<tt class="docutils literal"><span class="pre">X86TargetAsmInfo</span></tt>) is an example
+where the target specific <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt> class uses an overridden methods:
+<tt class="docutils literal"><span class="pre">ExpandInlineAsm</span></tt>.</p>
+<p>A target-specific implementation of <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> is written in
+<tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, which implements the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> class that converts
+the LLVM to printable assembly. The implementation must include the following
+headers that have declarations for the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> and
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> classes. The <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> is a subclass of
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/CodeGen/AsmPrinter.h"</span>
+<span class="cp">#include "llvm/CodeGen/MachineFunctionPass.h"</span>
+</pre></div>
+</div>
+<p>As a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> first calls <tt class="docutils literal"><span class="pre">doInitialization</span></tt> to set
+up the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt>. In <tt class="docutils literal"><span class="pre">SparcAsmPrinter</span></tt>, a <tt class="docutils literal"><span class="pre">Mangler</span></tt> object is
+instantiated to process variable names.</p>
+<p>In <tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, the <tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> method (declared in
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>) must be implemented for <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt>. In
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>, the <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method invokes
+<tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt>. Target-specific implementations of
+<tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> differ, but generally do the following to process each
+machine function:</p>
+<ul class="simple">
+<li>Call <tt class="docutils literal"><span class="pre">SetupMachineFunction</span></tt> to perform initialization.</li>
+<li>Call <tt class="docutils literal"><span class="pre">EmitConstantPool</span></tt> to print out (to the output stream) constants which
+have been spilled to memory.</li>
+<li>Call <tt class="docutils literal"><span class="pre">EmitJumpTableInfo</span></tt> to print out jump tables used by the current
+function.</li>
+<li>Print out the label for the current function.</li>
+<li>Print out the code for the function, including basic block labels and the
+assembly for the instruction (using <tt class="docutils literal"><span class="pre">printInstruction</span></tt>)</li>
+</ul>
+<p>The <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt> implementation must also include the code generated by
+TableGen that is output in the <tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt> file. The code in
+<tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt> contains an implementation of the <tt class="docutils literal"><span class="pre">printInstruction</span></tt>
+method that may call these methods:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">printOperand</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printMemOperand</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printCCOperand</span></tt> (for conditional statements)</li>
+<li><tt class="docutils literal"><span class="pre">printDataDirective</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printDeclare</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printImplicitDef</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printInlineAsm</span></tt></li>
+</ul>
+<p>The implementations of <tt class="docutils literal"><span class="pre">printDeclare</span></tt>, <tt class="docutils literal"><span class="pre">printImplicitDef</span></tt>,
+<tt class="docutils literal"><span class="pre">printInlineAsm</span></tt>, and <tt class="docutils literal"><span class="pre">printLabel</span></tt> in <tt class="docutils literal"><span class="pre">AsmPrinter.cpp</span></tt> are generally
+adequate for printing assembly and do not need to be overridden.</p>
+<p>The <tt class="docutils literal"><span class="pre">printOperand</span></tt> method is implemented with a long <tt class="docutils literal"><span class="pre">switch</span></tt>/<tt class="docutils literal"><span class="pre">case</span></tt>
+statement for the type of operand: register, immediate, basic block, external
+symbol, global address, constant pool index, or jump table index. For an
+instruction with a memory address operand, the <tt class="docutils literal"><span class="pre">printMemOperand</span></tt> method
+should be implemented to generate the proper output. Similarly,
+<tt class="docutils literal"><span class="pre">printCCOperand</span></tt> should be used to print a conditional operand.</p>
+<p><tt class="docutils literal"><span class="pre">doFinalization</span></tt> should be overridden in <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt>, and it should be
+called to shut down the assembly printer. During <tt class="docutils literal"><span class="pre">doFinalization</span></tt>, global
+variables and constants are printed to output.</p>
+</div>
+<div class="section" id="subtarget-support">
+<h2><a class="toc-backref" href="#id30">Subtarget Support</a><a class="headerlink" href="#subtarget-support" title="Permalink to this headline">¶</a></h2>
+<p>Subtarget support is used to inform the code generation process of instruction
+set variations for a given chip set. For example, the LLVM SPARC
+implementation provided covers three major versions of the SPARC microprocessor
+architecture: Version 8 (V8, which is a 32-bit architecture), Version 9 (V9, a
+64-bit architecture), and the UltraSPARC architecture. V8 has 16
+double-precision floating-point registers that are also usable as either 32
+single-precision or 8 quad-precision registers. V8 is also purely big-endian.
+V9 has 32 double-precision floating-point registers that are also usable as 16
+quad-precision registers, but cannot be used as single-precision registers.
+The UltraSPARC architecture combines V9 with UltraSPARC Visual Instruction Set
+extensions.</p>
+<p>If subtarget support is needed, you should implement a target-specific
+<tt class="docutils literal"><span class="pre">XXXSubtarget</span></tt> class for your architecture. This class should process the
+command-line options <tt class="docutils literal"><span class="pre">-mcpu=</span></tt> and <tt class="docutils literal"><span class="pre">-mattr=</span></tt>.</p>
+<p>TableGen uses definitions in the <tt class="docutils literal"><span class="pre">Target.td</span></tt> and <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> files to
+generate code in <tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt>. In <tt class="docutils literal"><span class="pre">Target.td</span></tt>, shown below, the
+<tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> interface is defined. The first 4 string parameters of
+the <tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> interface are a feature name, an attribute set by the
+feature, the value of the attribute, and a description of the feature. (The
+fifth parameter is a list of features whose presence is implied, and its
+default value is an empty array.)</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class SubtargetFeature<string n, string a, string v, string d,
+ list<SubtargetFeature> i = []> {
+ string Name = n;
+ string Attribute = a;
+ string Value = v;
+ string Desc = d;
+ list<SubtargetFeature> Implies = i;
+}
+</pre></div>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> file, the <tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> is used to define the
+following features.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>def FeatureV9 : SubtargetFeature<"v9", "IsV9", "true",
+ "Enable SPARC-V9 instructions">;
+def FeatureV8Deprecated : SubtargetFeature<"deprecated-v8",
+ "V8DeprecatedInsts", "true",
+ "Enable deprecated V8 instructions in V9 mode">;
+def FeatureVIS : SubtargetFeature<"vis", "IsVIS", "true",
+ "Enable UltraSPARC Visual Instruction Set extensions">;
+</pre></div>
+</div>
+<p>Elsewhere in <tt class="docutils literal"><span class="pre">Sparc.td</span></tt>, the <tt class="docutils literal"><span class="pre">Proc</span></tt> class is defined and then is used to
+define particular SPARC processor subtypes that may have the previously
+described features.</p>
+<div class="highlight-llvm"><div class="highlight"><pre>class Proc<string Name, list<SubtargetFeature> Features>
+ : Processor<Name, NoItineraries, Features>;
+
+def : Proc<"generic", []>;
+def : Proc<"v8", []>;
+def : Proc<"supersparc", []>;
+def : Proc<"sparclite", []>;
+def : Proc<"f934", []>;
+def : Proc<"hypersparc", []>;
+def : Proc<"sparclite86x", []>;
+def : Proc<"sparclet", []>;
+def : Proc<"tsc701", []>;
+def : Proc<"v9", [FeatureV9]>;
+def : Proc<"ultrasparc", [FeatureV9, FeatureV8Deprecated]>;
+def : Proc<"ultrasparc3", [FeatureV9, FeatureV8Deprecated]>;
+def : Proc<"ultrasparc3-vis", [FeatureV9, FeatureV8Deprecated, FeatureVIS]>;
+</pre></div>
+</div>
+<p>From <tt class="docutils literal"><span class="pre">Target.td</span></tt> and <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> files, the resulting
+<tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt> specifies enum values to identify the features,
+arrays of constants to represent the CPU features and CPU subtypes, and the
+<tt class="docutils literal"><span class="pre">ParseSubtargetFeatures</span></tt> method that parses the features string that sets
+specified subtarget options. The generated <tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt> file
+should be included in the <tt class="docutils literal"><span class="pre">SparcSubtarget.cpp</span></tt>. The target-specific
+implementation of the <tt class="docutils literal"><span class="pre">XXXSubtarget</span></tt> method should follow this pseudocode:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">XXXSubtarget</span><span class="o">::</span><span class="n">XXXSubtarget</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</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">FS</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Set the default features</span>
+ <span class="c1">// Determine default and user specified characteristics of the CPU</span>
+ <span class="c1">// Call ParseSubtargetFeatures(FS, CPU) to parse the features string</span>
+ <span class="c1">// Perform any additional operations</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="jit-support">
+<h2><a class="toc-backref" href="#id31">JIT Support</a><a class="headerlink" href="#jit-support" title="Permalink to this headline">¶</a></h2>
+<p>The implementation of a target machine optionally includes a Just-In-Time (JIT)
+code generator that emits machine code and auxiliary structures as binary
+output that can be written directly to memory. To do this, implement JIT code
+generation by performing the following steps:</p>
+<ul class="simple">
+<li>Write an <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> file that contains a machine function pass
+that transforms target-machine instructions into relocatable machine
+code.</li>
+<li>Write an <tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> file that implements the JIT interfaces for
+target-specific code-generation activities, such as emitting machine code and
+stubs.</li>
+<li>Modify <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> so that it provides a <tt class="docutils literal"><span class="pre">TargetJITInfo</span></tt> object
+through its <tt class="docutils literal"><span class="pre">getJITInfo</span></tt> method.</li>
+</ul>
+<p>There are several different approaches to writing the JIT support code. For
+instance, TableGen and target descriptor files may be used for creating a JIT
+code generator, but are not mandatory. For the Alpha and PowerPC target
+machines, TableGen is used to generate <tt class="docutils literal"><span class="pre">XXXGenCodeEmitter.inc</span></tt>, which
+contains the binary coding of machine instructions and the
+<tt class="docutils literal"><span class="pre">getBinaryCodeForInstr</span></tt> method to access those codes. Other JIT
+implementations do not.</p>
+<p>Both <tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> and <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> must include the
+<tt class="docutils literal"><span class="pre">llvm/CodeGen/MachineCodeEmitter.h</span></tt> header file that defines the
+<tt class="docutils literal"><span class="pre">MachineCodeEmitter</span></tt> class containing code for several callback functions
+that write data (in bytes, words, strings, etc.) to the output stream.</p>
+<div class="section" id="machine-code-emitter">
+<h3><a class="toc-backref" href="#id32">Machine Code Emitter</a><a class="headerlink" href="#machine-code-emitter" title="Permalink to this headline">¶</a></h3>
+<p>In <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt>, a target-specific of the <tt class="docutils literal"><span class="pre">Emitter</span></tt> class is
+implemented as a function pass (subclass of <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>). The
+target-specific implementation of <tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> (invoked by
+<tt class="docutils literal"><span class="pre">runOnFunction</span></tt> in <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>) iterates through the
+<tt class="docutils literal"><span class="pre">MachineBasicBlock</span></tt> calls <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> to process each instruction and
+emit binary code. <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> is largely implemented with case
+statements on the instruction types defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.h</span></tt>. For
+example, in <tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt>, the <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> method is built
+around the following <tt class="docutils literal"><span class="pre">switch</span></tt>/<tt class="docutils literal"><span class="pre">case</span></tt> statements:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">switch</span> <span class="p">(</span><span class="n">Desc</span><span class="o">-></span><span class="n">TSFlags</span> <span class="o">&</span> <span class="n">X86</span><span class="o">::</span><span class="n">FormMask</span><span class="p">)</span> <span class="p">{</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">Pseudo</span><span class="o">:</span> <span class="c1">// for not yet implemented instructions</span>
+ <span class="p">...</span> <span class="c1">// or pseudo-instructions</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">RawFrm</span><span class="o">:</span> <span class="c1">// for instructions with a fixed opcode value</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">AddRegFrm</span><span class="o">:</span> <span class="c1">// for instructions that have one register operand</span>
+ <span class="p">...</span> <span class="c1">// added to their opcode</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMDestReg</span><span class="o">:</span><span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a destination (register)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMDestMem</span><span class="o">:</span><span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a destination (memory)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMSrcReg</span><span class="o">:</span> <span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a source (register)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMSrcMem</span><span class="o">:</span> <span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a source (memory)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM0r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM1r</span><span class="o">:</span> <span class="c1">// for instructions that operate on</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM2r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM3r</span><span class="o">:</span> <span class="c1">// a REGISTER r/m operand and</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM4r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM5r</span><span class="o">:</span> <span class="c1">// use the Mod/RM byte and a field</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM6r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM7r</span><span class="o">:</span> <span class="c1">// to hold extended opcode data</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM0m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM1m</span><span class="o">:</span> <span class="c1">// for instructions that operate on</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM2m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM3m</span><span class="o">:</span> <span class="c1">// a MEMORY r/m operand and</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM4m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM5m</span><span class="o">:</span> <span class="c1">// use the Mod/RM byte and a field</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM6m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM7m</span><span class="o">:</span> <span class="c1">// to hold extended opcode data</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMInitReg</span><span class="o">:</span> <span class="c1">// for instructions whose source and</span>
+ <span class="p">...</span> <span class="c1">// destination are the same register</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The implementations of these case statements often first emit the opcode and
+then get the operand(s). Then depending upon the operand, helper methods may
+be called to process the operand(s). For example, in <tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt>,
+for the <tt class="docutils literal"><span class="pre">X86II::AddRegFrm</span></tt> case, the first data emitted (by <tt class="docutils literal"><span class="pre">emitByte</span></tt>) is
+the opcode added to the register operand. Then an object representing the
+machine operand, <tt class="docutils literal"><span class="pre">MO1</span></tt>, is extracted. The helper methods such as
+<tt class="docutils literal"><span class="pre">isImmediate</span></tt>, <tt class="docutils literal"><span class="pre">isGlobalAddress</span></tt>, <tt class="docutils literal"><span class="pre">isExternalSymbol</span></tt>,
+<tt class="docutils literal"><span class="pre">isConstantPoolIndex</span></tt>, and <tt class="docutils literal"><span class="pre">isJumpTableIndex</span></tt> determine the operand type.
+(<tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt> also has private methods such as <tt class="docutils literal"><span class="pre">emitConstant</span></tt>,
+<tt class="docutils literal"><span class="pre">emitGlobalAddress</span></tt>, <tt class="docutils literal"><span class="pre">emitExternalSymbolAddress</span></tt>, <tt class="docutils literal"><span class="pre">emitConstPoolAddress</span></tt>,
+and <tt class="docutils literal"><span class="pre">emitJumpTableAddress</span></tt> that emit the data into the output stream.)</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">AddRegFrm</span><span class="o">:</span>
+ <span class="n">MCE</span><span class="p">.</span><span class="n">emitByte</span><span class="p">(</span><span class="n">BaseOpcode</span> <span class="o">+</span> <span class="n">getX86RegNum</span><span class="p">(</span><span class="n">MI</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="n">CurOp</span><span class="o">++</span><span class="p">).</span><span class="n">getReg</span><span class="p">()));</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">CurOp</span> <span class="o">!=</span> <span class="n">NumOps</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="n">MachineOperand</span> <span class="o">&</span><span class="n">MO1</span> <span class="o">=</span> <span class="n">MI</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="n">CurOp</span><span class="o">++</span><span class="p">);</span>
+ <span class="kt">unsigned</span> <span class="n">Size</span> <span class="o">=</span> <span class="n">X86InstrInfo</span><span class="o">::</span><span class="n">sizeOfImm</span><span class="p">(</span><span class="n">Desc</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isImmediate</span><span class="p">())</span>
+ <span class="n">emitConstant</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getImm</span><span class="p">(),</span> <span class="n">Size</span><span class="p">);</span>
+ <span class="k">else</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">rt</span> <span class="o">=</span> <span class="n">Is64BitMode</span> <span class="o">?</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_pcrel_word</span>
+ <span class="o">:</span> <span class="p">(</span><span class="n">IsPIC</span> <span class="o">?</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_picrel_word</span> <span class="o">:</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_absolute_word</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Opcode</span> <span class="o">==</span> <span class="n">X86</span><span class="o">::</span><span class="n">MOV64ri</span><span class="p">)</span>
+ <span class="n">rt</span> <span class="o">=</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_absolute_dword</span><span class="p">;</span> <span class="c1">// FIXME: add X86II flag?</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isGlobalAddress</span><span class="p">())</span> <span class="p">{</span>
+ <span class="kt">bool</span> <span class="n">NeedStub</span> <span class="o">=</span> <span class="n">isa</span><span class="o"><</span><span class="n">Function</span><span class="o">></span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">());</span>
+ <span class="kt">bool</span> <span class="n">isLazy</span> <span class="o">=</span> <span class="n">gvNeedsLazyPtr</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">());</span>
+ <span class="n">emitGlobalAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">(),</span> <span class="n">rt</span><span class="p">,</span> <span class="n">MO1</span><span class="p">.</span><span class="n">getOffset</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span>
+ <span class="n">NeedStub</span><span class="p">,</span> <span class="n">isLazy</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">MO1</span><span class="p">.</span><span class="n">isExternalSymbol</span><span class="p">())</span>
+ <span class="n">emitExternalSymbolAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getSymbolName</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="k">else</span> <span class="nf">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isConstantPoolIndex</span><span class="p">())</span>
+ <span class="n">emitConstPoolAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getIndex</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="k">else</span> <span class="nf">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isJumpTableIndex</span><span class="p">())</span>
+ <span class="n">emitJumpTableAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getIndex</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="k">break</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>In the previous example, <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> uses the variable <tt class="docutils literal"><span class="pre">rt</span></tt>, which
+is a <tt class="docutils literal"><span class="pre">RelocationType</span></tt> enum that may be used to relocate addresses (for
+example, a global address with a PIC base offset). The <tt class="docutils literal"><span class="pre">RelocationType</span></tt> enum
+for that target is defined in the short target-specific <tt class="docutils literal"><span class="pre">XXXRelocations.h</span></tt>
+file. The <tt class="docutils literal"><span class="pre">RelocationType</span></tt> is used by the <tt class="docutils literal"><span class="pre">relocate</span></tt> method defined in
+<tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> to rewrite addresses for referenced global symbols.</p>
+<p>For example, <tt class="docutils literal"><span class="pre">X86Relocations.h</span></tt> specifies the following relocation types for
+the X86 addresses. In all four cases, the relocated value is added to the
+value already in memory. For <tt class="docutils literal"><span class="pre">reloc_pcrel_word</span></tt> and <tt class="docutils literal"><span class="pre">reloc_picrel_word</span></tt>,
+there is an additional initial adjustment.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">RelocationType</span> <span class="p">{</span>
+ <span class="n">reloc_pcrel_word</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// add reloc value after adjusting for the PC loc</span>
+ <span class="n">reloc_picrel_word</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// add reloc value after adjusting for the PIC base</span>
+ <span class="n">reloc_absolute_word</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> <span class="c1">// absolute relocation; no additional adjustment</span>
+ <span class="n">reloc_absolute_dword</span> <span class="o">=</span> <span class="mi">3</span> <span class="c1">// absolute relocation; no additional adjustment</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="target-jit-info">
+<h3><a class="toc-backref" href="#id33">Target JIT Info</a><a class="headerlink" href="#target-jit-info" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> implements the JIT interfaces for target-specific
+code-generation activities, such as emitting machine code and stubs. At
+minimum, a target-specific version of <tt class="docutils literal"><span class="pre">XXXJITInfo</span></tt> implements the following:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> — Initializes the JIT, gives the target a
+function that is used for compilation.</li>
+<li><tt class="docutils literal"><span class="pre">emitFunctionStub</span></tt> — Returns a native function with a specified address
+for a callback function.</li>
+<li><tt class="docutils literal"><span class="pre">relocate</span></tt> — Changes the addresses of referenced globals, based on
+relocation types.</li>
+<li>Callback function that are wrappers to a function stub that is used when the
+real target is not initially known.</li>
+</ul>
+<p><tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> is generally trivial to implement. It makes the
+incoming parameter as the global <tt class="docutils literal"><span class="pre">JITCompilerFunction</span></tt> and returns the
+callback function that will be used a function wrapper. For the Alpha target
+(in <tt class="docutils literal"><span class="pre">AlphaJITInfo.cpp</span></tt>), the <tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> implementation is
+simply:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">TargetJITInfo</span><span class="o">::</span><span class="n">LazyResolverFn</span> <span class="n">AlphaJITInfo</span><span class="o">::</span><span class="n">getLazyResolverFunction</span><span class="p">(</span>
+ <span class="n">JITCompilerFn</span> <span class="n">F</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">JITCompilerFunction</span> <span class="o">=</span> <span class="n">F</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">AlphaCompilationCallback</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For the X86 target, the <tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> implementation is a little
+more complicated, because it returns a different callback function for
+processors with SSE instructions and XMM registers.</p>
+<p>The callback function initially saves and later restores the callee register
+values, incoming arguments, and frame and return address. The callback
+function needs low-level access to the registers or stack, so it is typically
+implemented with assembler.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/WritingAnLLVMPass.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/WritingAnLLVMPass.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/WritingAnLLVMPass.html (added)
+++ www-releases/trunk/3.7.1/docs/WritingAnLLVMPass.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,1328 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Writing an LLVM Pass — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="index.html" />
+ <link rel="next" title="How To Use Attributes" href="HowToUseAttributes.html" />
+ <link rel="prev" title="Garbage Collection with LLVM" href="GarbageCollection.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToUseAttributes.html" title="How To Use Attributes"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GarbageCollection.html" title="Garbage Collection with LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="writing-an-llvm-pass">
+<h1>Writing an LLVM Pass<a class="headerlink" href="#writing-an-llvm-pass" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction-what-is-a-pass" id="id5">Introduction — What is a pass?</a></li>
+<li><a class="reference internal" href="#quick-start-writing-hello-world" id="id6">Quick Start — Writing hello world</a><ul>
+<li><a class="reference internal" href="#setting-up-the-build-environment" id="id7">Setting up the build environment</a></li>
+<li><a class="reference internal" href="#basic-code-required" id="id8">Basic code required</a></li>
+<li><a class="reference internal" href="#running-a-pass-with-opt" id="id9">Running a pass with <tt class="docutils literal"><span class="pre">opt</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#pass-classes-and-requirements" id="id10">Pass classes and requirements</a><ul>
+<li><a class="reference internal" href="#the-immutablepass-class" id="id11">The <tt class="docutils literal"><span class="pre">ImmutablePass</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-modulepass-class" id="id12">The <tt class="docutils literal"><span class="pre">ModulePass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-runonmodule-method" id="id13">The <tt class="docutils literal"><span class="pre">runOnModule</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-callgraphsccpass-class" id="id14">The <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-callgraph-method" id="id15">The <tt class="docutils literal"><span class="pre">doInitialization(CallGraph</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonscc-method" id="id16">The <tt class="docutils literal"><span class="pre">runOnSCC</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-dofinalization-callgraph-method" id="id17">The <tt class="docutils literal"><span class="pre">doFinalization(CallGraph</span> <span class="pre">&)</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-functionpass-class" id="id18">The <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-module-method" id="id19">The <tt class="docutils literal"><span class="pre">doInitialization(Module</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonfunction-method" id="id20">The <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-dofinalization-module-method" id="id21">The <tt class="docutils literal"><span class="pre">doFinalization(Module</span> <span class="pre">&)</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-looppass-class" id="id22">The <tt class="docutils literal"><span class="pre">LoopPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-loop-lppassmanager-method" id="id23">The <tt class="docutils literal"><span class="pre">doInitialization(Loop</span> <span class="pre">*,</span> <span class="pre">LPPassManager</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonloop-method" id="id24">The <tt class="docutils literal"><span class="pre">runOnLoop</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-dofinalization-method" id="id25">The <tt class="docutils literal"><span class="pre">doFinalization()</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-regionpass-class" id="id26">The <tt class="docutils literal"><span class="pre">RegionPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-region-rgpassmanager-method" id="id27">The <tt class="docutils literal"><span class="pre">doInitialization(Region</span> <span class="pre">*,</span> <span class="pre">RGPassManager</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonregion-method" id="id28">The <tt class="docutils literal"><span class="pre">runOnRegion</span></tt> method</a></li>
+<li><a class="reference internal" href="#id2" id="id29">The <tt class="docutils literal"><span class="pre">doFinalization()</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-basicblockpass-class" id="id30">The <tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-function-method" id="id31">The <tt class="docutils literal"><span class="pre">doInitialization(Function</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonbasicblock-method" id="id32">The <tt class="docutils literal"><span class="pre">runOnBasicBlock</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-dofinalization-function-method" id="id33">The <tt class="docutils literal"><span class="pre">doFinalization(Function</span> <span class="pre">&)</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-machinefunctionpass-class" id="id34">The <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-runonmachinefunction-machinefunction-mf-method" id="id35">The <tt class="docutils literal"><span class="pre">runOnMachineFunction(MachineFunction</span> <span class="pre">&MF)</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#pass-registration" id="id36">Pass registration</a><ul>
+<li><a class="reference internal" href="#the-print-method" id="id37">The <tt class="docutils literal"><span class="pre">print</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#specifying-interactions-between-passes" id="id38">Specifying interactions between passes</a><ul>
+<li><a class="reference internal" href="#the-getanalysisusage-method" id="id39">The <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-analysisusage-addrequired-and-analysisusage-addrequiredtransitive-methods" id="id40">The <tt class="docutils literal"><span class="pre">AnalysisUsage::addRequired<></span></tt> and <tt class="docutils literal"><span class="pre">AnalysisUsage::addRequiredTransitive<></span></tt> methods</a></li>
+<li><a class="reference internal" href="#the-analysisusage-addpreserved-method" id="id41">The <tt class="docutils literal"><span class="pre">AnalysisUsage::addPreserved<></span></tt> method</a></li>
+<li><a class="reference internal" href="#example-implementations-of-getanalysisusage" id="id42">Example implementations of <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt></a></li>
+<li><a class="reference internal" href="#the-getanalysis-and-getanalysisifavailable-methods" id="id43">The <tt class="docutils literal"><span class="pre">getAnalysis<></span></tt> and <tt class="docutils literal"><span class="pre">getAnalysisIfAvailable<></span></tt> methods</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#implementing-analysis-groups" id="id44">Implementing Analysis Groups</a><ul>
+<li><a class="reference internal" href="#analysis-group-concepts" id="id45">Analysis Group Concepts</a></li>
+<li><a class="reference internal" href="#using-registeranalysisgroup" id="id46">Using <tt class="docutils literal"><span class="pre">RegisterAnalysisGroup</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#pass-statistics" id="id47">Pass Statistics</a><ul>
+<li><a class="reference internal" href="#what-passmanager-does" id="id48">What PassManager does</a><ul>
+<li><a class="reference internal" href="#the-releasememory-method" id="id49">The <tt class="docutils literal"><span class="pre">releaseMemory</span></tt> method</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#registering-dynamically-loaded-passes" id="id50">Registering dynamically loaded passes</a><ul>
+<li><a class="reference internal" href="#using-existing-registries" id="id51">Using existing registries</a></li>
+<li><a class="reference internal" href="#creating-new-registries" id="id52">Creating new registries</a></li>
+<li><a class="reference internal" href="#using-gdb-with-dynamically-loaded-passes" id="id53">Using GDB with dynamically loaded passes</a><ul>
+<li><a class="reference internal" href="#setting-a-breakpoint-in-your-pass" id="id54">Setting a breakpoint in your pass</a></li>
+<li><a class="reference internal" href="#miscellaneous-problems" id="id55">Miscellaneous Problems</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#future-extensions-planned" id="id56">Future extensions planned</a><ul>
+<li><a class="reference internal" href="#multithreaded-llvm" id="id57">Multithreaded LLVM</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction-what-is-a-pass">
+<h2><a class="toc-backref" href="#id5">Introduction — What is a pass?</a><a class="headerlink" href="#introduction-what-is-a-pass" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM Pass Framework is an important part of the LLVM system, because LLVM
+passes are where most of the interesting parts of the compiler exist. Passes
+perform the transformations and optimizations that make up the compiler, they
+build the analysis results that are used by these transformations, and they
+are, above all, a structuring technique for compiler code.</p>
+<p>All LLVM passes are subclasses of the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a> class, which implement
+functionality by overriding virtual methods inherited from <tt class="docutils literal"><span class="pre">Pass</span></tt>. Depending
+on how your pass works, you should inherit from the <a class="reference internal" href="#writing-an-llvm-pass-modulepass"><em>ModulePass</em></a> , <a class="reference internal" href="#writing-an-llvm-pass-callgraphsccpass"><em>CallGraphSCCPass</em></a>, <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a> , or <a class="reference internal" href="#writing-an-llvm-pass-looppass"><em>LoopPass</em></a>, or <a class="reference internal" href="#writing-an-llvm-pass-regionpass"><em>RegionPass</em></a>, or <a class="reference internal" href="#writing-an-llvm-pass-basicblockpass"><em>BasicBlockPass</em></a> classes, which gives the system more
+information about what your pass does, and how it can be combined with other
+passes. One of the main features of the LLVM Pass Framework is that it
+schedules passes to run in an efficient way based on the constraints that your
+pass meets (which are indicated by which class they derive from).</p>
+<p>We start by showing you how to construct a pass, everything from setting up the
+code, to compiling, loading, and executing it. After the basics are down, more
+advanced features are discussed.</p>
+</div>
+<div class="section" id="quick-start-writing-hello-world">
+<h2><a class="toc-backref" href="#id6">Quick Start — Writing hello world</a><a class="headerlink" href="#quick-start-writing-hello-world" title="Permalink to this headline">¶</a></h2>
+<p>Here we describe how to write the “hello world” of passes. The “Hello” pass is
+designed to simply print out the name of non-external functions that exist in
+the program being compiled. It does not modify the program at all, it just
+inspects it. The source code and files for this pass are available in the LLVM
+source tree in the <tt class="docutils literal"><span class="pre">lib/Transforms/Hello</span></tt> directory.</p>
+<div class="section" id="setting-up-the-build-environment">
+<span id="writing-an-llvm-pass-makefile"></span><h3><a class="toc-backref" href="#id7">Setting up the build environment</a><a class="headerlink" href="#setting-up-the-build-environment" title="Permalink to this headline">¶</a></h3>
+<p>First, configure and build LLVM. This needs to be done directly inside the
+LLVM source tree rather than in a separate objects directory. Next, you need
+to create a new directory somewhere in the LLVM source base. For this example,
+we’ll assume that you made <tt class="docutils literal"><span class="pre">lib/Transforms/Hello</span></tt>. Finally, you must set up
+a build script (<tt class="docutils literal"><span class="pre">Makefile</span></tt>) that will compile the source code for the new
+pass. To do this, copy the following into <tt class="docutils literal"><span class="pre">Makefile</span></tt>:</p>
+<div class="highlight-make"><div class="highlight"><pre><span class="c"># Makefile for hello pass</span>
+
+<span class="c"># Path to top level of LLVM hierarchy</span>
+<span class="nv">LEVEL</span> <span class="o">=</span> ../../..
+
+<span class="c"># Name of the library to build</span>
+<span class="nv">LIBRARYNAME</span> <span class="o">=</span> Hello
+
+<span class="c"># Make the shared library become a loadable module so the tools can</span>
+<span class="c"># dlopen/dlsym on the resulting library.</span>
+<span class="nv">LOADABLE_MODULE</span> <span class="o">=</span> 1
+
+<span class="c"># Include the makefile implementation stuff</span>
+<span class="cp">include $(LEVEL)/Makefile.common</span>
+</pre></div>
+</div>
+<p>This makefile specifies that all of the <tt class="docutils literal"><span class="pre">.cpp</span></tt> files in the current directory
+are to be compiled and linked together into a shared object
+<tt class="docutils literal"><span class="pre">$(LEVEL)/Debug+Asserts/lib/Hello.so</span></tt> that can be dynamically loaded by the
+<strong class="program">opt</strong> or <strong class="program">bugpoint</strong> tools via their <a class="reference internal" href="CommandGuide/opt.html#cmdoption-load"><em class="xref std std-option">-load</em></a> options.
+If your operating system uses a suffix other than <tt class="docutils literal"><span class="pre">.so</span></tt> (such as Windows or Mac
+OS X), the appropriate extension will be used.</p>
+<p>If you are used CMake to build LLVM, see <a class="reference internal" href="CMake.html#cmake-out-of-source-pass"><em>Developing LLVM passes out of source</em></a>.</p>
+<p>Now that we have the build scripts set up, we just need to write the code for
+the pass itself.</p>
+</div>
+<div class="section" id="basic-code-required">
+<span id="writing-an-llvm-pass-basiccode"></span><h3><a class="toc-backref" href="#id8">Basic code required</a><a class="headerlink" href="#basic-code-required" title="Permalink to this headline">¶</a></h3>
+<p>Now that we have a way to compile our new pass, we just have to write it.
+Start out with:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Pass.h"</span>
+<span class="cp">#include "llvm/IR/Function.h"</span>
+<span class="cp">#include "llvm/Support/raw_ostream.h"</span>
+</pre></div>
+</div>
+<p>Which are needed because we are writing a <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a>, we are operating on
+<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Function.html">Function</a>s, and we will
+be doing some printing.</p>
+<p>Next we have:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>... which is required because the functions from the include files live in the
+llvm namespace.</p>
+<p>Next we have:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="p">{</span>
+</pre></div>
+</div>
+<p>... which starts out an anonymous namespace. Anonymous namespaces are to C++
+what the “<tt class="docutils literal"><span class="pre">static</span></tt>” keyword is to C (at global scope). It makes the things
+declared inside of the anonymous namespace visible only to the current file.
+If you’re not familiar with them, consult a decent C++ book for more
+information.</p>
+<p>Next, we declare our pass itself:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Hello</span> <span class="o">:</span> <span class="k">public</span> <span class="n">FunctionPass</span> <span class="p">{</span>
+</pre></div>
+</div>
+<p>This declares a “<tt class="docutils literal"><span class="pre">Hello</span></tt>” class that is a subclass of <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a>. The different builtin pass subclasses
+are described in detail <a class="reference internal" href="#writing-an-llvm-pass-pass-classes"><em>later</em></a>, but
+for now, know that <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> operates on a function at a time.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="kt">char</span> <span class="n">ID</span><span class="p">;</span>
+<span class="n">Hello</span><span class="p">()</span> <span class="o">:</span> <span class="n">FunctionPass</span><span class="p">(</span><span class="n">ID</span><span class="p">)</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>This declares pass identifier used by LLVM to identify pass. This allows LLVM
+to avoid using expensive C++ runtime information.</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="kt">bool</span> <span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="n">override</span> <span class="p">{</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"Hello: "</span><span class="p">;</span>
+ <span class="n">errs</span><span class="p">().</span><span class="n">write_escaped</span><span class="p">(</span><span class="n">F</span><span class="p">.</span><span class="n">getName</span><span class="p">())</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">};</span> <span class="c1">// end of struct Hello</span>
+<span class="p">}</span> <span class="c1">// end of anonymous namespace</span>
+</pre></div>
+</div>
+<p>We declare a <a class="reference internal" href="#writing-an-llvm-pass-runonfunction"><em>runOnFunction</em></a> method,
+which overrides an abstract virtual method inherited from <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a>. This is where we are supposed to do our
+thing, so we just print out our message with the name of each function.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">char</span> <span class="n">Hello</span><span class="o">::</span><span class="n">ID</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>We initialize pass ID here. LLVM uses ID’s address to identify a pass, so
+initialization value is not important.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">RegisterPass</span><span class="o"><</span><span class="n">Hello</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="s">"hello"</span><span class="p">,</span> <span class="s">"Hello World Pass"</span><span class="p">,</span>
+ <span class="nb">false</span> <span class="cm">/* Only looks at CFG */</span><span class="p">,</span>
+ <span class="nb">false</span> <span class="cm">/* Analysis Pass */</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Lastly, we <a class="reference internal" href="#writing-an-llvm-pass-registration"><em>register our class</em></a>
+<tt class="docutils literal"><span class="pre">Hello</span></tt>, giving it a command line argument “<tt class="docutils literal"><span class="pre">hello</span></tt>”, and a name “Hello
+World Pass”. The last two arguments describe its behavior: if a pass walks CFG
+without modifying it then the third argument is set to <tt class="docutils literal"><span class="pre">true</span></tt>; if a pass is
+an analysis pass, for example dominator tree pass, then <tt class="docutils literal"><span class="pre">true</span></tt> is supplied as
+the fourth argument.</p>
+<p>As a whole, the <tt class="docutils literal"><span class="pre">.cpp</span></tt> file looks like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Pass.h"</span>
+<span class="cp">#include "llvm/IR/Function.h"</span>
+<span class="cp">#include "llvm/Support/raw_ostream.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">struct</span> <span class="n">Hello</span> <span class="o">:</span> <span class="k">public</span> <span class="n">FunctionPass</span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">char</span> <span class="n">ID</span><span class="p">;</span>
+ <span class="n">Hello</span><span class="p">()</span> <span class="o">:</span> <span class="n">FunctionPass</span><span class="p">(</span><span class="n">ID</span><span class="p">)</span> <span class="p">{}</span>
+
+ <span class="kt">bool</span> <span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="n">override</span> <span class="p">{</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"Hello: "</span><span class="p">;</span>
+ <span class="n">errs</span><span class="p">().</span><span class="n">write_escaped</span><span class="p">(</span><span class="n">F</span><span class="p">.</span><span class="n">getName</span><span class="p">())</span> <span class="o"><<</span> <span class="sc">'\n'</span><span class="p">;</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">};</span>
+<span class="p">}</span>
+
+<span class="kt">char</span> <span class="n">Hello</span><span class="o">::</span><span class="n">ID</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="k">static</span> <span class="n">RegisterPass</span><span class="o"><</span><span class="n">Hello</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="s">"hello"</span><span class="p">,</span> <span class="s">"Hello World Pass"</span><span class="p">,</span> <span class="nb">false</span><span class="p">,</span> <span class="nb">false</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Now that it’s all together, compile the file with a simple “<tt class="docutils literal"><span class="pre">gmake</span></tt>” command
+in the local directory and you should get a new file
+“<tt class="docutils literal"><span class="pre">Debug+Asserts/lib/Hello.so</span></tt>” under the top level directory of the LLVM
+source tree (not in the local directory). Note that everything in this file is
+contained in an anonymous namespace — this reflects the fact that passes
+are self contained units that do not need external interfaces (although they
+can have them) to be useful.</p>
+</div>
+<div class="section" id="running-a-pass-with-opt">
+<h3><a class="toc-backref" href="#id9">Running a pass with <tt class="docutils literal"><span class="pre">opt</span></tt></a><a class="headerlink" href="#running-a-pass-with-opt" title="Permalink to this headline">¶</a></h3>
+<p>Now that you have a brand new shiny shared object file, we can use the
+<strong class="program">opt</strong> command to run an LLVM program through your pass. Because you
+registered your pass with <tt class="docutils literal"><span class="pre">RegisterPass</span></tt>, you will be able to use the
+<strong class="program">opt</strong> tool to access it, once loaded.</p>
+<p>To test it, follow the example at the end of the <a class="reference internal" href="GettingStarted.html"><em>Getting Started with the LLVM System</em></a> to
+compile “Hello World” to LLVM. We can now run the bitcode file (hello.bc) for
+the program through our transformation like this (or course, any bitcode file
+will work):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../../Debug+Asserts/lib/Hello.so -hello < hello.bc > /dev/null
+<span class="go">Hello: __main</span>
+<span class="go">Hello: puts</span>
+<span class="go">Hello: main</span>
+</pre></div>
+</div>
+<p>The <a class="reference internal" href="CommandGuide/opt.html#cmdoption-load"><em class="xref std std-option">-load</em></a> option specifies that <strong class="program">opt</strong> should load your pass
+as a shared object, which makes “<tt class="docutils literal"><span class="pre">-hello</span></tt>” a valid command line argument
+(which is one reason you need to <a class="reference internal" href="#writing-an-llvm-pass-registration"><em>register your pass</em></a>). Because the Hello pass does not modify
+the program in any interesting way, we just throw away the result of
+<strong class="program">opt</strong> (sending it to <tt class="docutils literal"><span class="pre">/dev/null</span></tt>).</p>
+<p>To see what happened to the other string you registered, try running
+<strong class="program">opt</strong> with the <a class="reference internal" href="CommandGuide/opt.html#cmdoption-help"><em class="xref std std-option">-help</em></a> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../../Debug+Asserts/lib/Hello.so -help
+<span class="go">OVERVIEW: llvm .bc -> .bc modular optimizer</span>
+
+<span class="go">USAGE: opt [options] <input bitcode></span>
+
+<span class="go">OPTIONS:</span>
+<span class="go"> Optimizations available:</span>
+<span class="go">...</span>
+<span class="go"> -globalopt - Global Variable Optimizer</span>
+<span class="go"> -globalsmodref-aa - Simple mod/ref analysis for globals</span>
+<span class="go"> -gvn - Global Value Numbering</span>
+<span class="go"> -hello - Hello World Pass</span>
+<span class="go"> -indvars - Induction Variable Simplification</span>
+<span class="go"> -inline - Function Integration/Inlining</span>
+<span class="go">...</span>
+</pre></div>
+</div>
+<p>The pass name gets added as the information string for your pass, giving some
+documentation to users of <strong class="program">opt</strong>. Now that you have a working pass,
+you would go ahead and make it do the cool transformations you want. Once you
+get it all working and tested, it may become useful to find out how fast your
+pass is. The <a class="reference internal" href="#writing-an-llvm-pass-passmanager"><em>PassManager</em></a> provides a
+nice command line option (<a class="reference internal" href="CommandGuide/llc.html#cmdoption--time-passes"><em class="xref std std-option">--time-passes</em></a>) that allows you to get
+information about the execution time of your pass along with the other passes
+you queue up. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../../Debug+Asserts/lib/Hello.so -hello -time-passes < hello.bc > /dev/null
+<span class="go">Hello: __main</span>
+<span class="go">Hello: puts</span>
+<span class="go">Hello: main</span>
+<span class="go">===============================================================================</span>
+<span class="go"> ... Pass execution timing report ...</span>
+<span class="go">===============================================================================</span>
+<span class="go"> Total Execution Time: 0.02 seconds (0.0479059 wall clock)</span>
+
+<span class="go"> ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Pass Name ---</span>
+<span class="go"> 0.0100 (100.0%) 0.0000 ( 0.0%) 0.0100 ( 50.0%) 0.0402 ( 84.0%) Bitcode Writer</span>
+<span class="go"> 0.0000 ( 0.0%) 0.0100 (100.0%) 0.0100 ( 50.0%) 0.0031 ( 6.4%) Dominator Set Construction</span>
+<span class="go"> 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0013 ( 2.7%) Module Verifier</span>
+<span class="go"> 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0033 ( 6.9%) Hello World Pass</span>
+<span class="go"> 0.0100 (100.0%) 0.0100 (100.0%) 0.0200 (100.0%) 0.0479 (100.0%) TOTAL</span>
+</pre></div>
+</div>
+<p>As you can see, our implementation above is pretty fast. The additional
+passes listed are automatically inserted by the <strong class="program">opt</strong> tool to verify
+that the LLVM emitted by your pass is still valid and well formed LLVM, which
+hasn’t been broken somehow.</p>
+<p>Now that you have seen the basics of the mechanics behind passes, we can talk
+about some more details of how they work and how to use them.</p>
+</div>
+</div>
+<div class="section" id="pass-classes-and-requirements">
+<span id="writing-an-llvm-pass-pass-classes"></span><h2><a class="toc-backref" href="#id10">Pass classes and requirements</a><a class="headerlink" href="#pass-classes-and-requirements" title="Permalink to this headline">¶</a></h2>
+<p>One of the first things that you should do when designing a new pass is to
+decide what class you should subclass for your pass. The <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> example uses the <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a> class for its implementation, but we did
+not discuss why or when this should occur. Here we talk about the classes
+available, from the most general to the most specific.</p>
+<p>When choosing a superclass for your <tt class="docutils literal"><span class="pre">Pass</span></tt>, you should choose the <strong>most
+specific</strong> class possible, while still being able to meet the requirements
+listed. This gives the LLVM Pass Infrastructure information necessary to
+optimize how passes are run, so that the resultant compiler isn’t unnecessarily
+slow.</p>
+<div class="section" id="the-immutablepass-class">
+<h3><a class="toc-backref" href="#id11">The <tt class="docutils literal"><span class="pre">ImmutablePass</span></tt> class</a><a class="headerlink" href="#the-immutablepass-class" title="Permalink to this headline">¶</a></h3>
+<p>The most plain and boring type of pass is the “<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1ImmutablePass.html">ImmutablePass</a>” class. This pass
+type is used for passes that do not have to be run, do not change state, and
+never need to be updated. This is not a normal type of transformation or
+analysis, but can provide information about the current compiler configuration.</p>
+<p>Although this pass class is very infrequently used, it is important for
+providing information about the current target machine being compiled for, and
+other static information that can affect the various transformations.</p>
+<p><tt class="docutils literal"><span class="pre">ImmutablePass</span></tt>es never invalidate other transformations, are never
+invalidated, and are never “run”.</p>
+</div>
+<div class="section" id="the-modulepass-class">
+<span id="writing-an-llvm-pass-modulepass"></span><h3><a class="toc-backref" href="#id12">The <tt class="docutils literal"><span class="pre">ModulePass</span></tt> class</a><a class="headerlink" href="#the-modulepass-class" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1ModulePass.html">ModulePass</a> class
+is the most general of all superclasses that you can use. Deriving from
+<tt class="docutils literal"><span class="pre">ModulePass</span></tt> indicates that your pass uses the entire program as a unit,
+referring to function bodies in no predictable order, or adding and removing
+functions. Because nothing is known about the behavior of <tt class="docutils literal"><span class="pre">ModulePass</span></tt>
+subclasses, no optimization can be done for their execution.</p>
+<p>A module pass can use function level passes (e.g. dominators) using the
+<tt class="docutils literal"><span class="pre">getAnalysis</span></tt> interface <tt class="docutils literal"><span class="pre">getAnalysis<DominatorTree>(llvm::Function</span> <span class="pre">*)</span></tt> to
+provide the function to retrieve analysis result for, if the function pass does
+not require any module or immutable passes. Note that this can only be done
+for functions for which the analysis ran, e.g. in the case of dominators you
+should only ask for the <tt class="docutils literal"><span class="pre">DominatorTree</span></tt> for function definitions, not
+declarations.</p>
+<p>To write a correct <tt class="docutils literal"><span class="pre">ModulePass</span></tt> subclass, derive from <tt class="docutils literal"><span class="pre">ModulePass</span></tt> and
+overload the <tt class="docutils literal"><span class="pre">runOnModule</span></tt> method with the following signature:</p>
+<div class="section" id="the-runonmodule-method">
+<h4><a class="toc-backref" href="#id13">The <tt class="docutils literal"><span class="pre">runOnModule</span></tt> method</a><a class="headerlink" href="#the-runonmodule-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnModule</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnModule</span></tt> method performs the interesting work of the pass. It
+should return <tt class="docutils literal"><span class="pre">true</span></tt> if the module was modified by the transformation and
+<tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</p>
+</div>
+</div>
+<div class="section" id="the-callgraphsccpass-class">
+<span id="writing-an-llvm-pass-callgraphsccpass"></span><h3><a class="toc-backref" href="#id14">The <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt> class</a><a class="headerlink" href="#the-callgraphsccpass-class" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1CallGraphSCCPass.html">CallGraphSCCPass</a> is used by
+passes that need to traverse the program bottom-up on the call graph (callees
+before callers). Deriving from <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt> provides some mechanics
+for building and traversing the <tt class="docutils literal"><span class="pre">CallGraph</span></tt>, but also allows the system to
+optimize execution of <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt>es. If your pass meets the
+requirements outlined below, and doesn’t meet the requirements of a
+<a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a> or <a class="reference internal" href="#writing-an-llvm-pass-basicblockpass"><em>BasicBlockPass</em></a>, you should derive from
+<tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>: explain briefly what SCC, Tarjan’s algo, and B-U mean.</p>
+<p>To be explicit, CallGraphSCCPass subclasses are:</p>
+<ol class="arabic simple">
+<li>... <em>not allowed</em> to inspect or modify any <tt class="docutils literal"><span class="pre">Function</span></tt>s other than those
+in the current SCC and the direct callers and direct callees of the SCC.</li>
+<li>... <em>required</em> to preserve the current <tt class="docutils literal"><span class="pre">CallGraph</span></tt> object, updating it to
+reflect any changes made to the program.</li>
+<li>... <em>not allowed</em> to add or remove SCC’s from the current Module, though
+they may change the contents of an SCC.</li>
+<li>... <em>allowed</em> to add or remove global variables from the current Module.</li>
+<li>... <em>allowed</em> to maintain state across invocations of <a class="reference internal" href="#writing-an-llvm-pass-runonscc"><em>runOnSCC</em></a> (including global data).</li>
+</ol>
+<p>Implementing a <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt> is slightly tricky in some cases because it
+has to handle SCCs with more than one node in it. All of the virtual methods
+described below should return <tt class="docutils literal"><span class="pre">true</span></tt> if they modified the program, or
+<tt class="docutils literal"><span class="pre">false</span></tt> if they didn’t.</p>
+<div class="section" id="the-doinitialization-callgraph-method">
+<h4><a class="toc-backref" href="#id15">The <tt class="docutils literal"><span class="pre">doInitialization(CallGraph</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-callgraph-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">CallGraph</span> <span class="o">&</span><span class="n">CG</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is allowed to do most of the things that
+<tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt>es are not allowed to do. They can add and remove
+functions, get pointers to functions, etc. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is
+designed to do simple initialization type of stuff that does not depend on the
+SCCs being processed. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to
+overlap with any other pass executions (thus it should be very fast).</p>
+</div>
+<div class="section" id="the-runonscc-method">
+<span id="writing-an-llvm-pass-runonscc"></span><h4><a class="toc-backref" href="#id16">The <tt class="docutils literal"><span class="pre">runOnSCC</span></tt> method</a><a class="headerlink" href="#the-runonscc-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnSCC</span><span class="p">(</span><span class="n">CallGraphSCC</span> <span class="o">&</span><span class="n">SCC</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnSCC</span></tt> method performs the interesting work of the pass, and should
+return <tt class="docutils literal"><span class="pre">true</span></tt> if the module was modified by the transformation, <tt class="docutils literal"><span class="pre">false</span></tt>
+otherwise.</p>
+</div>
+<div class="section" id="the-dofinalization-callgraph-method">
+<h4><a class="toc-backref" href="#id17">The <tt class="docutils literal"><span class="pre">doFinalization(CallGraph</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-dofinalization-callgraph-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">(</span><span class="n">CallGraph</span> <span class="o">&</span><span class="n">CG</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonscc"><em>runOnSCC</em></a> for every SCC in the program being compiled.</p>
+</div>
+</div>
+<div class="section" id="the-functionpass-class">
+<span id="writing-an-llvm-pass-functionpass"></span><h3><a class="toc-backref" href="#id18">The <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> class</a><a class="headerlink" href="#the-functionpass-class" title="Permalink to this headline">¶</a></h3>
+<p>In contrast to <tt class="docutils literal"><span class="pre">ModulePass</span></tt> subclasses, <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Pass.html">FunctionPass</a> subclasses do have a
+predictable, local behavior that can be expected by the system. All
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt> execute on each function in the program independent of all of
+the other functions in the program. <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es do not require that
+they are executed in a particular order, and <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es do not modify
+external functions.</p>
+<p>To be explicit, <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> subclasses are not allowed to:</p>
+<ol class="arabic simple">
+<li>Inspect or modify a <tt class="docutils literal"><span class="pre">Function</span></tt> other than the one currently being processed.</li>
+<li>Add or remove <tt class="docutils literal"><span class="pre">Function</span></tt>s from the current <tt class="docutils literal"><span class="pre">Module</span></tt>.</li>
+<li>Add or remove global variables from the current <tt class="docutils literal"><span class="pre">Module</span></tt>.</li>
+<li>Maintain state across invocations of <a class="reference internal" href="#writing-an-llvm-pass-runonfunction"><em>runOnFunction</em></a> (including global data).</li>
+</ol>
+<p>Implementing a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> is usually straightforward (See the <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello
+World</em></a> pass for example).
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es may overload three virtual methods to do their work. All
+of these methods should return <tt class="docutils literal"><span class="pre">true</span></tt> if they modified the program, or
+<tt class="docutils literal"><span class="pre">false</span></tt> if they didn’t.</p>
+<div class="section" id="the-doinitialization-module-method">
+<span id="writing-an-llvm-pass-doinitialization-mod"></span><h4><a class="toc-backref" href="#id19">The <tt class="docutils literal"><span class="pre">doInitialization(Module</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-module-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is allowed to do most of the things that
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es are not allowed to do. They can add and remove functions,
+get pointers to functions, etc. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is designed to
+do simple initialization type of stuff that does not depend on the functions
+being processed. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to
+overlap with any other pass executions (thus it should be very fast).</p>
+<p>A good example of how this method should be used is the <a class="reference external" href="http://llvm.org/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations</a> pass. This pass
+converts <tt class="docutils literal"><span class="pre">malloc</span></tt> and <tt class="docutils literal"><span class="pre">free</span></tt> instructions into platform dependent
+<tt class="docutils literal"><span class="pre">malloc()</span></tt> and <tt class="docutils literal"><span class="pre">free()</span></tt> function calls. It uses the <tt class="docutils literal"><span class="pre">doInitialization</span></tt>
+method to get a reference to the <tt class="docutils literal"><span class="pre">malloc</span></tt> and <tt class="docutils literal"><span class="pre">free</span></tt> functions that it
+needs, adding prototypes to the module if necessary.</p>
+</div>
+<div class="section" id="the-runonfunction-method">
+<span id="writing-an-llvm-pass-runonfunction"></span><h4><a class="toc-backref" href="#id20">The <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method</a><a class="headerlink" href="#the-runonfunction-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method must be implemented by your subclass to do the
+transformation or analysis work of your pass. As usual, a <tt class="docutils literal"><span class="pre">true</span></tt> value
+should be returned if the function is modified.</p>
+</div>
+<div class="section" id="the-dofinalization-module-method">
+<span id="writing-an-llvm-pass-dofinalization-mod"></span><h4><a class="toc-backref" href="#id21">The <tt class="docutils literal"><span class="pre">doFinalization(Module</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-dofinalization-module-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonfunction"><em>runOnFunction</em></a> for every function in the program being
+compiled.</p>
+</div>
+</div>
+<div class="section" id="the-looppass-class">
+<span id="writing-an-llvm-pass-looppass"></span><h3><a class="toc-backref" href="#id22">The <tt class="docutils literal"><span class="pre">LoopPass</span></tt> class</a><a class="headerlink" href="#the-looppass-class" title="Permalink to this headline">¶</a></h3>
+<p>All <tt class="docutils literal"><span class="pre">LoopPass</span></tt> execute on each loop in the function independent of all of the
+other loops in the function. <tt class="docutils literal"><span class="pre">LoopPass</span></tt> processes loops in loop nest order
+such that outer most loop is processed last.</p>
+<p><tt class="docutils literal"><span class="pre">LoopPass</span></tt> subclasses are allowed to update loop nest using <tt class="docutils literal"><span class="pre">LPPassManager</span></tt>
+interface. Implementing a loop pass is usually straightforward.
+<tt class="docutils literal"><span class="pre">LoopPass</span></tt>es may overload three virtual methods to do their work. All
+these methods should return <tt class="docutils literal"><span class="pre">true</span></tt> if they modified the program, or <tt class="docutils literal"><span class="pre">false</span></tt>
+if they didn’t.</p>
+<div class="section" id="the-doinitialization-loop-lppassmanager-method">
+<h4><a class="toc-backref" href="#id23">The <tt class="docutils literal"><span class="pre">doInitialization(Loop</span> <span class="pre">*,</span> <span class="pre">LPPassManager</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-loop-lppassmanager-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">Loop</span> <span class="o">*</span><span class="p">,</span> <span class="n">LPPassManager</span> <span class="o">&</span><span class="n">LPM</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is designed to do simple initialization type of
+stuff that does not depend on the functions being processed. The
+<tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to overlap with any other
+pass executions (thus it should be very fast). <tt class="docutils literal"><span class="pre">LPPassManager</span></tt> interface
+should be used to access <tt class="docutils literal"><span class="pre">Function</span></tt> or <tt class="docutils literal"><span class="pre">Module</span></tt> level analysis information.</p>
+</div>
+<div class="section" id="the-runonloop-method">
+<span id="writing-an-llvm-pass-runonloop"></span><h4><a class="toc-backref" href="#id24">The <tt class="docutils literal"><span class="pre">runOnLoop</span></tt> method</a><a class="headerlink" href="#the-runonloop-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnLoop</span><span class="p">(</span><span class="n">Loop</span> <span class="o">*</span><span class="p">,</span> <span class="n">LPPassManager</span> <span class="o">&</span><span class="n">LPM</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnLoop</span></tt> method must be implemented by your subclass to do the
+transformation or analysis work of your pass. As usual, a <tt class="docutils literal"><span class="pre">true</span></tt> value
+should be returned if the function is modified. <tt class="docutils literal"><span class="pre">LPPassManager</span></tt> interface
+should be used to update loop nest.</p>
+</div>
+<div class="section" id="the-dofinalization-method">
+<h4><a class="toc-backref" href="#id25">The <tt class="docutils literal"><span class="pre">doFinalization()</span></tt> method</a><a class="headerlink" href="#the-dofinalization-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonloop"><em>runOnLoop</em></a> for every loop in the program being compiled.</p>
+</div>
+</div>
+<div class="section" id="the-regionpass-class">
+<span id="writing-an-llvm-pass-regionpass"></span><h3><a class="toc-backref" href="#id26">The <tt class="docutils literal"><span class="pre">RegionPass</span></tt> class</a><a class="headerlink" href="#the-regionpass-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">RegionPass</span></tt> is similar to <a class="reference internal" href="#writing-an-llvm-pass-looppass"><em>LoopPass</em></a>,
+but executes on each single entry single exit region in the function.
+<tt class="docutils literal"><span class="pre">RegionPass</span></tt> processes regions in nested order such that the outer most
+region is processed last.</p>
+<p><tt class="docutils literal"><span class="pre">RegionPass</span></tt> subclasses are allowed to update the region tree by using the
+<tt class="docutils literal"><span class="pre">RGPassManager</span></tt> interface. You may overload three virtual methods of
+<tt class="docutils literal"><span class="pre">RegionPass</span></tt> to implement your own region pass. All these methods should
+return <tt class="docutils literal"><span class="pre">true</span></tt> if they modified the program, or <tt class="docutils literal"><span class="pre">false</span></tt> if they did not.</p>
+<div class="section" id="the-doinitialization-region-rgpassmanager-method">
+<h4><a class="toc-backref" href="#id27">The <tt class="docutils literal"><span class="pre">doInitialization(Region</span> <span class="pre">*,</span> <span class="pre">RGPassManager</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-region-rgpassmanager-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">Region</span> <span class="o">*</span><span class="p">,</span> <span class="n">RGPassManager</span> <span class="o">&</span><span class="n">RGM</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is designed to do simple initialization type of
+stuff that does not depend on the functions being processed. The
+<tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to overlap with any other
+pass executions (thus it should be very fast). <tt class="docutils literal"><span class="pre">RPPassManager</span></tt> interface
+should be used to access <tt class="docutils literal"><span class="pre">Function</span></tt> or <tt class="docutils literal"><span class="pre">Module</span></tt> level analysis information.</p>
+</div>
+<div class="section" id="the-runonregion-method">
+<span id="writing-an-llvm-pass-runonregion"></span><h4><a class="toc-backref" href="#id28">The <tt class="docutils literal"><span class="pre">runOnRegion</span></tt> method</a><a class="headerlink" href="#the-runonregion-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnRegion</span><span class="p">(</span><span class="n">Region</span> <span class="o">*</span><span class="p">,</span> <span class="n">RGPassManager</span> <span class="o">&</span><span class="n">RGM</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnRegion</span></tt> method must be implemented by your subclass to do the
+transformation or analysis work of your pass. As usual, a true value should be
+returned if the region is modified. <tt class="docutils literal"><span class="pre">RGPassManager</span></tt> interface should be used to
+update region tree.</p>
+</div>
+<div class="section" id="id2">
+<h4><a class="toc-backref" href="#id29">The <tt class="docutils literal"><span class="pre">doFinalization()</span></tt> method</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonregion"><em>runOnRegion</em></a> for every region in the program being
+compiled.</p>
+</div>
+</div>
+<div class="section" id="the-basicblockpass-class">
+<span id="writing-an-llvm-pass-basicblockpass"></span><h3><a class="toc-backref" href="#id30">The <tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt> class</a><a class="headerlink" href="#the-basicblockpass-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt>es are just like <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass’s</em></a> , except that they must limit their scope
+of inspection and modification to a single basic block at a time. As such,
+they are <strong>not</strong> allowed to do any of the following:</p>
+<ol class="arabic simple">
+<li>Modify or inspect any basic blocks outside of the current one.</li>
+<li>Maintain state across invocations of <a class="reference internal" href="#writing-an-llvm-pass-runonbasicblock"><em>runOnBasicBlock</em></a>.</li>
+<li>Modify the control flow graph (by altering terminator instructions)</li>
+<li>Any of the things forbidden for <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPasses</em></a>.</li>
+</ol>
+<p><tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt>es are useful for traditional local and “peephole”
+optimizations. They may override the same <a class="reference internal" href="#writing-an-llvm-pass-doinitialization-mod"><em>doInitialization(Module &)</em></a> and <a class="reference internal" href="#writing-an-llvm-pass-dofinalization-mod"><em>doFinalization(Module &)</em></a> methods that <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass’s</em></a> have, but also have the following virtual
+methods that may also be implemented:</p>
+<div class="section" id="the-doinitialization-function-method">
+<h4><a class="toc-backref" href="#id31">The <tt class="docutils literal"><span class="pre">doInitialization(Function</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-function-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is allowed to do most of the things that
+<tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt>es are not allowed to do, but that <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es
+can. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is designed to do simple initialization
+that does not depend on the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s being processed. The
+<tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to overlap with any other
+pass executions (thus it should be very fast).</p>
+</div>
+<div class="section" id="the-runonbasicblock-method">
+<span id="writing-an-llvm-pass-runonbasicblock"></span><h4><a class="toc-backref" href="#id32">The <tt class="docutils literal"><span class="pre">runOnBasicBlock</span></tt> method</a><a class="headerlink" href="#the-runonbasicblock-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnBasicBlock</span><span class="p">(</span><span class="n">BasicBlock</span> <span class="o">&</span><span class="n">BB</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Override this function to do the work of the <tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt>. This function
+is not allowed to inspect or modify basic blocks other than the parameter, and
+are not allowed to modify the CFG. A <tt class="docutils literal"><span class="pre">true</span></tt> value must be returned if the
+basic block is modified.</p>
+</div>
+<div class="section" id="the-dofinalization-function-method">
+<h4><a class="toc-backref" href="#id33">The <tt class="docutils literal"><span class="pre">doFinalization(Function</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-dofinalization-function-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonbasicblock"><em>runOnBasicBlock</em></a> for every <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> in the program
+being compiled. This can be used to perform per-function finalization.</p>
+</div>
+</div>
+<div class="section" id="the-machinefunctionpass-class">
+<h3><a class="toc-backref" href="#id34">The <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> class</a><a class="headerlink" href="#the-machinefunctionpass-class" title="Permalink to this headline">¶</a></h3>
+<p>A <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> is a part of the LLVM code generator that executes on
+the machine-dependent representation of each LLVM function in the program.</p>
+<p>Code generator passes are registered and initialized specially by
+<tt class="docutils literal"><span class="pre">TargetMachine::addPassesToEmitFile</span></tt> and similar routines, so they cannot
+generally be run from the <strong class="program">opt</strong> or <strong class="program">bugpoint</strong> commands.</p>
+<p>A <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> is also a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, so all the restrictions
+that apply to a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> also apply to it. <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>es
+also have additional restrictions. In particular, <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>es
+are not allowed to do any of the following:</p>
+<ol class="arabic simple">
+<li>Modify or create any LLVM IR <tt class="docutils literal"><span class="pre">Instruction</span></tt>s, <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s,
+<tt class="docutils literal"><span class="pre">Argument</span></tt>s, <tt class="docutils literal"><span class="pre">Function</span></tt>s, <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt>s,
+<tt class="docutils literal"><span class="pre">GlobalAlias</span></tt>es, or <tt class="docutils literal"><span class="pre">Module</span></tt>s.</li>
+<li>Modify a <tt class="docutils literal"><span class="pre">MachineFunction</span></tt> other than the one currently being processed.</li>
+<li>Maintain state across invocations of <a class="reference internal" href="#writing-an-llvm-pass-runonmachinefunction"><em>runOnMachineFunction</em></a> (including global data).</li>
+</ol>
+<div class="section" id="the-runonmachinefunction-machinefunction-mf-method">
+<span id="writing-an-llvm-pass-runonmachinefunction"></span><h4><a class="toc-backref" href="#id35">The <tt class="docutils literal"><span class="pre">runOnMachineFunction(MachineFunction</span> <span class="pre">&MF)</span></tt> method</a><a class="headerlink" href="#the-runonmachinefunction-machinefunction-mf-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnMachineFunction</span><span class="p">(</span><span class="n">MachineFunction</span> <span class="o">&</span><span class="n">MF</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> can be considered the main entry point of a
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>; that is, you should override this method to do the
+work of your <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>.</p>
+<p>The <tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> method is called on every <tt class="docutils literal"><span class="pre">MachineFunction</span></tt> in a
+<tt class="docutils literal"><span class="pre">Module</span></tt>, so that the <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> may perform optimizations on
+the machine-dependent representation of the function. If you want to get at
+the LLVM <tt class="docutils literal"><span class="pre">Function</span></tt> for the <tt class="docutils literal"><span class="pre">MachineFunction</span></tt> you’re working on, use
+<tt class="docutils literal"><span class="pre">MachineFunction</span></tt>‘s <tt class="docutils literal"><span class="pre">getFunction()</span></tt> accessor method — but remember, you
+may not modify the LLVM <tt class="docutils literal"><span class="pre">Function</span></tt> or its contents from a
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="pass-registration">
+<span id="writing-an-llvm-pass-registration"></span><h3><a class="toc-backref" href="#id36">Pass registration</a><a class="headerlink" href="#pass-registration" title="Permalink to this headline">¶</a></h3>
+<p>In the <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> example pass we
+illustrated how pass registration works, and discussed some of the reasons that
+it is used and what it does. Here we discuss how and why passes are
+registered.</p>
+<p>As we saw above, passes are registered with the <tt class="docutils literal"><span class="pre">RegisterPass</span></tt> template. The
+template parameter is the name of the pass that is to be used on the command
+line to specify that the pass should be added to a program (for example, with
+<strong class="program">opt</strong> or <strong class="program">bugpoint</strong>). The first argument is the name of the
+pass, which is to be used for the <a class="reference internal" href="CommandGuide/opt.html#cmdoption-help"><em class="xref std std-option">-help</em></a> output of programs, as well
+as for debug output generated by the <em class="xref std std-option">--debug-pass</em> option.</p>
+<p>If you want your pass to be easily dumpable, you should implement the virtual
+print method:</p>
+<div class="section" id="the-print-method">
+<h4><a class="toc-backref" href="#id37">The <tt class="docutils literal"><span class="pre">print</span></tt> method</a><a class="headerlink" href="#the-print-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">print</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="n">O</span><span class="p">,</span> <span class="k">const</span> <span class="n">Module</span> <span class="o">*</span><span class="n">M</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">print</span></tt> method must be implemented by “analyses” in order to print a
+human readable version of the analysis results. This is useful for debugging
+an analysis itself, as well as for other people to figure out how an analysis
+works. Use the opt <tt class="docutils literal"><span class="pre">-analyze</span></tt> argument to invoke this method.</p>
+<p>The <tt class="docutils literal"><span class="pre">llvm::raw_ostream</span></tt> parameter specifies the stream to write the results
+on, and the <tt class="docutils literal"><span class="pre">Module</span></tt> parameter gives a pointer to the top level module of the
+program that has been analyzed. Note however that this pointer may be <tt class="docutils literal"><span class="pre">NULL</span></tt>
+in certain circumstances (such as calling the <tt class="docutils literal"><span class="pre">Pass::dump()</span></tt> from a
+debugger), so it should only be used to enhance debug output, it should not be
+depended on.</p>
+</div>
+</div>
+<div class="section" id="specifying-interactions-between-passes">
+<span id="writing-an-llvm-pass-interaction"></span><h3><a class="toc-backref" href="#id38">Specifying interactions between passes</a><a class="headerlink" href="#specifying-interactions-between-passes" title="Permalink to this headline">¶</a></h3>
+<p>One of the main responsibilities of the <tt class="docutils literal"><span class="pre">PassManager</span></tt> is to make sure that
+passes interact with each other correctly. Because <tt class="docutils literal"><span class="pre">PassManager</span></tt> tries to
+<a class="reference internal" href="#writing-an-llvm-pass-passmanager"><em>optimize the execution of passes</em></a> it
+must know how the passes interact with each other and what dependencies exist
+between the various passes. To track this, each pass can declare the set of
+passes that are required to be executed before the current pass, and the passes
+which are invalidated by the current pass.</p>
+<p>Typically this functionality is used to require that analysis results are
+computed before your pass is run. Running arbitrary transformation passes can
+invalidate the computed analysis results, which is what the invalidation set
+specifies. If a pass does not implement the <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a> method, it defaults to not having any
+prerequisite passes, and invalidating <strong>all</strong> other passes.</p>
+<div class="section" id="the-getanalysisusage-method">
+<span id="writing-an-llvm-pass-getanalysisusage"></span><h4><a class="toc-backref" href="#id39">The <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt> method</a><a class="headerlink" href="#the-getanalysisusage-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">getAnalysisUsage</span><span class="p">(</span><span class="n">AnalysisUsage</span> <span class="o">&</span><span class="n">Info</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>By implementing the <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt> method, the required and invalidated
+sets may be specified for your transformation. The implementation should fill
+in the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1AnalysisUsage.html">AnalysisUsage</a> object with
+information about which passes are required and not invalidated. To do this, a
+pass may call any of the following methods on the <tt class="docutils literal"><span class="pre">AnalysisUsage</span></tt> object:</p>
+</div>
+<div class="section" id="the-analysisusage-addrequired-and-analysisusage-addrequiredtransitive-methods">
+<h4><a class="toc-backref" href="#id40">The <tt class="docutils literal"><span class="pre">AnalysisUsage::addRequired<></span></tt> and <tt class="docutils literal"><span class="pre">AnalysisUsage::addRequiredTransitive<></span></tt> methods</a><a class="headerlink" href="#the-analysisusage-addrequired-and-analysisusage-addrequiredtransitive-methods" title="Permalink to this headline">¶</a></h4>
+<p>If your pass requires a previous pass to be executed (an analysis for example),
+it can use one of these methods to arrange for it to be run before your pass.
+LLVM has many different types of analyses and passes that can be required,
+spanning the range from <tt class="docutils literal"><span class="pre">DominatorSet</span></tt> to <tt class="docutils literal"><span class="pre">BreakCriticalEdges</span></tt>. Requiring
+<tt class="docutils literal"><span class="pre">BreakCriticalEdges</span></tt>, for example, guarantees that there will be no critical
+edges in the CFG when your pass has been run.</p>
+<p>Some analyses chain to other analyses to do their job. For example, an
+<cite>AliasAnalysis <AliasAnalysis></cite> implementation is required to <a class="reference internal" href="AliasAnalysis.html#aliasanalysis-chaining"><em>chain</em></a> to other alias analysis passes. In cases where
+analyses chain, the <tt class="docutils literal"><span class="pre">addRequiredTransitive</span></tt> method should be used instead of
+the <tt class="docutils literal"><span class="pre">addRequired</span></tt> method. This informs the <tt class="docutils literal"><span class="pre">PassManager</span></tt> that the
+transitively required pass should be alive as long as the requiring pass is.</p>
+</div>
+<div class="section" id="the-analysisusage-addpreserved-method">
+<h4><a class="toc-backref" href="#id41">The <tt class="docutils literal"><span class="pre">AnalysisUsage::addPreserved<></span></tt> method</a><a class="headerlink" href="#the-analysisusage-addpreserved-method" title="Permalink to this headline">¶</a></h4>
+<p>One of the jobs of the <tt class="docutils literal"><span class="pre">PassManager</span></tt> is to optimize how and when analyses are
+run. In particular, it attempts to avoid recomputing data unless it needs to.
+For this reason, passes are allowed to declare that they preserve (i.e., they
+don’t invalidate) an existing analysis if it’s available. For example, a
+simple constant folding pass would not modify the CFG, so it can’t possibly
+affect the results of dominator analysis. By default, all passes are assumed
+to invalidate all others.</p>
+<p>The <tt class="docutils literal"><span class="pre">AnalysisUsage</span></tt> class provides several methods which are useful in
+certain circumstances that are related to <tt class="docutils literal"><span class="pre">addPreserved</span></tt>. In particular, the
+<tt class="docutils literal"><span class="pre">setPreservesAll</span></tt> method can be called to indicate that the pass does not
+modify the LLVM program at all (which is true for analyses), and the
+<tt class="docutils literal"><span class="pre">setPreservesCFG</span></tt> method can be used by transformations that change
+instructions in the program but do not modify the CFG or terminator
+instructions (note that this property is implicitly set for
+<a class="reference internal" href="#writing-an-llvm-pass-basicblockpass"><em>BasicBlockPass</em></a>es).</p>
+<p><tt class="docutils literal"><span class="pre">addPreserved</span></tt> is particularly useful for transformations like
+<tt class="docutils literal"><span class="pre">BreakCriticalEdges</span></tt>. This pass knows how to update a small set of loop and
+dominator related analyses if they exist, so it can preserve them, despite the
+fact that it hacks on the CFG.</p>
+</div>
+<div class="section" id="example-implementations-of-getanalysisusage">
+<h4><a class="toc-backref" href="#id42">Example implementations of <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt></a><a class="headerlink" href="#example-implementations-of-getanalysisusage" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// This example modifies the program, but does not modify the CFG</span>
+<span class="kt">void</span> <span class="n">LICM</span><span class="o">::</span><span class="n">getAnalysisUsage</span><span class="p">(</span><span class="n">AnalysisUsage</span> <span class="o">&</span><span class="n">AU</span><span class="p">)</span> <span class="k">const</span> <span class="p">{</span>
+ <span class="n">AU</span><span class="p">.</span><span class="n">setPreservesCFG</span><span class="p">();</span>
+ <span class="n">AU</span><span class="p">.</span><span class="n">addRequired</span><span class="o"><</span><span class="n">LoopInfoWrapperPass</span><span class="o">></span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-getanalysis-and-getanalysisifavailable-methods">
+<span id="writing-an-llvm-pass-getanalysis"></span><h4><a class="toc-backref" href="#id43">The <tt class="docutils literal"><span class="pre">getAnalysis<></span></tt> and <tt class="docutils literal"><span class="pre">getAnalysisIfAvailable<></span></tt> methods</a><a class="headerlink" href="#the-getanalysis-and-getanalysisifavailable-methods" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">Pass::getAnalysis<></span></tt> method is automatically inherited by your class,
+providing you with access to the passes that you declared that you required
+with the <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a>
+method. It takes a single template argument that specifies which pass class
+you want, and returns a reference to that pass. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">LICM</span><span class="o">::</span><span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LoopInfo</span> <span class="o">&</span><span class="n">LI</span> <span class="o">=</span> <span class="n">getAnalysis</span><span class="o"><</span><span class="n">LoopInfoWrapperPass</span><span class="o">></span><span class="p">().</span><span class="n">getLoopInfo</span><span class="p">();</span>
+ <span class="c1">//...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This method call returns a reference to the pass desired. You may get a
+runtime assertion failure if you attempt to get an analysis that you did not
+declare as required in your <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a> implementation. This method can be
+called by your <tt class="docutils literal"><span class="pre">run*</span></tt> method implementation, or by any other local method
+invoked by your <tt class="docutils literal"><span class="pre">run*</span></tt> method.</p>
+<p>A module level pass can use function level analysis info using this interface.
+For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">ModuleLevelPass</span><span class="o">::</span><span class="n">runOnModule</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="n">DominatorTree</span> <span class="o">&</span><span class="n">DT</span> <span class="o">=</span> <span class="n">getAnalysis</span><span class="o"><</span><span class="n">DominatorTree</span><span class="o">></span><span class="p">(</span><span class="n">Func</span><span class="p">);</span>
+ <span class="c1">//...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In above example, <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> for <tt class="docutils literal"><span class="pre">DominatorTree</span></tt> is called by pass
+manager before returning a reference to the desired pass.</p>
+<p>If your pass is capable of updating analyses if they exist (e.g.,
+<tt class="docutils literal"><span class="pre">BreakCriticalEdges</span></tt>, as described above), you can use the
+<tt class="docutils literal"><span class="pre">getAnalysisIfAvailable</span></tt> method, which returns a pointer to the analysis if
+it is active. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">DominatorSet</span> <span class="o">*</span><span class="n">DS</span> <span class="o">=</span> <span class="n">getAnalysisIfAvailable</span><span class="o"><</span><span class="n">DominatorSet</span><span class="o">></span><span class="p">())</span> <span class="p">{</span>
+ <span class="c1">// A DominatorSet is active. This code will update it.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="implementing-analysis-groups">
+<h3><a class="toc-backref" href="#id44">Implementing Analysis Groups</a><a class="headerlink" href="#implementing-analysis-groups" title="Permalink to this headline">¶</a></h3>
+<p>Now that we understand the basics of how passes are defined, how they are used,
+and how they are required from other passes, it’s time to get a little bit
+fancier. All of the pass relationships that we have seen so far are very
+simple: one pass depends on one other specific pass to be run before it can
+run. For many applications, this is great, for others, more flexibility is
+required.</p>
+<p>In particular, some analyses are defined such that there is a single simple
+interface to the analysis results, but multiple ways of calculating them.
+Consider alias analysis for example. The most trivial alias analysis returns
+“may alias” for any alias query. The most sophisticated analysis a
+flow-sensitive, context-sensitive interprocedural analysis that can take a
+significant amount of time to execute (and obviously, there is a lot of room
+between these two extremes for other implementations). To cleanly support
+situations like this, the LLVM Pass Infrastructure supports the notion of
+Analysis Groups.</p>
+<div class="section" id="analysis-group-concepts">
+<h4><a class="toc-backref" href="#id45">Analysis Group Concepts</a><a class="headerlink" href="#analysis-group-concepts" title="Permalink to this headline">¶</a></h4>
+<p>An Analysis Group is a single simple interface that may be implemented by
+multiple different passes. Analysis Groups can be given human readable names
+just like passes, but unlike passes, they need not derive from the <tt class="docutils literal"><span class="pre">Pass</span></tt>
+class. An analysis group may have one or more implementations, one of which is
+the “default” implementation.</p>
+<p>Analysis groups are used by client passes just like other passes are: the
+<tt class="docutils literal"><span class="pre">AnalysisUsage::addRequired()</span></tt> and <tt class="docutils literal"><span class="pre">Pass::getAnalysis()</span></tt> methods. In order
+to resolve this requirement, the <a class="reference internal" href="#writing-an-llvm-pass-passmanager"><em>PassManager</em></a> scans the available passes to see if any
+implementations of the analysis group are available. If none is available, the
+default implementation is created for the pass to use. All standard rules for
+<a class="reference internal" href="#writing-an-llvm-pass-interaction"><em>interaction between passes</em></a> still
+apply.</p>
+<p>Although <a class="reference internal" href="#writing-an-llvm-pass-registration"><em>Pass Registration</em></a> is
+optional for normal passes, all analysis group implementations must be
+registered, and must use the <a class="reference internal" href="#writing-an-llvm-pass-registeranalysisgroup"><em>INITIALIZE_AG_PASS</em></a> template to join the
+implementation pool. Also, a default implementation of the interface <strong>must</strong>
+be registered with <a class="reference internal" href="#writing-an-llvm-pass-registeranalysisgroup"><em>RegisterAnalysisGroup</em></a>.</p>
+<p>As a concrete example of an Analysis Group in action, consider the
+<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>
+analysis group. The default implementation of the alias analysis interface
+(the <a class="reference external" href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">basicaa</a> pass)
+just does a few simple checks that don’t require significant analysis to
+compute (such as: two different globals can never alias each other, etc).
+Passes that use the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a> interface (for
+example the <a class="reference external" href="http://llvm.org/doxygen/structGCSE.html">gcse</a> pass), do not
+care which implementation of alias analysis is actually provided, they just use
+the designated interface.</p>
+<p>From the user’s perspective, commands work just like normal. Issuing the
+command <tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-gcse</span> <span class="pre">...</span></tt> will cause the <tt class="docutils literal"><span class="pre">basicaa</span></tt> class to be instantiated
+and added to the pass sequence. Issuing the command <tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-somefancyaa</span> <span class="pre">-gcse</span>
+<span class="pre">...</span></tt> will cause the <tt class="docutils literal"><span class="pre">gcse</span></tt> pass to use the <tt class="docutils literal"><span class="pre">somefancyaa</span></tt> alias analysis
+(which doesn’t actually exist, it’s just a hypothetical example) instead.</p>
+</div>
+<div class="section" id="using-registeranalysisgroup">
+<span id="writing-an-llvm-pass-registeranalysisgroup"></span><h4><a class="toc-backref" href="#id46">Using <tt class="docutils literal"><span class="pre">RegisterAnalysisGroup</span></tt></a><a class="headerlink" href="#using-registeranalysisgroup" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">RegisterAnalysisGroup</span></tt> template is used to register the analysis group
+itself, while the <tt class="docutils literal"><span class="pre">INITIALIZE_AG_PASS</span></tt> is used to add pass implementations to
+the analysis group. First, an analysis group should be registered, with a
+human readable name provided for it. Unlike registration of passes, there is
+no command line argument to be specified for the Analysis Group Interface
+itself, because it is “abstract”:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">RegisterAnalysisGroup</span><span class="o"><</span><span class="n">AliasAnalysis</span><span class="o">></span> <span class="n">A</span><span class="p">(</span><span class="s">"Alias Analysis"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Once the analysis is registered, passes can declare that they are valid
+implementations of the interface by using the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="p">{</span>
+ <span class="c1">// Declare that we implement the AliasAnalysis interface</span>
+ <span class="n">INITIALIZE_AG_PASS</span><span class="p">(</span><span class="n">FancyAA</span><span class="p">,</span> <span class="n">AliasAnalysis</span> <span class="p">,</span> <span class="s">"somefancyaa"</span><span class="p">,</span>
+ <span class="s">"A more complex alias analysis implementation"</span><span class="p">,</span>
+ <span class="nb">false</span><span class="p">,</span> <span class="c1">// Is CFG Only?</span>
+ <span class="nb">true</span><span class="p">,</span> <span class="c1">// Is Analysis?</span>
+ <span class="nb">false</span><span class="p">);</span> <span class="c1">// Is default Analysis Group implementation?</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This just shows a class <tt class="docutils literal"><span class="pre">FancyAA</span></tt> that uses the <tt class="docutils literal"><span class="pre">INITIALIZE_AG_PASS</span></tt> macro
+both to register and to “join” the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a> analysis group.
+Every implementation of an analysis group should join using this macro.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="p">{</span>
+ <span class="c1">// Declare that we implement the AliasAnalysis interface</span>
+ <span class="n">INITIALIZE_AG_PASS</span><span class="p">(</span><span class="n">BasicAA</span><span class="p">,</span> <span class="n">AliasAnalysis</span><span class="p">,</span> <span class="s">"basicaa"</span><span class="p">,</span>
+ <span class="s">"Basic Alias Analysis (default AA impl)"</span><span class="p">,</span>
+ <span class="nb">false</span><span class="p">,</span> <span class="c1">// Is CFG Only?</span>
+ <span class="nb">true</span><span class="p">,</span> <span class="c1">// Is Analysis?</span>
+ <span class="nb">true</span><span class="p">);</span> <span class="c1">// Is default Analysis Group implementation?</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here we show how the default implementation is specified (using the final
+argument to the <tt class="docutils literal"><span class="pre">INITIALIZE_AG_PASS</span></tt> template). There must be exactly one
+default implementation available at all times for an Analysis Group to be used.
+Only default implementation can derive from <tt class="docutils literal"><span class="pre">ImmutablePass</span></tt>. Here we declare
+that the <a class="reference external" href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">BasicAliasAnalysis</a> pass is the default
+implementation for the interface.</p>
+</div>
+</div>
+</div>
+<div class="section" id="pass-statistics">
+<h2><a class="toc-backref" href="#id47">Pass Statistics</a><a class="headerlink" href="#pass-statistics" title="Permalink to this headline">¶</a></h2>
+<p>The <a class="reference external" href="http://llvm.org/doxygen/Statistic_8h-source.html">Statistic</a> class is
+designed to be an easy way to expose various success metrics from passes.
+These statistics are printed at the end of a run, when the <a class="reference internal" href="CommandGuide/opt.html#cmdoption-stats"><em class="xref std std-option">-stats</em></a>
+command line option is enabled on the command line. See the <a class="reference internal" href="ProgrammersManual.html#statistic"><em>Statistics
+section</em></a> in the Programmer’s Manual for details.</p>
+<div class="section" id="what-passmanager-does">
+<span id="writing-an-llvm-pass-passmanager"></span><h3><a class="toc-backref" href="#id48">What PassManager does</a><a class="headerlink" href="#what-passmanager-does" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://llvm.org/doxygen/PassManager_8h-source.html">PassManager</a> <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1PassManager.html">class</a> takes a list of
+passes, ensures their <a class="reference internal" href="#writing-an-llvm-pass-interaction"><em>prerequisites</em></a>
+are set up correctly, and then schedules passes to run efficiently. All of the
+LLVM tools that run passes use the PassManager for execution of these passes.</p>
+<p>The PassManager does two main things to try to reduce the execution time of a
+series of passes:</p>
+<ol class="arabic">
+<li><p class="first"><strong>Share analysis results.</strong> The <tt class="docutils literal"><span class="pre">PassManager</span></tt> attempts to avoid
+recomputing analysis results as much as possible. This means keeping track
+of which analyses are available already, which analyses get invalidated, and
+which analyses are needed to be run for a pass. An important part of work
+is that the <tt class="docutils literal"><span class="pre">PassManager</span></tt> tracks the exact lifetime of all analysis
+results, allowing it to <a class="reference internal" href="#writing-an-llvm-pass-releasememory"><em>free memory</em></a> allocated to holding analysis results
+as soon as they are no longer needed.</p>
+</li>
+<li><p class="first"><strong>Pipeline the execution of passes on the program.</strong> The <tt class="docutils literal"><span class="pre">PassManager</span></tt>
+attempts to get better cache and memory usage behavior out of a series of
+passes by pipelining the passes together. This means that, given a series
+of consecutive <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a>, it
+will execute all of the <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a> on the first function, then all of the
+<a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPasses</em></a> on the second
+function, etc... until the entire program has been run through the passes.</p>
+<p>This improves the cache behavior of the compiler, because it is only
+touching the LLVM program representation for a single function at a time,
+instead of traversing the entire program. It reduces the memory consumption
+of compiler, because, for example, only one <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1DominatorSet.html">DominatorSet</a> needs to be
+calculated at a time. This also makes it possible to implement some
+<a class="reference internal" href="#writing-an-llvm-pass-smp"><em>interesting enhancements</em></a> in the future.</p>
+</li>
+</ol>
+<p>The effectiveness of the <tt class="docutils literal"><span class="pre">PassManager</span></tt> is influenced directly by how much
+information it has about the behaviors of the passes it is scheduling. For
+example, the “preserved” set is intentionally conservative in the face of an
+unimplemented <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a>
+method. Not implementing when it should be implemented will have the effect of
+not allowing any analysis results to live across the execution of your pass.</p>
+<p>The <tt class="docutils literal"><span class="pre">PassManager</span></tt> class exposes a <tt class="docutils literal"><span class="pre">--debug-pass</span></tt> command line options that
+is useful for debugging pass execution, seeing how things work, and diagnosing
+when you should be preserving more analyses than you currently are. (To get
+information about all of the variants of the <tt class="docutils literal"><span class="pre">--debug-pass</span></tt> option, just type
+“<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-help-hidden</span></tt>”).</p>
+<p>By using the –debug-pass=Structure option, for example, we can see how our
+<a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> pass interacts with other
+passes. Lets try it out with the gcse and licm passes:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -licm --debug-pass<span class="o">=</span>Structure < hello.bc > /dev/null
+<span class="go">Module Pass Manager</span>
+<span class="go"> Function Pass Manager</span>
+<span class="go"> Dominator Set Construction</span>
+<span class="go"> Immediate Dominators Construction</span>
+<span class="go"> Global Common Subexpression Elimination</span>
+<span class="go">-- Immediate Dominators Construction</span>
+<span class="go">-- Global Common Subexpression Elimination</span>
+<span class="go"> Natural Loop Construction</span>
+<span class="go"> Loop Invariant Code Motion</span>
+<span class="go">-- Natural Loop Construction</span>
+<span class="go">-- Loop Invariant Code Motion</span>
+<span class="go"> Module Verifier</span>
+<span class="go">-- Dominator Set Construction</span>
+<span class="go">-- Module Verifier</span>
+<span class="go"> Bitcode Writer</span>
+<span class="go">--Bitcode Writer</span>
+</pre></div>
+</div>
+<p>This output shows us when passes are constructed and when the analysis results
+are known to be dead (prefixed with “<tt class="docutils literal"><span class="pre">--</span></tt>”). Here we see that GCSE uses
+dominator and immediate dominator information to do its job. The LICM pass
+uses natural loop information, which uses dominator sets, but not immediate
+dominators. Because immediate dominators are no longer useful after the GCSE
+pass, it is immediately destroyed. The dominator sets are then reused to
+compute natural loop information, which is then used by the LICM pass.</p>
+<p>After the LICM pass, the module verifier runs (which is automatically added by
+the <strong class="program">opt</strong> tool), which uses the dominator set to check that the
+resultant LLVM code is well formed. After it finishes, the dominator set
+information is destroyed, after being computed once, and shared by three
+passes.</p>
+<p>Lets see how this changes when we run the <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> pass in between the two passes:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass<span class="o">=</span>Structure < hello.bc > /dev/null
+<span class="go">Module Pass Manager</span>
+<span class="go"> Function Pass Manager</span>
+<span class="go"> Dominator Set Construction</span>
+<span class="go"> Immediate Dominators Construction</span>
+<span class="go"> Global Common Subexpression Elimination</span>
+<span class="go">-- Dominator Set Construction</span>
+<span class="go">-- Immediate Dominators Construction</span>
+<span class="go">-- Global Common Subexpression Elimination</span>
+<span class="go"> Hello World Pass</span>
+<span class="go">-- Hello World Pass</span>
+<span class="go"> Dominator Set Construction</span>
+<span class="go"> Natural Loop Construction</span>
+<span class="go"> Loop Invariant Code Motion</span>
+<span class="go">-- Natural Loop Construction</span>
+<span class="go">-- Loop Invariant Code Motion</span>
+<span class="go"> Module Verifier</span>
+<span class="go">-- Dominator Set Construction</span>
+<span class="go">-- Module Verifier</span>
+<span class="go"> Bitcode Writer</span>
+<span class="go">--Bitcode Writer</span>
+<span class="go">Hello: __main</span>
+<span class="go">Hello: puts</span>
+<span class="go">Hello: main</span>
+</pre></div>
+</div>
+<p>Here we see that the <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> pass
+has killed the Dominator Set pass, even though it doesn’t modify the code at
+all! To fix this, we need to add the following <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a> method to our pass:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// We don't modify the program, so we preserve all analyses</span>
+<span class="kt">void</span> <span class="nf">getAnalysisUsage</span><span class="p">(</span><span class="n">AnalysisUsage</span> <span class="o">&</span><span class="n">AU</span><span class="p">)</span> <span class="k">const</span> <span class="n">override</span> <span class="p">{</span>
+ <span class="n">AU</span><span class="p">.</span><span class="n">setPreservesAll</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Now when we run our pass, we get this output:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass<span class="o">=</span>Structure < hello.bc > /dev/null
+<span class="go">Pass Arguments: -gcse -hello -licm</span>
+<span class="go">Module Pass Manager</span>
+<span class="go"> Function Pass Manager</span>
+<span class="go"> Dominator Set Construction</span>
+<span class="go"> Immediate Dominators Construction</span>
+<span class="go"> Global Common Subexpression Elimination</span>
+<span class="go">-- Immediate Dominators Construction</span>
+<span class="go">-- Global Common Subexpression Elimination</span>
+<span class="go"> Hello World Pass</span>
+<span class="go">-- Hello World Pass</span>
+<span class="go"> Natural Loop Construction</span>
+<span class="go"> Loop Invariant Code Motion</span>
+<span class="go">-- Loop Invariant Code Motion</span>
+<span class="go">-- Natural Loop Construction</span>
+<span class="go"> Module Verifier</span>
+<span class="go">-- Dominator Set Construction</span>
+<span class="go">-- Module Verifier</span>
+<span class="go"> Bitcode Writer</span>
+<span class="go">--Bitcode Writer</span>
+<span class="go">Hello: __main</span>
+<span class="go">Hello: puts</span>
+<span class="go">Hello: main</span>
+</pre></div>
+</div>
+<p>Which shows that we don’t accidentally invalidate dominator information
+anymore, and therefore do not have to compute it twice.</p>
+<div class="section" id="the-releasememory-method">
+<span id="writing-an-llvm-pass-releasememory"></span><h4><a class="toc-backref" href="#id49">The <tt class="docutils literal"><span class="pre">releaseMemory</span></tt> method</a><a class="headerlink" href="#the-releasememory-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="nf">releaseMemory</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">PassManager</span></tt> automatically determines when to compute analysis results,
+and how long to keep them around for. Because the lifetime of the pass object
+itself is effectively the entire duration of the compilation process, we need
+some way to free analysis results when they are no longer useful. The
+<tt class="docutils literal"><span class="pre">releaseMemory</span></tt> virtual method is the way to do this.</p>
+<p>If you are writing an analysis or any other pass that retains a significant
+amount of state (for use by another pass which “requires” your pass and uses
+the <a class="reference internal" href="#writing-an-llvm-pass-getanalysis"><em>getAnalysis</em></a> method) you should
+implement <tt class="docutils literal"><span class="pre">releaseMemory</span></tt> to, well, release the memory allocated to maintain
+this internal state. This method is called after the <tt class="docutils literal"><span class="pre">run*</span></tt> method for the
+class, before the next call of <tt class="docutils literal"><span class="pre">run*</span></tt> in your pass.</p>
+</div>
+</div>
+</div>
+<div class="section" id="registering-dynamically-loaded-passes">
+<h2><a class="toc-backref" href="#id50">Registering dynamically loaded passes</a><a class="headerlink" href="#registering-dynamically-loaded-passes" title="Permalink to this headline">¶</a></h2>
+<p><em>Size matters</em> when constructing production quality tools using LLVM, both for
+the purposes of distribution, and for regulating the resident code size when
+running on the target system. Therefore, it becomes desirable to selectively
+use some passes, while omitting others and maintain the flexibility to change
+configurations later on. You want to be able to do all this, and, provide
+feedback to the user. This is where pass registration comes into play.</p>
+<p>The fundamental mechanisms for pass registration are the
+<tt class="docutils literal"><span class="pre">MachinePassRegistry</span></tt> class and subclasses of <tt class="docutils literal"><span class="pre">MachinePassRegistryNode</span></tt>.</p>
+<p>An instance of <tt class="docutils literal"><span class="pre">MachinePassRegistry</span></tt> is used to maintain a list of
+<tt class="docutils literal"><span class="pre">MachinePassRegistryNode</span></tt> objects. This instance maintains the list and
+communicates additions and deletions to the command line interface.</p>
+<p>An instance of <tt class="docutils literal"><span class="pre">MachinePassRegistryNode</span></tt> subclass is used to maintain
+information provided about a particular pass. This information includes the
+command line name, the command help string and the address of the function used
+to create an instance of the pass. A global static constructor of one of these
+instances <em>registers</em> with a corresponding <tt class="docutils literal"><span class="pre">MachinePassRegistry</span></tt>, the static
+destructor <em>unregisters</em>. Thus a pass that is statically linked in the tool
+will be registered at start up. A dynamically loaded pass will register on
+load and unregister at unload.</p>
+<div class="section" id="using-existing-registries">
+<h3><a class="toc-backref" href="#id51">Using existing registries</a><a class="headerlink" href="#using-existing-registries" title="Permalink to this headline">¶</a></h3>
+<p>There are predefined registries to track instruction scheduling
+(<tt class="docutils literal"><span class="pre">RegisterScheduler</span></tt>) and register allocation (<tt class="docutils literal"><span class="pre">RegisterRegAlloc</span></tt>) machine
+passes. Here we will describe how to <em>register</em> a register allocator machine
+pass.</p>
+<p>Implement your register allocator machine pass. In your register allocator
+<tt class="docutils literal"><span class="pre">.cpp</span></tt> file add the following include:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/CodeGen/RegAllocRegistry.h"</span>
+</pre></div>
+</div>
+<p>Also in your register allocator <tt class="docutils literal"><span class="pre">.cpp</span></tt> file, define a creator function in the
+form:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FunctionPass</span> <span class="o">*</span><span class="nf">createMyRegisterAllocator</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="n">MyRegisterAllocator</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that the signature of this function should match the type of
+<tt class="docutils literal"><span class="pre">RegisterRegAlloc::FunctionPassCtor</span></tt>. In the same file add the “installing”
+declaration, in the form:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">RegisterRegAlloc</span> <span class="nf">myRegAlloc</span><span class="p">(</span><span class="s">"myregalloc"</span><span class="p">,</span>
+ <span class="s">"my register allocator help string"</span><span class="p">,</span>
+ <span class="n">createMyRegisterAllocator</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Note the two spaces prior to the help string produces a tidy result on the
+<a class="reference internal" href="CommandGuide/opt.html#cmdoption-help"><em class="xref std std-option">-help</em></a> query.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> llc -help
+<span class="go"> ...</span>
+<span class="go"> -regalloc - Register allocator to use (default=linearscan)</span>
+<span class="go"> =linearscan - linear scan register allocator</span>
+<span class="go"> =local - local register allocator</span>
+<span class="go"> =simple - simple register allocator</span>
+<span class="go"> =myregalloc - my register allocator help string</span>
+<span class="go"> ...</span>
+</pre></div>
+</div>
+<p>And that’s it. The user is now free to use <tt class="docutils literal"><span class="pre">-regalloc=myregalloc</span></tt> as an
+option. Registering instruction schedulers is similar except use the
+<tt class="docutils literal"><span class="pre">RegisterScheduler</span></tt> class. Note that the
+<tt class="docutils literal"><span class="pre">RegisterScheduler::FunctionPassCtor</span></tt> is significantly different from
+<tt class="docutils literal"><span class="pre">RegisterRegAlloc::FunctionPassCtor</span></tt>.</p>
+<p>To force the load/linking of your register allocator into the
+<strong class="program">llc</strong>/<strong class="program">lli</strong> tools, add your creator function’s global
+declaration to <tt class="docutils literal"><span class="pre">Passes.h</span></tt> and add a “pseudo” call line to
+<tt class="docutils literal"><span class="pre">llvm/Codegen/LinkAllCodegenComponents.h</span></tt>.</p>
+</div>
+<div class="section" id="creating-new-registries">
+<h3><a class="toc-backref" href="#id52">Creating new registries</a><a class="headerlink" href="#creating-new-registries" title="Permalink to this headline">¶</a></h3>
+<p>The easiest way to get started is to clone one of the existing registries; we
+recommend <tt class="docutils literal"><span class="pre">llvm/CodeGen/RegAllocRegistry.h</span></tt>. The key things to modify are
+the class name and the <tt class="docutils literal"><span class="pre">FunctionPassCtor</span></tt> type.</p>
+<p>Then you need to declare the registry. Example: if your pass registry is
+<tt class="docutils literal"><span class="pre">RegisterMyPasses</span></tt> then define:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MachinePassRegistry</span> <span class="n">RegisterMyPasses</span><span class="o">::</span><span class="n">Registry</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>And finally, declare the command line option for your passes. Example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">RegisterMyPasses</span><span class="o">::</span><span class="n">FunctionPassCtor</span><span class="p">,</span> <span class="nb">false</span><span class="p">,</span>
+ <span class="n">RegisterPassParser</span><span class="o"><</span><span class="n">RegisterMyPasses</span><span class="o">></span> <span class="o">></span>
+<span class="n">MyPassOpt</span><span class="p">(</span><span class="s">"mypass"</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="o">&</span><span class="n">createDefaultMyPass</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">"my pass option help"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>Here the command option is “<tt class="docutils literal"><span class="pre">mypass</span></tt>”, with <tt class="docutils literal"><span class="pre">createDefaultMyPass</span></tt> as the
+default creator.</p>
+</div>
+<div class="section" id="using-gdb-with-dynamically-loaded-passes">
+<h3><a class="toc-backref" href="#id53">Using GDB with dynamically loaded passes</a><a class="headerlink" href="#using-gdb-with-dynamically-loaded-passes" title="Permalink to this headline">¶</a></h3>
+<p>Unfortunately, using GDB with dynamically loaded passes is not as easy as it
+should be. First of all, you can’t set a breakpoint in a shared object that
+has not been loaded yet, and second of all there are problems with inlined
+functions in shared objects. Here are some suggestions to debugging your pass
+with GDB.</p>
+<p>For sake of discussion, I’m going to assume that you are debugging a
+transformation invoked by <strong class="program">opt</strong>, although nothing described here
+depends on that.</p>
+<div class="section" id="setting-a-breakpoint-in-your-pass">
+<h4><a class="toc-backref" href="#id54">Setting a breakpoint in your pass</a><a class="headerlink" href="#setting-a-breakpoint-in-your-pass" title="Permalink to this headline">¶</a></h4>
+<p>First thing you do is start gdb on the opt process:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> gdb opt
+<span class="go">GNU gdb 5.0</span>
+<span class="go">Copyright 2000 Free Software Foundation, Inc.</span>
+<span class="go">GDB is free software, covered by the GNU General Public License, and you are</span>
+<span class="go">welcome to change it and/or distribute copies of it under certain conditions.</span>
+<span class="go">Type "show copying" to see the conditions.</span>
+<span class="go">There is absolutely no warranty for GDB. Type "show warranty" for details.</span>
+<span class="go">This GDB was configured as "sparc-sun-solaris2.6"...</span>
+<span class="go">(gdb)</span>
+</pre></div>
+</div>
+<p>Note that <strong class="program">opt</strong> has a lot of debugging information in it, so it takes
+time to load. Be patient. Since we cannot set a breakpoint in our pass yet
+(the shared object isn’t loaded until runtime), we must execute the process,
+and have it stop before it invokes our pass, but after it has loaded the shared
+object. The most foolproof way of doing this is to set a breakpoint in
+<tt class="docutils literal"><span class="pre">PassManager::run</span></tt> and then run the process with the arguments you want:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="o">(</span>gdb<span class="o">)</span> <span class="nb">break </span>llvm::PassManager::run
+<span class="go">Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.</span>
+<span class="go">(gdb) run test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]</span>
+<span class="go">Starting program: opt test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]</span>
+<span class="go">Breakpoint 1, PassManager::run (this=0xffbef174, M=@0x70b298) at Pass.cpp:70</span>
+<span class="go">70 bool PassManager::run(Module &M) { return PM->run(M); }</span>
+<span class="go">(gdb)</span>
+</pre></div>
+</div>
+<p>Once the <strong class="program">opt</strong> stops in the <tt class="docutils literal"><span class="pre">PassManager::run</span></tt> method you are now
+free to set breakpoints in your pass so that you can trace through execution or
+do other standard debugging stuff.</p>
+</div>
+<div class="section" id="miscellaneous-problems">
+<h4><a class="toc-backref" href="#id55">Miscellaneous Problems</a><a class="headerlink" href="#miscellaneous-problems" title="Permalink to this headline">¶</a></h4>
+<p>Once you have the basics down, there are a couple of problems that GDB has,
+some with solutions, some without.</p>
+<ul class="simple">
+<li>Inline functions have bogus stack information. In general, GDB does a pretty
+good job getting stack traces and stepping through inline functions. When a
+pass is dynamically loaded however, it somehow completely loses this
+capability. The only solution I know of is to de-inline a function (move it
+from the body of a class to a <tt class="docutils literal"><span class="pre">.cpp</span></tt> file).</li>
+<li>Restarting the program breaks breakpoints. After following the information
+above, you have succeeded in getting some breakpoints planted in your pass.
+Nex thing you know, you restart the program (i.e., you type “<tt class="docutils literal"><span class="pre">run</span></tt>” again),
+and you start getting errors about breakpoints being unsettable. The only
+way I have found to “fix” this problem is to delete the breakpoints that are
+already set in your pass, run the program, and re-set the breakpoints once
+execution stops in <tt class="docutils literal"><span class="pre">PassManager::run</span></tt>.</li>
+</ul>
+<p>Hopefully these tips will help with common case debugging situations. If you’d
+like to contribute some tips of your own, just contact <a class="reference external" href="mailto:sabre%40nondot.org">Chris</a>.</p>
+</div>
+</div>
+<div class="section" id="future-extensions-planned">
+<h3><a class="toc-backref" href="#id56">Future extensions planned</a><a class="headerlink" href="#future-extensions-planned" title="Permalink to this headline">¶</a></h3>
+<p>Although the LLVM Pass Infrastructure is very capable as it stands, and does
+some nifty stuff, there are things we’d like to add in the future. Here is
+where we are going:</p>
+<div class="section" id="multithreaded-llvm">
+<span id="writing-an-llvm-pass-smp"></span><h4><a class="toc-backref" href="#id57">Multithreaded LLVM</a><a class="headerlink" href="#multithreaded-llvm" title="Permalink to this headline">¶</a></h4>
+<p>Multiple CPU machines are becoming more common and compilation can never be
+fast enough: obviously we should allow for a multithreaded compiler. Because
+of the semantics defined for passes above (specifically they cannot maintain
+state across invocations of their <tt class="docutils literal"><span class="pre">run*</span></tt> methods), a nice clean way to
+implement a multithreaded compiler would be for the <tt class="docutils literal"><span class="pre">PassManager</span></tt> class to
+create multiple instances of each pass object, and allow the separate instances
+to be hacking on different parts of the program at the same time.</p>
+<p>This implementation would prevent each of the passes from having to implement
+multithreaded constructs, requiring only the LLVM core to have locking in a few
+places (for global resources). Although this is a simple extension, we simply
+haven’t had time (or multiprocessor machines, thus a reason) to implement this.
+Despite that, we have kept the LLVM passes SMP ready, and you should too.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToUseAttributes.html" title="How To Use Attributes"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GarbageCollection.html" title="Garbage Collection with LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/YamlIO.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/YamlIO.html?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/YamlIO.html (added)
+++ www-releases/trunk/3.7.1/docs/YamlIO.html Fri Jan 15 17:13:16 2016
@@ -0,0 +1,1029 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>YAML I/O — LLVM 3.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.7 documentation" href="index.html" />
+ <link rel="next" title="The Often Misunderstood GEP Instruction" href="GetElementPtr.html" />
+ <link rel="prev" title="LLVMâs Analysis and Transform Passes" href="Passes.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Passes.html" title="LLVMâs Analysis and Transform Passes"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="yaml-i-o">
+<h1>YAML I/O<a class="headerlink" href="#yaml-i-o" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction-to-yaml" id="id1">Introduction to YAML</a></li>
+<li><a class="reference internal" href="#introduction-to-yaml-i-o" id="id2">Introduction to YAML I/O</a></li>
+<li><a class="reference internal" href="#error-handling" id="id3">Error Handling</a></li>
+<li><a class="reference internal" href="#scalars" id="id4">Scalars</a><ul>
+<li><a class="reference internal" href="#built-in-types" id="id5">Built-in types</a></li>
+<li><a class="reference internal" href="#unique-types" id="id6">Unique types</a></li>
+<li><a class="reference internal" href="#hex-types" id="id7">Hex types</a></li>
+<li><a class="reference internal" href="#scalarenumerationtraits" id="id8">ScalarEnumerationTraits</a></li>
+<li><a class="reference internal" href="#bitvalue" id="id9">BitValue</a></li>
+<li><a class="reference internal" href="#custom-scalar" id="id10">Custom Scalar</a></li>
+<li><a class="reference internal" href="#block-scalars" id="id11">Block Scalars</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#mappings" id="id12">Mappings</a><ul>
+<li><a class="reference internal" href="#no-normalization" id="id13">No Normalization</a></li>
+<li><a class="reference internal" href="#normalization" id="id14">Normalization</a></li>
+<li><a class="reference internal" href="#default-values" id="id15">Default values</a></li>
+<li><a class="reference internal" href="#order-of-keys" id="id16">Order of Keys</a></li>
+<li><a class="reference internal" href="#tags" id="id17">Tags</a></li>
+<li><a class="reference internal" href="#validation" id="id18">Validation</a></li>
+<li><a class="reference internal" href="#flow-mapping" id="id19">Flow Mapping</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#sequence" id="id20">Sequence</a><ul>
+<li><a class="reference internal" href="#flow-sequence" id="id21">Flow Sequence</a></li>
+<li><a class="reference internal" href="#utility-macros" id="id22">Utility Macros</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#document-list" id="id23">Document List</a></li>
+<li><a class="reference internal" href="#user-context-data" id="id24">User Context Data</a></li>
+<li><a class="reference internal" href="#output" id="id25">Output</a></li>
+<li><a class="reference internal" href="#input" id="id26">Input</a></li>
+</ul>
+</div>
+<div class="section" id="introduction-to-yaml">
+<h2><a class="toc-backref" href="#id1">Introduction to YAML</a><a class="headerlink" href="#introduction-to-yaml" title="Permalink to this headline">¶</a></h2>
+<p>YAML is a human readable data serialization language. The full YAML language
+spec can be read at <a class="reference external" href="http://www.yaml.org/spec/1.2/spec.html#Introduction">yaml.org</a>. The simplest form of
+yaml is just “scalars”, “mappings”, and “sequences”. A scalar is any number
+or string. The pound/hash symbol (#) begins a comment line. A mapping is
+a set of key-value pairs where the key ends with a colon. For example:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># a mapping</span>
+<span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+</pre></div>
+</div>
+<p>A sequence is a list of items where each item starts with a leading dash (‘-‘).
+For example:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># a sequence</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86_64</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">PowerPC</span>
+</pre></div>
+</div>
+<p>You can combine mappings and sequences by indenting. For example a sequence
+of mappings in which one of the mapping values is itself a sequence:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># a sequence of mappings with one key's value being a sequence</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86_64</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Bob</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Dan</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">PowerPC</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86</span>
+</pre></div>
+</div>
+<p>Sometime sequences are known to be short and the one entry per line is too
+verbose, so YAML offers an alternate syntax for sequences called a “Flow
+Sequence” in which you put comma separated sequence elements into square
+brackets. The above example could then be simplified to :</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># a sequence of mappings with one key's value being a flow sequence</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">x86</span><span class="p-Indicator">,</span> <span class="nv">x86_64</span> <span class="p-Indicator">]</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Bob</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">x86</span> <span class="p-Indicator">]</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Dan</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">PowerPC</span><span class="p-Indicator">,</span> <span class="nv">x86</span> <span class="p-Indicator">]</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="introduction-to-yaml-i-o">
+<h2><a class="toc-backref" href="#id2">Introduction to YAML I/O</a><a class="headerlink" href="#introduction-to-yaml-i-o" title="Permalink to this headline">¶</a></h2>
+<p>The use of indenting makes the YAML easy for a human to read and understand,
+but having a program read and write YAML involves a lot of tedious details.
+The YAML I/O library structures and simplifies reading and writing YAML
+documents.</p>
+<p>YAML I/O assumes you have some “native” data structures which you want to be
+able to dump as YAML and recreate from YAML. The first step is to try
+writing example YAML for your data structures. You may find after looking at
+possible YAML representations that a direct mapping of your data structures
+to YAML is not very readable. Often the fields are not in the order that
+a human would find readable. Or the same information is replicated in multiple
+locations, making it hard for a human to write such YAML correctly.</p>
+<p>In relational database theory there is a design step called normalization in
+which you reorganize fields and tables. The same considerations need to
+go into the design of your YAML encoding. But, you may not want to change
+your existing native data structures. Therefore, when writing out YAML
+there may be a normalization step, and when reading YAML there would be a
+corresponding denormalization step.</p>
+<p>YAML I/O uses a non-invasive, traits based design. YAML I/O defines some
+abstract base templates. You specialize those templates on your data types.
+For instance, if you have an enumerated type FooBar you could specialize
+ScalarEnumerationTraits on that type and define the enumeration() method:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">ScalarEnumerationTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarEnumerationTraits</span><span class="o"><</span><span class="n">FooBar</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">enumeration</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">FooBar</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>As with all YAML I/O template specializations, the ScalarEnumerationTraits is used for
+both reading and writing YAML. That is, the mapping between in-memory enum
+values and the YAML string representation is only in one place.
+This assures that the code for writing and parsing of YAML stays in sync.</p>
+<p>To specify a YAML mappings, you define a specialization on
+llvm::yaml::MappingTraits.
+If your native data structure happens to be a struct that is already normalized,
+then the specialization is simple. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Person</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Person</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">name</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"hat-size"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">hatSize</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>A YAML sequence is automatically inferred if you data type has begin()/end()
+iterators and a push_back() method. Therefore any of the STL containers
+(such as std::vector<>) will automatically translate to YAML sequences.</p>
+<p>Once you have defined specializations for your data types, you can
+programmatically use YAML I/O to write a YAML document:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Output</span><span class="p">;</span>
+
+<span class="n">Person</span> <span class="n">tom</span><span class="p">;</span>
+<span class="n">tom</span><span class="p">.</span><span class="n">name</span> <span class="o">=</span> <span class="s">"Tom"</span><span class="p">;</span>
+<span class="n">tom</span><span class="p">.</span><span class="n">hatSize</span> <span class="o">=</span> <span class="mi">8</span><span class="p">;</span>
+<span class="n">Person</span> <span class="n">dan</span><span class="p">;</span>
+<span class="n">dan</span><span class="p">.</span><span class="n">name</span> <span class="o">=</span> <span class="s">"Dan"</span><span class="p">;</span>
+<span class="n">dan</span><span class="p">.</span><span class="n">hatSize</span> <span class="o">=</span> <span class="mi">7</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">Person</span><span class="o">></span> <span class="n">persons</span><span class="p">;</span>
+<span class="n">persons</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">tom</span><span class="p">);</span>
+<span class="n">persons</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">dan</span><span class="p">);</span>
+
+<span class="n">Output</span> <span class="nf">yout</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">outs</span><span class="p">());</span>
+<span class="n">yout</span> <span class="o"><<</span> <span class="n">persons</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This would write the following:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+ <span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">8</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Dan</span>
+ <span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+</pre></div>
+</div>
+<p>And you can also read such YAML documents with the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Input</span><span class="p">;</span>
+
+<span class="k">typedef</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">Person</span><span class="o">></span> <span class="n">PersonList</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">PersonList</span><span class="o">></span> <span class="n">docs</span><span class="p">;</span>
+
+<span class="n">Input</span> <span class="nf">yin</span><span class="p">(</span><span class="n">document</span><span class="p">.</span><span class="n">getBuffer</span><span class="p">());</span>
+<span class="n">yin</span> <span class="o">>></span> <span class="n">docs</span><span class="p">;</span>
+
+<span class="k">if</span> <span class="p">(</span> <span class="n">yin</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">)</span>
+ <span class="k">return</span><span class="p">;</span>
+
+<span class="c1">// Process read document</span>
+<span class="k">for</span> <span class="p">(</span> <span class="n">PersonList</span> <span class="o">&</span><span class="n">pl</span> <span class="o">:</span> <span class="n">docs</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span> <span class="n">Person</span> <span class="o">&</span><span class="n">person</span> <span class="o">:</span> <span class="n">pl</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="n">cout</span> <span class="o"><<</span> <span class="s">"name="</span> <span class="o"><<</span> <span class="n">person</span><span class="p">.</span><span class="n">name</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>One other feature of YAML is the ability to define multiple documents in a
+single file. That is why reading YAML produces a vector of your document type.</p>
+</div>
+<div class="section" id="error-handling">
+<h2><a class="toc-backref" href="#id3">Error Handling</a><a class="headerlink" href="#error-handling" title="Permalink to this headline">¶</a></h2>
+<p>When parsing a YAML document, if the input does not match your schema (as
+expressed in your XxxTraits<> specializations). YAML I/O
+will print out an error message and your Input object’s error() method will
+return true. For instance the following document:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+ <span class="l-Scalar-Plain">shoe-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">12</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Dan</span>
+ <span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+</pre></div>
+</div>
+<p>Has a key (shoe-size) that is not defined in the schema. YAML I/O will
+automatically generate this error:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">YAML:2:2</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">error</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">unknown key 'shoe-size'</span>
+ <span class="l-Scalar-Plain">shoe-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">12</span>
+ <span class="l-Scalar-Plain">^~~~~~~~~</span>
+</pre></div>
+</div>
+<p>Similar errors are produced for other input not conforming to the schema.</p>
+</div>
+<div class="section" id="scalars">
+<h2><a class="toc-backref" href="#id4">Scalars</a><a class="headerlink" href="#scalars" title="Permalink to this headline">¶</a></h2>
+<p>YAML scalars are just strings (i.e. not a sequence or mapping). The YAML I/O
+library provides support for translating between YAML scalars and specific
+C++ types.</p>
+<div class="section" id="built-in-types">
+<h3><a class="toc-backref" href="#id5">Built-in types</a><a class="headerlink" href="#built-in-types" title="Permalink to this headline">¶</a></h3>
+<p>The following types have built-in support in YAML I/O:</p>
+<ul class="simple">
+<li>bool</li>
+<li>float</li>
+<li>double</li>
+<li>StringRef</li>
+<li>std::string</li>
+<li>int64_t</li>
+<li>int32_t</li>
+<li>int16_t</li>
+<li>int8_t</li>
+<li>uint64_t</li>
+<li>uint32_t</li>
+<li>uint16_t</li>
+<li>uint8_t</li>
+</ul>
+<p>That is, you can use those types in fields of MappingTraits or as element type
+in sequence. When reading, YAML I/O will validate that the string found
+is convertible to that type and error out if not.</p>
+</div>
+<div class="section" id="unique-types">
+<h3><a class="toc-backref" href="#id6">Unique types</a><a class="headerlink" href="#unique-types" title="Permalink to this headline">¶</a></h3>
+<p>Given that YAML I/O is trait based, the selection of how to convert your data
+to YAML is based on the type of your data. But in C++ type matching, typedefs
+do not generate unique type names. That means if you have two typedefs of
+unsigned int, to YAML I/O both types look exactly like unsigned int. To
+facilitate make unique type names, YAML I/O provides a macro which is used
+like a typedef on built-in types, but expands to create a class with conversion
+operators to and from the base type. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">LLVM_YAML_STRONG_TYPEDEF</span><span class="p">(</span><span class="kt">uint32_t</span><span class="p">,</span> <span class="n">MyFooFlags</span><span class="p">)</span>
+<span class="n">LLVM_YAML_STRONG_TYPEDEF</span><span class="p">(</span><span class="kt">uint32_t</span><span class="p">,</span> <span class="n">MyBarFlags</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This generates two classes MyFooFlags and MyBarFlags which you can use in your
+native data structures instead of uint32_t. They are implicitly
+converted to and from uint32_t. The point of creating these unique types
+is that you can now specify traits on them to get different YAML conversions.</p>
+</div>
+<div class="section" id="hex-types">
+<h3><a class="toc-backref" href="#id7">Hex types</a><a class="headerlink" href="#hex-types" title="Permalink to this headline">¶</a></h3>
+<p>An example use of a unique type is that YAML I/O provides fixed sized unsigned
+integers that are written with YAML I/O as hexadecimal instead of the decimal
+format used by the built-in integer types:</p>
+<ul class="simple">
+<li>Hex64</li>
+<li>Hex32</li>
+<li>Hex16</li>
+<li>Hex8</li>
+</ul>
+<p>You can use llvm::yaml::Hex32 instead of uint32_t and the only different will
+be that when YAML I/O writes out that type it will be formatted in hexadecimal.</p>
+</div>
+<div class="section" id="scalarenumerationtraits">
+<h3><a class="toc-backref" href="#id8">ScalarEnumerationTraits</a><a class="headerlink" href="#scalarenumerationtraits" title="Permalink to this headline">¶</a></h3>
+<p>YAML I/O supports translating between in-memory enumerations and a set of string
+values in YAML documents. This is done by specializing ScalarEnumerationTraits<>
+on your enumeration type and define a enumeration() method.
+For instance, suppose you had an enumeration of CPUs and a struct with it as
+a field:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">CPUs</span> <span class="p">{</span>
+ <span class="n">cpu_x86_64</span> <span class="o">=</span> <span class="mi">5</span><span class="p">,</span>
+ <span class="n">cpu_x86</span> <span class="o">=</span> <span class="mi">7</span><span class="p">,</span>
+ <span class="n">cpu_PowerPC</span> <span class="o">=</span> <span class="mi">8</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">Info</span> <span class="p">{</span>
+ <span class="n">CPUs</span> <span class="n">cpu</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">flags</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>To support reading and writing of this enumeration, you can define a
+ScalarEnumerationTraits specialization on CPUs, which can then be used
+as a field type:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">ScalarEnumerationTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarEnumerationTraits</span><span class="o"><</span><span class="n">CPUs</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">enumeration</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">CPUs</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">enumCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"x86_64"</span><span class="p">,</span> <span class="n">cpu_x86_64</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">enumCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"x86"</span><span class="p">,</span> <span class="n">cpu_x86</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">enumCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"PowerPC"</span><span class="p">,</span> <span class="n">cpu_PowerPC</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Info</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Info</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"cpu"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">cpu</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"flags"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">flags</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>When reading YAML, if the string found does not match any of the strings
+specified by enumCase() methods, an error is automatically generated.
+When writing YAML, if the value being written does not match any of the values
+specified by the enumCase() methods, a runtime assertion is triggered.</p>
+</div>
+<div class="section" id="bitvalue">
+<h3><a class="toc-backref" href="#id9">BitValue</a><a class="headerlink" href="#bitvalue" title="Permalink to this headline">¶</a></h3>
+<p>Another common data structure in C++ is a field where each bit has a unique
+meaning. This is often used in a “flags” field. YAML I/O has support for
+converting such fields to a flow sequence. For instance suppose you
+had the following bit flags defined:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+ <span class="n">flagsPointy</span> <span class="o">=</span> <span class="mi">1</span>
+ <span class="n">flagsHollow</span> <span class="o">=</span> <span class="mi">2</span>
+ <span class="n">flagsFlat</span> <span class="o">=</span> <span class="mi">4</span>
+ <span class="n">flagsRound</span> <span class="o">=</span> <span class="mi">8</span>
+<span class="p">};</span>
+
+<span class="n">LLVM_YAML_STRONG_TYPEDEF</span><span class="p">(</span><span class="kt">uint32_t</span><span class="p">,</span> <span class="n">MyFlags</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>To support reading and writing of MyFlags, you specialize ScalarBitSetTraits<>
+on MyFlags and provide the bit values and their names.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">ScalarBitSetTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarBitSetTraits</span><span class="o"><</span><span class="n">MyFlags</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">bitset</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyFlags</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"hollow"</span><span class="p">,</span> <span class="n">flagHollow</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"flat"</span><span class="p">,</span> <span class="n">flagFlat</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"round"</span><span class="p">,</span> <span class="n">flagRound</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"pointy"</span><span class="p">,</span> <span class="n">flagPointy</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">Info</span> <span class="p">{</span>
+ <span class="n">StringRef</span> <span class="n">name</span><span class="p">;</span>
+ <span class="n">MyFlags</span> <span class="n">flags</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Info</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Info</span><span class="o">&</span> <span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">name</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"flags"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">flags</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>With the above, YAML I/O (when writing) will test mask each value in the
+bitset trait against the flags field, and each that matches will
+cause the corresponding string to be added to the flow sequence. The opposite
+is done when reading and any unknown string values will result in a error. With
+the above schema, a same valid YAML document is:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">flags</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">pointy</span><span class="p-Indicator">,</span> <span class="nv">flat</span> <span class="p-Indicator">]</span>
+</pre></div>
+</div>
+<p>Sometimes a “flags” field might contains an enumeration part
+defined by a bit-mask.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+ <span class="n">flagsFeatureA</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+ <span class="n">flagsFeatureB</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
+ <span class="n">flagsFeatureC</span> <span class="o">=</span> <span class="mi">4</span><span class="p">,</span>
+
+ <span class="n">flagsCPUMask</span> <span class="o">=</span> <span class="mi">24</span><span class="p">,</span>
+
+ <span class="n">flagsCPU1</span> <span class="o">=</span> <span class="mi">8</span><span class="p">,</span>
+ <span class="n">flagsCPU2</span> <span class="o">=</span> <span class="mi">16</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>To support reading and writing such fields, you need to use the maskedBitSet()
+method and provide the bit values, their names and the enumeration mask.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarBitSetTraits</span><span class="o"><</span><span class="n">MyFlags</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">bitset</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyFlags</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"featureA"</span><span class="p">,</span> <span class="n">flagsFeatureA</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"featureB"</span><span class="p">,</span> <span class="n">flagsFeatureB</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"featureC"</span><span class="p">,</span> <span class="n">flagsFeatureC</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">maskedBitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"CPU1"</span><span class="p">,</span> <span class="n">flagsCPU1</span><span class="p">,</span> <span class="n">flagsCPUMask</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">maskedBitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"CPU2"</span><span class="p">,</span> <span class="n">flagsCPU2</span><span class="p">,</span> <span class="n">flagsCPUMask</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>YAML I/O (when writing) will apply the enumeration mask to the flags field,
+and compare the result and values from the bitset. As in case of a regular
+bitset, each that matches will cause the corresponding string to be added
+to the flow sequence.</p>
+</div>
+<div class="section" id="custom-scalar">
+<h3><a class="toc-backref" href="#id10">Custom Scalar</a><a class="headerlink" href="#custom-scalar" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes for readability a scalar needs to be formatted in a custom way. For
+instance your internal data structure may use a integer for time (seconds since
+some epoch), but in YAML it would be much nicer to express that integer in
+some time format (e.g. 4-May-2012 10:30pm). YAML I/O has a way to support
+custom formatting and parsing of scalar types by specializing ScalarTraits<> on
+your data type. When writing, YAML I/O will provide the native type and
+your specialization must create a temporary llvm::StringRef. When reading,
+YAML I/O will provide an llvm::StringRef of scalar and your specialization
+must convert that to your native data type. An outline of a custom scalar type
+looks like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">ScalarTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarTraits</span><span class="o"><</span><span class="n">MyCustomType</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span> <span class="o">&</span><span class="n">value</span><span class="p">,</span> <span class="kt">void</span><span class="o">*</span><span class="p">,</span> <span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="n">out</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">out</span> <span class="o"><<</span> <span class="n">value</span><span class="p">;</span> <span class="c1">// do custom formatting here</span>
+ <span class="p">}</span>
+ <span class="k">static</span> <span class="n">StringRef</span> <span class="n">input</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">scalar</span><span class="p">,</span> <span class="kt">void</span><span class="o">*</span><span class="p">,</span> <span class="n">T</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// do custom parsing here. Return the empty string on success,</span>
+ <span class="c1">// or an error message on failure.</span>
+ <span class="k">return</span> <span class="n">StringRef</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="c1">// Determine if this scalar needs quotes.</span>
+ <span class="k">static</span> <span class="kt">bool</span> <span class="n">mustQuote</span><span class="p">(</span><span class="n">StringRef</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">true</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="block-scalars">
+<h3><a class="toc-backref" href="#id11">Block Scalars</a><a class="headerlink" href="#block-scalars" title="Permalink to this headline">¶</a></h3>
+<p>YAML block scalars are string literals that are represented in YAML using the
+literal block notation, just like the example shown below:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">text</span><span class="p-Indicator">:</span> <span class="p-Indicator">|</span>
+ <span class="no">First line</span>
+ <span class="no">Second line</span>
+</pre></div>
+</div>
+<p>The YAML I/O library provides support for translating between YAML block scalars
+and specific C++ types by allowing you to specialize BlockScalarTraits<> on
+your data type. The library doesn’t provide any built-in support for block
+scalar I/O for types like std::string and llvm::StringRef as they are already
+supported by YAML I/O and use the ordinary scalar notation by default.</p>
+<p>BlockScalarTraits specializations are very similar to the
+ScalarTraits specialization - YAML I/O will provide the native type and your
+specialization must create a temporary llvm::StringRef when writing, and
+it will also provide an llvm::StringRef that has the value of that block scalar
+and your specialization must convert that to your native data type when reading.
+An example of a custom type with an appropriate specialization of
+BlockScalarTraits is shown below:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">BlockScalarTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">MyStringType</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">Str</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">BlockScalarTraits</span><span class="o"><</span><span class="n">MyStringType</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span><span class="k">const</span> <span class="n">MyStringType</span> <span class="o">&</span><span class="n">Value</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Ctxt</span><span class="p">,</span>
+ <span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="n">OS</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">OS</span> <span class="o"><<</span> <span class="n">Value</span><span class="p">.</span><span class="n">Str</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">static</span> <span class="n">StringRef</span> <span class="n">input</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">Scalar</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Ctxt</span><span class="p">,</span>
+ <span class="n">MyStringType</span> <span class="o">&</span><span class="n">Value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Value</span><span class="p">.</span><span class="n">Str</span> <span class="o">=</span> <span class="n">Scalar</span><span class="p">.</span><span class="n">str</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nf">StringRef</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="mappings">
+<h2><a class="toc-backref" href="#id12">Mappings</a><a class="headerlink" href="#mappings" title="Permalink to this headline">¶</a></h2>
+<p>To be translated to or from a YAML mapping for your type T you must specialize
+llvm::yaml::MappingTraits on T and implement the “void mapping(IO &io, T&)”
+method. If your native data structures use pointers to a class everywhere,
+you can specialize on the class pointer. Examples:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="c1">// Example of struct Foo which is used by value</span>
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Foo</span> <span class="o">&</span><span class="n">foo</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"size"</span><span class="p">,</span> <span class="n">foo</span><span class="p">.</span><span class="n">size</span><span class="p">);</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="c1">// Example of struct Bar which is natively always a pointer</span>
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Bar</span><span class="o">*></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Bar</span> <span class="o">*&</span><span class="n">bar</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"size"</span><span class="p">,</span> <span class="n">bar</span><span class="o">-></span><span class="n">size</span><span class="p">);</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<div class="section" id="no-normalization">
+<h3><a class="toc-backref" href="#id13">No Normalization</a><a class="headerlink" href="#no-normalization" title="Permalink to this headline">¶</a></h3>
+<p>The mapping() method is responsible, if needed, for normalizing and
+denormalizing. In a simple case where the native data structure requires no
+normalization, the mapping method just uses mapOptional() or mapRequired() to
+bind the struct’s fields to YAML key names. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Person</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Person</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">name</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"hat-size"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">hatSize</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="normalization">
+<h3><a class="toc-backref" href="#id14">Normalization</a><a class="headerlink" href="#normalization" title="Permalink to this headline">¶</a></h3>
+<p>When [de]normalization is required, the mapping() method needs a way to access
+normalized values as fields. To help with this, there is
+a template MappingNormalization<> which you can then use to automatically
+do the normalization and denormalization. The template is used to create
+a local variable in your mapping() method which contains the normalized keys.</p>
+<p>Suppose you have native data type
+Polar which specifies a position in polar coordinates (distance, angle):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Polar</span> <span class="p">{</span>
+ <span class="kt">float</span> <span class="n">distance</span><span class="p">;</span>
+ <span class="kt">float</span> <span class="n">angle</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>but you’ve decided the normalized YAML for should be in x,y coordinates. That
+is, you want the yaml to look like:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">x</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">10.3</span>
+<span class="l-Scalar-Plain">y</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">-4.7</span>
+</pre></div>
+</div>
+<p>You can support this by defining a MappingTraits that normalizes the polar
+coordinates to x,y coordinates when writing YAML and denormalizes x,y
+coordinates into polar when reading YAML.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Polar</span><span class="o">></span> <span class="p">{</span>
+
+ <span class="k">class</span> <span class="nc">NormalizedPolar</span> <span class="p">{</span>
+ <span class="nl">public:</span>
+ <span class="n">NormalizedPolar</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">)</span>
+ <span class="o">:</span> <span class="n">x</span><span class="p">(</span><span class="mf">0.0</span><span class="p">),</span> <span class="n">y</span><span class="p">(</span><span class="mf">0.0</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">}</span>
+ <span class="n">NormalizedPolar</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="p">,</span> <span class="n">Polar</span> <span class="o">&</span><span class="n">polar</span><span class="p">)</span>
+ <span class="o">:</span> <span class="n">x</span><span class="p">(</span><span class="n">polar</span><span class="p">.</span><span class="n">distance</span> <span class="o">*</span> <span class="n">cos</span><span class="p">(</span><span class="n">polar</span><span class="p">.</span><span class="n">angle</span><span class="p">)),</span>
+ <span class="n">y</span><span class="p">(</span><span class="n">polar</span><span class="p">.</span><span class="n">distance</span> <span class="o">*</span> <span class="n">sin</span><span class="p">(</span><span class="n">polar</span><span class="p">.</span><span class="n">angle</span><span class="p">))</span> <span class="p">{</span>
+ <span class="p">}</span>
+ <span class="n">Polar</span> <span class="n">denormalize</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">Polar</span><span class="p">(</span><span class="n">sqrt</span><span class="p">(</span><span class="n">x</span><span class="o">*</span><span class="n">x</span><span class="o">+</span><span class="n">y</span><span class="o">*</span><span class="n">y</span><span class="p">),</span> <span class="n">arctan</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">y</span><span class="p">));</span>
+ <span class="p">}</span>
+
+ <span class="kt">float</span> <span class="n">x</span><span class="p">;</span>
+ <span class="kt">float</span> <span class="n">y</span><span class="p">;</span>
+ <span class="p">};</span>
+
+ <span class="k">static</span> <span class="kt">void</span> <span class="nf">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Polar</span> <span class="o">&</span><span class="n">polar</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MappingNormalization</span><span class="o"><</span><span class="n">NormalizedPolar</span><span class="p">,</span> <span class="n">Polar</span><span class="o">></span> <span class="n">keys</span><span class="p">(</span><span class="n">io</span><span class="p">,</span> <span class="n">polar</span><span class="p">);</span>
+
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"x"</span><span class="p">,</span> <span class="n">keys</span><span class="o">-></span><span class="n">x</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"y"</span><span class="p">,</span> <span class="n">keys</span><span class="o">-></span><span class="n">y</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>When writing YAML, the local variable “keys” will be a stack allocated
+instance of NormalizedPolar, constructed from the supplied polar object which
+initializes it x and y fields. The mapRequired() methods then write out the x
+and y values as key/value pairs.</p>
+<p>When reading YAML, the local variable “keys” will be a stack allocated instance
+of NormalizedPolar, constructed by the empty constructor. The mapRequired
+methods will find the matching key in the YAML document and fill in the x and y
+fields of the NormalizedPolar object keys. At the end of the mapping() method
+when the local keys variable goes out of scope, the denormalize() method will
+automatically be called to convert the read values back to polar coordinates,
+and then assigned back to the second parameter to mapping().</p>
+<p>In some cases, the normalized class may be a subclass of the native type and
+could be returned by the denormalize() method, except that the temporary
+normalized instance is stack allocated. In these cases, the utility template
+MappingNormalizationHeap<> can be used instead. It just like
+MappingNormalization<> except that it heap allocates the normalized object
+when reading YAML. It never destroys the normalized object. The denormalize()
+method can this return “this”.</p>
+</div>
+<div class="section" id="default-values">
+<h3><a class="toc-backref" href="#id15">Default values</a><a class="headerlink" href="#default-values" title="Permalink to this headline">¶</a></h3>
+<p>Within a mapping() method, calls to io.mapRequired() mean that that key is
+required to exist when parsing YAML documents, otherwise YAML I/O will issue an
+error.</p>
+<p>On the other hand, keys registered with io.mapOptional() are allowed to not
+exist in the YAML document being read. So what value is put in the field
+for those optional keys?
+There are two steps to how those optional fields are filled in. First, the
+second parameter to the mapping() method is a reference to a native class. That
+native class must have a default constructor. Whatever value the default
+constructor initially sets for an optional field will be that field’s value.
+Second, the mapOptional() method has an optional third parameter. If provided
+it is the value that mapOptional() should set that field to if the YAML document
+does not have that key.</p>
+<p>There is one important difference between those two ways (default constructor
+and third parameter to mapOptional). When YAML I/O generates a YAML document,
+if the mapOptional() third parameter is used, if the actual value being written
+is the same as (using ==) the default value, then that key/value is not written.</p>
+</div>
+<div class="section" id="order-of-keys">
+<h3><a class="toc-backref" href="#id16">Order of Keys</a><a class="headerlink" href="#order-of-keys" title="Permalink to this headline">¶</a></h3>
+<p>When writing out a YAML document, the keys are written in the order that the
+calls to mapRequired()/mapOptional() are made in the mapping() method. This
+gives you a chance to write the fields in an order that a human reader of
+the YAML document would find natural. This may be different that the order
+of the fields in the native class.</p>
+<p>When reading in a YAML document, the keys in the document can be in any order,
+but they are processed in the order that the calls to mapRequired()/mapOptional()
+are made in the mapping() method. That enables some interesting
+functionality. For instance, if the first field bound is the cpu and the second
+field bound is flags, and the flags are cpu specific, you can programmatically
+switch how the flags are converted to and from YAML based on the cpu.
+This works for both reading and writing. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">Info</span> <span class="p">{</span>
+ <span class="n">CPUs</span> <span class="n">cpu</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">flags</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Info</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Info</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"cpu"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">cpu</span><span class="p">);</span>
+ <span class="c1">// flags must come after cpu for this to work when reading yaml</span>
+ <span class="k">if</span> <span class="p">(</span> <span class="n">info</span><span class="p">.</span><span class="n">cpu</span> <span class="o">==</span> <span class="n">cpu_x86_64</span> <span class="p">)</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"flags"</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="n">My86_64Flags</span><span class="o">*</span><span class="p">)</span><span class="n">info</span><span class="p">.</span><span class="n">flags</span><span class="p">);</span>
+ <span class="k">else</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"flags"</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="n">My86Flags</span><span class="o">*</span><span class="p">)</span><span class="n">info</span><span class="p">.</span><span class="n">flags</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tags">
+<h3><a class="toc-backref" href="#id17">Tags</a><a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h3>
+<p>The YAML syntax supports tags as a way to specify the type of a node before
+it is parsed. This allows dynamic types of nodes. But the YAML I/O model uses
+static typing, so there are limits to how you can use tags with the YAML I/O
+model. Recently, we added support to YAML I/O for checking/setting the optional
+tag on a map. Using this functionality it is even possbile to support different
+mappings, as long as they are convertable.</p>
+<p>To check a tag, inside your mapping() method you can use io.mapTag() to specify
+what the tag should be. This will also add that tag when writing yaml.</p>
+</div>
+<div class="section" id="validation">
+<h3><a class="toc-backref" href="#id18">Validation</a><a class="headerlink" href="#validation" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes in a yaml map, each key/value pair is valid, but the combination is
+not. This is similar to something having no syntax errors, but still having
+semantic errors. To support semantic level checking, YAML I/O allows
+an optional <tt class="docutils literal"><span class="pre">validate()</span></tt> method in a MappingTraits template specialization.</p>
+<p>When parsing yaml, the <tt class="docutils literal"><span class="pre">validate()</span></tt> method is call <em>after</em> all key/values in
+the map have been processed. Any error message returned by the <tt class="docutils literal"><span class="pre">validate()</span></tt>
+method during input will be printed just a like a syntax error would be printed.
+When writing yaml, the <tt class="docutils literal"><span class="pre">validate()</span></tt> method is called <em>before</em> the yaml
+key/values are written. Any error during output will trigger an <tt class="docutils literal"><span class="pre">assert()</span></tt>
+because it is a programming error to have invalid struct values.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">Stuff</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Stuff</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Stuff</span> <span class="o">&</span><span class="n">stuff</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+ <span class="k">static</span> <span class="n">StringRef</span> <span class="n">validate</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Stuff</span> <span class="o">&</span><span class="n">stuff</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Look at all fields in 'stuff' and if there</span>
+ <span class="c1">// are any bad values return a string describing</span>
+ <span class="c1">// the error. Otherwise return an empty string.</span>
+ <span class="k">return</span> <span class="n">StringRef</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="flow-mapping">
+<h3><a class="toc-backref" href="#id19">Flow Mapping</a><a class="headerlink" href="#flow-mapping" title="Permalink to this headline">¶</a></h3>
+<p>A YAML “flow mapping” is a mapping that uses the inline notation
+(e.g { x: 1, y: 0 } ) when written to YAML. To specify that a type should be
+written in YAML using flow mapping, your MappingTraits specialization should
+add “static const bool flow = true;”. For instance:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">Stuff</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Stuff</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Stuff</span> <span class="o">&</span><span class="n">stuff</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+
+ <span class="k">static</span> <span class="k">const</span> <span class="kt">bool</span> <span class="n">flow</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Flow mappings are subject to line wrapping according to the Output object
+configuration.</p>
+</div>
+</div>
+<div class="section" id="sequence">
+<h2><a class="toc-backref" href="#id20">Sequence</a><a class="headerlink" href="#sequence" title="Permalink to this headline">¶</a></h2>
+<p>To be translated to or from a YAML sequence for your type T you must specialize
+llvm::yaml::SequenceTraits on T and implement two methods:
+<tt class="docutils literal"><span class="pre">size_t</span> <span class="pre">size(IO</span> <span class="pre">&io,</span> <span class="pre">T&)</span></tt> and
+<tt class="docutils literal"><span class="pre">T::value_type&</span> <span class="pre">element(IO</span> <span class="pre">&io,</span> <span class="pre">T&,</span> <span class="pre">size_t</span> <span class="pre">indx)</span></tt>. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">SequenceTraits</span><span class="o"><</span><span class="n">MySeq</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MySeq</span> <span class="o">&</span><span class="n">list</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="n">MySeqEl</span> <span class="o">&</span><span class="n">element</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MySeq</span> <span class="o">&</span><span class="n">list</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">index</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The size() method returns how many elements are currently in your sequence.
+The element() method returns a reference to the i’th element in the sequence.
+When parsing YAML, the element() method may be called with an index one bigger
+than the current size. Your element() method should allocate space for one
+more element (using default constructor if element is a C++ object) and returns
+a reference to that new allocated space.</p>
+<div class="section" id="flow-sequence">
+<h3><a class="toc-backref" href="#id21">Flow Sequence</a><a class="headerlink" href="#flow-sequence" title="Permalink to this headline">¶</a></h3>
+<p>A YAML “flow sequence” is a sequence that when written to YAML it uses the
+inline notation (e.g [ foo, bar ] ). To specify that a sequence type should
+be written in YAML as a flow sequence, your SequenceTraits specialization should
+add “static const bool flow = true;”. For instance:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">SequenceTraits</span><span class="o"><</span><span class="n">MyList</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyList</span> <span class="o">&</span><span class="n">list</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="n">MyListEl</span> <span class="o">&</span><span class="n">element</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyList</span> <span class="o">&</span><span class="n">list</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">index</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+
+ <span class="c1">// The existence of this member causes YAML I/O to use a flow sequence</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="kt">bool</span> <span class="n">flow</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>With the above, if you used MyList as the data type in your native data
+structures, then when converted to YAML, a flow sequence of integers
+will be used (e.g. [ 10, -3, 4 ]).</p>
+<p>Flow sequences are subject to line wrapping according to the Output object
+configuration.</p>
+</div>
+<div class="section" id="utility-macros">
+<h3><a class="toc-backref" href="#id22">Utility Macros</a><a class="headerlink" href="#utility-macros" title="Permalink to this headline">¶</a></h3>
+<p>Since a common source of sequences is std::vector<>, YAML I/O provides macros:
+LLVM_YAML_IS_SEQUENCE_VECTOR() and LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR() which
+can be used to easily specify SequenceTraits<> on a std::vector type. YAML
+I/O does not partial specialize SequenceTraits on std::vector<> because that
+would force all vectors to be sequences. An example use of the macros:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">MyType1</span><span class="o">></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">MyType2</span><span class="o">></span><span class="p">;</span>
+<span class="n">LLVM_YAML_IS_SEQUENCE_VECTOR</span><span class="p">(</span><span class="n">MyType1</span><span class="p">)</span>
+<span class="n">LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR</span><span class="p">(</span><span class="n">MyType2</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="document-list">
+<h2><a class="toc-backref" href="#id23">Document List</a><a class="headerlink" href="#document-list" title="Permalink to this headline">¶</a></h2>
+<p>YAML allows you to define multiple “documents” in a single YAML file. Each
+new document starts with a left aligned “—” token. The end of all documents
+is denoted with a left aligned ”...” token. Many users of YAML will never
+have need for multiple documents. The top level node in their YAML schema
+will be a mapping or sequence. For those cases, the following is not needed.
+But for cases where you do want multiple documents, you can specify a
+trait for you document list type. The trait has the same methods as
+SequenceTraits but is named DocumentListTraits. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">DocumentListTraits</span><span class="o"><</span><span class="n">MyDocList</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyDocList</span> <span class="o">&</span><span class="n">list</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="n">MyDocType</span> <span class="n">element</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyDocList</span> <span class="o">&</span><span class="n">list</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">index</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>
+<div class="section" id="user-context-data">
+<h2><a class="toc-backref" href="#id24">User Context Data</a><a class="headerlink" href="#user-context-data" title="Permalink to this headline">¶</a></h2>
+<p>When an llvm::yaml::Input or llvm::yaml::Output object is created their
+constructors take an optional “context” parameter. This is a pointer to
+whatever state information you might need.</p>
+<p>For instance, in a previous example we showed how the conversion type for a
+flags field could be determined at runtime based on the value of another field
+in the mapping. But what if an inner mapping needs to know some field value
+of an outer mapping? That is where the “context” parameter comes in. You
+can set values in the context in the outer map’s mapping() method and
+retrieve those values in the inner map’s mapping() method.</p>
+<p>The context value is just a void*. All your traits which use the context
+and operate on your native data types, need to agree what the context value
+actually is. It could be a pointer to an object or struct which your various
+traits use to shared context sensitive information.</p>
+</div>
+<div class="section" id="output">
+<h2><a class="toc-backref" href="#id25">Output</a><a class="headerlink" href="#output" title="Permalink to this headline">¶</a></h2>
+<p>The llvm::yaml::Output class is used to generate a YAML document from your
+in-memory data structures, using traits defined on your data types.
+To instantiate an Output object you need an llvm::raw_ostream, an optional
+context pointer and an optional wrapping column:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Output</span> <span class="o">:</span> <span class="k">public</span> <span class="n">IO</span> <span class="p">{</span>
+<span class="nl">public:</span>
+ <span class="n">Output</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">context</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">,</span> <span class="kt">int</span> <span class="n">WrapColumn</span> <span class="o">=</span> <span class="mi">70</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Once you have an Output object, you can use the C++ stream operator on it
+to write your native data as YAML. One thing to recall is that a YAML file
+can contain multiple “documents”. If the top level data structure you are
+streaming as YAML is a mapping, scalar, or sequence, then Output assumes you
+are generating one document and wraps the mapping output
+with “<tt class="docutils literal"><span class="pre">---</span></tt>” and trailing “<tt class="docutils literal"><span class="pre">...</span></tt>”.</p>
+<p>The WrapColumn parameter will cause the flow mappings and sequences to
+line-wrap when they go over the supplied column. Pass 0 to completely
+suppress the wrapping.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Output</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">dumpMyMapDoc</span><span class="p">(</span><span class="k">const</span> <span class="n">MyMapType</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Output</span> <span class="n">yout</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">outs</span><span class="p">());</span>
+ <span class="n">yout</span> <span class="o"><<</span> <span class="n">info</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The above could produce output like:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="nn">---</span>
+<span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+<span class="nn">...</span>
+</pre></div>
+</div>
+<p>On the other hand, if the top level data structure you are streaming as YAML
+has a DocumentListTraits specialization, then Output walks through each element
+of your DocumentList and generates a “—” before the start of each element
+and ends with a ”...”.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Output</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">dumpMyMapDoc</span><span class="p">(</span><span class="k">const</span> <span class="n">MyDocListType</span> <span class="o">&</span><span class="n">docList</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Output</span> <span class="n">yout</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">outs</span><span class="p">());</span>
+ <span class="n">yout</span> <span class="o"><<</span> <span class="n">docList</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The above could produce output like:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="nn">---</span>
+<span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+<span class="nn">---</span>
+<span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">shoe-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">11</span>
+<span class="nn">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="input">
+<h2><a class="toc-backref" href="#id26">Input</a><a class="headerlink" href="#input" title="Permalink to this headline">¶</a></h2>
+<p>The llvm::yaml::Input class is used to parse YAML document(s) into your native
+data structures. To instantiate an Input
+object you need a StringRef to the entire YAML file, and optionally a context
+pointer:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Input</span> <span class="o">:</span> <span class="k">public</span> <span class="n">IO</span> <span class="p">{</span>
+<span class="nl">public:</span>
+ <span class="n">Input</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">inputContent</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">context</span><span class="o">=</span><span class="nb">NULL</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Once you have an Input object, you can use the C++ stream operator to read
+the document(s). If you expect there might be multiple YAML documents in
+one file, you’ll need to specialize DocumentListTraits on a list of your
+document type and stream in that document list type. Otherwise you can
+just stream in the document type. Also, you can check if there was
+any syntax errors in the YAML be calling the error() method on the Input
+object. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Reading a single document</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Input</span><span class="p">;</span>
+
+<span class="n">Input</span> <span class="nf">yin</span><span class="p">(</span><span class="n">mb</span><span class="p">.</span><span class="n">getBuffer</span><span class="p">());</span>
+
+<span class="c1">// Parse the YAML file</span>
+<span class="n">MyDocType</span> <span class="n">theDoc</span><span class="p">;</span>
+<span class="n">yin</span> <span class="o">>></span> <span class="n">theDoc</span><span class="p">;</span>
+
+<span class="c1">// Check for error</span>
+<span class="k">if</span> <span class="p">(</span> <span class="n">yin</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">)</span>
+ <span class="k">return</span><span class="p">;</span>
+</pre></div>
+</div>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Reading multiple documents in one file</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Input</span><span class="p">;</span>
+
+<span class="n">LLVM_YAML_IS_DOCUMENT_LIST_VECTOR</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">MyDocType</span><span class="o">></span><span class="p">)</span>
+
+<span class="n">Input</span> <span class="n">yin</span><span class="p">(</span><span class="n">mb</span><span class="p">.</span><span class="n">getBuffer</span><span class="p">());</span>
+
+<span class="c1">// Parse the YAML file</span>
+<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">MyDocType</span><span class="o">></span> <span class="n">theDocList</span><span class="p">;</span>
+<span class="n">yin</span> <span class="o">>></span> <span class="n">theDocList</span><span class="p">;</span>
+
+<span class="c1">// Check for error</span>
+<span class="k">if</span> <span class="p">(</span> <span class="n">yin</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">)</span>
+ <span class="k">return</span><span class="p">;</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Passes.html" title="LLVMâs Analysis and Transform Passes"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-01-04.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.7.1/docs/_images/ARM-BE-bitcastfail.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/ARM-BE-bitcastfail.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/ARM-BE-bitcastfail.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/ARM-BE-bitcastsuccess.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/ARM-BE-bitcastsuccess.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/ARM-BE-bitcastsuccess.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/ARM-BE-ld1.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/ARM-BE-ld1.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/ARM-BE-ld1.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/ARM-BE-ldr.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/ARM-BE-ldr.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/ARM-BE-ldr.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/LangImpl5-cfg.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/LangImpl5-cfg.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/LangImpl5-cfg.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/MCJIT-creation.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/MCJIT-creation.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/MCJIT-creation.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/MCJIT-dyld-load.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/MCJIT-dyld-load.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/MCJIT-dyld-load.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/MCJIT-engine-builder.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/MCJIT-engine-builder.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/MCJIT-engine-builder.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/MCJIT-load-object.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/MCJIT-load-object.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/MCJIT-load-object.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/MCJIT-load.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/MCJIT-load.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/MCJIT-load.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/MCJIT-resolve-relocations.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/MCJIT-resolve-relocations.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/MCJIT-resolve-relocations.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/gcc-loops.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/gcc-loops.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/gcc-loops.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_images/linpack-pc.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_images/linpack-pc.png?rev=257950&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.7.1/docs/_images/linpack-pc.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.7.1/docs/_sources/AMDGPUUsage.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/AMDGPUUsage.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/AMDGPUUsage.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/AMDGPUUsage.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,177 @@
+==============================
+User Guide for AMDGPU Back-end
+==============================
+
+Introduction
+============
+
+The AMDGPU back-end provides ISA code generation for AMD GPUs, starting with
+the R600 family up until the current Volcanic Islands (GCN Gen 3).
+
+
+Assembler
+=========
+
+The assembler is currently considered experimental.
+
+For syntax examples look in test/MC/AMDGPU.
+
+Below some of the currently supported features (modulo bugs). These
+all apply to the Southern Islands ISA, Sea Islands and Volcanic Islands
+are also supported but may be missing some instructions and have more bugs:
+
+DS Instructions
+---------------
+All DS instructions are supported.
+
+FLAT Instructions
+------------------
+These instructions are only present in the Sea Islands and Volcanic Islands
+instruction set. All FLAT instructions are supported for these architectures
+
+MUBUF Instructions
+------------------
+All non-atomic MUBUF instructions are supported.
+
+SMRD Instructions
+-----------------
+Only the s_load_dword* SMRD instructions are supported.
+
+SOP1 Instructions
+-----------------
+All SOP1 instructions are supported.
+
+SOP2 Instructions
+-----------------
+All SOP2 instructions are supported.
+
+SOPC Instructions
+-----------------
+All SOPC instructions are supported.
+
+SOPP Instructions
+-----------------
+
+Unless otherwise mentioned, all SOPP instructions that have one or more
+operands accept integer operands only. No verification is performed
+on the operands, so it is up to the programmer to be familiar with the
+range or acceptable values.
+
+s_waitcnt
+^^^^^^^^^
+
+s_waitcnt accepts named arguments to specify which memory counter(s) to
+wait for.
+
+.. code-block:: nasm
+
+ // Wait for all counters to be 0
+ s_waitcnt 0
+
+ // Equivalent to s_waitcnt 0. Counter names can also be delimited by
+ // '&' or ','.
+ s_waitcnt vmcnt(0) expcnt(0) lgkcmt(0)
+
+ // Wait for vmcnt counter to be 1.
+ s_waitcnt vmcnt(1)
+
+VOP1, VOP2, VOP3, VOPC Instructions
+-----------------------------------
+
+All 32-bit and 64-bit encodings should work.
+
+The assembler will automatically detect which encoding size to use for
+VOP1, VOP2, and VOPC instructions based on the operands. If you want to force
+a specific encoding size, you can add an _e32 (for 32-bit encoding) or
+_e64 (for 64-bit encoding) suffix to the instruction. Most, but not all
+instructions support an explicit suffix. These are all valid assembly
+strings:
+
+.. code-block:: nasm
+
+ v_mul_i32_i24 v1, v2, v3
+ v_mul_i32_i24_e32 v1, v2, v3
+ v_mul_i32_i24_e64 v1, v2, v3
+
+Assembler Directives
+--------------------
+
+.hsa_code_object_version major, minor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*major* and *minor* are integers that specify the version of the HSA code
+object that will be generated by the assembler. This value will be stored
+in an entry of the .note section.
+
+.hsa_code_object_isa [major, minor, stepping, vendor, arch]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*major*, *minor*, and *stepping* are all integers that describe the instruction
+set architecture (ISA) version of the assembly program.
+
+*vendor* and *arch* are quoted strings. *vendor* should always be equal to
+"AMD" and *arch* should always be equal to "AMDGPU".
+
+If no arguments are specified, then the assembler will derive the ISA version,
+*vendor*, and *arch* from the value of the -mcpu option that is passed to the
+assembler.
+
+ISA version, *vendor*, and *arch* will all be stored in a single entry of the
+.note section.
+
+.amd_kernel_code_t
+^^^^^^^^^^^^^^^^^^
+
+This directive marks the beginning of a list of key / value pairs that are used
+to specify the amd_kernel_code_t object that will be emitted by the assembler.
+The list must be terminated by the *.end_amd_kernel_code_t* directive. For
+any amd_kernel_code_t values that are unspecified a default value will be
+used. The default value for all keys is 0, with the following exceptions:
+
+- *kernel_code_version_major* defaults to 1.
+- *machine_kind* defaults to 1.
+- *machine_version_major*, *machine_version_minor*, and
+ *machine_version_stepping* are derived from the value of the -mcpu option
+ that is passed to the assembler.
+- *kernel_code_entry_byte_offset* defaults to 256.
+- *wavefront_size* defaults to 6.
+- *kernarg_segment_alignment*, *group_segment_alignment*, and
+ *private_segment_alignment* default to 4. Note that alignments are specified
+ as a power of two, so a value of **n** means an alignment of 2^ **n**.
+
+The *.amd_kernel_code_t* directive must be placed immediately after the
+function label and before any instructions.
+
+For a full list of amd_kernel_code_t keys, see the examples in
+test/CodeGen/AMDGPU/hsa.s. For an explanation of the meanings of the different
+keys, see the comments in lib/Target/AMDGPU/AmdKernelCodeT.h
+
+Here is an example of a minimal amd_kernel_code_t specification:
+
+.. code-block:: nasm
+
+ .hsa_code_object_version 1,0
+ .hsa_code_object_isa
+
+ .text
+
+ hello_world:
+
+ .amd_kernel_code_t
+ enable_sgpr_kernarg_segment_ptr = 1
+ is_ptr64 = 1
+ compute_pgm_rsrc1_vgprs = 0
+ compute_pgm_rsrc1_sgprs = 0
+ compute_pgm_rsrc2_user_sgpr = 2
+ kernarg_segment_byte_size = 8
+ wavefront_sgpr_count = 2
+ workitem_vgpr_count = 3
+ .end_amd_kernel_code_t
+
+ s_load_dwordx2 s[0:1], s[0:1] 0x0
+ v_mov_b32 v0, 3.14159
+ s_waitcnt lgkmcnt(0)
+ v_mov_b32 v1, s0
+ v_mov_b32 v2, s1
+ flat_store_dword v0, v[1:2]
+ s_endpgm
Added: www-releases/trunk/3.7.1/docs/_sources/AliasAnalysis.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/AliasAnalysis.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/AliasAnalysis.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/AliasAnalysis.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,713 @@
+==================================
+LLVM Alias Analysis Infrastructure
+==================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Alias Analysis (aka Pointer Analysis) is a class of techniques which attempt to
+determine whether or not two pointers ever can point to the same object in
+memory. There are many different algorithms for alias analysis and many
+different ways of classifying them: flow-sensitive vs. flow-insensitive,
+context-sensitive vs. context-insensitive, field-sensitive
+vs. field-insensitive, unification-based vs. subset-based, etc. Traditionally,
+alias analyses respond to a query with a `Must, May, or No`_ alias response,
+indicating that two pointers always point to the same object, might point to the
+same object, or are known to never point to the same object.
+
+The LLVM `AliasAnalysis
+<http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__ class is the
+primary interface used by clients and implementations of alias analyses in the
+LLVM system. This class is the common interface between clients of alias
+analysis information and the implementations providing it, and is designed to
+support a wide range of implementations and clients (but currently all clients
+are assumed to be flow-insensitive). In addition to simple alias analysis
+information, this class exposes Mod/Ref information from those implementations
+which can provide it, allowing for powerful analyses and transformations to work
+well together.
+
+This document contains information necessary to successfully implement this
+interface, use it, and to test both sides. It also explains some of the finer
+points about what exactly results mean. If you feel that something is unclear
+or should be added, please `let me know <mailto:sabre at nondot.org>`_.
+
+``AliasAnalysis`` Class Overview
+================================
+
+The `AliasAnalysis <http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__
+class defines the interface that the various alias analysis implementations
+should support. This class exports two important enums: ``AliasResult`` and
+``ModRefResult`` which represent the result of an alias query or a mod/ref
+query, respectively.
+
+The ``AliasAnalysis`` interface exposes information about memory, represented in
+several different ways. In particular, memory objects are represented as a
+starting address and size, and function calls are represented as the actual
+``call`` or ``invoke`` instructions that performs the call. The
+``AliasAnalysis`` interface also exposes some helper methods which allow you to
+get mod/ref information for arbitrary instructions.
+
+All ``AliasAnalysis`` interfaces require that in queries involving multiple
+values, values which are not :ref:`constants <constants>` are all
+defined within the same function.
+
+Representation of Pointers
+--------------------------
+
+Most importantly, the ``AliasAnalysis`` class provides several methods which are
+used to query whether or not two memory objects alias, whether function calls
+can modify or read a memory object, etc. For all of these queries, memory
+objects are represented as a pair of their starting address (a symbolic LLVM
+``Value*``) and a static size.
+
+Representing memory objects as a starting address and a size is critically
+important for correct Alias Analyses. For example, consider this (silly, but
+possible) C code:
+
+.. code-block:: c++
+
+ int i;
+ char C[2];
+ char A[10];
+ /* ... */
+ for (i = 0; i != 10; ++i) {
+ C[0] = A[i]; /* One byte store */
+ C[1] = A[9-i]; /* One byte store */
+ }
+
+In this case, the ``basicaa`` pass will disambiguate the stores to ``C[0]`` and
+``C[1]`` because they are accesses to two distinct locations one byte apart, and
+the accesses are each one byte. In this case, the Loop Invariant Code Motion
+(LICM) pass can use store motion to remove the stores from the loop. In
+constrast, the following code:
+
+.. code-block:: c++
+
+ int i;
+ char C[2];
+ char A[10];
+ /* ... */
+ for (i = 0; i != 10; ++i) {
+ ((short*)C)[0] = A[i]; /* Two byte store! */
+ C[1] = A[9-i]; /* One byte store */
+ }
+
+In this case, the two stores to C do alias each other, because the access to the
+``&C[0]`` element is a two byte access. If size information wasn't available in
+the query, even the first case would have to conservatively assume that the
+accesses alias.
+
+.. _alias:
+
+The ``alias`` method
+--------------------
+
+The ``alias`` method is the primary interface used to determine whether or not
+two memory objects alias each other. It takes two memory objects as input and
+returns MustAlias, PartialAlias, MayAlias, or NoAlias as appropriate.
+
+Like all ``AliasAnalysis`` interfaces, the ``alias`` method requires that either
+the two pointer values be defined within the same function, or at least one of
+the values is a :ref:`constant <constants>`.
+
+.. _Must, May, or No:
+
+Must, May, and No Alias Responses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``NoAlias`` response may be used when there is never an immediate dependence
+between any memory reference *based* on one pointer and any memory reference
+*based* the other. The most obvious example is when the two pointers point to
+non-overlapping memory ranges. Another is when the two pointers are only ever
+used for reading memory. Another is when the memory is freed and reallocated
+between accesses through one pointer and accesses through the other --- in this
+case, there is a dependence, but it's mediated by the free and reallocation.
+
+As an exception to this is with the :ref:`noalias <noalias>` keyword;
+the "irrelevant" dependencies are ignored.
+
+The ``MayAlias`` response is used whenever the two pointers might refer to the
+same object.
+
+The ``PartialAlias`` response is used when the two memory objects are known to
+be overlapping in some way, but do not start at the same address.
+
+The ``MustAlias`` response may only be returned if the two memory objects are
+guaranteed to always start at exactly the same location. A ``MustAlias``
+response implies that the pointers compare equal.
+
+The ``getModRefInfo`` methods
+-----------------------------
+
+The ``getModRefInfo`` methods return information about whether the execution of
+an instruction can read or modify a memory location. Mod/Ref information is
+always conservative: if an instruction **might** read or write a location,
+``ModRef`` is returned.
+
+The ``AliasAnalysis`` class also provides a ``getModRefInfo`` method for testing
+dependencies between function calls. This method takes two call sites (``CS1``
+& ``CS2``), returns ``NoModRef`` if neither call writes to memory read or
+written by the other, ``Ref`` if ``CS1`` reads memory written by ``CS2``,
+``Mod`` if ``CS1`` writes to memory read or written by ``CS2``, or ``ModRef`` if
+``CS1`` might read or write memory written to by ``CS2``. Note that this
+relation is not commutative.
+
+Other useful ``AliasAnalysis`` methods
+--------------------------------------
+
+Several other tidbits of information are often collected by various alias
+analysis implementations and can be put to good use by various clients.
+
+The ``pointsToConstantMemory`` method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``pointsToConstantMemory`` method returns true if and only if the analysis
+can prove that the pointer only points to unchanging memory locations
+(functions, constant global variables, and the null pointer). This information
+can be used to refine mod/ref information: it is impossible for an unchanging
+memory location to be modified.
+
+.. _never access memory or only read memory:
+
+The ``doesNotAccessMemory`` and ``onlyReadsMemory`` methods
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These methods are used to provide very simple mod/ref information for function
+calls. The ``doesNotAccessMemory`` method returns true for a function if the
+analysis can prove that the function never reads or writes to memory, or if the
+function only reads from constant memory. Functions with this property are
+side-effect free and only depend on their input arguments, allowing them to be
+eliminated if they form common subexpressions or be hoisted out of loops. Many
+common functions behave this way (e.g., ``sin`` and ``cos``) but many others do
+not (e.g., ``acos``, which modifies the ``errno`` variable).
+
+The ``onlyReadsMemory`` method returns true for a function if analysis can prove
+that (at most) the function only reads from non-volatile memory. Functions with
+this property are side-effect free, only depending on their input arguments and
+the state of memory when they are called. This property allows calls to these
+functions to be eliminated and moved around, as long as there is no store
+instruction that changes the contents of memory. Note that all functions that
+satisfy the ``doesNotAccessMemory`` method also satisfies ``onlyReadsMemory``.
+
+Writing a new ``AliasAnalysis`` Implementation
+==============================================
+
+Writing a new alias analysis implementation for LLVM is quite straight-forward.
+There are already several implementations that you can use for examples, and the
+following information should help fill in any details. For a examples, take a
+look at the `various alias analysis implementations`_ included with LLVM.
+
+Different Pass styles
+---------------------
+
+The first step to determining what type of :doc:`LLVM pass <WritingAnLLVMPass>`
+you need to use for your Alias Analysis. As is the case with most other
+analyses and transformations, the answer should be fairly obvious from what type
+of problem you are trying to solve:
+
+#. If you require interprocedural analysis, it should be a ``Pass``.
+#. If you are a function-local analysis, subclass ``FunctionPass``.
+#. If you don't need to look at the program at all, subclass ``ImmutablePass``.
+
+In addition to the pass that you subclass, you should also inherit from the
+``AliasAnalysis`` interface, of course, and use the ``RegisterAnalysisGroup``
+template to register as an implementation of ``AliasAnalysis``.
+
+Required initialization calls
+-----------------------------
+
+Your subclass of ``AliasAnalysis`` is required to invoke two methods on the
+``AliasAnalysis`` base class: ``getAnalysisUsage`` and
+``InitializeAliasAnalysis``. In particular, your implementation of
+``getAnalysisUsage`` should explicitly call into the
+``AliasAnalysis::getAnalysisUsage`` method in addition to doing any declaring
+any pass dependencies your pass has. Thus you should have something like this:
+
+.. code-block:: c++
+
+ void getAnalysisUsage(AnalysisUsage &AU) const {
+ AliasAnalysis::getAnalysisUsage(AU);
+ // declare your dependencies here.
+ }
+
+Additionally, your must invoke the ``InitializeAliasAnalysis`` method from your
+analysis run method (``run`` for a ``Pass``, ``runOnFunction`` for a
+``FunctionPass``, or ``InitializePass`` for an ``ImmutablePass``). For example
+(as part of a ``Pass``):
+
+.. code-block:: c++
+
+ bool run(Module &M) {
+ InitializeAliasAnalysis(this);
+ // Perform analysis here...
+ return false;
+ }
+
+Required methods to override
+----------------------------
+
+You must override the ``getAdjustedAnalysisPointer`` method on all subclasses
+of ``AliasAnalysis``. An example implementation of this method would look like:
+
+.. code-block:: c++
+
+ void *getAdjustedAnalysisPointer(const void* ID) override {
+ if (ID == &AliasAnalysis::ID)
+ return (AliasAnalysis*)this;
+ return this;
+ }
+
+Interfaces which may be specified
+---------------------------------
+
+All of the `AliasAnalysis
+<http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__ virtual methods
+default to providing :ref:`chaining <aliasanalysis-chaining>` to another alias
+analysis implementation, which ends up returning conservatively correct
+information (returning "May" Alias and "Mod/Ref" for alias and mod/ref queries
+respectively). Depending on the capabilities of the analysis you are
+implementing, you just override the interfaces you can improve.
+
+.. _aliasanalysis-chaining:
+
+``AliasAnalysis`` chaining behavior
+-----------------------------------
+
+With only one special exception (the :ref:`-no-aa <aliasanalysis-no-aa>` pass)
+every alias analysis pass chains to another alias analysis implementation (for
+example, the user can specify "``-basicaa -ds-aa -licm``" to get the maximum
+benefit from both alias analyses). The alias analysis class automatically
+takes care of most of this for methods that you don't override. For methods
+that you do override, in code paths that return a conservative MayAlias or
+Mod/Ref result, simply return whatever the superclass computes. For example:
+
+.. code-block:: c++
+
+ AliasResult alias(const Value *V1, unsigned V1Size,
+ const Value *V2, unsigned V2Size) {
+ if (...)
+ return NoAlias;
+ ...
+
+ // Couldn't determine a must or no-alias result.
+ return AliasAnalysis::alias(V1, V1Size, V2, V2Size);
+ }
+
+In addition to analysis queries, you must make sure to unconditionally pass LLVM
+`update notification`_ methods to the superclass as well if you override them,
+which allows all alias analyses in a change to be updated.
+
+.. _update notification:
+
+Updating analysis results for transformations
+---------------------------------------------
+
+Alias analysis information is initially computed for a static snapshot of the
+program, but clients will use this information to make transformations to the
+code. All but the most trivial forms of alias analysis will need to have their
+analysis results updated to reflect the changes made by these transformations.
+
+The ``AliasAnalysis`` interface exposes four methods which are used to
+communicate program changes from the clients to the analysis implementations.
+Various alias analysis implementations should use these methods to ensure that
+their internal data structures are kept up-to-date as the program changes (for
+example, when an instruction is deleted), and clients of alias analysis must be
+sure to call these interfaces appropriately.
+
+The ``deleteValue`` method
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``deleteValue`` method is called by transformations when they remove an
+instruction or any other value from the program (including values that do not
+use pointers). Typically alias analyses keep data structures that have entries
+for each value in the program. When this method is called, they should remove
+any entries for the specified value, if they exist.
+
+The ``copyValue`` method
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``copyValue`` method is used when a new value is introduced into the
+program. There is no way to introduce a value into the program that did not
+exist before (this doesn't make sense for a safe compiler transformation), so
+this is the only way to introduce a new value. This method indicates that the
+new value has exactly the same properties as the value being copied.
+
+The ``replaceWithNewValue`` method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This method is a simple helper method that is provided to make clients easier to
+use. It is implemented by copying the old analysis information to the new
+value, then deleting the old value. This method cannot be overridden by alias
+analysis implementations.
+
+The ``addEscapingUse`` method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``addEscapingUse`` method is used when the uses of a pointer value have
+changed in ways that may invalidate precomputed analysis information.
+Implementations may either use this callback to provide conservative responses
+for points whose uses have change since analysis time, or may recompute some or
+all of their internal state to continue providing accurate responses.
+
+In general, any new use of a pointer value is considered an escaping use, and
+must be reported through this callback, *except* for the uses below:
+
+* A ``bitcast`` or ``getelementptr`` of the pointer
+* A ``store`` through the pointer (but not a ``store`` *of* the pointer)
+* A ``load`` through the pointer
+
+Efficiency Issues
+-----------------
+
+From the LLVM perspective, the only thing you need to do to provide an efficient
+alias analysis is to make sure that alias analysis **queries** are serviced
+quickly. The actual calculation of the alias analysis results (the "run"
+method) is only performed once, but many (perhaps duplicate) queries may be
+performed. Because of this, try to move as much computation to the run method
+as possible (within reason).
+
+Limitations
+-----------
+
+The AliasAnalysis infrastructure has several limitations which make writing a
+new ``AliasAnalysis`` implementation difficult.
+
+There is no way to override the default alias analysis. It would be very useful
+to be able to do something like "``opt -my-aa -O2``" and have it use ``-my-aa``
+for all passes which need AliasAnalysis, but there is currently no support for
+that, short of changing the source code and recompiling. Similarly, there is
+also no way of setting a chain of analyses as the default.
+
+There is no way for transform passes to declare that they preserve
+``AliasAnalysis`` implementations. The ``AliasAnalysis`` interface includes
+``deleteValue`` and ``copyValue`` methods which are intended to allow a pass to
+keep an AliasAnalysis consistent, however there's no way for a pass to declare
+in its ``getAnalysisUsage`` that it does so. Some passes attempt to use
+``AU.addPreserved<AliasAnalysis>``, however this doesn't actually have any
+effect.
+
+``AliasAnalysisCounter`` (``-count-aa``) and ``AliasDebugger`` (``-debug-aa``)
+are implemented as ``ModulePass`` classes, so if your alias analysis uses
+``FunctionPass``, it won't be able to use these utilities. If you try to use
+them, the pass manager will silently route alias analysis queries directly to
+``BasicAliasAnalysis`` instead.
+
+Similarly, the ``opt -p`` option introduces ``ModulePass`` passes between each
+pass, which prevents the use of ``FunctionPass`` alias analysis passes.
+
+The ``AliasAnalysis`` API does have functions for notifying implementations when
+values are deleted or copied, however these aren't sufficient. There are many
+other ways that LLVM IR can be modified which could be relevant to
+``AliasAnalysis`` implementations which can not be expressed.
+
+The ``AliasAnalysisDebugger`` utility seems to suggest that ``AliasAnalysis``
+implementations can expect that they will be informed of any relevant ``Value``
+before it appears in an alias query. However, popular clients such as ``GVN``
+don't support this, and are known to trigger errors when run with the
+``AliasAnalysisDebugger``.
+
+Due to several of the above limitations, the most obvious use for the
+``AliasAnalysisCounter`` utility, collecting stats on all alias queries in a
+compilation, doesn't work, even if the ``AliasAnalysis`` implementations don't
+use ``FunctionPass``. There's no way to set a default, much less a default
+sequence, and there's no way to preserve it.
+
+The ``AliasSetTracker`` class (which is used by ``LICM``) makes a
+non-deterministic number of alias queries. This can cause stats collected by
+``AliasAnalysisCounter`` to have fluctuations among identical runs, for
+example. Another consequence is that debugging techniques involving pausing
+execution after a predetermined number of queries can be unreliable.
+
+Many alias queries can be reformulated in terms of other alias queries. When
+multiple ``AliasAnalysis`` queries are chained together, it would make sense to
+start those queries from the beginning of the chain, with care taken to avoid
+infinite looping, however currently an implementation which wants to do this can
+only start such queries from itself.
+
+Using alias analysis results
+============================
+
+There are several different ways to use alias analysis results. In order of
+preference, these are:
+
+Using the ``MemoryDependenceAnalysis`` Pass
+-------------------------------------------
+
+The ``memdep`` pass uses alias analysis to provide high-level dependence
+information about memory-using instructions. This will tell you which store
+feeds into a load, for example. It uses caching and other techniques to be
+efficient, and is used by Dead Store Elimination, GVN, and memcpy optimizations.
+
+.. _AliasSetTracker:
+
+Using the ``AliasSetTracker`` class
+-----------------------------------
+
+Many transformations need information about alias **sets** that are active in
+some scope, rather than information about pairwise aliasing. The
+`AliasSetTracker <http://llvm.org/doxygen/classllvm_1_1AliasSetTracker.html>`__
+class is used to efficiently build these Alias Sets from the pairwise alias
+analysis information provided by the ``AliasAnalysis`` interface.
+
+First you initialize the AliasSetTracker by using the "``add``" methods to add
+information about various potentially aliasing instructions in the scope you are
+interested in. Once all of the alias sets are completed, your pass should
+simply iterate through the constructed alias sets, using the ``AliasSetTracker``
+``begin()``/``end()`` methods.
+
+The ``AliasSet``\s formed by the ``AliasSetTracker`` are guaranteed to be
+disjoint, calculate mod/ref information and volatility for the set, and keep
+track of whether or not all of the pointers in the set are Must aliases. The
+AliasSetTracker also makes sure that sets are properly folded due to call
+instructions, and can provide a list of pointers in each set.
+
+As an example user of this, the `Loop Invariant Code Motion
+<doxygen/structLICM.html>`_ pass uses ``AliasSetTracker``\s to calculate alias
+sets for each loop nest. If an ``AliasSet`` in a loop is not modified, then all
+load instructions from that set may be hoisted out of the loop. If any alias
+sets are stored to **and** are must alias sets, then the stores may be sunk
+to outside of the loop, promoting the memory location to a register for the
+duration of the loop nest. Both of these transformations only apply if the
+pointer argument is loop-invariant.
+
+The AliasSetTracker implementation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The AliasSetTracker class is implemented to be as efficient as possible. It
+uses the union-find algorithm to efficiently merge AliasSets when a pointer is
+inserted into the AliasSetTracker that aliases multiple sets. The primary data
+structure is a hash table mapping pointers to the AliasSet they are in.
+
+The AliasSetTracker class must maintain a list of all of the LLVM ``Value*``\s
+that are in each AliasSet. Since the hash table already has entries for each
+LLVM ``Value*`` of interest, the AliasesSets thread the linked list through
+these hash-table nodes to avoid having to allocate memory unnecessarily, and to
+make merging alias sets extremely efficient (the linked list merge is constant
+time).
+
+You shouldn't need to understand these details if you are just a client of the
+AliasSetTracker, but if you look at the code, hopefully this brief description
+will help make sense of why things are designed the way they are.
+
+Using the ``AliasAnalysis`` interface directly
+----------------------------------------------
+
+If neither of these utility class are what your pass needs, you should use the
+interfaces exposed by the ``AliasAnalysis`` class directly. Try to use the
+higher-level methods when possible (e.g., use mod/ref information instead of the
+`alias`_ method directly if possible) to get the best precision and efficiency.
+
+Existing alias analysis implementations and clients
+===================================================
+
+If you're going to be working with the LLVM alias analysis infrastructure, you
+should know what clients and implementations of alias analysis are available.
+In particular, if you are implementing an alias analysis, you should be aware of
+the `the clients`_ that are useful for monitoring and evaluating different
+implementations.
+
+.. _various alias analysis implementations:
+
+Available ``AliasAnalysis`` implementations
+-------------------------------------------
+
+This section lists the various implementations of the ``AliasAnalysis``
+interface. With the exception of the :ref:`-no-aa <aliasanalysis-no-aa>`
+implementation, all of these :ref:`chain <aliasanalysis-chaining>` to other
+alias analysis implementations.
+
+.. _aliasanalysis-no-aa:
+
+The ``-no-aa`` pass
+^^^^^^^^^^^^^^^^^^^
+
+The ``-no-aa`` pass is just like what it sounds: an alias analysis that never
+returns any useful information. This pass can be useful if you think that alias
+analysis is doing something wrong and are trying to narrow down a problem.
+
+The ``-basicaa`` pass
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``-basicaa`` pass is an aggressive local analysis that *knows* many
+important facts:
+
+* Distinct globals, stack allocations, and heap allocations can never alias.
+* Globals, stack allocations, and heap allocations never alias the null pointer.
+* Different fields of a structure do not alias.
+* Indexes into arrays with statically differing subscripts cannot alias.
+* Many common standard C library functions `never access memory or only read
+ memory`_.
+* Pointers that obviously point to constant globals "``pointToConstantMemory``".
+* Function calls can not modify or references stack allocations if they never
+ escape from the function that allocates them (a common case for automatic
+ arrays).
+
+The ``-globalsmodref-aa`` pass
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This pass implements a simple context-sensitive mod/ref and alias analysis for
+internal global variables that don't "have their address taken". If a global
+does not have its address taken, the pass knows that no pointers alias the
+global. This pass also keeps track of functions that it knows never access
+memory or never read memory. This allows certain optimizations (e.g. GVN) to
+eliminate call instructions entirely.
+
+The real power of this pass is that it provides context-sensitive mod/ref
+information for call instructions. This allows the optimizer to know that calls
+to a function do not clobber or read the value of the global, allowing loads and
+stores to be eliminated.
+
+.. note::
+
+ This pass is somewhat limited in its scope (only support non-address taken
+ globals), but is very quick analysis.
+
+The ``-steens-aa`` pass
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``-steens-aa`` pass implements a variation on the well-known "Steensgaard's
+algorithm" for interprocedural alias analysis. Steensgaard's algorithm is a
+unification-based, flow-insensitive, context-insensitive, and field-insensitive
+alias analysis that is also very scalable (effectively linear time).
+
+The LLVM ``-steens-aa`` pass implements a "speculatively field-**sensitive**"
+version of Steensgaard's algorithm using the Data Structure Analysis framework.
+This gives it substantially more precision than the standard algorithm while
+maintaining excellent analysis scalability.
+
+.. note::
+
+ ``-steens-aa`` is available in the optional "poolalloc" module. It is not part
+ of the LLVM core.
+
+The ``-ds-aa`` pass
+^^^^^^^^^^^^^^^^^^^
+
+The ``-ds-aa`` pass implements the full Data Structure Analysis algorithm. Data
+Structure Analysis is a modular unification-based, flow-insensitive,
+context-**sensitive**, and speculatively field-**sensitive** alias
+analysis that is also quite scalable, usually at ``O(n * log(n))``.
+
+This algorithm is capable of responding to a full variety of alias analysis
+queries, and can provide context-sensitive mod/ref information as well. The
+only major facility not implemented so far is support for must-alias
+information.
+
+.. note::
+
+ ``-ds-aa`` is available in the optional "poolalloc" module. It is not part of
+ the LLVM core.
+
+The ``-scev-aa`` pass
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``-scev-aa`` pass implements AliasAnalysis queries by translating them into
+ScalarEvolution queries. This gives it a more complete understanding of
+``getelementptr`` instructions and loop induction variables than other alias
+analyses have.
+
+Alias analysis driven transformations
+-------------------------------------
+
+LLVM includes several alias-analysis driven transformations which can be used
+with any of the implementations above.
+
+The ``-adce`` pass
+^^^^^^^^^^^^^^^^^^
+
+The ``-adce`` pass, which implements Aggressive Dead Code Elimination uses the
+``AliasAnalysis`` interface to delete calls to functions that do not have
+side-effects and are not used.
+
+The ``-licm`` pass
+^^^^^^^^^^^^^^^^^^
+
+The ``-licm`` pass implements various Loop Invariant Code Motion related
+transformations. It uses the ``AliasAnalysis`` interface for several different
+transformations:
+
+* It uses mod/ref information to hoist or sink load instructions out of loops if
+ there are no instructions in the loop that modifies the memory loaded.
+
+* It uses mod/ref information to hoist function calls out of loops that do not
+ write to memory and are loop-invariant.
+
+* If uses alias information to promote memory objects that are loaded and stored
+ to in loops to live in a register instead. It can do this if there are no may
+ aliases to the loaded/stored memory location.
+
+The ``-argpromotion`` pass
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``-argpromotion`` pass promotes by-reference arguments to be passed in
+by-value instead. In particular, if pointer arguments are only loaded from it
+passes in the value loaded instead of the address to the function. This pass
+uses alias information to make sure that the value loaded from the argument
+pointer is not modified between the entry of the function and any load of the
+pointer.
+
+The ``-gvn``, ``-memcpyopt``, and ``-dse`` passes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These passes use AliasAnalysis information to reason about loads and stores.
+
+.. _the clients:
+
+Clients for debugging and evaluation of implementations
+-------------------------------------------------------
+
+These passes are useful for evaluating the various alias analysis
+implementations. You can use them with commands like:
+
+.. code-block:: bash
+
+ % opt -ds-aa -aa-eval foo.bc -disable-output -stats
+
+The ``-print-alias-sets`` pass
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``-print-alias-sets`` pass is exposed as part of the ``opt`` tool to print
+out the Alias Sets formed by the `AliasSetTracker`_ class. This is useful if
+you're using the ``AliasSetTracker`` class. To use it, use something like:
+
+.. code-block:: bash
+
+ % opt -ds-aa -print-alias-sets -disable-output
+
+The ``-count-aa`` pass
+^^^^^^^^^^^^^^^^^^^^^^
+
+The ``-count-aa`` pass is useful to see how many queries a particular pass is
+making and what responses are returned by the alias analysis. As an example:
+
+.. code-block:: bash
+
+ % opt -basicaa -count-aa -ds-aa -count-aa -licm
+
+will print out how many queries (and what responses are returned) by the
+``-licm`` pass (of the ``-ds-aa`` pass) and how many queries are made of the
+``-basicaa`` pass by the ``-ds-aa`` pass. This can be useful when debugging a
+transformation or an alias analysis implementation.
+
+The ``-aa-eval`` pass
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``-aa-eval`` pass simply iterates through all pairs of pointers in a
+function and asks an alias analysis whether or not the pointers alias. This
+gives an indication of the precision of the alias analysis. Statistics are
+printed indicating the percent of no/may/must aliases found (a more precise
+algorithm will have a lower number of may aliases).
+
+Memory Dependence Analysis
+==========================
+
+If you're just looking to be a client of alias analysis information, consider
+using the Memory Dependence Analysis interface instead. MemDep is a lazy,
+caching layer on top of alias analysis that is able to answer the question of
+what preceding memory operations a given instruction depends on, either at an
+intra- or inter-block level. Because of its laziness and caching policy, using
+MemDep can be a significant performance win over accessing alias analysis
+directly.
Added: www-releases/trunk/3.7.1/docs/_sources/Atomics.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/Atomics.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/Atomics.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/Atomics.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,459 @@
+==============================================
+LLVM Atomic Instructions and Concurrency Guide
+==============================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Historically, LLVM has not had very strong support for concurrency; some minimal
+intrinsics were provided, and ``volatile`` was used in some cases to achieve
+rough semantics in the presence of concurrency. However, this is changing;
+there are now new instructions which are well-defined in the presence of threads
+and asynchronous signals, and the model for existing instructions has been
+clarified in the IR.
+
+The atomic instructions are designed specifically to provide readable IR and
+optimized code generation for the following:
+
+* The new C++11 ``<atomic>`` header. (`C++11 draft available here
+ <http://www.open-std.org/jtc1/sc22/wg21/>`_.) (`C11 draft available here
+ <http://www.open-std.org/jtc1/sc22/wg14/>`_.)
+
+* Proper semantics for Java-style memory, for both ``volatile`` and regular
+ shared variables. (`Java Specification
+ <http://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html>`_)
+
+* gcc-compatible ``__sync_*`` builtins. (`Description
+ <https://gcc.gnu.org/onlinedocs/gcc/_005f_005fsync-Builtins.html>`_)
+
+* Other scenarios with atomic semantics, including ``static`` variables with
+ non-trivial constructors in C++.
+
+Atomic and volatile in the IR are orthogonal; "volatile" is the C/C++ volatile,
+which ensures that every volatile load and store happens and is performed in the
+stated order. A couple examples: if a SequentiallyConsistent store is
+immediately followed by another SequentiallyConsistent store to the same
+address, the first store can be erased. This transformation is not allowed for a
+pair of volatile stores. On the other hand, a non-volatile non-atomic load can
+be moved across a volatile load freely, but not an Acquire load.
+
+This document is intended to provide a guide to anyone either writing a frontend
+for LLVM or working on optimization passes for LLVM with a guide for how to deal
+with instructions with special semantics in the presence of concurrency. This
+is not intended to be a precise guide to the semantics; the details can get
+extremely complicated and unreadable, and are not usually necessary.
+
+.. _Optimization outside atomic:
+
+Optimization outside atomic
+===========================
+
+The basic ``'load'`` and ``'store'`` allow a variety of optimizations, but can
+lead to undefined results in a concurrent environment; see `NotAtomic`_. This
+section specifically goes into the one optimizer restriction which applies in
+concurrent environments, which gets a bit more of an extended description
+because any optimization dealing with stores needs to be aware of it.
+
+From the optimizer's point of view, the rule is that if there are not any
+instructions with atomic ordering involved, concurrency does not matter, with
+one exception: if a variable might be visible to another thread or signal
+handler, a store cannot be inserted along a path where it might not execute
+otherwise. Take the following example:
+
+.. code-block:: c
+
+ /* C code, for readability; run through clang -O2 -S -emit-llvm to get
+ equivalent IR */
+ int x;
+ void f(int* a) {
+ for (int i = 0; i < 100; i++) {
+ if (a[i])
+ x += 1;
+ }
+ }
+
+The following is equivalent in non-concurrent situations:
+
+.. code-block:: c
+
+ int x;
+ void f(int* a) {
+ int xtemp = x;
+ for (int i = 0; i < 100; i++) {
+ if (a[i])
+ xtemp += 1;
+ }
+ x = xtemp;
+ }
+
+However, LLVM is not allowed to transform the former to the latter: it could
+indirectly introduce undefined behavior if another thread can access ``x`` at
+the same time. (This example is particularly of interest because before the
+concurrency model was implemented, LLVM would perform this transformation.)
+
+Note that speculative loads are allowed; a load which is part of a race returns
+``undef``, but does not have undefined behavior.
+
+Atomic instructions
+===================
+
+For cases where simple loads and stores are not sufficient, LLVM provides
+various atomic instructions. The exact guarantees provided depend on the
+ordering; see `Atomic orderings`_.
+
+``load atomic`` and ``store atomic`` provide the same basic functionality as
+non-atomic loads and stores, but provide additional guarantees in situations
+where threads and signals are involved.
+
+``cmpxchg`` and ``atomicrmw`` are essentially like an atomic load followed by an
+atomic store (where the store is conditional for ``cmpxchg``), but no other
+memory operation can happen on any thread between the load and store.
+
+A ``fence`` provides Acquire and/or Release ordering which is not part of
+another operation; it is normally used along with Monotonic memory operations.
+A Monotonic load followed by an Acquire fence is roughly equivalent to an
+Acquire load, and a Monotonic store following a Release fence is roughly
+equivalent to a Release store. SequentiallyConsistent fences behave as both
+an Acquire and a Release fence, and offer some additional complicated
+guarantees, see the C++11 standard for details.
+
+Frontends generating atomic instructions generally need to be aware of the
+target to some degree; atomic instructions are guaranteed to be lock-free, and
+therefore an instruction which is wider than the target natively supports can be
+impossible to generate.
+
+.. _Atomic orderings:
+
+Atomic orderings
+================
+
+In order to achieve a balance between performance and necessary guarantees,
+there are six levels of atomicity. They are listed in order of strength; each
+level includes all the guarantees of the previous level except for
+Acquire/Release. (See also `LangRef Ordering <LangRef.html#ordering>`_.)
+
+.. _NotAtomic:
+
+NotAtomic
+---------
+
+NotAtomic is the obvious, a load or store which is not atomic. (This isn't
+really a level of atomicity, but is listed here for comparison.) This is
+essentially a regular load or store. If there is a race on a given memory
+location, loads from that location return undef.
+
+Relevant standard
+ This is intended to match shared variables in C/C++, and to be used in any
+ other context where memory access is necessary, and a race is impossible. (The
+ precise definition is in `LangRef Memory Model <LangRef.html#memmodel>`_.)
+
+Notes for frontends
+ The rule is essentially that all memory accessed with basic loads and stores
+ by multiple threads should be protected by a lock or other synchronization;
+ otherwise, you are likely to run into undefined behavior. If your frontend is
+ for a "safe" language like Java, use Unordered to load and store any shared
+ variable. Note that NotAtomic volatile loads and stores are not properly
+ atomic; do not try to use them as a substitute. (Per the C/C++ standards,
+ volatile does provide some limited guarantees around asynchronous signals, but
+ atomics are generally a better solution.)
+
+Notes for optimizers
+ Introducing loads to shared variables along a codepath where they would not
+ otherwise exist is allowed; introducing stores to shared variables is not. See
+ `Optimization outside atomic`_.
+
+Notes for code generation
+ The one interesting restriction here is that it is not allowed to write to
+ bytes outside of the bytes relevant to a store. This is mostly relevant to
+ unaligned stores: it is not allowed in general to convert an unaligned store
+ into two aligned stores of the same width as the unaligned store. Backends are
+ also expected to generate an i8 store as an i8 store, and not an instruction
+ which writes to surrounding bytes. (If you are writing a backend for an
+ architecture which cannot satisfy these restrictions and cares about
+ concurrency, please send an email to llvm-dev.)
+
+Unordered
+---------
+
+Unordered is the lowest level of atomicity. It essentially guarantees that races
+produce somewhat sane results instead of having undefined behavior. It also
+guarantees the operation to be lock-free, so it does not depend on the data
+being part of a special atomic structure or depend on a separate per-process
+global lock. Note that code generation will fail for unsupported atomic
+operations; if you need such an operation, use explicit locking.
+
+Relevant standard
+ This is intended to match the Java memory model for shared variables.
+
+Notes for frontends
+ This cannot be used for synchronization, but is useful for Java and other
+ "safe" languages which need to guarantee that the generated code never
+ exhibits undefined behavior. Note that this guarantee is cheap on common
+ platforms for loads of a native width, but can be expensive or unavailable for
+ wider loads, like a 64-bit store on ARM. (A frontend for Java or other "safe"
+ languages would normally split a 64-bit store on ARM into two 32-bit unordered
+ stores.)
+
+Notes for optimizers
+ In terms of the optimizer, this prohibits any transformation that transforms a
+ single load into multiple loads, transforms a store into multiple stores,
+ narrows a store, or stores a value which would not be stored otherwise. Some
+ examples of unsafe optimizations are narrowing an assignment into a bitfield,
+ rematerializing a load, and turning loads and stores into a memcpy
+ call. Reordering unordered operations is safe, though, and optimizers should
+ take advantage of that because unordered operations are common in languages
+ that need them.
+
+Notes for code generation
+ These operations are required to be atomic in the sense that if you use
+ unordered loads and unordered stores, a load cannot see a value which was
+ never stored. A normal load or store instruction is usually sufficient, but
+ note that an unordered load or store cannot be split into multiple
+ instructions (or an instruction which does multiple memory operations, like
+ ``LDRD`` on ARM without LPAE, or not naturally-aligned ``LDRD`` on LPAE ARM).
+
+Monotonic
+---------
+
+Monotonic is the weakest level of atomicity that can be used in synchronization
+primitives, although it does not provide any general synchronization. It
+essentially guarantees that if you take all the operations affecting a specific
+address, a consistent ordering exists.
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_relaxed``; see those
+ standards for the exact definition.
+
+Notes for frontends
+ If you are writing a frontend which uses this directly, use with caution. The
+ guarantees in terms of synchronization are very weak, so make sure these are
+ only used in a pattern which you know is correct. Generally, these would
+ either be used for atomic operations which do not protect other memory (like
+ an atomic counter), or along with a ``fence``.
+
+Notes for optimizers
+ In terms of the optimizer, this can be treated as a read+write on the relevant
+ memory location (and alias analysis will take advantage of that). In addition,
+ it is legal to reorder non-atomic and Unordered loads around Monotonic
+ loads. CSE/DSE and a few other optimizations are allowed, but Monotonic
+ operations are unlikely to be used in ways which would make those
+ optimizations useful.
+
+Notes for code generation
+ Code generation is essentially the same as that for unordered for loads and
+ stores. No fences are required. ``cmpxchg`` and ``atomicrmw`` are required
+ to appear as a single operation.
+
+Acquire
+-------
+
+Acquire provides a barrier of the sort necessary to acquire a lock to access
+other memory with normal loads and stores.
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_acquire``. It should also be
+ used for C++11/C11 ``memory_order_consume``.
+
+Notes for frontends
+ If you are writing a frontend which uses this directly, use with caution.
+ Acquire only provides a semantic guarantee when paired with a Release
+ operation.
+
+Notes for optimizers
+ Optimizers not aware of atomics can treat this like a nothrow call. It is
+ also possible to move stores from before an Acquire load or read-modify-write
+ operation to after it, and move non-Acquire loads from before an Acquire
+ operation to after it.
+
+Notes for code generation
+ Architectures with weak memory ordering (essentially everything relevant today
+ except x86 and SPARC) require some sort of fence to maintain the Acquire
+ semantics. The precise fences required varies widely by architecture, but for
+ a simple implementation, most architectures provide a barrier which is strong
+ enough for everything (``dmb`` on ARM, ``sync`` on PowerPC, etc.). Putting
+ such a fence after the equivalent Monotonic operation is sufficient to
+ maintain Acquire semantics for a memory operation.
+
+Release
+-------
+
+Release is similar to Acquire, but with a barrier of the sort necessary to
+release a lock.
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_release``.
+
+Notes for frontends
+ If you are writing a frontend which uses this directly, use with caution.
+ Release only provides a semantic guarantee when paired with a Acquire
+ operation.
+
+Notes for optimizers
+ Optimizers not aware of atomics can treat this like a nothrow call. It is
+ also possible to move loads from after a Release store or read-modify-write
+ operation to before it, and move non-Release stores from after an Release
+ operation to before it.
+
+Notes for code generation
+ See the section on Acquire; a fence before the relevant operation is usually
+ sufficient for Release. Note that a store-store fence is not sufficient to
+ implement Release semantics; store-store fences are generally not exposed to
+ IR because they are extremely difficult to use correctly.
+
+AcquireRelease
+--------------
+
+AcquireRelease (``acq_rel`` in IR) provides both an Acquire and a Release
+barrier (for fences and operations which both read and write memory).
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_acq_rel``.
+
+Notes for frontends
+ If you are writing a frontend which uses this directly, use with caution.
+ Acquire only provides a semantic guarantee when paired with a Release
+ operation, and vice versa.
+
+Notes for optimizers
+ In general, optimizers should treat this like a nothrow call; the possible
+ optimizations are usually not interesting.
+
+Notes for code generation
+ This operation has Acquire and Release semantics; see the sections on Acquire
+ and Release.
+
+SequentiallyConsistent
+----------------------
+
+SequentiallyConsistent (``seq_cst`` in IR) provides Acquire semantics for loads
+and Release semantics for stores. Additionally, it guarantees that a total
+ordering exists between all SequentiallyConsistent operations.
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_seq_cst``, Java volatile, and
+ the gcc-compatible ``__sync_*`` builtins which do not specify otherwise.
+
+Notes for frontends
+ If a frontend is exposing atomic operations, these are much easier to reason
+ about for the programmer than other kinds of operations, and using them is
+ generally a practical performance tradeoff.
+
+Notes for optimizers
+ Optimizers not aware of atomics can treat this like a nothrow call. For
+ SequentiallyConsistent loads and stores, the same reorderings are allowed as
+ for Acquire loads and Release stores, except that SequentiallyConsistent
+ operations may not be reordered.
+
+Notes for code generation
+ SequentiallyConsistent loads minimally require the same barriers as Acquire
+ operations and SequentiallyConsistent stores require Release
+ barriers. Additionally, the code generator must enforce ordering between
+ SequentiallyConsistent stores followed by SequentiallyConsistent loads. This
+ is usually done by emitting either a full fence before the loads or a full
+ fence after the stores; which is preferred varies by architecture.
+
+Atomics and IR optimization
+===========================
+
+Predicates for optimizer writers to query:
+
+* ``isSimple()``: A load or store which is not volatile or atomic. This is
+ what, for example, memcpyopt would check for operations it might transform.
+
+* ``isUnordered()``: A load or store which is not volatile and at most
+ Unordered. This would be checked, for example, by LICM before hoisting an
+ operation.
+
+* ``mayReadFromMemory()``/``mayWriteToMemory()``: Existing predicate, but note
+ that they return true for any operation which is volatile or at least
+ Monotonic.
+
+* ``isAtLeastAcquire()``/``isAtLeastRelease()``: These are predicates on
+ orderings. They can be useful for passes that are aware of atomics, for
+ example to do DSE across a single atomic access, but not across a
+ release-acquire pair (see MemoryDependencyAnalysis for an example of this)
+
+* Alias analysis: Note that AA will return ModRef for anything Acquire or
+ Release, and for the address accessed by any Monotonic operation.
+
+To support optimizing around atomic operations, make sure you are using the
+right predicates; everything should work if that is done. If your pass should
+optimize some atomic operations (Unordered operations in particular), make sure
+it doesn't replace an atomic load or store with a non-atomic operation.
+
+Some examples of how optimizations interact with various kinds of atomic
+operations:
+
+* ``memcpyopt``: An atomic operation cannot be optimized into part of a
+ memcpy/memset, including unordered loads/stores. It can pull operations
+ across some atomic operations.
+
+* LICM: Unordered loads/stores can be moved out of a loop. It just treats
+ monotonic operations like a read+write to a memory location, and anything
+ stricter than that like a nothrow call.
+
+* DSE: Unordered stores can be DSE'ed like normal stores. Monotonic stores can
+ be DSE'ed in some cases, but it's tricky to reason about, and not especially
+ important. It is possible in some case for DSE to operate across a stronger
+ atomic operation, but it is fairly tricky. DSE delegates this reasoning to
+ MemoryDependencyAnalysis (which is also used by other passes like GVN).
+
+* Folding a load: Any atomic load from a constant global can be constant-folded,
+ because it cannot be observed. Similar reasoning allows scalarrepl with
+ atomic loads and stores.
+
+Atomics and Codegen
+===================
+
+Atomic operations are represented in the SelectionDAG with ``ATOMIC_*`` opcodes.
+On architectures which use barrier instructions for all atomic ordering (like
+ARM), appropriate fences can be emitted by the AtomicExpand Codegen pass if
+``setInsertFencesForAtomic()`` was used.
+
+The MachineMemOperand for all atomic operations is currently marked as volatile;
+this is not correct in the IR sense of volatile, but CodeGen handles anything
+marked volatile very conservatively. This should get fixed at some point.
+
+Common architectures have some way of representing at least a pointer-sized
+lock-free ``cmpxchg``; such an operation can be used to implement all the other
+atomic operations which can be represented in IR up to that size. Backends are
+expected to implement all those operations, but not operations which cannot be
+implemented in a lock-free manner. It is expected that backends will give an
+error when given an operation which cannot be implemented. (The LLVM code
+generator is not very helpful here at the moment, but hopefully that will
+change.)
+
+On x86, all atomic loads generate a ``MOV``. SequentiallyConsistent stores
+generate an ``XCHG``, other stores generate a ``MOV``. SequentiallyConsistent
+fences generate an ``MFENCE``, other fences do not cause any code to be
+generated. cmpxchg uses the ``LOCK CMPXCHG`` instruction. ``atomicrmw xchg``
+uses ``XCHG``, ``atomicrmw add`` and ``atomicrmw sub`` use ``XADD``, and all
+other ``atomicrmw`` operations generate a loop with ``LOCK CMPXCHG``. Depending
+on the users of the result, some ``atomicrmw`` operations can be translated into
+operations like ``LOCK AND``, but that does not work in general.
+
+On ARM (before v8), MIPS, and many other RISC architectures, Acquire, Release,
+and SequentiallyConsistent semantics require barrier instructions for every such
+operation. Loads and stores generate normal instructions. ``cmpxchg`` and
+``atomicrmw`` can be represented using a loop with LL/SC-style instructions
+which take some sort of exclusive lock on a cache line (``LDREX`` and ``STREX``
+on ARM, etc.).
+
+It is often easiest for backends to use AtomicExpandPass to lower some of the
+atomic constructs. Here are some lowerings it can do:
+
+* cmpxchg -> loop with load-linked/store-conditional
+ by overriding ``hasLoadLinkedStoreConditional()``, ``emitLoadLinked()``,
+ ``emitStoreConditional()``
+* large loads/stores -> ll-sc/cmpxchg
+ by overriding ``shouldExpandAtomicStoreInIR()``/``shouldExpandAtomicLoadInIR()``
+* strong atomic accesses -> monotonic accesses + fences
+ by using ``setInsertFencesForAtomic()`` and overriding ``emitLeadingFence()``
+ and ``emitTrailingFence()``
+* atomic rmw -> loop with cmpxchg or load-linked/store-conditional
+ by overriding ``expandAtomicRMWInIR()``
+
+For an example of all of these, look at the ARM backend.
Added: www-releases/trunk/3.7.1/docs/_sources/BigEndianNEON.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/BigEndianNEON.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/BigEndianNEON.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/BigEndianNEON.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,205 @@
+==============================================
+Using ARM NEON instructions in big endian mode
+==============================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Generating code for big endian ARM processors is for the most part straightforward. NEON loads and stores however have some interesting properties that make code generation decisions less obvious in big endian mode.
+
+The aim of this document is to explain the problem with NEON loads and stores, and the solution that has been implemented in LLVM.
+
+In this document the term "vector" refers to what the ARM ABI calls a "short vector", which is a sequence of items that can fit in a NEON register. This sequence can be 64 or 128 bits in length, and can constitute 8, 16, 32 or 64 bit items. This document refers to A64 instructions throughout, but is almost applicable to the A32/ARMv7 instruction sets also. The ABI format for passing vectors in A32 is sligtly different to A64. Apart from that, the same concepts apply.
+
+Example: C-level intrinsics -> assembly
+---------------------------------------
+
+It may be helpful first to illustrate how C-level ARM NEON intrinsics are lowered to instructions.
+
+This trivial C function takes a vector of four ints and sets the zero'th lane to the value "42"::
+
+ #include <arm_neon.h>
+ int32x4_t f(int32x4_t p) {
+ return vsetq_lane_s32(42, p, 0);
+ }
+
+arm_neon.h intrinsics generate "generic" IR where possible (that is, normal IR instructions not ``llvm.arm.neon.*`` intrinsic calls). The above generates::
+
+ define <4 x i32> @f(<4 x i32> %p) {
+ %vset_lane = insertelement <4 x i32> %p, i32 42, i32 0
+ ret <4 x i32> %vset_lane
+ }
+
+Which then becomes the following trivial assembly::
+
+ f: // @f
+ movz w8, #0x2a
+ ins v0.s[0], w8
+ ret
+
+Problem
+=======
+
+The main problem is how vectors are represented in memory and in registers.
+
+First, a recap. The "endianness" of an item affects its representation in memory only. In a register, a number is just a sequence of bits - 64 bits in the case of AArch64 general purpose registers. Memory, however, is a sequence of addressable units of 8 bits in size. Any number greater than 8 bits must therefore be split up into 8-bit chunks, and endianness describes the order in which these chunks are laid out in memory.
+
+A "little endian" layout has the least significant byte first (lowest in memory address). A "big endian" layout has the *most* significant byte first. This means that when loading an item from big endian memory, the lowest 8-bits in memory must go in the most significant 8-bits, and so forth.
+
+``LDR`` and ``LD1``
+===================
+
+.. figure:: ARM-BE-ldr.png
+ :align: right
+
+ Big endian vector load using ``LDR``.
+
+
+A vector is a consecutive sequence of items that are operated on simultaneously. To load a 64-bit vector, 64 bits need to be read from memory. In little endian mode, we can do this by just performing a 64-bit load - ``LDR q0, [foo]``. However if we try this in big endian mode, because of the byte swapping the lane indices end up being swapped! The zero'th item as laid out in memory becomes the n'th lane in the vector.
+
+.. figure:: ARM-BE-ld1.png
+ :align: right
+
+ Big endian vector load using ``LD1``. Note that the lanes retain the correct ordering.
+
+
+Because of this, the instruction ``LD1`` performs a vector load but performs byte swapping not on the entire 64 bits, but on the individual items within the vector. This means that the register content is the same as it would have been on a little endian system.
+
+It may seem that ``LD1`` should suffice to peform vector loads on a big endian machine. However there are pros and cons to the two approaches that make it less than simple which register format to pick.
+
+There are two options:
+
+ 1. The content of a vector register is the same *as if* it had been loaded with an ``LDR`` instruction.
+ 2. The content of a vector register is the same *as if* it had been loaded with an ``LD1`` instruction.
+
+Because ``LD1 == LDR + REV`` and similarly ``LDR == LD1 + REV`` (on a big endian system), we can simulate either type of load with the other type of load plus a ``REV`` instruction. So we're not deciding which instructions to use, but which format to use (which will then influence which instruction is best to use).
+
+.. The 'clearer' container is required to make the following section header come after the floated
+ images above.
+.. container:: clearer
+
+ Note that throughout this section we only mention loads. Stores have exactly the same problems as their associated loads, so have been skipped for brevity.
+
+
+Considerations
+==============
+
+LLVM IR Lane ordering
+---------------------
+
+LLVM IR has first class vector types. In LLVM IR, the zero'th element of a vector resides at the lowest memory address. The optimizer relies on this property in certain areas, for example when concatenating vectors together. The intention is for arrays and vectors to have identical memory layouts - ``[4 x i8]`` and ``<4 x i8>`` should be represented the same in memory. Without this property there would be many special cases that the optimizer would have to cleverly handle.
+
+Use of ``LDR`` would break this lane ordering property. This doesn't preclude the use of ``LDR``, but we would have to do one of two things:
+
+ 1. Insert a ``REV`` instruction to reverse the lane order after every ``LDR``.
+ 2. Disable all optimizations that rely on lane layout, and for every access to an individual lane (``insertelement``/``extractelement``/``shufflevector``) reverse the lane index.
+
+AAPCS
+-----
+
+The ARM procedure call standard (AAPCS) defines the ABI for passing vectors between functions in registers. It states:
+
+ When a short vector is transferred between registers and memory it is treated as an opaque object. That is a short vector is stored in memory as if it were stored with a single ``STR`` of the entire register; a short vector is loaded from memory using the corresponding ``LDR`` instruction. On a little-endian system this means that element 0 will always contain the lowest addressed element of a short vector; on a big-endian system element 0 will contain the highest-addressed element of a short vector.
+
+ -- Procedure Call Standard for the ARM 64-bit Architecture (AArch64), 4.1.2 Short Vectors
+
+The use of ``LDR`` and ``STR`` as the ABI defines has at least one advantage over ``LD1`` and ``ST1``. ``LDR`` and ``STR`` are oblivious to the size of the individual lanes of a vector. ``LD1`` and ``ST1`` are not - the lane size is encoded within them. This is important across an ABI boundary, because it would become necessary to know the lane width the callee expects. Consider the following code:
+
+.. code-block:: c
+
+ <callee.c>
+ void callee(uint32x2_t v) {
+ ...
+ }
+
+ <caller.c>
+ extern void callee(uint32x2_t);
+ void caller() {
+ callee(...);
+ }
+
+If ``callee`` changed its signature to ``uint16x4_t``, which is equivalent in register content, if we passed as ``LD1`` we'd break this code until ``caller`` was updated and recompiled.
+
+There is an argument that if the signatures of the two functions are different then the behaviour should be undefined. But there may be functions that are agnostic to the lane layout of the vector, and treating the vector as an opaque value (just loading it and storing it) would be impossible without a common format across ABI boundaries.
+
+So to preserve ABI compatibility, we need to use the ``LDR`` lane layout across function calls.
+
+Alignment
+---------
+
+In strict alignment mode, ``LDR qX`` requires its address to be 128-bit aligned, whereas ``LD1`` only requires it to be as aligned as the lane size. If we canonicalised on using ``LDR``, we'd still need to use ``LD1`` in some places to avoid alignment faults (the result of the ``LD1`` would then need to be reversed with ``REV``).
+
+Most operating systems however do not run with alignment faults enabled, so this is often not an issue.
+
+Summary
+-------
+
+The following table summarises the instructions that are required to be emitted for each property mentioned above for each of the two solutions.
+
++-------------------------------+-------------------------------+---------------------+
+| | ``LDR`` layout | ``LD1`` layout |
++===============================+===============================+=====================+
+| Lane ordering | ``LDR + REV`` | ``LD1`` |
++-------------------------------+-------------------------------+---------------------+
+| AAPCS | ``LDR`` | ``LD1 + REV`` |
++-------------------------------+-------------------------------+---------------------+
+| Alignment for strict mode | ``LDR`` / ``LD1 + REV`` | ``LD1`` |
++-------------------------------+-------------------------------+---------------------+
+
+Neither approach is perfect, and choosing one boils down to choosing the lesser of two evils. The issue with lane ordering, it was decided, would have to change target-agnostic compiler passes and would result in a strange IR in which lane indices were reversed. It was decided that this was worse than the changes that would have to be made to support ``LD1``, so ``LD1`` was chosen as the canonical vector load instruction (and by inference, ``ST1`` for vector stores).
+
+Implementation
+==============
+
+There are 3 parts to the implementation:
+
+ 1. Predicate ``LDR`` and ``STR`` instructions so that they are never allowed to be selected to generate vector loads and stores. The exception is one-lane vectors [1]_ - these by definition cannot have lane ordering problems so are fine to use ``LDR``/``STR``.
+
+ 2. Create code generation patterns for bitconverts that create ``REV`` instructions.
+
+ 3. Make sure appropriate bitconverts are created so that vector values get passed over call boundaries as 1-element vectors (which is the same as if they were loaded with ``LDR``).
+
+Bitconverts
+-----------
+
+.. image:: ARM-BE-bitcastfail.png
+ :align: right
+
+The main problem with the ``LD1`` solution is dealing with bitconverts (or bitcasts, or reinterpret casts). These are pseudo instructions that only change the compiler's interpretation of data, not the underlying data itself. A requirement is that if data is loaded and then saved again (called a "round trip"), the memory contents should be the same after the store as before the load. If a vector is loaded and is then bitconverted to a different vector type before storing, the round trip will currently be broken.
+
+Take for example this code sequence::
+
+ %0 = load <4 x i32> %x
+ %1 = bitcast <4 x i32> %0 to <2 x i64>
+ store <2 x i64> %1, <2 x i64>* %y
+
+This would produce a code sequence such as that in the figure on the right. The mismatched ``LD1`` and ``ST1`` cause the stored data to differ from the loaded data.
+
+.. container:: clearer
+
+ When we see a bitcast from type ``X`` to type ``Y``, what we need to do is to change the in-register representation of the data to be *as if* it had just been loaded by a ``LD1`` of type ``Y``.
+
+.. image:: ARM-BE-bitcastsuccess.png
+ :align: right
+
+Conceptually this is simple - we can insert a ``REV`` undoing the ``LD1`` of type ``X`` (converting the in-register representation to the same as if it had been loaded by ``LDR``) and then insert another ``REV`` to change the representation to be as if it had been loaded by an ``LD1`` of type ``Y``.
+
+For the previous example, this would be::
+
+ LD1 v0.4s, [x]
+
+ REV64 v0.4s, v0.4s // There is no REV128 instruction, so it must be synthesizedcd
+ EXT v0.16b, v0.16b, v0.16b, #8 // with a REV64 then an EXT to swap the two 64-bit elements.
+
+ REV64 v0.2d, v0.2d
+ EXT v0.16b, v0.16b, v0.16b, #8
+
+ ST1 v0.2d, [y]
+
+It turns out that these ``REV`` pairs can, in almost all cases, be squashed together into a single ``REV``. For the example above, a ``REV128 4s`` + ``REV128 2d`` is actually a ``REV64 4s``, as shown in the figure on the right.
+
+.. [1] One lane vectors may seem useless as a concept but they serve to distinguish between values held in general purpose registers and values held in NEON/VFP registers. For example, an ``i64`` would live in an ``x`` register, but ``<1 x i64>`` would live in a ``d`` register.
+
Added: www-releases/trunk/3.7.1/docs/_sources/BitCodeFormat.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/BitCodeFormat.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/BitCodeFormat.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/BitCodeFormat.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,1134 @@
+.. role:: raw-html(raw)
+ :format: html
+
+========================
+LLVM Bitcode File Format
+========================
+
+.. contents::
+ :local:
+
+Abstract
+========
+
+This document describes the LLVM bitstream file format and the encoding of the
+LLVM IR into it.
+
+Overview
+========
+
+What is commonly known as the LLVM bitcode file format (also, sometimes
+anachronistically known as bytecode) is actually two things: a `bitstream
+container format`_ and an `encoding of LLVM IR`_ into the container format.
+
+The bitstream format is an abstract encoding of structured data, very similar to
+XML in some ways. Like XML, bitstream files contain tags, and nested
+structures, and you can parse the file without having to understand the tags.
+Unlike XML, the bitstream format is a binary encoding, and unlike XML it
+provides a mechanism for the file to self-describe "abbreviations", which are
+effectively size optimizations for the content.
+
+LLVM IR files may be optionally embedded into a `wrapper`_ structure, or in a
+`native object file`_. Both of these mechanisms make it easy to embed extra
+data along with LLVM IR files.
+
+This document first describes the LLVM bitstream format, describes the wrapper
+format, then describes the record structure used by LLVM IR files.
+
+.. _bitstream container format:
+
+Bitstream Format
+================
+
+The bitstream format is literally a stream of bits, with a very simple
+structure. This structure consists of the following concepts:
+
+* A "`magic number`_" that identifies the contents of the stream.
+
+* Encoding `primitives`_ like variable bit-rate integers.
+
+* `Blocks`_, which define nested content.
+
+* `Data Records`_, which describe entities within the file.
+
+* Abbreviations, which specify compression optimizations for the file.
+
+Note that the :doc:`llvm-bcanalyzer <CommandGuide/llvm-bcanalyzer>` tool can be
+used to dump and inspect arbitrary bitstreams, which is very useful for
+understanding the encoding.
+
+.. _magic number:
+
+Magic Numbers
+-------------
+
+The first two bytes of a bitcode file are 'BC' (``0x42``, ``0x43``). The second
+two bytes are an application-specific magic number. Generic bitcode tools can
+look at only the first two bytes to verify the file is bitcode, while
+application-specific programs will want to look at all four.
+
+.. _primitives:
+
+Primitives
+----------
+
+A bitstream literally consists of a stream of bits, which are read in order
+starting with the least significant bit of each byte. The stream is made up of
+a number of primitive values that encode a stream of unsigned integer values.
+These integers are encoded in two ways: either as `Fixed Width Integers`_ or as
+`Variable Width Integers`_.
+
+.. _Fixed Width Integers:
+.. _fixed-width value:
+
+Fixed Width Integers
+^^^^^^^^^^^^^^^^^^^^
+
+Fixed-width integer values have their low bits emitted directly to the file.
+For example, a 3-bit integer value encodes 1 as 001. Fixed width integers are
+used when there are a well-known number of options for a field. For example,
+boolean values are usually encoded with a 1-bit wide integer.
+
+.. _Variable Width Integers:
+.. _Variable Width Integer:
+.. _variable-width value:
+
+Variable Width Integers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Variable-width integer (VBR) values encode values of arbitrary size, optimizing
+for the case where the values are small. Given a 4-bit VBR field, any 3-bit
+value (0 through 7) is encoded directly, with the high bit set to zero. Values
+larger than N-1 bits emit their bits in a series of N-1 bit chunks, where all
+but the last set the high bit.
+
+For example, the value 27 (0x1B) is encoded as 1011 0011 when emitted as a vbr4
+value. The first set of four bits indicates the value 3 (011) with a
+continuation piece (indicated by a high bit of 1). The next word indicates a
+value of 24 (011 << 3) with no continuation. The sum (3+24) yields the value
+27.
+
+.. _char6-encoded value:
+
+6-bit characters
+^^^^^^^^^^^^^^^^
+
+6-bit characters encode common characters into a fixed 6-bit field. They
+represent the following characters with the following 6-bit values:
+
+::
+
+ 'a' .. 'z' --- 0 .. 25
+ 'A' .. 'Z' --- 26 .. 51
+ '0' .. '9' --- 52 .. 61
+ '.' --- 62
+ '_' --- 63
+
+This encoding is only suitable for encoding characters and strings that consist
+only of the above characters. It is completely incapable of encoding characters
+not in the set.
+
+Word Alignment
+^^^^^^^^^^^^^^
+
+Occasionally, it is useful to emit zero bits until the bitstream is a multiple
+of 32 bits. This ensures that the bit position in the stream can be represented
+as a multiple of 32-bit words.
+
+Abbreviation IDs
+----------------
+
+A bitstream is a sequential series of `Blocks`_ and `Data Records`_. Both of
+these start with an abbreviation ID encoded as a fixed-bitwidth field. The
+width is specified by the current block, as described below. The value of the
+abbreviation ID specifies either a builtin ID (which have special meanings,
+defined below) or one of the abbreviation IDs defined for the current block by
+the stream itself.
+
+The set of builtin abbrev IDs is:
+
+* 0 - `END_BLOCK`_ --- This abbrev ID marks the end of the current block.
+
+* 1 - `ENTER_SUBBLOCK`_ --- This abbrev ID marks the beginning of a new
+ block.
+
+* 2 - `DEFINE_ABBREV`_ --- This defines a new abbreviation.
+
+* 3 - `UNABBREV_RECORD`_ --- This ID specifies the definition of an
+ unabbreviated record.
+
+Abbreviation IDs 4 and above are defined by the stream itself, and specify an
+`abbreviated record encoding`_.
+
+.. _Blocks:
+
+Blocks
+------
+
+Blocks in a bitstream denote nested regions of the stream, and are identified by
+a content-specific id number (for example, LLVM IR uses an ID of 12 to represent
+function bodies). Block IDs 0-7 are reserved for `standard blocks`_ whose
+meaning is defined by Bitcode; block IDs 8 and greater are application
+specific. Nested blocks capture the hierarchical structure of the data encoded
+in it, and various properties are associated with blocks as the file is parsed.
+Block definitions allow the reader to efficiently skip blocks in constant time
+if the reader wants a summary of blocks, or if it wants to efficiently skip data
+it does not understand. The LLVM IR reader uses this mechanism to skip function
+bodies, lazily reading them on demand.
+
+When reading and encoding the stream, several properties are maintained for the
+block. In particular, each block maintains:
+
+#. A current abbrev id width. This value starts at 2 at the beginning of the
+ stream, and is set every time a block record is entered. The block entry
+ specifies the abbrev id width for the body of the block.
+
+#. A set of abbreviations. Abbreviations may be defined within a block, in
+ which case they are only defined in that block (neither subblocks nor
+ enclosing blocks see the abbreviation). Abbreviations can also be defined
+ inside a `BLOCKINFO`_ block, in which case they are defined in all blocks
+ that match the ID that the ``BLOCKINFO`` block is describing.
+
+As sub blocks are entered, these properties are saved and the new sub-block has
+its own set of abbreviations, and its own abbrev id width. When a sub-block is
+popped, the saved values are restored.
+
+.. _ENTER_SUBBLOCK:
+
+ENTER_SUBBLOCK Encoding
+^^^^^^^^^^^^^^^^^^^^^^^
+
+:raw-html:`<tt>`
+[ENTER_SUBBLOCK, blockid\ :sub:`vbr8`, newabbrevlen\ :sub:`vbr4`, <align32bits>, blocklen_32]
+:raw-html:`</tt>`
+
+The ``ENTER_SUBBLOCK`` abbreviation ID specifies the start of a new block
+record. The ``blockid`` value is encoded as an 8-bit VBR identifier, and
+indicates the type of block being entered, which can be a `standard block`_ or
+an application-specific block. The ``newabbrevlen`` value is a 4-bit VBR, which
+specifies the abbrev id width for the sub-block. The ``blocklen`` value is a
+32-bit aligned value that specifies the size of the subblock in 32-bit
+words. This value allows the reader to skip over the entire block in one jump.
+
+.. _END_BLOCK:
+
+END_BLOCK Encoding
+^^^^^^^^^^^^^^^^^^
+
+``[END_BLOCK, <align32bits>]``
+
+The ``END_BLOCK`` abbreviation ID specifies the end of the current block record.
+Its end is aligned to 32-bits to ensure that the size of the block is an even
+multiple of 32-bits.
+
+.. _Data Records:
+
+Data Records
+------------
+
+Data records consist of a record code and a number of (up to) 64-bit integer
+values. The interpretation of the code and values is application specific and
+may vary between different block types. Records can be encoded either using an
+unabbrev record, or with an abbreviation. In the LLVM IR format, for example,
+there is a record which encodes the target triple of a module. The code is
+``MODULE_CODE_TRIPLE``, and the values of the record are the ASCII codes for the
+characters in the string.
+
+.. _UNABBREV_RECORD:
+
+UNABBREV_RECORD Encoding
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+:raw-html:`<tt>`
+[UNABBREV_RECORD, code\ :sub:`vbr6`, numops\ :sub:`vbr6`, op0\ :sub:`vbr6`, op1\ :sub:`vbr6`, ...]
+:raw-html:`</tt>`
+
+An ``UNABBREV_RECORD`` provides a default fallback encoding, which is both
+completely general and extremely inefficient. It can describe an arbitrary
+record by emitting the code and operands as VBRs.
+
+For example, emitting an LLVM IR target triple as an unabbreviated record
+requires emitting the ``UNABBREV_RECORD`` abbrevid, a vbr6 for the
+``MODULE_CODE_TRIPLE`` code, a vbr6 for the length of the string, which is equal
+to the number of operands, and a vbr6 for each character. Because there are no
+letters with values less than 32, each letter would need to be emitted as at
+least a two-part VBR, which means that each letter would require at least 12
+bits. This is not an efficient encoding, but it is fully general.
+
+.. _abbreviated record encoding:
+
+Abbreviated Record Encoding
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[<abbrevid>, fields...]``
+
+An abbreviated record is a abbreviation id followed by a set of fields that are
+encoded according to the `abbreviation definition`_. This allows records to be
+encoded significantly more densely than records encoded with the
+`UNABBREV_RECORD`_ type, and allows the abbreviation types to be specified in
+the stream itself, which allows the files to be completely self describing. The
+actual encoding of abbreviations is defined below.
+
+The record code, which is the first field of an abbreviated record, may be
+encoded in the abbreviation definition (as a literal operand) or supplied in the
+abbreviated record (as a Fixed or VBR operand value).
+
+.. _abbreviation definition:
+
+Abbreviations
+-------------
+
+Abbreviations are an important form of compression for bitstreams. The idea is
+to specify a dense encoding for a class of records once, then use that encoding
+to emit many records. It takes space to emit the encoding into the file, but
+the space is recouped (hopefully plus some) when the records that use it are
+emitted.
+
+Abbreviations can be determined dynamically per client, per file. Because the
+abbreviations are stored in the bitstream itself, different streams of the same
+format can contain different sets of abbreviations according to the needs of the
+specific stream. As a concrete example, LLVM IR files usually emit an
+abbreviation for binary operators. If a specific LLVM module contained no or
+few binary operators, the abbreviation does not need to be emitted.
+
+.. _DEFINE_ABBREV:
+
+DEFINE_ABBREV Encoding
+^^^^^^^^^^^^^^^^^^^^^^
+
+:raw-html:`<tt>`
+[DEFINE_ABBREV, numabbrevops\ :sub:`vbr5`, abbrevop0, abbrevop1, ...]
+:raw-html:`</tt>`
+
+A ``DEFINE_ABBREV`` record adds an abbreviation to the list of currently defined
+abbreviations in the scope of this block. This definition only exists inside
+this immediate block --- it is not visible in subblocks or enclosing blocks.
+Abbreviations are implicitly assigned IDs sequentially starting from 4 (the
+first application-defined abbreviation ID). Any abbreviations defined in a
+``BLOCKINFO`` record for the particular block type receive IDs first, in order,
+followed by any abbreviations defined within the block itself. Abbreviated data
+records reference this ID to indicate what abbreviation they are invoking.
+
+An abbreviation definition consists of the ``DEFINE_ABBREV`` abbrevid followed
+by a VBR that specifies the number of abbrev operands, then the abbrev operands
+themselves. Abbreviation operands come in three forms. They all start with a
+single bit that indicates whether the abbrev operand is a literal operand (when
+the bit is 1) or an encoding operand (when the bit is 0).
+
+#. Literal operands --- :raw-html:`<tt>` [1\ :sub:`1`, litvalue\
+ :sub:`vbr8`] :raw-html:`</tt>` --- Literal operands specify that the value in
+ the result is always a single specific value. This specific value is emitted
+ as a vbr8 after the bit indicating that it is a literal operand.
+
+#. Encoding info without data --- :raw-html:`<tt>` [0\ :sub:`1`, encoding\
+ :sub:`3`] :raw-html:`</tt>` --- Operand encodings that do not have extra data
+ are just emitted as their code.
+
+#. Encoding info with data --- :raw-html:`<tt>` [0\ :sub:`1`, encoding\
+ :sub:`3`, value\ :sub:`vbr5`] :raw-html:`</tt>` --- Operand encodings that do
+ have extra data are emitted as their code, followed by the extra data.
+
+The possible operand encodings are:
+
+* Fixed (code 1): The field should be emitted as a `fixed-width value`_, whose
+ width is specified by the operand's extra data.
+
+* VBR (code 2): The field should be emitted as a `variable-width value`_, whose
+ width is specified by the operand's extra data.
+
+* Array (code 3): This field is an array of values. The array operand has no
+ extra data, but expects another operand to follow it, indicating the element
+ type of the array. When reading an array in an abbreviated record, the first
+ integer is a vbr6 that indicates the array length, followed by the encoded
+ elements of the array. An array may only occur as the last operand of an
+ abbreviation (except for the one final operand that gives the array's
+ type).
+
+* Char6 (code 4): This field should be emitted as a `char6-encoded value`_.
+ This operand type takes no extra data. Char6 encoding is normally used as an
+ array element type.
+
+* Blob (code 5): This field is emitted as a vbr6, followed by padding to a
+ 32-bit boundary (for alignment) and an array of 8-bit objects. The array of
+ bytes is further followed by tail padding to ensure that its total length is a
+ multiple of 4 bytes. This makes it very efficient for the reader to decode
+ the data without having to make a copy of it: it can use a pointer to the data
+ in the mapped in file and poke directly at it. A blob may only occur as the
+ last operand of an abbreviation.
+
+For example, target triples in LLVM modules are encoded as a record of the form
+``[TRIPLE, 'a', 'b', 'c', 'd']``. Consider if the bitstream emitted the
+following abbrev entry:
+
+::
+
+ [0, Fixed, 4]
+ [0, Array]
+ [0, Char6]
+
+When emitting a record with this abbreviation, the above entry would be emitted
+as:
+
+:raw-html:`<tt><blockquote>`
+[4\ :sub:`abbrevwidth`, 2\ :sub:`4`, 4\ :sub:`vbr6`, 0\ :sub:`6`, 1\ :sub:`6`, 2\ :sub:`6`, 3\ :sub:`6`]
+:raw-html:`</blockquote></tt>`
+
+These values are:
+
+#. The first value, 4, is the abbreviation ID for this abbreviation.
+
+#. The second value, 2, is the record code for ``TRIPLE`` records within LLVM IR
+ file ``MODULE_BLOCK`` blocks.
+
+#. The third value, 4, is the length of the array.
+
+#. The rest of the values are the char6 encoded values for ``"abcd"``.
+
+With this abbreviation, the triple is emitted with only 37 bits (assuming a
+abbrev id width of 3). Without the abbreviation, significantly more space would
+be required to emit the target triple. Also, because the ``TRIPLE`` value is
+not emitted as a literal in the abbreviation, the abbreviation can also be used
+for any other string value.
+
+.. _standard blocks:
+.. _standard block:
+
+Standard Blocks
+---------------
+
+In addition to the basic block structure and record encodings, the bitstream
+also defines specific built-in block types. These block types specify how the
+stream is to be decoded or other metadata. In the future, new standard blocks
+may be added. Block IDs 0-7 are reserved for standard blocks.
+
+.. _BLOCKINFO:
+
+#0 - BLOCKINFO Block
+^^^^^^^^^^^^^^^^^^^^
+
+The ``BLOCKINFO`` block allows the description of metadata for other blocks.
+The currently specified records are:
+
+::
+
+ [SETBID (#1), blockid]
+ [DEFINE_ABBREV, ...]
+ [BLOCKNAME, ...name...]
+ [SETRECORDNAME, RecordID, ...name...]
+
+The ``SETBID`` record (code 1) indicates which block ID is being described.
+``SETBID`` records can occur multiple times throughout the block to change which
+block ID is being described. There must be a ``SETBID`` record prior to any
+other records.
+
+Standard ``DEFINE_ABBREV`` records can occur inside ``BLOCKINFO`` blocks, but
+unlike their occurrence in normal blocks, the abbreviation is defined for blocks
+matching the block ID we are describing, *not* the ``BLOCKINFO`` block
+itself. The abbreviations defined in ``BLOCKINFO`` blocks receive abbreviation
+IDs as described in `DEFINE_ABBREV`_.
+
+The ``BLOCKNAME`` record (code 2) can optionally occur in this block. The
+elements of the record are the bytes of the string name of the block.
+llvm-bcanalyzer can use this to dump out bitcode files symbolically.
+
+The ``SETRECORDNAME`` record (code 3) can also optionally occur in this block.
+The first operand value is a record ID number, and the rest of the elements of
+the record are the bytes for the string name of the record. llvm-bcanalyzer can
+use this to dump out bitcode files symbolically.
+
+Note that although the data in ``BLOCKINFO`` blocks is described as "metadata,"
+the abbreviations they contain are essential for parsing records from the
+corresponding blocks. It is not safe to skip them.
+
+.. _wrapper:
+
+Bitcode Wrapper Format
+======================
+
+Bitcode files for LLVM IR may optionally be wrapped in a simple wrapper
+structure. This structure contains a simple header that indicates the offset
+and size of the embedded BC file. This allows additional information to be
+stored alongside the BC file. The structure of this file header is:
+
+:raw-html:`<tt><blockquote>`
+[Magic\ :sub:`32`, Version\ :sub:`32`, Offset\ :sub:`32`, Size\ :sub:`32`, CPUType\ :sub:`32`]
+:raw-html:`</blockquote></tt>`
+
+Each of the fields are 32-bit fields stored in little endian form (as with the
+rest of the bitcode file fields). The Magic number is always ``0x0B17C0DE`` and
+the version is currently always ``0``. The Offset field is the offset in bytes
+to the start of the bitcode stream in the file, and the Size field is the size
+in bytes of the stream. CPUType is a target-specific value that can be used to
+encode the CPU of the target.
+
+.. _native object file:
+
+Native Object File Wrapper Format
+=================================
+
+Bitcode files for LLVM IR may also be wrapped in a native object file
+(i.e. ELF, COFF, Mach-O). The bitcode must be stored in a section of the
+object file named ``.llvmbc``. This wrapper format is useful for accommodating
+LTO in compilation pipelines where intermediate objects must be native object
+files which contain metadata in other sections.
+
+Not all tools support this format.
+
+.. _encoding of LLVM IR:
+
+LLVM IR Encoding
+================
+
+LLVM IR is encoded into a bitstream by defining blocks and records. It uses
+blocks for things like constant pools, functions, symbol tables, etc. It uses
+records for things like instructions, global variable descriptors, type
+descriptions, etc. This document does not describe the set of abbreviations
+that the writer uses, as these are fully self-described in the file, and the
+reader is not allowed to build in any knowledge of this.
+
+Basics
+------
+
+LLVM IR Magic Number
+^^^^^^^^^^^^^^^^^^^^
+
+The magic number for LLVM IR files is:
+
+:raw-html:`<tt><blockquote>`
+[0x0\ :sub:`4`, 0xC\ :sub:`4`, 0xE\ :sub:`4`, 0xD\ :sub:`4`]
+:raw-html:`</blockquote></tt>`
+
+When combined with the bitcode magic number and viewed as bytes, this is
+``"BC 0xC0DE"``.
+
+.. _Signed VBRs:
+
+Signed VBRs
+^^^^^^^^^^^
+
+`Variable Width Integer`_ encoding is an efficient way to encode arbitrary sized
+unsigned values, but is an extremely inefficient for encoding signed values, as
+signed values are otherwise treated as maximally large unsigned values.
+
+As such, signed VBR values of a specific width are emitted as follows:
+
+* Positive values are emitted as VBRs of the specified width, but with their
+ value shifted left by one.
+
+* Negative values are emitted as VBRs of the specified width, but the negated
+ value is shifted left by one, and the low bit is set.
+
+With this encoding, small positive and small negative values can both be emitted
+efficiently. Signed VBR encoding is used in ``CST_CODE_INTEGER`` and
+``CST_CODE_WIDE_INTEGER`` records within ``CONSTANTS_BLOCK`` blocks.
+It is also used for phi instruction operands in `MODULE_CODE_VERSION`_ 1.
+
+LLVM IR Blocks
+^^^^^^^^^^^^^^
+
+LLVM IR is defined with the following blocks:
+
+* 8 --- `MODULE_BLOCK`_ --- This is the top-level block that contains the entire
+ module, and describes a variety of per-module information.
+
+* 9 --- `PARAMATTR_BLOCK`_ --- This enumerates the parameter attributes.
+
+* 10 --- `TYPE_BLOCK`_ --- This describes all of the types in the module.
+
+* 11 --- `CONSTANTS_BLOCK`_ --- This describes constants for a module or
+ function.
+
+* 12 --- `FUNCTION_BLOCK`_ --- This describes a function body.
+
+* 13 --- `TYPE_SYMTAB_BLOCK`_ --- This describes the type symbol table.
+
+* 14 --- `VALUE_SYMTAB_BLOCK`_ --- This describes a value symbol table.
+
+* 15 --- `METADATA_BLOCK`_ --- This describes metadata items.
+
+* 16 --- `METADATA_ATTACHMENT`_ --- This contains records associating metadata
+ with function instruction values.
+
+.. _MODULE_BLOCK:
+
+MODULE_BLOCK Contents
+---------------------
+
+The ``MODULE_BLOCK`` block (id 8) is the top-level block for LLVM bitcode files,
+and each bitcode file must contain exactly one. In addition to records
+(described below) containing information about the module, a ``MODULE_BLOCK``
+block may contain the following sub-blocks:
+
+* `BLOCKINFO`_
+* `PARAMATTR_BLOCK`_
+* `TYPE_BLOCK`_
+* `TYPE_SYMTAB_BLOCK`_
+* `VALUE_SYMTAB_BLOCK`_
+* `CONSTANTS_BLOCK`_
+* `FUNCTION_BLOCK`_
+* `METADATA_BLOCK`_
+
+.. _MODULE_CODE_VERSION:
+
+MODULE_CODE_VERSION Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[VERSION, version#]``
+
+The ``VERSION`` record (code 1) contains a single value indicating the format
+version. Versions 0 and 1 are supported at this time. The difference between
+version 0 and 1 is in the encoding of instruction operands in
+each `FUNCTION_BLOCK`_.
+
+In version 0, each value defined by an instruction is assigned an ID
+unique to the function. Function-level value IDs are assigned starting from
+``NumModuleValues`` since they share the same namespace as module-level
+values. The value enumerator resets after each function. When a value is
+an operand of an instruction, the value ID is used to represent the operand.
+For large functions or large modules, these operand values can be large.
+
+The encoding in version 1 attempts to avoid large operand values
+in common cases. Instead of using the value ID directly, operands are
+encoded as relative to the current instruction. Thus, if an operand
+is the value defined by the previous instruction, the operand
+will be encoded as 1.
+
+For example, instead of
+
+.. code-block:: llvm
+
+ #n = load #n-1
+ #n+1 = icmp eq #n, #const0
+ br #n+1, label #(bb1), label #(bb2)
+
+version 1 will encode the instructions as
+
+.. code-block:: llvm
+
+ #n = load #1
+ #n+1 = icmp eq #1, (#n+1)-#const0
+ br #1, label #(bb1), label #(bb2)
+
+Note in the example that operands which are constants also use
+the relative encoding, while operands like basic block labels
+do not use the relative encoding.
+
+Forward references will result in a negative value.
+This can be inefficient, as operands are normally encoded
+as unsigned VBRs. However, forward references are rare, except in the
+case of phi instructions. For phi instructions, operands are encoded as
+`Signed VBRs`_ to deal with forward references.
+
+
+MODULE_CODE_TRIPLE Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[TRIPLE, ...string...]``
+
+The ``TRIPLE`` record (code 2) contains a variable number of values representing
+the bytes of the ``target triple`` specification string.
+
+MODULE_CODE_DATALAYOUT Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[DATALAYOUT, ...string...]``
+
+The ``DATALAYOUT`` record (code 3) contains a variable number of values
+representing the bytes of the ``target datalayout`` specification string.
+
+MODULE_CODE_ASM Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[ASM, ...string...]``
+
+The ``ASM`` record (code 4) contains a variable number of values representing
+the bytes of ``module asm`` strings, with individual assembly blocks separated
+by newline (ASCII 10) characters.
+
+.. _MODULE_CODE_SECTIONNAME:
+
+MODULE_CODE_SECTIONNAME Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[SECTIONNAME, ...string...]``
+
+The ``SECTIONNAME`` record (code 5) contains a variable number of values
+representing the bytes of a single section name string. There should be one
+``SECTIONNAME`` record for each section name referenced (e.g., in global
+variable or function ``section`` attributes) within the module. These records
+can be referenced by the 1-based index in the *section* fields of ``GLOBALVAR``
+or ``FUNCTION`` records.
+
+MODULE_CODE_DEPLIB Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[DEPLIB, ...string...]``
+
+The ``DEPLIB`` record (code 6) contains a variable number of values representing
+the bytes of a single dependent library name string, one of the libraries
+mentioned in a ``deplibs`` declaration. There should be one ``DEPLIB`` record
+for each library name referenced.
+
+MODULE_CODE_GLOBALVAR Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[GLOBALVAR, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal, unnamed_addr, externally_initialized, dllstorageclass, comdat]``
+
+The ``GLOBALVAR`` record (code 7) marks the declaration or definition of a
+global variable. The operand fields are:
+
+* *pointer type*: The type index of the pointer type used to point to this
+ global variable
+
+* *isconst*: Non-zero if the variable is treated as constant within the module,
+ or zero if it is not
+
+* *initid*: If non-zero, the value index of the initializer for this variable,
+ plus 1.
+
+.. _linkage type:
+
+* *linkage*: An encoding of the linkage type for this variable:
+ * ``external``: code 0
+ * ``weak``: code 1
+ * ``appending``: code 2
+ * ``internal``: code 3
+ * ``linkonce``: code 4
+ * ``dllimport``: code 5
+ * ``dllexport``: code 6
+ * ``extern_weak``: code 7
+ * ``common``: code 8
+ * ``private``: code 9
+ * ``weak_odr``: code 10
+ * ``linkonce_odr``: code 11
+ * ``available_externally``: code 12
+ * deprecated : code 13
+ * deprecated : code 14
+
+* alignment*: The logarithm base 2 of the variable's requested alignment, plus 1
+
+* *section*: If non-zero, the 1-based section index in the table of
+ `MODULE_CODE_SECTIONNAME`_ entries.
+
+.. _visibility:
+
+* *visibility*: If present, an encoding of the visibility of this variable:
+ * ``default``: code 0
+ * ``hidden``: code 1
+ * ``protected``: code 2
+
+* *threadlocal*: If present, an encoding of the thread local storage mode of the
+ variable:
+ * ``not thread local``: code 0
+ * ``thread local; default TLS model``: code 1
+ * ``localdynamic``: code 2
+ * ``initialexec``: code 3
+ * ``localexec``: code 4
+
+* *unnamed_addr*: If present and non-zero, indicates that the variable has
+ ``unnamed_addr``
+
+.. _bcdllstorageclass:
+
+* *dllstorageclass*: If present, an encoding of the DLL storage class of this variable:
+
+ * ``default``: code 0
+ * ``dllimport``: code 1
+ * ``dllexport``: code 2
+
+.. _FUNCTION:
+
+MODULE_CODE_FUNCTION Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[FUNCTION, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc, prologuedata, dllstorageclass, comdat, prefixdata, personalityfn]``
+
+The ``FUNCTION`` record (code 8) marks the declaration or definition of a
+function. The operand fields are:
+
+* *type*: The type index of the function type describing this function
+
+* *callingconv*: The calling convention number:
+ * ``ccc``: code 0
+ * ``fastcc``: code 8
+ * ``coldcc``: code 9
+ * ``webkit_jscc``: code 12
+ * ``anyregcc``: code 13
+ * ``preserve_mostcc``: code 14
+ * ``preserve_allcc``: code 15
+ * ``x86_stdcallcc``: code 64
+ * ``x86_fastcallcc``: code 65
+ * ``arm_apcscc``: code 66
+ * ``arm_aapcscc``: code 67
+ * ``arm_aapcs_vfpcc``: code 68
+
+* isproto*: Non-zero if this entry represents a declaration rather than a
+ definition
+
+* *linkage*: An encoding of the `linkage type`_ for this function
+
+* *paramattr*: If nonzero, the 1-based parameter attribute index into the table
+ of `PARAMATTR_CODE_ENTRY`_ entries.
+
+* *alignment*: The logarithm base 2 of the function's requested alignment, plus
+ 1
+
+* *section*: If non-zero, the 1-based section index in the table of
+ `MODULE_CODE_SECTIONNAME`_ entries.
+
+* *visibility*: An encoding of the `visibility`_ of this function
+
+* *gc*: If present and nonzero, the 1-based garbage collector index in the table
+ of `MODULE_CODE_GCNAME`_ entries.
+
+* *unnamed_addr*: If present and non-zero, indicates that the function has
+ ``unnamed_addr``
+
+* *prologuedata*: If non-zero, the value index of the prologue data for this function,
+ plus 1.
+
+* *dllstorageclass*: An encoding of the
+ :ref:`dllstorageclass<bcdllstorageclass>` of this function
+
+* *comdat*: An encoding of the COMDAT of this function
+
+* *prefixdata*: If non-zero, the value index of the prefix data for this function,
+ plus 1.
+
+* *personalityfn*: If non-zero, the value index of the personality function for this function,
+ plus 1.
+
+MODULE_CODE_ALIAS Record
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[ALIAS, alias type, aliasee val#, linkage, visibility, dllstorageclass]``
+
+The ``ALIAS`` record (code 9) marks the definition of an alias. The operand
+fields are
+
+* *alias type*: The type index of the alias
+
+* *aliasee val#*: The value index of the aliased value
+
+* *linkage*: An encoding of the `linkage type`_ for this alias
+
+* *visibility*: If present, an encoding of the `visibility`_ of the alias
+
+* *dllstorageclass*: If present, an encoding of the
+ :ref:`dllstorageclass<bcdllstorageclass>` of the alias
+
+MODULE_CODE_PURGEVALS Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[PURGEVALS, numvals]``
+
+The ``PURGEVALS`` record (code 10) resets the module-level value list to the
+size given by the single operand value. Module-level value list items are added
+by ``GLOBALVAR``, ``FUNCTION``, and ``ALIAS`` records. After a ``PURGEVALS``
+record is seen, new value indices will start from the given *numvals* value.
+
+.. _MODULE_CODE_GCNAME:
+
+MODULE_CODE_GCNAME Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[GCNAME, ...string...]``
+
+The ``GCNAME`` record (code 11) contains a variable number of values
+representing the bytes of a single garbage collector name string. There should
+be one ``GCNAME`` record for each garbage collector name referenced in function
+``gc`` attributes within the module. These records can be referenced by 1-based
+index in the *gc* fields of ``FUNCTION`` records.
+
+.. _PARAMATTR_BLOCK:
+
+PARAMATTR_BLOCK Contents
+------------------------
+
+The ``PARAMATTR_BLOCK`` block (id 9) contains a table of entries describing the
+attributes of function parameters. These entries are referenced by 1-based index
+in the *paramattr* field of module block `FUNCTION`_ records, or within the
+*attr* field of function block ``INST_INVOKE`` and ``INST_CALL`` records.
+
+Entries within ``PARAMATTR_BLOCK`` are constructed to ensure that each is unique
+(i.e., no two indicies represent equivalent attribute lists).
+
+.. _PARAMATTR_CODE_ENTRY:
+
+PARAMATTR_CODE_ENTRY Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[ENTRY, paramidx0, attr0, paramidx1, attr1...]``
+
+The ``ENTRY`` record (code 1) contains an even number of values describing a
+unique set of function parameter attributes. Each *paramidx* value indicates
+which set of attributes is represented, with 0 representing the return value
+attributes, 0xFFFFFFFF representing function attributes, and other values
+representing 1-based function parameters. Each *attr* value is a bitmap with the
+following interpretation:
+
+* bit 0: ``zeroext``
+* bit 1: ``signext``
+* bit 2: ``noreturn``
+* bit 3: ``inreg``
+* bit 4: ``sret``
+* bit 5: ``nounwind``
+* bit 6: ``noalias``
+* bit 7: ``byval``
+* bit 8: ``nest``
+* bit 9: ``readnone``
+* bit 10: ``readonly``
+* bit 11: ``noinline``
+* bit 12: ``alwaysinline``
+* bit 13: ``optsize``
+* bit 14: ``ssp``
+* bit 15: ``sspreq``
+* bits 16-31: ``align n``
+* bit 32: ``nocapture``
+* bit 33: ``noredzone``
+* bit 34: ``noimplicitfloat``
+* bit 35: ``naked``
+* bit 36: ``inlinehint``
+* bits 37-39: ``alignstack n``, represented as the logarithm
+ base 2 of the requested alignment, plus 1
+
+.. _TYPE_BLOCK:
+
+TYPE_BLOCK Contents
+-------------------
+
+The ``TYPE_BLOCK`` block (id 10) contains records which constitute a table of
+type operator entries used to represent types referenced within an LLVM
+module. Each record (with the exception of `NUMENTRY`_) generates a single type
+table entry, which may be referenced by 0-based index from instructions,
+constants, metadata, type symbol table entries, or other type operator records.
+
+Entries within ``TYPE_BLOCK`` are constructed to ensure that each entry is
+unique (i.e., no two indicies represent structurally equivalent types).
+
+.. _TYPE_CODE_NUMENTRY:
+.. _NUMENTRY:
+
+TYPE_CODE_NUMENTRY Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[NUMENTRY, numentries]``
+
+The ``NUMENTRY`` record (code 1) contains a single value which indicates the
+total number of type code entries in the type table of the module. If present,
+``NUMENTRY`` should be the first record in the block.
+
+TYPE_CODE_VOID Record
+^^^^^^^^^^^^^^^^^^^^^
+
+``[VOID]``
+
+The ``VOID`` record (code 2) adds a ``void`` type to the type table.
+
+TYPE_CODE_HALF Record
+^^^^^^^^^^^^^^^^^^^^^
+
+``[HALF]``
+
+The ``HALF`` record (code 10) adds a ``half`` (16-bit floating point) type to
+the type table.
+
+TYPE_CODE_FLOAT Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[FLOAT]``
+
+The ``FLOAT`` record (code 3) adds a ``float`` (32-bit floating point) type to
+the type table.
+
+TYPE_CODE_DOUBLE Record
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``[DOUBLE]``
+
+The ``DOUBLE`` record (code 4) adds a ``double`` (64-bit floating point) type to
+the type table.
+
+TYPE_CODE_LABEL Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[LABEL]``
+
+The ``LABEL`` record (code 5) adds a ``label`` type to the type table.
+
+TYPE_CODE_OPAQUE Record
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``[OPAQUE]``
+
+The ``OPAQUE`` record (code 6) adds an ``opaque`` type to the type table. Note
+that distinct ``opaque`` types are not unified.
+
+TYPE_CODE_INTEGER Record
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[INTEGER, width]``
+
+The ``INTEGER`` record (code 7) adds an integer type to the type table. The
+single *width* field indicates the width of the integer type.
+
+TYPE_CODE_POINTER Record
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[POINTER, pointee type, address space]``
+
+The ``POINTER`` record (code 8) adds a pointer type to the type table. The
+operand fields are
+
+* *pointee type*: The type index of the pointed-to type
+
+* *address space*: If supplied, the target-specific numbered address space where
+ the pointed-to object resides. Otherwise, the default address space is zero.
+
+TYPE_CODE_FUNCTION Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[FUNCTION, vararg, ignored, retty, ...paramty... ]``
+
+The ``FUNCTION`` record (code 9) adds a function type to the type table. The
+operand fields are
+
+* *vararg*: Non-zero if the type represents a varargs function
+
+* *ignored*: This value field is present for backward compatibility only, and is
+ ignored
+
+* *retty*: The type index of the function's return type
+
+* *paramty*: Zero or more type indices representing the parameter types of the
+ function
+
+TYPE_CODE_STRUCT Record
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``[STRUCT, ispacked, ...eltty...]``
+
+The ``STRUCT`` record (code 10) adds a struct type to the type table. The
+operand fields are
+
+* *ispacked*: Non-zero if the type represents a packed structure
+
+* *eltty*: Zero or more type indices representing the element types of the
+ structure
+
+TYPE_CODE_ARRAY Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[ARRAY, numelts, eltty]``
+
+The ``ARRAY`` record (code 11) adds an array type to the type table. The
+operand fields are
+
+* *numelts*: The number of elements in arrays of this type
+
+* *eltty*: The type index of the array element type
+
+TYPE_CODE_VECTOR Record
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``[VECTOR, numelts, eltty]``
+
+The ``VECTOR`` record (code 12) adds a vector type to the type table. The
+operand fields are
+
+* *numelts*: The number of elements in vectors of this type
+
+* *eltty*: The type index of the vector element type
+
+TYPE_CODE_X86_FP80 Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[X86_FP80]``
+
+The ``X86_FP80`` record (code 13) adds an ``x86_fp80`` (80-bit floating point)
+type to the type table.
+
+TYPE_CODE_FP128 Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[FP128]``
+
+The ``FP128`` record (code 14) adds an ``fp128`` (128-bit floating point) type
+to the type table.
+
+TYPE_CODE_PPC_FP128 Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[PPC_FP128]``
+
+The ``PPC_FP128`` record (code 15) adds a ``ppc_fp128`` (128-bit floating point)
+type to the type table.
+
+TYPE_CODE_METADATA Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[METADATA]``
+
+The ``METADATA`` record (code 16) adds a ``metadata`` type to the type table.
+
+.. _CONSTANTS_BLOCK:
+
+CONSTANTS_BLOCK Contents
+------------------------
+
+The ``CONSTANTS_BLOCK`` block (id 11) ...
+
+.. _FUNCTION_BLOCK:
+
+FUNCTION_BLOCK Contents
+-----------------------
+
+The ``FUNCTION_BLOCK`` block (id 12) ...
+
+In addition to the record types described below, a ``FUNCTION_BLOCK`` block may
+contain the following sub-blocks:
+
+* `CONSTANTS_BLOCK`_
+* `VALUE_SYMTAB_BLOCK`_
+* `METADATA_ATTACHMENT`_
+
+.. _TYPE_SYMTAB_BLOCK:
+
+TYPE_SYMTAB_BLOCK Contents
+--------------------------
+
+The ``TYPE_SYMTAB_BLOCK`` block (id 13) contains entries which map between
+module-level named types and their corresponding type indices.
+
+.. _TST_CODE_ENTRY:
+
+TST_CODE_ENTRY Record
+^^^^^^^^^^^^^^^^^^^^^
+
+``[ENTRY, typeid, ...string...]``
+
+The ``ENTRY`` record (code 1) contains a variable number of values, with the
+first giving the type index of the designated type, and the remaining values
+giving the character codes of the type name. Each entry corresponds to a single
+named type.
+
+.. _VALUE_SYMTAB_BLOCK:
+
+VALUE_SYMTAB_BLOCK Contents
+---------------------------
+
+The ``VALUE_SYMTAB_BLOCK`` block (id 14) ...
+
+.. _METADATA_BLOCK:
+
+METADATA_BLOCK Contents
+-----------------------
+
+The ``METADATA_BLOCK`` block (id 15) ...
+
+.. _METADATA_ATTACHMENT:
+
+METADATA_ATTACHMENT Contents
+----------------------------
+
+The ``METADATA_ATTACHMENT`` block (id 16) ...
Added: www-releases/trunk/3.7.1/docs/_sources/BitSets.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/BitSets.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/BitSets.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/BitSets.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,70 @@
+=======
+Bitsets
+=======
+
+This is a mechanism that allows IR modules to co-operatively build pointer
+sets corresponding to addresses within a given set of globals. One example
+of a use case for this is to allow a C++ program to efficiently verify (at
+each call site) that a vtable pointer is in the set of valid vtable pointers
+for the type of the class or its derived classes.
+
+To use the mechanism, a client creates a global metadata node named
+``llvm.bitsets``. Each element is a metadata node with three elements:
+the first is a metadata string containing an identifier for the bitset,
+the second is a global variable and the third is a byte offset into the
+global variable.
+
+This will cause a link-time optimization pass to generate bitsets from the
+memory addresses referenced from the elements of the bitset metadata. The pass
+will lay out the referenced globals consecutively, so their definitions must
+be available at LTO time. The `GlobalLayoutBuilder`_ class is responsible for
+laying out the globals efficiently to minimize the sizes of the underlying
+bitsets. An intrinsic, :ref:`llvm.bitset.test <bitset.test>`, generates code
+to test whether a given pointer is a member of a bitset.
+
+:Example:
+
+::
+
+ target datalayout = "e-p:32:32"
+
+ @a = internal global i32 0
+ @b = internal global i32 0
+ @c = internal global i32 0
+ @d = internal global [2 x i32] [i32 0, i32 0]
+
+ !llvm.bitsets = !{!0, !1, !2, !3, !4}
+
+ !0 = !{!"bitset1", i32* @a, i32 0}
+ !1 = !{!"bitset1", i32* @b, i32 0}
+ !2 = !{!"bitset2", i32* @b, i32 0}
+ !3 = !{!"bitset2", i32* @c, i32 0}
+ !4 = !{!"bitset2", i32* @d, i32 4}
+
+ declare i1 @llvm.bitset.test(i8* %ptr, metadata %bitset) nounwind readnone
+
+ define i1 @foo(i32* %p) {
+ %pi8 = bitcast i32* %p to i8*
+ %x = call i1 @llvm.bitset.test(i8* %pi8, metadata !"bitset1")
+ ret i1 %x
+ }
+
+ define i1 @bar(i32* %p) {
+ %pi8 = bitcast i32* %p to i8*
+ %x = call i1 @llvm.bitset.test(i8* %pi8, metadata !"bitset2")
+ ret i1 %x
+ }
+
+ define void @main() {
+ %a1 = call i1 @foo(i32* @a) ; returns 1
+ %b1 = call i1 @foo(i32* @b) ; returns 1
+ %c1 = call i1 @foo(i32* @c) ; returns 0
+ %a2 = call i1 @bar(i32* @a) ; returns 0
+ %b2 = call i1 @bar(i32* @b) ; returns 1
+ %c2 = call i1 @bar(i32* @c) ; returns 1
+ %d02 = call i1 @bar(i32* getelementptr ([2 x i32]* @d, i32 0, i32 0)) ; returns 0
+ %d12 = call i1 @bar(i32* getelementptr ([2 x i32]* @d, i32 0, i32 1)) ; returns 1
+ ret void
+ }
+
+.. _GlobalLayoutBuilder: http://llvm.org/klaus/llvm/blob/master/include/llvm/Transforms/IPO/LowerBitSets.h
Added: www-releases/trunk/3.7.1/docs/_sources/BlockFrequencyTerminology.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/BlockFrequencyTerminology.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/BlockFrequencyTerminology.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/BlockFrequencyTerminology.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,130 @@
+================================
+LLVM Block Frequency Terminology
+================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Block Frequency is a metric for estimating the relative frequency of different
+basic blocks. This document describes the terminology that the
+``BlockFrequencyInfo`` and ``MachineBlockFrequencyInfo`` analysis passes use.
+
+Branch Probability
+==================
+
+Blocks with multiple successors have probabilities associated with each
+outgoing edge. These are called branch probabilities. For a given block, the
+sum of its outgoing branch probabilities should be 1.0.
+
+Branch Weight
+=============
+
+Rather than storing fractions on each edge, we store an integer weight.
+Weights are relative to the other edges of a given predecessor block. The
+branch probability associated with a given edge is its own weight divided by
+the sum of the weights on the predecessor's outgoing edges.
+
+For example, consider this IR:
+
+.. code-block:: llvm
+
+ define void @foo() {
+ ; ...
+ A:
+ br i1 %cond, label %B, label %C, !prof !0
+ ; ...
+ }
+ !0 = metadata !{metadata !"branch_weights", i32 7, i32 8}
+
+and this simple graph representation::
+
+ A -> B (edge-weight: 7)
+ A -> C (edge-weight: 8)
+
+The probability of branching from block A to block B is 7/15, and the
+probability of branching from block A to block C is 8/15.
+
+See :doc:`BranchWeightMetadata` for details about the branch weight IR
+representation.
+
+Block Frequency
+===============
+
+Block frequency is a relative metric that represents the number of times a
+block executes. The ratio of a block frequency to the entry block frequency is
+the expected number of times the block will execute per entry to the function.
+
+Block frequency is the main output of the ``BlockFrequencyInfo`` and
+``MachineBlockFrequencyInfo`` analysis passes.
+
+Implementation: a series of DAGs
+================================
+
+The implementation of the block frequency calculation analyses each loop,
+bottom-up, ignoring backedges; i.e., as a DAG. After each loop is processed,
+it's packaged up to act as a pseudo-node in its parent loop's (or the
+function's) DAG analysis.
+
+Block Mass
+==========
+
+For each DAG, the entry node is assigned a mass of ``UINT64_MAX`` and mass is
+distributed to successors according to branch weights. Block Mass uses a
+fixed-point representation where ``UINT64_MAX`` represents ``1.0`` and ``0``
+represents a number just above ``0.0``.
+
+After mass is fully distributed, in any cut of the DAG that separates the exit
+nodes from the entry node, the sum of the block masses of the nodes succeeded
+by a cut edge should equal ``UINT64_MAX``. In other words, mass is conserved
+as it "falls" through the DAG.
+
+If a function's basic block graph is a DAG, then block masses are valid block
+frequencies. This works poorly in practise though, since downstream users rely
+on adding block frequencies together without hitting the maximum.
+
+Loop Scale
+==========
+
+Loop scale is a metric that indicates how many times a loop iterates per entry.
+As mass is distributed through the loop's DAG, the (otherwise ignored) backedge
+mass is collected. This backedge mass is used to compute the exit frequency,
+and thus the loop scale.
+
+Implementation: Getting from mass and scale to frequency
+========================================================
+
+After analysing the complete series of DAGs, each block has a mass (local to
+its containing loop, if any), and each loop pseudo-node has a loop scale and
+its own mass (from its parent's DAG).
+
+We can get an initial frequency assignment (with entry frequency of 1.0) by
+multiplying these masses and loop scales together. A given block's frequency
+is the product of its mass, the mass of containing loops' pseudo nodes, and the
+containing loops' loop scales.
+
+Since downstream users need integers (not floating point), this initial
+frequency assignment is shifted as necessary into the range of ``uint64_t``.
+
+Block Bias
+==========
+
+Block bias is a proposed *absolute* metric to indicate a bias toward or away
+from a given block during a function's execution. The idea is that bias can be
+used in isolation to indicate whether a block is relatively hot or cold, or to
+compare two blocks to indicate whether one is hotter or colder than the other.
+
+The proposed calculation involves calculating a *reference* block frequency,
+where:
+
+* every branch weight is assumed to be 1 (i.e., every branch probability
+ distribution is even) and
+
+* loop scales are ignored.
+
+This reference frequency represents what the block frequency would be in an
+unbiased graph.
+
+The bias is the ratio of the block frequency to this reference block frequency.
Added: www-releases/trunk/3.7.1/docs/_sources/BranchWeightMetadata.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/BranchWeightMetadata.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/BranchWeightMetadata.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/BranchWeightMetadata.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,140 @@
+===========================
+LLVM Branch Weight Metadata
+===========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Branch Weight Metadata represents branch weights as its likeliness to be taken
+(see :doc:`BlockFrequencyTerminology`). Metadata is assigned to the
+``TerminatorInst`` as a ``MDNode`` of the ``MD_prof`` kind. The first operator
+is always a ``MDString`` node with the string "branch_weights". Number of
+operators depends on the terminator type.
+
+Branch weights might be fetch from the profiling file, or generated based on
+`__builtin_expect`_ instruction.
+
+All weights are represented as an unsigned 32-bit values, where higher value
+indicates greater chance to be taken.
+
+Supported Instructions
+======================
+
+``BranchInst``
+^^^^^^^^^^^^^^
+
+Metadata is only assigned to the conditional branches. There are two extra
+operarands for the true and the false branch.
+
+.. code-block:: llvm
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <TRUE_BRANCH_WEIGHT>,
+ i32 <FALSE_BRANCH_WEIGHT>
+ }
+
+``SwitchInst``
+^^^^^^^^^^^^^^
+
+Branch weights are assigned to every case (including the ``default`` case which
+is always case #0).
+
+.. code-block:: llvm
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <DEFAULT_BRANCH_WEIGHT>
+ [ , i32 <CASE_BRANCH_WEIGHT> ... ]
+ }
+
+``IndirectBrInst``
+^^^^^^^^^^^^^^^^^^
+
+Branch weights are assigned to every destination.
+
+.. code-block:: llvm
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <LABEL_BRANCH_WEIGHT>
+ [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
+ }
+
+Other
+^^^^^
+
+Other terminator instructions are not allowed to contain Branch Weight Metadata.
+
+.. _\__builtin_expect:
+
+Built-in ``expect`` Instructions
+================================
+
+``__builtin_expect(long exp, long c)`` instruction provides branch prediction
+information. The return value is the value of ``exp``.
+
+It is especially useful in conditional statements. Currently Clang supports two
+conditional statements:
+
+``if`` statement
+^^^^^^^^^^^^^^^^
+
+The ``exp`` parameter is the condition. The ``c`` parameter is the expected
+comparison value. If it is equal to 1 (true), the condition is likely to be
+true, in other case condition is likely to be false. For example:
+
+.. code-block:: c++
+
+ if (__builtin_expect(x > 0, 1)) {
+ // This block is likely to be taken.
+ }
+
+``switch`` statement
+^^^^^^^^^^^^^^^^^^^^
+
+The ``exp`` parameter is the value. The ``c`` parameter is the expected
+value. If the expected value doesn't show on the cases list, the ``default``
+case is assumed to be likely taken.
+
+.. code-block:: c++
+
+ switch (__builtin_expect(x, 5)) {
+ default: break;
+ case 0: // ...
+ case 3: // ...
+ case 5: // This case is likely to be taken.
+ }
+
+CFG Modifications
+=================
+
+Branch Weight Metatada is not proof against CFG changes. If terminator operands'
+are changed some action should be taken. In other case some misoptimizations may
+occur due to incorrent branch prediction information.
+
+Function Entry Counts
+=====================
+
+To allow comparing different functions durint inter-procedural analysis and
+optimization, ``MD_prof`` nodes can also be assigned to a function definition.
+The first operand is a string indicating the name of the associated counter.
+
+Currently, one counter is supported: "function_entry_count". This is a 64-bit
+counter that indicates the number of times that this function was invoked (in
+the case of instrumentation-based profiles). In the case of sampling-based
+profiles, this counter is an approximation of how many times the function was
+invoked.
+
+For example, in the code below, the instrumentation for function foo()
+indicates that it was called 2,590 times at runtime.
+
+.. code-block:: llvm
+
+ define i32 @foo() !prof !1 {
+ ret i32 0
+ }
+ !1 = !{!"function_entry_count", i64 2590}
Added: www-releases/trunk/3.7.1/docs/_sources/Bugpoint.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/Bugpoint.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/Bugpoint.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/Bugpoint.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,216 @@
+====================================
+LLVM bugpoint tool: design and usage
+====================================
+
+.. contents::
+ :local:
+
+Description
+===========
+
+``bugpoint`` narrows down the source of problems in LLVM tools and passes. It
+can be used to debug three types of failures: optimizer crashes, miscompilations
+by optimizers, or bad native code generation (including problems in the static
+and JIT compilers). It aims to reduce large test cases to small, useful ones.
+For example, if ``opt`` crashes while optimizing a file, it will identify the
+optimization (or combination of optimizations) that causes the crash, and reduce
+the file down to a small example which triggers the crash.
+
+For detailed case scenarios, such as debugging ``opt``, or one of the LLVM code
+generators, see :doc:`HowToSubmitABug`.
+
+Design Philosophy
+=================
+
+``bugpoint`` is designed to be a useful tool without requiring any hooks into
+the LLVM infrastructure at all. It works with any and all LLVM passes and code
+generators, and does not need to "know" how they work. Because of this, it may
+appear to do stupid things or miss obvious simplifications. ``bugpoint`` is
+also designed to trade off programmer time for computer time in the
+compiler-debugging process; consequently, it may take a long period of
+(unattended) time to reduce a test case, but we feel it is still worth it. Note
+that ``bugpoint`` is generally very quick unless debugging a miscompilation
+where each test of the program (which requires executing it) takes a long time.
+
+Automatic Debugger Selection
+----------------------------
+
+``bugpoint`` reads each ``.bc`` or ``.ll`` file specified on the command line
+and links them together into a single module, called the test program. If any
+LLVM passes are specified on the command line, it runs these passes on the test
+program. If any of the passes crash, or if they produce malformed output (which
+causes the verifier to abort), ``bugpoint`` starts the `crash debugger`_.
+
+Otherwise, if the ``-output`` option was not specified, ``bugpoint`` runs the
+test program with the "safe" backend (which is assumed to generate good code) to
+generate a reference output. Once ``bugpoint`` has a reference output for the
+test program, it tries executing it with the selected code generator. If the
+selected code generator crashes, ``bugpoint`` starts the `crash debugger`_ on
+the code generator. Otherwise, if the resulting output differs from the
+reference output, it assumes the difference resulted from a code generator
+failure, and starts the `code generator debugger`_.
+
+Finally, if the output of the selected code generator matches the reference
+output, ``bugpoint`` runs the test program after all of the LLVM passes have
+been applied to it. If its output differs from the reference output, it assumes
+the difference resulted from a failure in one of the LLVM passes, and enters the
+`miscompilation debugger`_. Otherwise, there is no problem ``bugpoint`` can
+debug.
+
+.. _crash debugger:
+
+Crash debugger
+--------------
+
+If an optimizer or code generator crashes, ``bugpoint`` will try as hard as it
+can to reduce the list of passes (for optimizer crashes) and the size of the
+test program. First, ``bugpoint`` figures out which combination of optimizer
+passes triggers the bug. This is useful when debugging a problem exposed by
+``opt``, for example, because it runs over 38 passes.
+
+Next, ``bugpoint`` tries removing functions from the test program, to reduce its
+size. Usually it is able to reduce a test program to a single function, when
+debugging intraprocedural optimizations. Once the number of functions has been
+reduced, it attempts to delete various edges in the control flow graph, to
+reduce the size of the function as much as possible. Finally, ``bugpoint``
+deletes any individual LLVM instructions whose absence does not eliminate the
+failure. At the end, ``bugpoint`` should tell you what passes crash, give you a
+bitcode file, and give you instructions on how to reproduce the failure with
+``opt`` or ``llc``.
+
+.. _code generator debugger:
+
+Code generator debugger
+-----------------------
+
+The code generator debugger attempts to narrow down the amount of code that is
+being miscompiled by the selected code generator. To do this, it takes the test
+program and partitions it into two pieces: one piece which it compiles with the
+"safe" backend (into a shared object), and one piece which it runs with either
+the JIT or the static LLC compiler. It uses several techniques to reduce the
+amount of code pushed through the LLVM code generator, to reduce the potential
+scope of the problem. After it is finished, it emits two bitcode files (called
+"test" [to be compiled with the code generator] and "safe" [to be compiled with
+the "safe" backend], respectively), and instructions for reproducing the
+problem. The code generator debugger assumes that the "safe" backend produces
+good code.
+
+.. _miscompilation debugger:
+
+Miscompilation debugger
+-----------------------
+
+The miscompilation debugger works similarly to the code generator debugger. It
+works by splitting the test program into two pieces, running the optimizations
+specified on one piece, linking the two pieces back together, and then executing
+the result. It attempts to narrow down the list of passes to the one (or few)
+which are causing the miscompilation, then reduce the portion of the test
+program which is being miscompiled. The miscompilation debugger assumes that
+the selected code generator is working properly.
+
+Advice for using bugpoint
+=========================
+
+``bugpoint`` can be a remarkably useful tool, but it sometimes works in
+non-obvious ways. Here are some hints and tips:
+
+* In the code generator and miscompilation debuggers, ``bugpoint`` only works
+ with programs that have deterministic output. Thus, if the program outputs
+ ``argv[0]``, the date, time, or any other "random" data, ``bugpoint`` may
+ misinterpret differences in these data, when output, as the result of a
+ miscompilation. Programs should be temporarily modified to disable outputs
+ that are likely to vary from run to run.
+
+* In the code generator and miscompilation debuggers, debugging will go faster
+ if you manually modify the program or its inputs to reduce the runtime, but
+ still exhibit the problem.
+
+* ``bugpoint`` is extremely useful when working on a new optimization: it helps
+ track down regressions quickly. To avoid having to relink ``bugpoint`` every
+ time you change your optimization however, have ``bugpoint`` dynamically load
+ your optimization with the ``-load`` option.
+
+* ``bugpoint`` can generate a lot of output and run for a long period of time.
+ It is often useful to capture the output of the program to file. For example,
+ in the C shell, you can run:
+
+ .. code-block:: console
+
+ $ bugpoint ... |& tee bugpoint.log
+
+ to get a copy of ``bugpoint``'s output in the file ``bugpoint.log``, as well
+ as on your terminal.
+
+* ``bugpoint`` cannot debug problems with the LLVM linker. If ``bugpoint``
+ crashes before you see its "All input ok" message, you might try ``llvm-link
+ -v`` on the same set of input files. If that also crashes, you may be
+ experiencing a linker bug.
+
+* ``bugpoint`` is useful for proactively finding bugs in LLVM. Invoking
+ ``bugpoint`` with the ``-find-bugs`` option will cause the list of specified
+ optimizations to be randomized and applied to the program. This process will
+ repeat until a bug is found or the user kills ``bugpoint``.
+
+What to do when bugpoint isn't enough
+=====================================
+
+Sometimes, ``bugpoint`` is not enough. In particular, InstCombine and
+TargetLowering both have visitor structured code with lots of potential
+transformations. If the process of using bugpoint has left you with still too
+much code to figure out and the problem seems to be in instcombine, the
+following steps may help. These same techniques are useful with TargetLowering
+as well.
+
+Turn on ``-debug-only=instcombine`` and see which transformations within
+instcombine are firing by selecting out lines with "``IC``" in them.
+
+At this point, you have a decision to make. Is the number of transformations
+small enough to step through them using a debugger? If so, then try that.
+
+If there are too many transformations, then a source modification approach may
+be helpful. In this approach, you can modify the source code of instcombine to
+disable just those transformations that are being performed on your test input
+and perform a binary search over the set of transformations. One set of places
+to modify are the "``visit*``" methods of ``InstCombiner`` (*e.g.*
+``visitICmpInst``) by adding a "``return false``" as the first line of the
+method.
+
+If that still doesn't remove enough, then change the caller of
+``InstCombiner::DoOneIteration``, ``InstCombiner::runOnFunction`` to limit the
+number of iterations.
+
+You may also find it useful to use "``-stats``" now to see what parts of
+instcombine are firing. This can guide where to put additional reporting code.
+
+At this point, if the amount of transformations is still too large, then
+inserting code to limit whether or not to execute the body of the code in the
+visit function can be helpful. Add a static counter which is incremented on
+every invocation of the function. Then add code which simply returns false on
+desired ranges. For example:
+
+.. code-block:: c++
+
+
+ static int calledCount = 0;
+ calledCount++;
+ DEBUG(if (calledCount < 212) return false);
+ DEBUG(if (calledCount > 217) return false);
+ DEBUG(if (calledCount == 213) return false);
+ DEBUG(if (calledCount == 214) return false);
+ DEBUG(if (calledCount == 215) return false);
+ DEBUG(if (calledCount == 216) return false);
+ DEBUG(dbgs() << "visitXOR calledCount: " << calledCount << "\n");
+ DEBUG(dbgs() << "I: "; I->dump());
+
+could be added to ``visitXOR`` to limit ``visitXor`` to being applied only to
+calls 212 and 217. This is from an actual test case and raises an important
+point---a simple binary search may not be sufficient, as transformations that
+interact may require isolating more than one call. In TargetLowering, use
+``return SDNode();`` instead of ``return false;``.
+
+Now that the number of transformations is down to a manageable number, try
+examining the output to see if you can figure out which transformations are
+being done. If that can be figured out, then do the usual debugging. If which
+code corresponds to the transformation being performed isn't obvious, set a
+breakpoint after the call count based disabling and step through the code.
+Alternatively, you can use "``printf``" style debugging to report waypoints.
Added: www-releases/trunk/3.7.1/docs/_sources/BuildingLLVMWithAutotools.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/BuildingLLVMWithAutotools.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/BuildingLLVMWithAutotools.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/BuildingLLVMWithAutotools.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,332 @@
+====================================
+Building LLVM With Autotools
+====================================
+
+.. contents::
+ :local:
+
+Overview
+========
+
+This document details how to use the LLVM autotools based build system to
+configure and build LLVM from source. The normal developer process using CMake
+is detailed `here <GettingStarted.html#check-here>`_.
+
+A Quick Summary
+---------------
+
+#. Configure and build LLVM and Clang:
+
+ * ``cd where-you-want-to-build-llvm``
+ * ``mkdir build`` (for building without polluting the source dir)
+ * ``cd build``
+ * ``../llvm/configure [options]``
+ Some common options:
+
+ * ``--prefix=directory`` --- Specify for *directory* the full pathname of
+ where you want the LLVM tools and libraries to be installed (default
+ ``/usr/local``).
+
+ * ``--enable-optimized`` --- Compile with optimizations enabled (default
+ is NO).
+
+ * ``--enable-assertions`` --- Compile with assertion checks enabled
+ (default is YES).
+
+ * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run
+ simultaneously. This builds both LLVM and Clang for Debug+Asserts mode.
+ The ``--enable-optimized`` configure option is used to specify a Release
+ build.
+
+ * ``make check-all`` --- This run the regression tests to ensure everything
+ is in working order.
+
+ * If you get an "internal compiler error (ICE)" or test failures, see
+ `here <GettingStarted.html#check-here>`_.
+
+Local LLVM Configuration
+------------------------
+
+Once checked out from the Subversion repository, the LLVM suite source code must
+be configured via the ``configure`` script. This script sets variables in the
+various ``*.in`` files, most notably ``llvm/Makefile.config`` and
+``llvm/include/Config/config.h``. It also populates *OBJ_ROOT* with the
+Makefiles needed to begin building LLVM.
+
+The following environment variables are used by the ``configure`` script to
+configure the build system:
+
++------------+-----------------------------------------------------------+
+| Variable | Purpose |
++============+===========================================================+
+| CC | Tells ``configure`` which C compiler to use. By default, |
+| | ``configure`` will check ``PATH`` for ``clang`` and GCC C |
+| | compilers (in this order). Use this variable to override |
+| | ``configure``\'s default behavior. |
++------------+-----------------------------------------------------------+
+| CXX | Tells ``configure`` which C++ compiler to use. By |
+| | default, ``configure`` will check ``PATH`` for |
+| | ``clang++`` and GCC C++ compilers (in this order). Use |
+| | this variable to override ``configure``'s default |
+| | behavior. |
++------------+-----------------------------------------------------------+
+
+The following options can be used to set or enable LLVM specific options:
+
+``--enable-optimized``
+
+ Enables optimized compilation (debugging symbols are removed and GCC
+ optimization flags are enabled). Note that this is the default setting if you
+ are using the LLVM distribution. The default behavior of a Subversion
+ checkout is to use an unoptimized build (also known as a debug build).
+
+``--enable-debug-runtime``
+
+ Enables debug symbols in the runtime libraries. The default is to strip debug
+ symbols from the runtime libraries.
+
+``--enable-jit``
+
+ Compile the Just In Time (JIT) compiler functionality. This is not available
+ on all platforms. The default is dependent on platform, so it is best to
+ explicitly enable it if you want it.
+
+``--enable-targets=target-option``
+
+ Controls which targets will be built and linked into llc. The default value
+ for ``target_options`` is "all" which builds and links all available targets.
+ The "host" target is selected as the target of the build host. You can also
+ specify a comma separated list of target names that you want available in llc.
+ The target names use all lower case. The current set of targets is:
+
+ ``aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430,
+ powerpc, nvptx, r600, sparc, systemz, x86, x86_64, xcore``.
+
+``--enable-doxygen``
+
+ Look for the doxygen program and enable construction of doxygen based
+ documentation from the source code. This is disabled by default because
+ generating the documentation can take a long time and producess 100s of
+ megabytes of output.
+
+To configure LLVM, follow these steps:
+
+#. Change directory into the object root directory:
+
+ .. code-block:: console
+
+ % cd OBJ_ROOT
+
+#. Run the ``configure`` script located in the LLVM source tree:
+
+ .. code-block:: console
+
+ % $LLVM_SRC_DIR/configure --prefix=/install/path [other options]
+
+Compiling the LLVM Suite Source Code
+------------------------------------
+
+Once you have configured LLVM, you can build it. There are three types of
+builds:
+
+Debug Builds
+
+ These builds are the default when one is using a Subversion checkout and
+ types ``gmake`` (unless the ``--enable-optimized`` option was used during
+ configuration). The build system will compile the tools and libraries with
+ debugging information. To get a Debug Build using the LLVM distribution the
+ ``--disable-optimized`` option must be passed to ``configure``.
+
+Release (Optimized) Builds
+
+ These builds are enabled with the ``--enable-optimized`` option to
+ ``configure`` or by specifying ``ENABLE_OPTIMIZED=1`` on the ``gmake`` command
+ line. For these builds, the build system will compile the tools and libraries
+ with GCC optimizations enabled and strip debugging information from the
+ libraries and executables it generates. Note that Release Builds are default
+ when using an LLVM distribution.
+
+Profile Builds
+
+ These builds are for use with profiling. They compile profiling information
+ into the code for use with programs like ``gprof``. Profile builds must be
+ started by specifying ``ENABLE_PROFILING=1`` on the ``gmake`` command line.
+
+Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
+directory and issuing the following command:
+
+.. code-block:: console
+
+ % gmake
+
+If the build fails, please `check here <GettingStarted.html#check-here>`_
+to see if you are using a version of GCC that is known not to compile LLVM.
+
+If you have multiple processors in your machine, you may wish to use some of the
+parallel build options provided by GNU Make. For example, you could use the
+command:
+
+.. code-block:: console
+
+ % gmake -j2
+
+There are several special targets which are useful when working with the LLVM
+source code:
+
+``gmake clean``
+
+ Removes all files generated by the build. This includes object files,
+ generated C/C++ files, libraries, and executables.
+
+``gmake dist-clean``
+
+ Removes everything that ``gmake clean`` does, but also removes files generated
+ by ``configure``. It attempts to return the source tree to the original state
+ in which it was shipped.
+
+``gmake install``
+
+ Installs LLVM header files, libraries, tools, and documentation in a hierarchy
+ under ``$PREFIX``, specified with ``$LLVM_SRC_DIR/configure --prefix=[dir]``, which
+ defaults to ``/usr/local``.
+
+``gmake -C runtime install-bytecode``
+
+ Assuming you built LLVM into $OBJDIR, when this command is run, it will
+ install bitcode libraries into the GCC front end's bitcode library directory.
+ If you need to update your bitcode libraries, this is the target to use once
+ you've built them.
+
+Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on
+these ``make`` targets and descriptions of other targets available.
+
+It is also possible to override default values from ``configure`` by declaring
+variables on the command line. The following are some examples:
+
+``gmake ENABLE_OPTIMIZED=1``
+
+ Perform a Release (Optimized) build.
+
+``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1``
+
+ Perform a Release (Optimized) build without assertions enabled.
+
+``gmake ENABLE_OPTIMIZED=0``
+
+ Perform a Debug build.
+
+``gmake ENABLE_PROFILING=1``
+
+ Perform a Profiling build.
+
+``gmake VERBOSE=1``
+
+ Print what ``gmake`` is doing on standard output.
+
+``gmake TOOL_VERBOSE=1``
+
+ Ask each tool invoked by the makefiles to print out what it is doing on
+ the standard output. This also implies ``VERBOSE=1``.
+
+Every directory in the LLVM object tree includes a ``Makefile`` to build it and
+any subdirectories that it contains. Entering any directory inside the LLVM
+object tree and typing ``gmake`` should rebuild anything in or below that
+directory that is out of date.
+
+This does not apply to building the documentation.
+LLVM's (non-Doxygen) documentation is produced with the
+`Sphinx <http://sphinx-doc.org/>`_ documentation generation system.
+There are some HTML documents that have not yet been converted to the new
+system (which uses the easy-to-read and easy-to-write
+`reStructuredText <http://sphinx-doc.org/rest.html>`_ plaintext markup
+language).
+The generated documentation is built in the ``$LLVM_SRC_DIR/docs`` directory using
+a special makefile.
+For instructions on how to install Sphinx, see
+`Sphinx Introduction for LLVM Developers
+<http://lld.llvm.org/sphinx_intro.html>`_.
+After following the instructions there for installing Sphinx, build the LLVM
+HTML documentation by doing the following:
+
+.. code-block:: console
+
+ $ cd $LLVM_SRC_DIR/docs
+ $ make -f Makefile.sphinx
+
+This creates a ``_build/html`` sub-directory with all of the HTML files, not
+just the generated ones.
+This directory corresponds to ``llvm.org/docs``.
+For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to
+``llvm.org/docs/SphinxQuickstartTemplate.html``.
+The :doc:`SphinxQuickstartTemplate` is useful when creating a new document.
+
+Cross-Compiling LLVM
+--------------------
+
+It is possible to cross-compile LLVM itself. That is, you can create LLVM
+executables and libraries to be hosted on a platform different from the platform
+where they are built (a Canadian Cross build). To configure a cross-compile,
+supply the configure script with ``--build`` and ``--host`` options that are
+different. The values of these options must be legal target triples that your
+GCC compiler supports.
+
+The result of such a build is executables that are not runnable on on the build
+host (--build option) but can be executed on the compile host (--host option).
+
+Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general
+<http://clang.llvm.org/docs/CrossCompilation.html>`_ for more information
+about cross-compiling.
+
+The Location of LLVM Object Files
+---------------------------------
+
+The LLVM build system is capable of sharing a single LLVM source tree among
+several LLVM builds. Hence, it is possible to build LLVM for several different
+platforms or configurations using the same source tree.
+
+This is accomplished in the typical autoconf manner:
+
+* Change directory to where the LLVM object files should live:
+
+ .. code-block:: console
+
+ % cd OBJ_ROOT
+
+* Run the ``configure`` script found in the LLVM source directory:
+
+ .. code-block:: console
+
+ % $LLVM_SRC_DIR/configure
+
+The LLVM build will place files underneath *OBJ_ROOT* in directories named after
+the build type:
+
+Debug Builds with assertions enabled (the default)
+
+ Tools
+
+ ``OBJ_ROOT/Debug+Asserts/bin``
+
+ Libraries
+
+ ``OBJ_ROOT/Debug+Asserts/lib``
+
+Release Builds
+
+ Tools
+
+ ``OBJ_ROOT/Release/bin``
+
+ Libraries
+
+ ``OBJ_ROOT/Release/lib``
+
+Profile Builds
+
+ Tools
+
+ ``OBJ_ROOT/Profile/bin``
+
+ Libraries
+
+ ``OBJ_ROOT/Profile/lib``
Added: www-releases/trunk/3.7.1/docs/_sources/CMake.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/CMake.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/CMake.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/CMake.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,623 @@
+========================
+Building LLVM with CMake
+========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+`CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
+does not build the project, it generates the files needed by your build tool
+(GNU make, Visual Studio, etc) for building LLVM.
+
+If you are really anxious about getting a functional LLVM build, go to the
+`Quick start`_ section. If you are a CMake novice, start on `Basic CMake usage`_
+and then go back to the `Quick start`_ once you know what you are doing. The
+`Options and variables`_ section is a reference for customizing your build. If
+you already have experience with CMake, this is the recommended starting point.
+
+.. _Quick start:
+
+Quick start
+===========
+
+We use here the command-line, non-interactive CMake interface.
+
+#. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install
+ CMake. Version 2.8.8 is the minimum required.
+
+#. Open a shell. Your development tools must be reachable from this shell
+ through the PATH environment variable.
+
+#. Create a directory for containing the build. It is not supported to build
+ LLVM on the source directory. cd to this directory:
+
+ .. code-block:: console
+
+ $ mkdir mybuilddir
+ $ cd mybuilddir
+
+#. Execute this command on the shell replacing `path/to/llvm/source/root` with
+ the path to the root of your LLVM source tree:
+
+ .. code-block:: console
+
+ $ cmake path/to/llvm/source/root
+
+ CMake will detect your development environment, perform a series of test and
+ generate the files required for building LLVM. CMake will use default values
+ for all build parameters. See the `Options and variables`_ section for
+ fine-tuning your build
+
+ This can fail if CMake can't detect your toolset, or if it thinks that the
+ environment is not sane enough. On this case make sure that the toolset that
+ you intend to use is the only one reachable from the shell and that the shell
+ itself is the correct one for you development environment. CMake will refuse
+ to build MinGW makefiles if you have a POSIX shell reachable through the PATH
+ environment variable, for instance. You can force CMake to use a given build
+ tool, see the `Usage`_ section.
+
+#. After CMake has finished running, proceed to use IDE project files or start
+ the build from the build directory:
+
+ .. code-block:: console
+
+ $ cmake --build .
+
+ The ``--build`` option tells ``cmake`` to invoke the underlying build
+ tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc).
+
+ The underlying build tool can be invoked directly either of course, but
+ the ``--build`` option is portable.
+
+#. After LLVM has finished building, install it from the build directory:
+
+ .. code-block:: console
+
+ $ cmake --build . --target install
+
+ The ``--target`` option with ``install`` parameter in addition to
+ the ``--build`` option tells ``cmake`` to build the ``install`` target.
+
+ It is possible to set a different install prefix at installation time
+ by invoking the ``cmake_install.cmake`` script generated in the
+ build directory:
+
+ .. code-block:: console
+
+ $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
+
+.. _Basic CMake usage:
+.. _Usage:
+
+Basic CMake usage
+=================
+
+This section explains basic aspects of CMake, mostly for explaining those
+options which you may need on your day-to-day usage.
+
+CMake comes with extensive documentation in the form of html files and on the
+cmake executable itself. Execute ``cmake --help`` for further help options.
+
+CMake requires to know for which build tool it shall generate files (GNU make,
+Visual Studio, Xcode, etc). If not specified on the command line, it tries to
+guess it based on you environment. Once identified the build tool, CMake uses
+the corresponding *Generator* for creating files for your build tool. You can
+explicitly specify the generator with the command line option ``-G "Name of the
+generator"``. For knowing the available generators on your platform, execute
+
+.. code-block:: console
+
+ $ cmake --help
+
+This will list the generator's names at the end of the help text. Generator's
+names are case-sensitive. Example:
+
+.. code-block:: console
+
+ $ cmake -G "Visual Studio 11" path/to/llvm/source/root
+
+For a given development platform there can be more than one adequate
+generator. If you use Visual Studio "NMake Makefiles" is a generator you can use
+for building with NMake. By default, CMake chooses the more specific generator
+supported by your development environment. If you want an alternative generator,
+you must tell this to CMake with the ``-G`` option.
+
+.. todo::
+
+ Explain variables and cache. Move explanation here from #options section.
+
+.. _Options and variables:
+
+Options and variables
+=====================
+
+Variables customize how the build will be generated. Options are boolean
+variables, with possible values ON/OFF. Options and variables are defined on the
+CMake command line like this:
+
+.. code-block:: console
+
+ $ cmake -DVARIABLE=value path/to/llvm/source
+
+You can set a variable after the initial CMake invocation for changing its
+value. You can also undefine a variable:
+
+.. code-block:: console
+
+ $ cmake -UVARIABLE path/to/llvm/source
+
+Variables are stored on the CMake cache. This is a file named ``CMakeCache.txt``
+on the root of the build directory. Do not hand-edit it.
+
+Variables are listed here appending its type after a colon. It is correct to
+write the variable and the type on the CMake command line:
+
+.. code-block:: console
+
+ $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
+
+Frequently-used CMake variables
+-------------------------------
+
+Here are some of the CMake variables that are used often, along with a
+brief explanation and LLVM-specific notes. For full documentation, check the
+CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
+
+**CMAKE_BUILD_TYPE**:STRING
+ Sets the build type for ``make`` based generators. Possible values are
+ Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
+ the user sets the build type with the IDE settings.
+
+**CMAKE_INSTALL_PREFIX**:PATH
+ Path where LLVM will be installed if "make install" is invoked or the
+ "INSTALL" target is built.
+
+**LLVM_LIBDIR_SUFFIX**:STRING
+ Extra suffix to append to the directory where libraries are to be
+ installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
+ to install libraries to ``/usr/lib64``.
+
+**CMAKE_C_FLAGS**:STRING
+ Extra flags to use when compiling C source files.
+
+**CMAKE_CXX_FLAGS**:STRING
+ Extra flags to use when compiling C++ source files.
+
+**BUILD_SHARED_LIBS**:BOOL
+ Flag indicating if shared libraries will be built. Its default value is
+ OFF. Shared libraries are not supported on Windows and not recommended on the
+ other OSes.
+
+.. _LLVM-specific variables:
+
+LLVM-specific variables
+-----------------------
+
+**LLVM_TARGETS_TO_BUILD**:STRING
+ Semicolon-separated list of targets to build, or *all* for building all
+ targets. Case-sensitive. Defaults to *all*. Example:
+ ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
+
+**LLVM_BUILD_TOOLS**:BOOL
+ Build LLVM tools. Defaults to ON. Targets for building each tool are generated
+ in any case. You can build an tool separately by invoking its target. For
+ example, you can build *llvm-as* with a makefile-based system executing *make
+ llvm-as* on the root of your build directory.
+
+**LLVM_INCLUDE_TOOLS**:BOOL
+ Generate build targets for the LLVM tools. Defaults to ON. You can use that
+ option for disabling the generation of build targets for the LLVM tools.
+
+**LLVM_BUILD_EXAMPLES**:BOOL
+ Build LLVM examples. Defaults to OFF. Targets for building each example are
+ generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more
+ details.
+
+**LLVM_INCLUDE_EXAMPLES**:BOOL
+ Generate build targets for the LLVM examples. Defaults to ON. You can use that
+ option for disabling the generation of build targets for the LLVM examples.
+
+**LLVM_BUILD_TESTS**:BOOL
+ Build LLVM unit tests. Defaults to OFF. Targets for building each unit test
+ are generated in any case. You can build a specific unit test with the target
+ *UnitTestNameTests* (where at this time *UnitTestName* can be ADT, Analysis,
+ ExecutionEngine, JIT, Support, Transform, VMCore; see the subdirectories of
+ *unittests* for an updated list.) It is possible to build all unit tests with
+ the target *UnitTests*.
+
+**LLVM_INCLUDE_TESTS**:BOOL
+ Generate build targets for the LLVM unit tests. Defaults to ON. You can use
+ that option for disabling the generation of build targets for the LLVM unit
+ tests.
+
+**LLVM_APPEND_VC_REV**:BOOL
+ Append version control revision info (svn revision number or Git revision id)
+ to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work
+ cmake must be invoked before the build. Defaults to OFF.
+
+**LLVM_ENABLE_THREADS**:BOOL
+ Build with threads support, if available. Defaults to ON.
+
+**LLVM_ENABLE_CXX1Y**:BOOL
+ Build in C++1y mode, if available. Defaults to OFF.
+
+**LLVM_ENABLE_ASSERTIONS**:BOOL
+ Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
+ is *Debug*.
+
+**LLVM_ENABLE_EH**:BOOL
+ Build LLVM with exception handling support. This is necessary if you wish to
+ link against LLVM libraries and make use of C++ exceptions in your own code
+ that need to propagate through LLVM code. Defaults to OFF.
+
+**LLVM_ENABLE_PIC**:BOOL
+ Add the ``-fPIC`` flag for the compiler command-line, if the compiler supports
+ this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
+
+**LLVM_ENABLE_RTTI**:BOOL
+ Build LLVM with run time type information. Defaults to OFF.
+
+**LLVM_ENABLE_WARNINGS**:BOOL
+ Enable all compiler warnings. Defaults to ON.
+
+**LLVM_ENABLE_PEDANTIC**:BOOL
+ Enable pedantic mode. This disables compiler specific extensions, if
+ possible. Defaults to ON.
+
+**LLVM_ENABLE_WERROR**:BOOL
+ Stop and fail build, if a compiler warning is triggered. Defaults to OFF.
+
+**LLVM_ABI_BREAKING_CHECKS**:STRING
+ Used to decide if LLVM should be built with ABI breaking checks or
+ not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
+ `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an
+ assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on
+ (off) irrespective of whether normal (`NDEBUG` based) assertions are
+ enabled or not. A version of LLVM built with ABI breaking checks
+ is not ABI compatible with a version built without it.
+
+**LLVM_BUILD_32_BITS**:BOOL
+ Build 32-bits executables and libraries on 64-bits systems. This option is
+ available only on some 64-bits unix systems. Defaults to OFF.
+
+**LLVM_TARGET_ARCH**:STRING
+ LLVM target to use for native code generation. This is required for JIT
+ generation. It defaults to "host", meaning that it shall pick the architecture
+ of the machine where LLVM is being built. If you are cross-compiling, set it
+ to the target architecture name.
+
+**LLVM_TABLEGEN**:STRING
+ Full path to a native TableGen executable (usually named ``tblgen``). This is
+ intended for cross-compiling: if the user sets this variable, no native
+ TableGen will be created.
+
+**LLVM_LIT_ARGS**:STRING
+ Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
+ By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
+ others.
+
+**LLVM_LIT_TOOLS_DIR**:PATH
+ The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to "",
+ then Lit seeks tools according to %PATH%. Lit can find tools(eg. grep, sort,
+ &c) on LLVM_LIT_TOOLS_DIR at first, without specifying GnuWin32 to %PATH%.
+
+**LLVM_ENABLE_FFI**:BOOL
+ Indicates whether LLVM Interpreter will be linked with Foreign Function
+ Interface library. If the library or its headers are installed on a custom
+ location, you can set the variables FFI_INCLUDE_DIR and
+ FFI_LIBRARY_DIR. Defaults to OFF.
+
+**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
+ Path to ``{Clang,lld,Polly}``\'s source directory. Defaults to
+ ``tools/{clang,lld,polly}``. ``{Clang,lld,Polly}`` will not be built when it
+ is empty or it does not point to a valid path.
+
+**LLVM_USE_OPROFILE**:BOOL
+ Enable building OProfile JIT support. Defaults to OFF
+
+**LLVM_USE_INTEL_JITEVENTS**:BOOL
+ Enable building support for Intel JIT Events API. Defaults to OFF
+
+**LLVM_ENABLE_ZLIB**:BOOL
+ Build with zlib to support compression/uncompression in LLVM tools.
+ Defaults to ON.
+
+**LLVM_USE_SANITIZER**:STRING
+ Define the sanitizer used to build LLVM binaries and tests. Possible values
+ are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,
+ and ``Address;Undefined``. Defaults to empty string.
+
+**LLVM_PARALLEL_COMPILE_JOBS**:STRING
+ Define the maximum number of concurrent compilation jobs.
+
+**LLVM_PARALLEL_LINK_JOBS**:STRING
+ Define the maximum number of concurrent link jobs.
+
+**LLVM_BUILD_DOCS**:BOOL
+ Enables all enabled documentation targets (i.e. Doxgyen and Sphinx targets) to
+ be built as part of the normal build. If the ``install`` target is run then
+ this also enables all built documentation targets to be installed. Defaults to
+ OFF.
+
+**LLVM_ENABLE_DOXYGEN**:BOOL
+ Enables the generation of browsable HTML documentation using doxygen.
+ Defaults to OFF.
+
+**LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL
+ Enables the generation of a Qt Compressed Help file. Defaults to OFF.
+ This affects the make target ``doxygen-llvm``. When enabled, apart from
+ the normal HTML output generated by doxygen, this will produce a QCH file
+ named ``org.llvm.qch``. You can then load this file into Qt Creator.
+ This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
+ otherwise this has no effect.
+
+**LLVM_DOXYGEN_QCH_FILENAME**:STRING
+ The filename of the Qt Compressed Help file that will be generated when
+ ``-DLLVM_ENABLE_DOXYGEN=ON`` and
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
+ ``org.llvm.qch``.
+ This option is only useful in combination with
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
+ otherwise this has no effect.
+
+**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
+ Namespace under which the intermediate Qt Help Project file lives. See `Qt
+ Help Project`_
+ for more information. Defaults to "org.llvm". This option is only useful in
+ combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
+ this has no effect.
+
+**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
+ See `Qt Help Project`_ for
+ more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
+ is a combination of the package name and version string. This filter can then
+ be used in Qt Creator to select only documentation from LLVM when browsing
+ through all the help files that you might have loaded. This option is only
+ useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
+ otherwise this has no effect.
+
+.. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
+
+**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
+ The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
+ ``find_program()`` can find. This option is only useful in combination with
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise this has no
+ effect.
+
+**LLVM_DOXYGEN_SVG**:BOOL
+ Uses .svg files instead of .png files for graphs in the Doxygen output.
+ Defaults to OFF.
+
+**LLVM_ENABLE_SPHINX**:BOOL
+ If enabled CMake will search for the ``sphinx-build`` executable and will make
+ the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
+ Defaults to OFF.
+
+**SPHINX_EXECUTABLE**:STRING
+ The path to the ``sphinx-build`` executable detected by CMake.
+
+**SPHINX_OUTPUT_HTML**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for
+ building the documentation as html are added (but not built by default unless
+ ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the
+ source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
+ and ``docs-lld-html``). Defaults to ON.
+
+**SPHINX_OUTPUT_MAN**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building
+ the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``
+ is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
+ to ON.
+
+**SPHINX_WARNINGS_AS_ERRORS**:BOOL
+ If enabled then sphinx documentation warnings will be treated as
+ errors. Defaults to ON.
+
+Executing the test suite
+========================
+
+Testing is performed when the *check* target is built. For instance, if you are
+using makefiles, execute this command while on the top level of your build
+directory:
+
+.. code-block:: console
+
+ $ make check
+
+On Visual Studio, you may run tests to build the project "check".
+
+Cross compiling
+===============
+
+See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for
+generic instructions on how to cross-compile with CMake. It goes into detailed
+explanations and may seem daunting, but it is not. On the wiki page there are
+several examples including toolchain files. Go directly to `this section
+<http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains>`_
+for a quick solution.
+
+Also see the `LLVM-specific variables`_ section for variables used when
+cross-compiling.
+
+Embedding LLVM in your project
+==============================
+
+From LLVM 3.5 onwards both the CMake and autoconf/Makefile build systems export
+LLVM libraries as importable CMake targets. This means that clients of LLVM can
+now reliably use CMake to develop their own LLVM based projects against an
+installed version of LLVM regardless of how it was built.
+
+Here is a simple example of CMakeLists.txt file that imports the LLVM libraries
+and uses them to build a simple application ``simple-tool``.
+
+.. code-block:: cmake
+
+ cmake_minimum_required(VERSION 2.8.8)
+ project(SimpleProject)
+
+ find_package(LLVM REQUIRED CONFIG)
+
+ message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
+ message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
+
+ # Set your project compile flags.
+ # E.g. if using the C++ header files
+ # you will need to enable C++11 support
+ # for your compiler.
+
+ include_directories(${LLVM_INCLUDE_DIRS})
+ add_definitions(${LLVM_DEFINITIONS})
+
+ # Now build our tools
+ add_executable(simple-tool tool.cpp)
+
+ # Find the libraries that correspond to the LLVM components
+ # that we wish to use
+ llvm_map_components_to_libnames(llvm_libs support core irreader)
+
+ # Link against LLVM libraries
+ target_link_libraries(simple-tool ${llvm_libs})
+
+The ``find_package(...)`` directive when used in CONFIG mode (as in the above
+example) will look for the ``LLVMConfig.cmake`` file in various locations (see
+cmake manual for details). It creates a ``LLVM_DIR`` cache entry to save the
+directory where ``LLVMConfig.cmake`` is found or allows the user to specify the
+directory (e.g. by passing ``-DLLVM_DIR=/usr/share/llvm/cmake`` to
+the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
+
+This file is available in two different locations.
+
+* ``<INSTALL_PREFIX>/share/llvm/cmake/LLVMConfig.cmake`` where
+ ``<INSTALL_PREFIX>`` is the install prefix of an installed version of LLVM.
+ On Linux typically this is ``/usr/share/llvm/cmake/LLVMConfig.cmake``.
+
+* ``<LLVM_BUILD_ROOT>/share/llvm/cmake/LLVMConfig.cmake`` where
+ ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note this only
+ available when building LLVM with CMake**
+
+If LLVM is installed in your operating system's normal installation prefix (e.g.
+on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
+automatically find LLVM if it is installed correctly. If LLVM is not installed
+or you wish to build directly against the LLVM build tree you can use
+``LLVM_DIR`` as previously mentioned.
+
+The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables
+include
+
+``LLVM_CMAKE_DIR``
+ The path to the LLVM CMake directory (i.e. the directory containing
+ LLVMConfig.cmake).
+
+``LLVM_DEFINITIONS``
+ A list of preprocessor defines that should be used when building against LLVM.
+
+``LLVM_ENABLE_ASSERTIONS``
+ This is set to ON if LLVM was built with assertions, otherwise OFF.
+
+``LLVM_ENABLE_EH``
+ This is set to ON if LLVM was built with exception handling (EH) enabled,
+ otherwise OFF.
+
+``LLVM_ENABLE_RTTI``
+ This is set to ON if LLVM was built with run time type information (RTTI),
+ otherwise OFF.
+
+``LLVM_INCLUDE_DIRS``
+ A list of include paths to directories containing LLVM header files.
+
+``LLVM_PACKAGE_VERSION``
+ The LLVM version. This string can be used with CMake conditionals. E.g. ``if
+ (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.
+
+``LLVM_TOOLS_BINARY_DIR``
+ The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
+
+Notice that in the above example we link ``simple-tool`` against several LLVM
+libraries. The list of libraries is determined by using the
+``llvm_map_components_to_libnames()`` CMake function. For a list of available
+components look at the output of running ``llvm-config --components``.
+
+Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was
+used instead of ``llvm_map_components_to_libnames()``. This is now deprecated
+and will be removed in a future version of LLVM.
+
+.. _cmake-out-of-source-pass:
+
+Developing LLVM passes out of source
+------------------------------------
+
+It is possible to develop LLVM passes out of LLVM's source tree (i.e. against an
+installed or built LLVM). An example of a project layout is provided below.
+
+.. code-block:: none
+
+ <project dir>/
+ |
+ CMakeLists.txt
+ <pass name>/
+ |
+ CMakeLists.txt
+ Pass.cpp
+ ...
+
+Contents of ``<project dir>/CMakeLists.txt``:
+
+.. code-block:: cmake
+
+ find_package(LLVM REQUIRED CONFIG)
+
+ add_definitions(${LLVM_DEFINITIONS})
+ include_directories(${LLVM_INCLUDE_DIRS})
+
+ add_subdirectory(<pass name>)
+
+Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
+
+.. code-block:: cmake
+
+ add_library(LLVMPassname MODULE Pass.cpp)
+
+Note if you intend for this pass to be merged into the LLVM source tree at some
+point in the future it might make more sense to use LLVM's internal
+add_llvm_loadable_module function instead by...
+
+
+Adding the following to ``<project dir>/CMakeLists.txt`` (after
+``find_package(LLVM ...)``)
+
+.. code-block:: cmake
+
+ list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
+ include(AddLLVM)
+
+And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to
+
+.. code-block:: cmake
+
+ add_llvm_loadable_module(LLVMPassname
+ Pass.cpp
+ )
+
+When you are done developing your pass, you may wish to integrate it
+into LLVM source tree. You can achieve it in two easy steps:
+
+#. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory.
+
+#. Adding ``add_subdirectory(<pass name>)`` line into
+ ``<LLVM root>/lib/Transform/CMakeLists.txt``.
+
+Compiler/Platform-specific topics
+=================================
+
+Notes for specific compilers and/or platforms.
+
+Microsoft Visual C++
+--------------------
+
+**LLVM_COMPILER_JOBS**:STRING
+ Specifies the maximum number of parallell compiler jobs to use per project
+ when building with msbuild or Visual Studio. Only supported for the Visual
+ Studio 2010 CMake generator. 0 means use all processors. Default is 0.
Added: www-releases/trunk/3.7.1/docs/_sources/CodeGenerator.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.1/docs/_sources/CodeGenerator.txt?rev=257950&view=auto
==============================================================================
--- www-releases/trunk/3.7.1/docs/_sources/CodeGenerator.txt (added)
+++ www-releases/trunk/3.7.1/docs/_sources/CodeGenerator.txt Fri Jan 15 17:13:16 2016
@@ -0,0 +1,2647 @@
+==========================================
+The LLVM Target-Independent Code Generator
+==========================================
+
+.. role:: raw-html(raw)
+ :format: html
+
+.. raw:: html
+
+ <style>
+ .unknown { background-color: #C0C0C0; text-align: center; }
+ .unknown:before { content: "?" }
+ .no { background-color: #C11B17 }
+ .no:before { content: "N" }
+ .partial { background-color: #F88017 }
+ .yes { background-color: #0F0; }
+ .yes:before { content: "Y" }
+ .na { background-color: #6666FF; }
+ .na:before { content: "N/A" }
+ </style>
+
+.. contents::
+ :local:
+
+.. warning::
+ This is a work in progress.
+
+Introduction
+============
+
+The LLVM target-independent code generator is a framework that provides a suite
+of reusable components for translating the LLVM internal representation to the
+machine code for a specified target---either in assembly form (suitable for a
+static compiler) or in binary machine code format (usable for a JIT
+compiler). The LLVM target-independent code generator consists of six main
+components:
+
+1. `Abstract target description`_ interfaces which capture important properties
+ about various aspects of the machine, independently of how they will be used.
+ These interfaces are defined in ``include/llvm/Target/``.
+
+2. Classes used to represent the `code being generated`_ for a target. These
+ classes are intended to be abstract enough to represent the machine code for
+ *any* target machine. These classes are defined in
+ ``include/llvm/CodeGen/``. At this level, concepts like "constant pool
+ entries" and "jump tables" are explicitly exposed.
+
+3. Classes and algorithms used to represent code as the object file level, the
+ `MC Layer`_. These classes represent assembly level constructs like labels,
+ sections, and instructions. At this level, concepts like "constant pool
+ entries" and "jump tables" don't exist.
+
+4. `Target-independent algorithms`_ used to implement various phases of native
+ code generation (register allocation, scheduling, stack frame representation,
+ etc). This code lives in ``lib/CodeGen/``.
+
+5. `Implementations of the abstract target description interfaces`_ for
+ particular targets. These machine descriptions make use of the components
+ provided by LLVM, and can optionally provide custom target-specific passes,
+ to build complete code generators for a specific target. Target descriptions
+ live in ``lib/Target/``.
+
+6. The target-independent JIT components. The LLVM JIT is completely target
+ independent (it uses the ``TargetJITInfo`` structure to interface for
+ target-specific issues. The code for the target-independent JIT lives in
+ ``lib/ExecutionEngine/JIT``.
+
+Depending on which part of the code generator you are interested in working on,
+different pieces of this will be useful to you. In any case, you should be
+familiar with the `target description`_ and `machine code representation`_
+classes. If you want to add a backend for a new target, you will need to
+`implement the target description`_ classes for your new target and understand
+the :doc:`LLVM code representation <LangRef>`. If you are interested in
+implementing a new `code generation algorithm`_, it should only depend on the
+target-description and machine code representation classes, ensuring that it is
+portable.
+
+Required components in the code generator
+-----------------------------------------
+
+The two pieces of the LLVM code generator are the high-level interface to the
+code generator and the set of reusable components that can be used to build
+target-specific backends. The two most important interfaces (:raw-html:`<tt>`
+`TargetMachine`_ :raw-html:`</tt>` and :raw-html:`<tt>` `DataLayout`_
+:raw-html:`</tt>`) are the only ones that are required to be defined for a
+backend to fit into the LLVM system, but the others must be defined if the
+reusable code generator components are going to be used.
+
+This design has two important implications. The first is that LLVM can support
+completely non-traditional code generation targets. For example, the C backend
+does not require register allocation, instruction selection, or any of the other
+standard components provided by the system. As such, it only implements these
+two interfaces, and does its own thing. Note that C backend was removed from the
+trunk since LLVM 3.1 release. Another example of a code generator like this is a
+(purely hypothetical) backend that converts LLVM to the GCC RTL form and uses
+GCC to emit machine code for a target.
+
+This design also implies that it is possible to design and implement radically
+different code generators in the LLVM system that do not make use of any of the
+built-in components. Doing so is not recommended at all, but could be required
+for radically different targets that do not fit into the LLVM machine
+description model: FPGAs for example.
+
+.. _high-level design of the code generator:
+
+The high-level design of the code generator
+-------------------------------------------
+
+The LLVM target-independent code generator is designed to support efficient and
+quality code generation for standard register-based microprocessors. Code
+generation in this model is divided into the following stages:
+
+1. `Instruction Selection`_ --- This phase determines an efficient way to
+ express the input LLVM code in the target instruction set. This stage
+ produces the initial code for the program in the target instruction set, then
+ makes use of virtual registers in SSA form and physical registers that
+ represent any required register assignments due to target constraints or
+ calling conventions. This step turns the LLVM code into a DAG of target
+ instructions.
+
+2. `Scheduling and Formation`_ --- This phase takes the DAG of target
+ instructions produced by the instruction selection phase, determines an
+ ordering of the instructions, then emits the instructions as :raw-html:`<tt>`
+ `MachineInstr`_\s :raw-html:`</tt>` with that ordering. Note that we
+ describe this in the `instruction selection section`_ because it operates on
+ a `SelectionDAG`_.
+
+3. `SSA-based Machine Code Optimizations`_ --- This optional stage consists of a
+ series of machine-code optimizations that operate on the SSA-form produced by
+ the instruction selector. Optimizations like modulo-scheduling or peephole
+ optimization work here.
+
+4. `Register Allocation`_ --- The target code is transformed from an infinite
+ virtual register file in SSA form to the concrete register file used by the
+ target. This phase introduces spill code and eliminates all virtual register
+ references from the program.
+
+5. `Prolog/Epilog Code Insertion`_ --- Once the machine code has been generated
+ for the function and the amount of stack space required is known (used for
+ LLVM alloca's and spill slots), the prolog and epilog code for the function
+ can be inserted and "abstract stack location references" can be eliminated.
+ This stage is responsible for implementing optimizations like frame-pointer
+ elimination and stack packing.
+
+6. `Late Machine Code Optimizations`_ --- Optimizations that operate on "final"
+ machine code can go here, such as spill code scheduling and peephole
+ optimizations.
+
+7. `Code Emission`_ --- The final stage actually puts out the code for the
+ current function, either in the target assembler format or in machine
+ code.
+
+The code generator is based on the assumption that the instruction selector will
+use an optimal pattern matching selector to create high-quality sequences of
+native instructions. Alternative code generator designs based on pattern
+expansion and aggressive iterative peephole optimization are much slower. This
+design permits efficient compilation (important for JIT environments) and
+aggressive optimization (used when generating code offline) by allowing
+components of varying levels of sophistication to be used for any step of
+compilation.
+
+In addition to these stages, target implementations can insert arbitrary
+target-specific passes into the flow. For example, the X86 target uses a
+special pass to handle the 80x87 floating point stack architecture. Other
+targets with unusual requirements can be supported with custom passes as needed.
+
+Using TableGen for target description
+-------------------------------------
+
+The target description classes require a detailed description of the target
+architecture. These target descriptions often have a large amount of common
+information (e.g., an ``add`` instruction is almost identical to a ``sub``
+instruction). In order to allow the maximum amount of commonality to be
+factored out, the LLVM code generator uses the
+:doc:`TableGen/index` tool to describe big chunks of the
+target machine, which allows the use of domain-specific and target-specific
+abstractions to reduce the amount of repetition.
+
+As LLVM continues to be developed and refined, we plan to move more and more of
+the target description to the ``.td`` form. Doing so gives us a number of
+advantages. The most important is that it makes it easier to port LLVM because
+it reduces the amount of C++ code that has to be written, and the surface area
+of the code generator that needs to be understood before someone can get
+something working. Second, it makes it easier to change things. In particular,
+if tables and other things are all emitted by ``tblgen``, we only need a change
+in one place (``tblgen``) to update all of the targets to a new interface.
+
+.. _Abstract target description:
+.. _target description:
+
+Target description classes
+==========================
+
+The LLVM target description classes (located in the ``include/llvm/Target``
+directory) provide an abstract description of the target machine independent of
+any particular client. These classes are designed to capture the *abstract*
+properties of the target (such as the instructions and registers it has), and do
+not incorporate any particular pieces of code generation algorithms.
+
+All of the target description classes (except the :raw-html:`<tt>` `DataLayout`_
+:raw-html:`</tt>` class) are designed to be subclassed by the concrete target
+implementation, and have virtual methods implemented. To get to these
+implementations, the :raw-html:`<tt>` `TargetMachine`_ :raw-html:`</tt>` class
+provides accessors that should be implemented by the target.
+
+.. _TargetMachine:
+
+The ``TargetMachine`` class
+---------------------------
+
+The ``TargetMachine`` class provides virtual methods that are used to access the
+target-specific implementations of the various target description classes via
+the ``get*Info`` methods (``getInstrInfo``, ``getRegisterInfo``,
+``getFrameInfo``, etc.). This class is designed to be specialized by a concrete
+target implementation (e.g., ``X86TargetMachine``) which implements the various
+virtual methods. The only required target description class is the
+:raw-html:`<tt>` `DataLayout`_ :raw-html:`</tt>` class, but if the code
+generator components are to be used, the other interfaces should be implemented
+as well.
+
+.. _DataLayout:
+
+The ``DataLayout`` class
+------------------------
+
+The ``DataLayout`` class is the only required target description class, and it
+is the only class that is not extensible (you cannot derive a new class from
+it). ``DataLayout`` specifies information about how the target lays out memory
+for structures, the alignment requirements for various data types, the size of
+pointers in the target, and whether the target is little-endian or
+big-endian.
+
+.. _TargetLowering:
+
+The ``TargetLowering`` class
+----------------------------
+
+The ``TargetLowering`` class is used by SelectionDAG based instruction selectors
+primarily to describe how LLVM code should be lowered to SelectionDAG
+operations. Among other things, this class indicates:
+
+* an initial register class to use for various ``ValueType``\s,
+
+* which operations are natively supported by the target machine,
+
+* the return type of ``setcc`` operations,
+
+* the type to use for shift amounts, and
+
+* various high-level characteristics, like whether it is profitable to turn
+ division by a constant into a multiplication sequence.
+
+.. _TargetRegisterInfo:
+
+The ``TargetRegisterInfo`` class
+--------------------------------
+
+The ``TargetRegisterInfo`` class is used to describe the register file of the
+target and any interactions between the registers.
+
+Registers are represented in the code generator by unsigned integers. Physical
+registers (those that actually exist in the target description) are unique
+small numbers, and virtual registers are generally large. Note that
+register ``#0`` is reserved as a flag value.
+
+Each register in the processor description has an associated
+``TargetRegisterDesc`` entry, which provides a textual name for the register
+(used for assembly output and debugging dumps) and a set of aliases (used to
+indicate whether one register overlaps with another).
+
+In addition to the per-register description, the ``TargetRegisterInfo`` class
+exposes a set of processor specific register classes (instances of the
+``TargetRegisterClass`` class). Each register class contains sets of registers
+that have the same properties (for example, they are all 32-bit integer
+registers). Each SSA virtual register created by the instruction selector has
+an associated register class. When the register allocator runs, it replaces
+virtual registers with a physical register in the set.
+
+The target-specific implementations of these classes is auto-generated from a
+:doc:`TableGen/index` description of the register file.
+
+.. _TargetInstrInfo:
+
+The ``TargetInstrInfo`` class
+-----------------------------
+
+The ``TargetInstrInfo`` class is used to describe the machine instructions
+supported by the target. Descriptions define things like the mnemonic for
+the opcode, the number of operands, the list of implicit register uses and defs,
+whether the instruction has certain target-independent properties (accesses
+memory, is commutable, etc), and holds any target-specific flags.
+
+The ``TargetFrameLowering`` class
+---------------------------------
+
+The ``TargetFrameLowering`` class is used to provide information about the stack
+frame layout of the target. It holds the direction of stack growth, the known
+stack alignment on entry to each function, and the offset to the local area.
+The offset to the local area is the offset from the stack pointer on function
+entry to the first location where function data (local variables, spill
+locations) can be stored.
+
+The ``TargetSubtarget`` class
+-----------------------------
+
+The ``TargetSubtarget`` class is used to provide information about the specific
+chip set being targeted. A sub-target informs code generation of which
+instructions are supported, instruction latencies and instruction execution
+itinerary; i.e., which processing units are used, in what order, and for how
+long.
+
+The ``TargetJITInfo`` class
+---------------------------
+
+The ``TargetJITInfo`` class exposes an abstract interface used by the
+Just-In-Time code generator to perform target-specific activities, such as
+emitting stubs. If a ``TargetMachine`` supports JIT code generation, it should
+provide one of these objects through the ``getJITInfo`` method.
+
+.. _code being generated:
+.. _machine code representation:
+
+Machine code description classes
+================================
+
+At the high-level, LLVM code is translated to a machine specific representation
+formed out of :raw-html:`<tt>` `MachineFunction`_ :raw-html:`</tt>`,
+:raw-html:`<tt>` `MachineBasicBlock`_ :raw-html:`</tt>`, and :raw-html:`<tt>`
+`MachineInstr`_ :raw-html:`</tt>` instances (defined in
+``include/llvm/CodeGen``). This representation is completely target agnostic,
+representing instructions in their most abstract form: an opcode and a series of
+operands. This representation is designed to support both an SSA representation
+for machine code, as well as a register allocated, non-SSA form.
+
+.. _MachineInstr:
+
+The ``MachineInstr`` class
+--------------------------
+
+Target machine instructions are represented as instances of the ``MachineInstr``
+class. This class is an extremely abstract way of representing machine
+instructions. In particular, it only keeps track of an opcode number and a set
+of operands.
+
+The opcode number is a simple unsigned integer that only has meaning to a
+specific backend. All of the instructions for a target should be defined in the
+``*InstrInfo.td`` file for the target. The opcode enum values are auto-generated
+from this description. The ``MachineInstr`` class does not have any information
+about how to interpret the instruction (i.e., what the semantics of the
+instruction are); for that you must refer to the :raw-html:`<tt>`
+`TargetInstrInfo`_ :raw-html:`</tt>` class.
+
+The operands of a machine instruction can be of several different types: a
+register reference, a constant integer, a basic block reference, etc. In
+addition, a machine operand should be marked as a def or a use of the value
+(though only registers are allowed to be defs).
+
+By convention, the LLVM code generator orders instruction operands so that all
+register definitions come before the register uses, even on architectures that
+are normally printed in other orders. For example, the SPARC add instruction:
+"``add %i1, %i2, %i3``" adds the "%i1", and "%i2" registers and stores the
+result into the "%i3" register. In the LLVM code generator, the operands should
+be stored as "``%i3, %i1, %i2``": with the destination first.
+
+Keeping destination (definition) operands at the beginning of the operand list
+has several advantages. In particular, the debugging printer will print the
+instruction like this:
+
+.. code-block:: llvm
+
+ %r3 = add %i1, %i2
+
+Also if the first operand is a def, it is easier to `create instructions`_ whose
+only def is the first operand.
+
+.. _create instructions:
+
+Using the ``MachineInstrBuilder.h`` functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Machine instructions are created by using the ``BuildMI`` functions, located in
+the ``include/llvm/CodeGen/MachineInstrBuilder.h`` file. The ``BuildMI``
+functions make it easy to build arbitrary machine instructions. Usage of the
+``BuildMI`` functions look like this:
+
+.. code-block:: c++
+
+ // Create a 'DestReg = mov 42' (rendered in X86 assembly as 'mov DestReg, 42')
+ // instruction. The '1' specifies how many operands will be added.
+ MachineInstr *MI = BuildMI(X86::MOV32ri, 1, DestReg).addImm(42);
+
+ // Create the same instr, but insert it at the end of a basic block.
+ MachineBasicBlock &MBB = ...
+ BuildMI(MBB, X86::MOV32ri, 1, DestReg).addImm(42);
+
+ // Create the same instr, but insert it before a specified iterator point.
+ MachineBasicBlock::iterator MBBI = ...
+ BuildMI(MBB, MBBI, X86::MOV32ri, 1, DestReg).addImm(42);
+
+ // Create a 'cmp Reg, 0' instruction, no destination reg.
+ MI = BuildMI(X86::CMP32ri, 2).addReg(Reg).addImm(0);
+
+ // Create an 'sahf' instruction which takes no operands and stores nothing.
+ MI = BuildMI(X86::SAHF, 0);
+
+ // Create a self looping branch instruction.
+ BuildMI(MBB, X86::JNE, 1).addMBB(&MBB);
+
+The key thing to remember with the ``BuildMI`` functions is that you have to
+specify the number of operands that the machine instruction will take. This
+allows for efficient memory allocation. You also need to specify if operands
+default to be uses of values, not definitions. If you need to add a definition
+operand (other than the optional destination register), you must explicitly mark
+it as such:
+
+.. code-block:: c++
+
+ MI.addReg(Reg, RegState::Define);
+
+Fixed (preassigned) registers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One important issue that the code generator needs to be aware of is the presence
+of fixed registers. In particular, there are often places in the instruction
+stream where the register allocator *must* arrange for a particular value to be
+in a particular register. This can occur due to limitations of the instruction
+set (e.g., the X86 can only do a 32-bit divide with the ``EAX``/``EDX``
+registers), or external factors like calling conventions. In any case, the
+instruction selector should emit code that copies a virtual register into or out
+of a physical register when needed.
+
+For example, consider this simple LLVM example:
+
+.. code-block:: llvm
+
+ define i32 @test(i32 %X, i32 %Y) {
+ %Z = sdiv i32 %X, %Y
+ ret i32 %Z
+ }
+
+The X86 instruction selector might produce this machine code for the ``div`` and
+``ret``:
+
+.. code-block:: llvm
+
+ ;; Start of div
+ %EAX = mov %reg1024 ;; Copy X (in reg1024) into EAX
+ %reg1027 = sar %reg1024, 31
+ %EDX = mov %reg1027 ;; Sign extend X into EDX
+ idiv %reg1025 ;; Divide by Y (in reg1025)
+ %reg1026 = mov %EAX ;; Read the result (Z) out of EAX
+
+ ;; Start of ret
+ %EAX = mov %reg1026 ;; 32-bit return value goes in EAX
+ ret
+
+By the end of code generation, the register allocator would coalesce the
+registers and delete the resultant identity moves producing the following
+code:
+
+.. code-block:: llvm
+
+ ;; X is in EAX, Y is in ECX
+ mov %EAX, %EDX
+ sar %EDX, 31
+ idiv %ECX
+ ret
+
+This approach is extremely general (if it can handle the X86 architecture, it
+can handle anything!) and allows all of the target specific knowledge about the
+instruction stream to be isolated in the instruction selector. Note that
+physical registers should have a short lifetime for good code generation, and
+all physical registers are assumed dead on entry to and exit from basic blocks
+(before register allocation). Thus, if you need a value to be live across basic
+block boundaries, it *must* live in a virtual register.
+
+Call-clobbered registers
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some machine instructions, like calls, clobber a large number of physical
+registers. Rather than adding ``<def,dead>`` operands for all of them, it is
+possible to use an ``MO_RegisterMask`` operand instead. The register mask
+operand holds a bit mask of preserved registers, and everything else is
+considered to be clobbered by the instruction.
+
+Machine code in SSA form
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``MachineInstr``'s are initially selected in SSA-form, and are maintained in
+SSA-form until register allocation happens. For the most part, this is
+trivially simple since LLVM is already in SSA form; LLVM PHI nodes become
+machine code PHI nodes, and virtual registers are only allowed to have a single
+definition.
+
+After register allocation, machine code is no longer in SSA-form because there
+are no virtual registers left in the code.
+
+.. _MachineBasicBlock:
+
+The ``MachineBasicBlock`` class
+-------------------------------
+
+The ``MachineBasicBlock`` class contains a list of machine instructions
+(:raw-html:`<tt>` `MachineInstr`_ :raw-html:`</tt>` instances). It roughly
+corresponds to the LLVM code input to the instruction selector, but there can be
+a one-to-many mapping (i.e. one LLVM basic block can map to multiple machine
+basic blocks). The ``MachineBasicBlock`` class has a "``getBasicBlock``" method,
+which returns the LLVM basic block that it comes from.
+
+.. _MachineFunction:
+
+The ``MachineFunction`` class
+-----------------------------
+
+The ``MachineFunction`` class contains a list of machine basic blocks
+(:raw-html:`<tt>` `MachineBasicBlock`_ :raw-html:`</tt>` instances). It
+corresponds one-to-one with the LLVM function input to the instruction selector.
+In addition to a list of basic blocks, the ``MachineFunction`` contains a a
+``MachineConstantPool``, a ``MachineFrameInfo``, a ``MachineFunctionInfo``, and
+a ``MachineRegisterInfo``. See ``include/llvm/CodeGen/MachineFunction.h`` for
+more information.
+
+``MachineInstr Bundles``
+------------------------
+
+LLVM code generator can model sequences of instructions as MachineInstr
+bundles. A MI bundle can model a VLIW group / pack which contains an arbitrary
+number of parallel instructions. It can also be used to model a sequential list
+of instructions (potentially with data dependencies) that cannot be legally
+separated (e.g. ARM Thumb2 IT blocks).
+
+Conceptually a MI bundle is a MI with a number of other MIs nested within:
+
+::
+
+ --------------
+ | Bundle | ---------
+ -------------- \
+ | ----------------
+ | | MI |
+ | ----------------
+ | |
+ | ----------------
+ | | MI |
+ | ----------------
+ | |
+ | ----------------
+ | | MI |
+ | ----------------
+ |
+ --------------
+ | Bundle | --------
+ -------------- \
+ | ----------------
+ | | MI |
+ | ----------------
+ | |
+ | ----------------
+ | | MI |
+ | ----------------
+ | |
+ | ...
+ |
+ --------------
+ | Bundle | --------
+ -------------- \
+ |
+ ...
+
+MI bundle support does not change the physical representations of
+MachineBasicBlock and MachineInstr. All the MIs (including top level and nested
+ones) are stored as sequential list of MIs. The "bundled" MIs are marked with
+the 'InsideBundle' flag. A top level MI with the special BUNDLE opcode is used
+to represent the start of a bundle. It's legal to mix BUNDLE MIs with indiviual
+MIs that are not inside bundles nor represent bundles.
+
+MachineInstr passes should operate on a MI bundle as a single unit. Member
+methods have been taught to correctly handle bundles and MIs inside bundles.
+The MachineBasicBlock iterator has been modified to skip over bundled MIs to
+enforce the bundle-as-a-single-unit concept. An alternative iterator
+instr_iterator has been added to MachineBasicBlock to allow passes to iterate
+over all of the MIs in a MachineBasicBlock, including those which are nested
+inside bundles. The top level BUNDLE instruction must have the correct set of
+register MachineOperand's that represent the cumulative inputs and outputs of
+the bundled MIs.
+
+Packing / bundling of MachineInstr's should be done as part of the register
+allocation super-pass. More specifically, the pass which determines what MIs
+should be bundled together must be done after code generator exits SSA form
+(i.e. after two-address pass, PHI elimination, and copy coalescing). Bundles
+should only be finalized (i.e. adding BUNDLE MIs and input and output register
+MachineOperands) after virtual registers have been rewritten into physical
+registers. This requirement eliminates the need to add virtual register operands
+to BUNDLE instructions which would effectively double the virtual register def
+and use lists.
+
+.. _MC Layer:
+
+The "MC" Layer
+==============
+
+The MC Layer is used to represent and process code at the raw machine code
+level, devoid of "high level" information like "constant pools", "jump tables",
+"global variables" or anything like that. At this level, LLVM handles things
+like label names, machine instructions, and sections in the object file. The
+code in this layer is used for a number of important purposes: the tail end of
+the code generator uses it to write a .s or .o file, and it is also used by the
+llvm-mc tool to implement standalone machine code assemblers and disassemblers.
+
+This section describes some of the important classes. There are also a number
+of important subsystems that interact at this layer, they are described later in
+this manual.
+
+.. _MCStreamer:
+
+The ``MCStreamer`` API
+----------------------
+
+MCStreamer is best thought of as an assembler API. It is an abstract API which
+is *implemented* in different ways (e.g. to output a .s file, output an ELF .o
+file, etc) but whose API correspond directly to what you see in a .s file.
+MCStreamer has one method per directive, such as EmitLabel, EmitSymbolAttribute,
+SwitchSection, EmitValue (for .byte, .word), etc, which directly correspond to
+assembly level directives. It also has an EmitInstruction method, which is used
+to output an MCInst to the streamer.
+
+This API is most important for two clients: the llvm-mc stand-alone assembler is
+effectively a parser that parses a line, then invokes a method on MCStreamer. In
+the code generator, the `Code Emission`_ phase of the code generator lowers
+higher level LLVM IR and Machine* constructs down to the MC layer, emitting
+directives through MCStreamer.
+
+On the implementation side of MCStreamer, there are two major implementations:
+one for writing out a .s file (MCAsmStreamer), and one for writing out a .o
+file (MCObjectStreamer). MCAsmStreamer is a straight-forward implementation
+that prints out a directive for each method (e.g. ``EmitValue -> .byte``), but
+MCObjectStreamer implements a full assembler.
+
+For target specific directives, the MCStreamer has a MCTargetStreamer instance.
+Each target that needs it defines a class that inherits from it and is a lot
+like MCStreamer itself: It has one method per directive and two classes that
+inherit from it, a target object streamer and a target asm streamer. The target
+asm streamer just prints it (``emitFnStart -> .fnstrart``), and the object
+streamer implement the assembler logic for it.
+
+To make llvm use these classes, the target initialization must call
+TargetRegistry::RegisterAsmStreamer and TargetRegistry::RegisterMCObjectStreamer
+passing callbacks that allocate the corresponding target streamer and pass it
+to createAsmStreamer or to the appropriate object streamer constructor.
+
+The ``MCContext`` class
+-----------------------
+
+The MCContext class is the owner of a variety of uniqued data structures at the
+MC layer, including symbols, sections, etc. As such, this is the class that you
+interact with to create symbols and sections. This class can not be subclassed.
+
+The ``MCSymbol`` class
+----------------------
+
+The MCSymbol class represents a symbol (aka label) in the assembly file. There
+are two interesting kinds of symbols: assembler temporary symbols, and normal
+symbols. Assembler temporary symbols are used and processed by the assembler
+but are discarded when the object file is produced. The distinction is usually
+represented by adding a prefix to the label, for example "L" labels are
+assembler temporary labels in MachO.
+
+MCSymbols are created by MCContext and uniqued there. This means that MCSymbols
+can be compared for pointer equivalence to find out if they are the same symbol.
+Note that pointer inequality does not guarantee the labels will end up at
+different addresses though. It's perfectly legal to output something like this
+to the .s file:
+
+::
+
+ foo:
+ bar:
+ .byte 4
+
+In this case, both the foo and bar symbols will have the same address.
+
+The ``MCSection`` class
+-----------------------
+
+The ``MCSection`` class represents an object-file specific section. It is
+subclassed by object file specific implementations (e.g. ``MCSectionMachO``,
+``MCSectionCOFF``, ``MCSectionELF``) and these are created and uniqued by
+MCContext. The MCStreamer has a notion of the current section, which can be
+changed with the SwitchToSection method (which corresponds to a ".section"
+directive in a .s file).
+
+.. _MCInst:
+
+The ``MCInst`` class
+--------------------
+
+The ``MCInst`` class is a target-independent representation of an instruction.
+It is a simple class (much more so than `MachineInstr`_) that holds a
+target-specific opcode and a vector of MCOperands. MCOperand, in turn, is a
+simple discriminated union of three cases: 1) a simple immediate, 2) a target
+register ID, 3) a symbolic expression (e.g. "``Lfoo-Lbar+42``") as an MCExpr.
+
+MCInst is the common currency used to represent machine instructions at the MC
+layer. It is the type used by the instruction encoder, the instruction printer,
+and the type generated by the assembly parser and disassembler.
+
+.. _Target-independent algorithms:
+.. _code generation algorithm:
+
+Target-independent code generation algorithms
+=============================================
+
+This section documents the phases described in the `high-level design of the
+code generator`_. It explains how they work and some of the rationale behind
+their design.
+
+.. _Instruction Selection:
+.. _instruction selection section:
+
+Instruction Selection
+---------------------
+
+Instruction Selection is the process of translating LLVM code presented to the
+code generator into target-specific machine instructions. There are several
+well-known ways to do this in the literature. LLVM uses a SelectionDAG based
+instruction selector.
+
+Portions of the DAG instruction selector are generated from the target
+description (``*.td``) files. Our goal is for the entire instruction selector
+to be generated from these ``.td`` files, though currently there are still
+things that require custom C++ code.
+
+.. _SelectionDAG:
+
+Introduction to SelectionDAGs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SelectionDAG provides an abstraction for code representation in a way that
+is amenable to instruction selection using automatic techniques
+(e.g. dynamic-programming based optimal pattern matching selectors). It is also
+well-suited to other phases of code generation; in particular, instruction
+scheduling (SelectionDAG's are very close to scheduling DAGs post-selection).
+Additionally, the SelectionDAG provides a host representation where a large
+variety of very-low-level (but target-independent) `optimizations`_ may be
+performed; ones which require extensive information about the instructions
+efficiently supported by the target.
+
+The SelectionDAG is a Directed-Acyclic-Graph whose nodes are instances of the
+``SDNode`` class. The primary payload of the ``SDNode`` is its operation code
+(Opcode) that indicates what operation the node performs and the operands to the
+operation. The various operation node types are described at the top of the
+``include/llvm/CodeGen/ISDOpcodes.h`` file.
+
+Although most operations define a single value, each node in the graph may
+define multiple values. For example, a combined div/rem operation will define
+both the dividend and the remainder. Many other situations require multiple
+values as well. Each node also has some number of operands, which are edges to
+the node defining the used value. Because nodes may define multiple values,
+edges are represented by instances of the ``SDValue`` class, which is a
+``<SDNode, unsigned>`` pair, indicating the node and result value being used,
+respectively. Each value produced by an ``SDNode`` has an associated ``MVT``
+(Machine Value Type) indicating what the type of the value is.
+
+SelectionDAGs contain two different kinds of values: those that represent data
+flow and those that represent control flow dependencies. Data values are simple
+edges with an integer or floating point value type. Control edges are
+represented as "chain" edges which are of type ``MVT::Other``. These edges
+provide an ordering between nodes that have side effects (such as loads, stores,
+calls, returns, etc). All nodes that have side effects should take a token
+chain as input and produce a new one as output. By convention, token chain
+inputs are always operand #0, and chain results are always the last value
+produced by an operation. However, after instruction selection, the
+machine nodes have their chain after the instruction's operands, and
+may be followed by glue nodes.
+
+A SelectionDAG has designated "Entry" and "Root" nodes. The Entry node is
+always a marker node with an Opcode of ``ISD::EntryToken``. The Root node is
+the final side-effecting node in the token chain. For example, in a single basic
+block function it would be the return node.
+
+One important concept for SelectionDAGs is the notion of a "legal" vs.
+"illegal" DAG. A legal DAG for a target is one that only uses supported
+operations and supported types. On a 32-bit PowerPC, for example, a DAG with a
+value of type i1, i8, i16, or i64 would be illegal, as would a DAG that uses a
+SREM or UREM operation. The `legalize types`_ and `legalize operations`_ phases
+are responsible for turning an illegal DAG into a legal DAG.
+
+.. _SelectionDAG-Process:
+
+SelectionDAG Instruction Selection Process
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SelectionDAG-based instruction selection consists of the following steps:
+
+#. `Build initial DAG`_ --- This stage performs a simple translation from the
+ input LLVM code to an illegal SelectionDAG.
+
+#. `Optimize SelectionDAG`_ --- This stage performs simple optimizations on the
+ SelectionDAG to simplify it, and recognize meta instructions (like rotates
+ and ``div``/``rem`` pairs) for targets that support these meta operations.
+ This makes the resultant code more efficient and the `select instructions
+ from DAG`_ phase (below) simpler.
+
+#. `Legalize SelectionDAG Types`_ --- This stage transforms SelectionDAG nodes
+ to eliminate any types that are unsupported on the target.
+
+#. `Optimize SelectionDAG`_ --- The SelectionDAG optimizer is run to clean up
+ redundancies exposed by type legalization.
+
+#. `Legalize SelectionDAG Ops`_ --- This stage transforms SelectionDAG nodes to
+ eliminate any operations that are unsupported on the target.
+
+#. `Optimize SelectionDAG`_ --- The SelectionDAG optimizer is run to eliminate
+ inefficiencies introduced by operation legalization.
+
+#. `Select instructions from DAG`_ --- Finally, the target instruction selector
+ matches the DAG operations to target instructions. This process translates
+ the target-independent input DAG into another DAG of target instructions.
+
+#. `SelectionDAG Scheduling and Formation`_ --- The last phase assigns a linear
+ order to the instructions in the target-instruction DAG and emits them into
+ the MachineFunction being compiled. This step uses traditional prepass
+ scheduling techniques.
+
+After all of these steps are complete, the SelectionDAG is destroyed and the
+rest of the code generation passes are run.
+
+One great way to visualize what is going on here is to take advantage of a few
+LLC command line options. The following options pop up a window displaying the
+SelectionDAG at specific times (if you only get errors printed to the console
+while using this, you probably `need to configure your
+system <ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ to add support for it).
+
+* ``-view-dag-combine1-dags`` displays the DAG after being built, before the
+ first optimization pass.
+
+* ``-view-legalize-dags`` displays the DAG before Legalization.
+
+* ``-view-dag-combine2-dags`` displays the DAG before the second optimization
+ pass.
+
+* ``-view-isel-dags`` displays the DAG before the Select phase.
+
+* ``-view-sched-dags`` displays the DAG before Scheduling.
+
+The ``-view-sunit-dags`` displays the Scheduler's dependency graph. This graph
+is based on the final SelectionDAG, with nodes that must be scheduled together
+bundled into a single scheduling-unit node, and with immediate operands and
+other nodes that aren't relevant for scheduling omitted.
+
+The option ``-filter-view-dags`` allows to select the name of the basic block
+that you are interested to visualize and filters all the previous
+``view-*-dags`` options.
+
+.. _Build initial DAG:
+
+Initial SelectionDAG Construction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The initial SelectionDAG is na\ :raw-html:`ï`\ vely peephole expanded from
+the LLVM input by the ``SelectionDAGBuilder`` class. The intent of this pass
+is to expose as much low-level, target-specific details to the SelectionDAG as
+possible. This pass is mostly hard-coded (e.g. an LLVM ``add`` turns into an
+``SDNode add`` while a ``getelementptr`` is expanded into the obvious
+arithmetic). This pass requires target-specific hooks to lower calls, returns,
+varargs, etc. For these features, the :raw-html:`<tt>` `TargetLowering`_
+:raw-html:`</tt>` interface is used.
+
+.. _legalize types:
+.. _Legalize SelectionDAG Types:
+.. _Legalize SelectionDAG Ops:
+
+SelectionDAG LegalizeTypes Phase
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Legalize phase is in charge of converting a DAG to only use the types that
+are natively supported by the target.
+
+There are two main ways of converting values of unsupported scalar types to
+values of supported types: converting small types to larger types ("promoting"),
+and breaking up large integer types into smaller ones ("expanding"). For
+example, a target might require that all f32 values are promoted to f64 and that
+all i1/i8/i16 values are promoted to i32. The same target might require that
+all i64 values be expanded into pairs of i32 values. These changes can insert
+sign and zero extensions as needed to make sure that the final code has the same
+behavior as the input.
+
+There are two main ways of converting values of unsupported vector types to
+value of supported types: splitting vector types, multiple times if necessary,
+until a legal type is found, and extending vector types by adding elements to
+the end to round them out to legal types ("widening"). If a vector gets split
+all the way down to single-element parts with no supported vector type being
+found, the elements are converted to scalars ("scalarizing").
+
+A target implementation tells the legalizer which types are supported (and which
+register class to use for them) by calling the ``addRegisterClass`` method in
+its ``TargetLowering`` constructor.
+
+.. _legalize operations:
+.. _Legalizer:
+
+SelectionDAG Legalize Phase
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Legalize phase is in charge of converting a DAG to only use the operations
+that are natively supported by the target.
+
+Targets often have weird constraints, such as not supporting every operation on
+every supported datatype (e.g. X86 does not support byte conditional moves and
+PowerPC does not support sign-extending loads from a 16-bit memory location).
+Legalize takes care of this by open-coding another sequence of operations to
+emulate the operation ("expansion"), by promoting one type to a larger type that
+supports the operation ("promotion"), or by using a target-specific hook to
+implement the legalization ("custom").
+
+A target implementation tells the legalizer which operations are not supported
+(and which of the above three actions to take) by calling the
+``setOperationAction`` method in its ``TargetLowering`` constructor.
+
+Prior to the existence of the Legalize passes, we required that every target
+`selector`_ supported and handled every operator and type even if they are not
+natively supported. The introduction of the Legalize phases allows all of the
+canonicalization patterns to be shared across targets, and makes it very easy to
+optimize the canonicalized code because it is still in the form of a DAG.
+
+.. _optimizations:
+.. _Optimize SelectionDAG:
+.. _selector:
+
+SelectionDAG Optimization Phase: the DAG Combiner
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SelectionDAG optimization phase is run multiple times for code generation,
+immediately after the DAG is built and once after each legalization. The first
+run of the pass allows the initial code to be cleaned up (e.g. performing
+optimizations that depend on knowing that the operators have restricted type
+inputs). Subsequent runs of the pass clean up the messy code generated by the
+Legalize passes, which allows Legalize to be very simple (it can focus on making
+code legal instead of focusing on generating *good* and legal code).
+
+One important class of optimizations performed is optimizing inserted sign and
+zero extension instructions. We currently use ad-hoc techniques, but could move
+to more rigorous techniques in the future. Here are some good papers on the
+subject:
+
+"`Widening integer arithmetic <http://www.eecs.harvard.edu/~nr/pubs/widen-abstract.html>`_" :raw-html:`<br>`
+Kevin Redwine and Norman Ramsey :raw-html:`<br>`
+International Conference on Compiler Construction (CC) 2004
+
+"`Effective sign extension elimination <http://portal.acm.org/citation.cfm?doid=512529.512552>`_" :raw-html:`<br>`
+Motohiro Kawahito, Hideaki Komatsu, and Toshio Nakatani :raw-html:`<br>`
+Proceedings of the ACM SIGPLAN 2002 Conference on Programming Language Design
+and Implementation.
+
+.. _Select instructions from DAG:
+
+SelectionDAG Select Phase
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Select phase is the bulk of the target-specific code for instruction
+selection. This phase takes a legal SelectionDAG as input, pattern matches the
+instructions supported by the target to this DAG, and produces a new DAG of
+target code. For example, consider the following LLVM fragment:
+
+.. code-block:: llvm
+
+ %t1 = fadd float %W, %X
+ %t2 = fmul float %t1, %Y
+ %t3 = fadd float %t2, %Z
+
+This LLVM code corresponds to a SelectionDAG that looks basically like this:
+
+.. code-block:: llvm
+
+ (fadd:f32 (fmul:f32 (fadd:f32 W, X), Y), Z)
+
+If a target supports floating point multiply-and-add (FMA) operations, one of
+the adds can be merged with the multiply. On the PowerPC, for example, the
+output of the instruction selector might look like this DAG:
+
+::
+
+ (FMADDS (FADDS W, X), Y, Z)
+
+The ``FMADDS`` instruction is a ternary instruction that multiplies its first
+two operands and adds the third (as single-precision floating-point numbers).
+The ``FADDS`` instruction is a simple binary single-precision add instruction.
+To perform this pattern match, the PowerPC backend includes the following
+instruction definitions:
+
+.. code-block:: text
+ :emphasize-lines: 4-5,9
+
+ def FMADDS : AForm_1<59, 29,
+ (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRC, F4RC:$FRB),
+ "fmadds $FRT, $FRA, $FRC, $FRB",
+ [(set F4RC:$FRT, (fadd (fmul F4RC:$FRA, F4RC:$FRC),
+ F4RC:$FRB))]>;
+ def FADDS : AForm_2<59, 21,
+ (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRB),
+ "fadds $FRT, $FRA, $FRB",
+ [(set F4RC:$FRT, (fadd F4RC:$FRA, F4RC:$FRB))]>;
+
+The highlighted portion of the instruction definitions indicates the pattern
+used to match the instructions. The DAG operators (like ``fmul``/``fadd``)
+are defined in the ``include/llvm/Target/TargetSelectionDAG.td`` file.
+"``F4RC``" is the register class of the input and result values.
+
+The TableGen DAG instruction selector generator reads the instruction patterns
+in the ``.td`` file and automatically builds parts of the pattern matching code
+for your target. It has the following strengths:
+
+* At compiler-compiler time, it analyzes your instruction patterns and tells you
+ if your patterns make sense or not.
+
+* It can handle arbitrary constraints on operands for the pattern match. In
+ particular, it is straight-forward to say things like "match any immediate
+ that is a 13-bit sign-extended value". For examples, see the ``immSExt16``
+ and related ``tblgen`` classes in the PowerPC backend.
+
+* It knows several important identities for the patterns defined. For example,
+ it knows that addition is commutative, so it allows the ``FMADDS`` pattern
+ above to match "``(fadd X, (fmul Y, Z))``" as well as "``(fadd (fmul X, Y),
+ Z)``", without the target author having to specially handle this case.
+
+* It has a full-featured type-inferencing system. In particular, you should
+ rarely have to explicitly tell the system what type parts of your patterns
+ are. In the ``FMADDS`` case above, we didn't have to tell ``tblgen`` that all
+ of the nodes in the pattern are of type 'f32'. It was able to infer and
+ propagate this knowledge from the fact that ``F4RC`` has type 'f32'.
+
+* Targets can define their own (and rely on built-in) "pattern fragments".
+ Pattern fragments are chunks of reusable patterns that get inlined into your
+ patterns during compiler-compiler time. For example, the integer "``(not
+ x)``" operation is actually defined as a pattern fragment that expands as
+ "``(xor x, -1)``", since the SelectionDAG does not have a native '``not``'
+ operation. Targets can define their own short-hand fragments as they see fit.
+ See the definition of '``not``' and '``ineg``' for examples.
+
+* In addition to instructions, targets can specify arbitrary patterns that map
+ to one or more instructions using the 'Pat' class. For example, the PowerPC
+ has no way to load an arbitrary integer immediate into a register in one
+ instruction. To tell tblgen how to do this, it defines:
+
+ ::
+
+ // Arbitrary immediate support. Implement in terms of LIS/ORI.
+ def : Pat<(i32 imm:$imm),
+ (ORI (LIS (HI16 imm:$imm)), (LO16 imm:$imm))>;
+
+ If none of the single-instruction patterns for loading an immediate into a
+ register match, this will be used. This rule says "match an arbitrary i32
+ immediate, turning it into an ``ORI`` ('or a 16-bit immediate') and an ``LIS``
+ ('load 16-bit immediate, where the immediate is shifted to the left 16 bits')
+ instruction". To make this work, the ``LO16``/``HI16`` node transformations
+ are used to manipulate the input immediate (in this case, take the high or low
+ 16-bits of the immediate).
+
+* When using the 'Pat' class to map a pattern to an instruction that has one
+ or more complex operands (like e.g. `X86 addressing mode`_), the pattern may
+ either specify the operand as a whole using a ``ComplexPattern``, or else it
+ may specify the components of the complex operand separately. The latter is
+ done e.g. for pre-increment instructions by the PowerPC back end:
+
+ ::
+
+ def STWU : DForm_1<37, (outs ptr_rc:$ea_res), (ins GPRC:$rS, memri:$dst),
+ "stwu $rS, $dst", LdStStoreUpd, []>,
+ RegConstraint<"$dst.reg = $ea_res">, NoEncode<"$ea_res">;
+
+ def : Pat<(pre_store GPRC:$rS, ptr_rc:$ptrreg, iaddroff:$ptroff),
+ (STWU GPRC:$rS, iaddroff:$ptroff, ptr_rc:$ptrreg)>;
+
+ Here, the pair of ``ptroff`` and ``ptrreg`` operands is matched onto the
+ complex operand ``dst`` of class ``memri`` in the ``STWU`` instruction.
+
+* While the system does automate a lot, it still allows you to write custom C++
+ code to match special cases if there is something that is hard to
+ express.
+
+While it has many strengths, the system currently has some limitations,
+primarily because it is a work in progress and is not yet finished:
+
+* Overall, there is no way to define or match SelectionDAG nodes that define
+ multiple values (e.g. ``SMUL_LOHI``, ``LOAD``, ``CALL``, etc). This is the
+ biggest reason that you currently still *have to* write custom C++ code
+ for your instruction selector.
+
+* There is no great way to support matching complex addressing modes yet. In
+ the future, we will extend pattern fragments to allow them to define multiple
+ values (e.g. the four operands of the `X86 addressing mode`_, which are
+ currently matched with custom C++ code). In addition, we'll extend fragments
+ so that a fragment can match multiple different patterns.
+
+* We don't automatically infer flags like ``isStore``/``isLoad`` yet.
+
+* We don't automatically generate the set of supported registers and operations
+ for the `Legalizer`_ yet.
+
+* We don't have a way of tying in custom legalized nodes yet.
+
+Despite these limitations, the instruction selector generator is still quite
+useful for most of the binary and logical operations in typical instruction
+sets. If you run into any problems or can't figure out how to do something,
+please let Chris know!
+
+.. _Scheduling and Formation:
+.. _SelectionDAG Scheduling and Formation:
+
+SelectionDAG Scheduling and Formation Phase
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The scheduling phase takes the DAG of target instructions from the selection
+phase and assigns an order. The scheduler can pick an order depending on
+various constraints of the machines (i.e. order for minimal register pressure or
+try to cover instruction latencies). Once an order is established, the DAG is
+converted to a list of :raw-html:`<tt>` `MachineInstr`_\s :raw-html:`</tt>` and
+the SelectionDAG is destroyed.
+
+Note that this phase is logically separate from the instruction selection phase,
+but is tied to it closely in the code because it operates on SelectionDAGs.
+
+Future directions for the SelectionDAG
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Optional function-at-a-time selection.
+
+#. Auto-generate entire selector from ``.td`` file.
+
+.. _SSA-based Machine Code Optimizations:
+
+SSA-based Machine Code Optimizations
+------------------------------------
+
+To Be Written
+
+Live Intervals
+--------------
+
+Live Intervals are the ranges (intervals) where a variable is *live*. They are
+used by some `register allocator`_ passes to determine if two or more virtual
+registers which require the same physical register are live at the same point in
+the program (i.e., they conflict). When this situation occurs, one virtual
+register must be *spilled*.
+
+Live Variable Analysis
+^^^^^^^^^^^^^^^^^^^^^^
+
+The first step in determining the live intervals of variables is to calculate
+the set of registers that are immediately dead after the instruction (i.e., the
+instruction calculates the value, but it is never used) and the set of registers
+that are used by the instruction, but are never used after the instruction
+(i.e., they are killed). Live variable information is computed for
+each *virtual* register and *register allocatable* physical register
+in the function. This is done in a very efficient manner because it uses SSA to
+sparsely compute lifetime information for virtual registers (which are in SSA
+form) and only has to track physical registers within a block. Before register
+allocation, LLVM can assume that physical registers are only live within a
+single basic block. This allows it to do a single, local analysis to resolve
+physical register lifetimes within each basic block. If a physical register is
+not register allocatable (e.g., a stack pointer or condition codes), it is not
+tracked.
+
+Physical registers may be live in to or out of a function. Live in values are
+typically arguments in registers. Live out values are typically return values in
+registers. Live in values are marked as such, and are given a dummy "defining"
+instruction during live intervals analysis. If the last basic block of a
+function is a ``return``, then it's marked as using all live out values in the
+function.
+
+``PHI`` nodes need to be handled specially, because the calculation of the live
+variable information from a depth first traversal of the CFG of the function
+won't guarantee that a virtual register used by the ``PHI`` node is defined
+before it's used. When a ``PHI`` node is encountered, only the definition is
+handled, because the uses will be handled in other basic blocks.
+
+For each ``PHI`` node of the current basic block, we simulate an assignment at
+the end of the current basic block and traverse the successor basic blocks. If a
+successor basic block has a ``PHI`` node and one of the ``PHI`` node's operands
+is coming from the current basic block, then the variable is marked as *alive*
+within the current basic block and all of its predecessor basic blocks, until
+the basic block with the defining instruction is encountered.
+
+Live Intervals Analysis
+^^^^^^^^^^^^^^^^^^^^^^^
+
+We now have the information available to perform the live intervals analysis and
+build the live intervals themselves. We start off by numbering the basic blocks
+and machine instructions. We then handle the "live-in" values. These are in
+physical registers, so the physical register is assumed to be killed by the end
+of the basic block. Live intervals for virtual registers are computed for some
+ordering of the machine instructions ``[1, N]``. A live interval is an interval
+``[i, j)``, where ``1 >= i >= j > N``, for which a variable is live.
+
+.. note::
+ More to come...
+
+.. _Register Allocation:
+.. _register allocator:
+
+Register Allocation
+-------------------
+
+The *Register Allocation problem* consists in mapping a program
+:raw-html:`<b><tt>` P\ :sub:`v`\ :raw-html:`</tt></b>`, that can use an unbounded
+number of virtual registers, to a program :raw-html:`<b><tt>` P\ :sub:`p`\
+:raw-html:`</tt></b>` that contains a finite (possibly small) number of physical
+registers. Each target architecture has a different number of physical
+registers. If the number of physical registers is not enough to accommodate all
+the virtual registers, some of them will have to be mapped into memory. These
+virtuals are called *spilled virtuals*.
+
+How registers are represented in LLVM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In LLVM, physical registers are denoted by integer numbers that normally range
+from 1 to 1023. To see how this numbering is defined for a particular
+architecture, you can read the ``GenRegisterNames.inc`` file for that
+architecture. For instance, by inspecting
+``lib/Target/X86/X86GenRegisterInfo.inc`` we see that the 32-bit register
+``EAX`` is denoted by 43, and the MMX register ``MM0`` is mapped to 65.
+
+Some architectures contain registers that share the same physical location. A
+notable example is the X86 platform. For instance, in the X86 architecture, the
+registers ``EAX``, ``AX`` and ``AL`` share the first eight bits. These physical
+registers are marked as *aliased* in LLVM. Given a particular architecture, you
+can check which registers are aliased by inspecting its ``RegisterInfo.td``
+file. Moreover, the class ``MCRegAliasIterator`` enumerates all the physical
+registers aliased to a register.
+
+Physical registers, in LLVM, are grouped in *Register Classes*. Elements in the
+same register class are functionally equivalent, and can be interchangeably
+used. Each virtual register can only be mapped to physical registers of a
+particular class. For instance, in the X86 architecture, some virtuals can only
+be allocated to 8 bit registers. A register class is described by
+``TargetRegisterClass`` objects. To discover if a virtual register is
+compatible with a given physical, this code can be used:
+
+.. code-block:: c++
+
+ bool RegMapping_Fer::compatible_class(MachineFunction &mf,
+ unsigned v_reg,
+ unsigned p_reg) {
+ assert(TargetRegisterInfo::isPhysicalRegister(p_reg) &&
+ "Target register must be physical");
+ const TargetRegisterClass *trc = mf.getRegInfo().getRegClass(v_reg);
+ return trc->contains(p_reg);
+ }
+
+Sometimes, mostly for debugging purposes, it is useful to change the number of
+physical registers available in the target architecture. This must be done
+statically, inside the ``TargetRegsterInfo.td`` file. Just ``grep`` for
+``RegisterClass``, the last parameter of which is a list of registers. Just
+commenting some out is one simple way to avoid them being used. A more polite
+way is to explicitly exclude some registers from the *allocation order*. See the
+definition of the ``GR8`` register class in
+``lib/Target/X86/X86RegisterInfo.td`` for an example of this.
+
+Virtual registers are also denoted by integer numbers. Contrary to physical
+registers, different virtual registers never share the same number. Whereas
+physical registers are statically defined in a ``TargetRegisterInfo.td`` file
+and cannot be created by the application developer, that is not the case with
+virtual registers. In order to create new virtual registers, use the method
+``MachineRegisterInfo::createVirtualRegister()``. This method will return a new
+virtual register. Use an ``IndexedMap<Foo, VirtReg2IndexFunctor>`` to hold
+information per virtual register. If you need to enumerate all virtual
+registers, use the function ``TargetRegisterInfo::index2VirtReg()`` to find the
+virtual register numbers:
+
+.. code-block:: c++
+
+ for (unsigned i = 0, e = MRI->getNumVirtRegs(); i != e; ++i) {
+ unsigned VirtReg = TargetRegisterInfo::index2VirtReg(i);
+ stuff(VirtReg);
+ }
+
+Before register allocation, the operands of an instruction are mostly virtual
+registers, although physical registers may also be used. In order to check if a
+given machine operand is a register, use the boolean function
+``MachineOperand::isRegister()``. To obtain the integer code of a register, use
+``MachineOperand::getReg()``. An instruction may define or use a register. For
+instance, ``ADD reg:1026 := reg:1025 reg:1024`` defines the registers 1024, and
+uses registers 1025 and 1026. Given a register operand, the method
+``MachineOperand::isUse()`` informs if that register is being used by the
+instruction. The method ``MachineOperand::isDef()`` informs if that registers is
+being defined.
+
+We will call physical registers present in the LLVM bitcode before register
+allocation *pre-colored registers*. Pre-colored registers are used in many
+different situations, for instance, to pass parameters of functions calls, and
+to store results of particular instructions. There are two types of pre-colored
+registers: the ones *implicitly* defined, and those *explicitly*
+defined. Explicitly defined registers are normal operands, and can be accessed
+with ``MachineInstr::getOperand(int)::getReg()``. In order to check which
+registers are implicitly defined by an instruction, use the
+``TargetInstrInfo::get(opcode)::ImplicitDefs``, where ``opcode`` is the opcode
+of the target instruction. One important difference between explicit and
+implicit physical registers is that the latter are defined statically for each
+instruction, whereas the former may vary depending on the program being
+compiled. For example, an instruction that represents a function call will
+always implicitly define or use the same set of physical registers. To read the
+registers implicitly used by an instruction, use
+``TargetInstrInfo::get(opcode)::ImplicitUses``. Pre-colored registers impose
+constraints on any register allocation algorithm. The register allocator must
+make sure that none of them are overwritten by the values of virtual registers
+while still alive.
+
+Mapping virtual registers to physical registers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two ways to map virtual registers to physical registers (or to memory
+slots). The first way, that we will call *direct mapping*, is based on the use
+of methods of the classes ``TargetRegisterInfo``, and ``MachineOperand``. The
+second way, that we will call *indirect mapping*, relies on the ``VirtRegMap``
+class in order to insert loads and stores sending and getting values to and from
+memory.
+
+The direct mapping provides more flexibility to the developer of the register
+allocator; however, it is more error prone, and demands more implementation
+work. Basically, the programmer will have to specify where load and store
+instructions should be inserted in the target function being compiled in order
+to get and store values in memory. To assign a physical register to a virtual
+register present in a given operand, use ``MachineOperand::setReg(p_reg)``. To
+insert a store instruction, use ``TargetInstrInfo::storeRegToStackSlot(...)``,
+and to insert a load instruction, use ``TargetInstrInfo::loadRegFromStackSlot``.
+
+The indirect mapping shields the application developer from the complexities of
+inserting load and store instructions. In order to map a virtual register to a
+physical one, use ``VirtRegMap::assignVirt2Phys(vreg, preg)``. In order to map
+a certain virtual register to memory, use
+``VirtRegMap::assignVirt2StackSlot(vreg)``. This method will return the stack
+slot where ``vreg``'s value will be located. If it is necessary to map another
+virtual register to the same stack slot, use
+``VirtRegMap::assignVirt2StackSlot(vreg, stack_location)``. One important point
+to consider when using the indirect mapping, is that even if a virtual register
+is mapped to memory, it still needs to be mapped to a physical register. This
+physical register is the location where the virtual register is supposed to be
+found before being stored or after being reloaded.
+
+If the indirect strategy is used, after all the virtual registers have been
+mapped to physical registers or stack slots, it is necessary to use a spiller
+object to place load and store instructions in the code. Every virtual that has
+been mapped to a stack slot will be stored to memory after being defined and will
+be loaded before being used. The implementation of the spiller tries to recycle
+load/store instructions, avoiding unnecessary instructions. For an example of
+how to invoke the spiller, see ``RegAllocLinearScan::runOnMachineFunction`` in
+``lib/CodeGen/RegAllocLinearScan.cpp``.
+
+Handling two address instructions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With very rare exceptions (e.g., function calls), the LLVM machine code
+instructions are three address instructions. That is, each instruction is
+expected to define at most one register, and to use at most two registers.
+However, some architectures use two address instructions. In this case, the
+defined register is also one of the used registers. For instance, an instruction
+such as ``ADD %EAX, %EBX``, in X86 is actually equivalent to ``%EAX = %EAX +
+%EBX``.
+
+In order to produce correct code, LLVM must convert three address instructions
+that represent two address instructions into true two address instructions. LLVM
+provides the pass ``TwoAddressInstructionPass`` for this specific purpose. It
+must be run before register allocation takes place. After its execution, the
+resulting code may no longer be in SSA form. This happens, for instance, in
+situations where an instruction such as ``%a = ADD %b %c`` is converted to two
+instructions such as:
+
+::
+
+ %a = MOVE %b
+ %a = ADD %a %c
+
+Notice that, internally, the second instruction is represented as ``ADD
+%a[def/use] %c``. I.e., the register operand ``%a`` is both used and defined by
+the instruction.
+
+The SSA deconstruction phase
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An important transformation that happens during register allocation is called
+the *SSA Deconstruction Phase*. The SSA form simplifies many analyses that are
+performed on the control flow graph of programs. However, traditional
+instruction sets do not implement PHI instructions. Thus, in order to generate
+executable code, compilers must replace PHI instructions with other instructions
+that preserve their semantics.
+
+There are many ways in which PHI instructions can safely be removed from the
+target code. The most traditional PHI deconstruction algorithm replaces PHI
+instructions with copy instructions. That is the strategy adopted by LLVM. The
+SSA deconstruction algorithm is implemented in
+``lib/CodeGen/PHIElimination.cpp``. In order to invoke this pass, the identifier
+``PHIEliminationID`` must be marked as required in the code of the register
+allocator.
+
+Instruction folding
+^^^^^^^^^^^^^^^^^^^
+
+*Instruction folding* is an optimization performed during register allocation
+that removes unnecessary copy instructions. For instance, a sequence of
+instructions such as:
+
+::
+
+ %EBX = LOAD %mem_address
+ %EAX = COPY %EBX
+
+can be safely substituted by the single instruction:
+
+::
+
+ %EAX = LOAD %mem_address
+
+Instructions can be folded with the
+``TargetRegisterInfo::foldMemoryOperand(...)`` method. Care must be taken when
+folding instructions; a folded instruction can be quite different from the
+original instruction. See ``LiveIntervals::addIntervalsForSpills`` in
+``lib/CodeGen/LiveIntervalAnalysis.cpp`` for an example of its use.
+
+Built in register allocators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The LLVM infrastructure provides the application developer with three different
+register allocators:
+
+* *Fast* --- This register allocator is the default for debug builds. It
+ allocates registers on a basic block level, attempting to keep values in
+ registers and reusing registers as appropriate.
+
+* *Basic* --- This is an incremental approach to register allocation. Live
+ ranges are assigned to registers one at a time in an order that is driven by
+ heuristics. Since code can be rewritten on-the-fly during allocation, this
+ framework allows interesting allocators to be developed as extensions. It is
+ not itself a production register allocator but is a potentially useful
+ stand-alone mode for triaging bugs and as a performance baseline.
+
+* *Greedy* --- *The default allocator*. This is a highly tuned implementation of
+ the *Basic* allocator that incorporates global live range splitting. This
+ allocator works hard to minimize the cost of spill code.
+
+* *PBQP* --- A Partitioned Boolean Quadratic Programming (PBQP) based register
+ allocator. This allocator works by constructing a PBQP problem representing
+ the register allocation problem under consideration, solving this using a PBQP
+ solver, and mapping the solution back to a register assignment.
+
+The type of register allocator used in ``llc`` can be chosen with the command
+line option ``-regalloc=...``:
+
+.. code-block:: bash
+
+ $ llc -regalloc=linearscan file.bc -o ln.s
+ $ llc -regalloc=fast file.bc -o fa.s
+ $ llc -regalloc=pbqp file.bc -o pbqp.s
+
+.. _Prolog/Epilog Code Insertion:
+
+Prolog/Epilog Code Insertion
+----------------------------
+
+Compact Unwind
+
+Throwing an exception requires *unwinding* out of a function. The information on
+how to unwind a given function is traditionally expressed in DWARF unwind
+(a.k.a. frame) info. But that format was originally developed for debuggers to
+backtrace, and each Frame Description Entry (FDE) requires ~20-30 bytes per
+function. There is also the cost of mapping from an address in a function to the
+corresponding FDE at runtime. An alternative unwind encoding is called *compact
+unwind* and requires just 4-bytes per function.
+
+The compact unwind encoding is a 32-bit value, which is encoded in an
+architecture-specific way. It specifies which registers to restore and from
+where, and how to unwind out of the function. When the linker creates a final
+linked image, it will create a ``__TEXT,__unwind_info`` section. This section is
+a small and fast way for the runtime to access unwind info for any given
+function. If we emit compact unwind info for the function, that compact unwind
+info will be encoded in the ``__TEXT,__unwind_info`` section. If we emit DWARF
+unwind info, the ``__TEXT,__unwind_info`` section will contain the offset of the
+FDE in the ``__TEXT,__eh_frame`` section in the final linked image.
+
+For X86, there are three modes for the compact unwind encoding:
+
+*Function with a Frame Pointer (``EBP`` or ``RBP``)*
+ ``EBP/RBP``-based frame, where ``EBP/RBP`` is pushed onto the stack
+ immediately after the return address, then ``ESP/RSP`` is moved to
+ ``EBP/RBP``. Thus to unwind, ``ESP/RSP`` is restored with the current
+ ``EBP/RBP`` value, then ``EBP/RBP`` is restored by popping the stack, and the
+ return is done by popping the stack once more into the PC. All non-volatile
+ registers that need to be restored must have been saved in a small range on
+ the stack that starts ``EBP-4`` to ``EBP-1020`` (``RBP-8`` to
+ ``RBP-1020``). The offset (divided by 4 in 32-bit mode and 8 in 64-bit mode)
+ is encoded in bits 16-23 (mask: ``0x00FF0000``). The registers saved are
+ encoded in bits 0-14 (mask: ``0x00007FFF``) as five 3-bit entries from the
+ following table:
+
+ ============== ============= ===============
+ Compact Number i386 Register x86-64 Register
+ ============== ============= ===============
+ 1 ``EBX`` ``RBX``
+ 2 ``ECX`` ``R12``
+ 3 ``EDX`` ``R13``
+ 4 ``EDI`` ``R14``
+ 5 ``ESI`` ``R15``
+ 6 ``EBP`` ``RBP``
+ ============== ============= ===============
+
+*Frameless with a Small Constant Stack Size (``EBP`` or ``RBP`` is not used as a frame pointer)*
+ To return, a constant (encoded in the compact unwind encoding) is added to the
+ ``ESP/RSP``. Then the return is done by popping the stack into the PC. All
+ non-volatile registers that need to be restored must have been saved on the
+ stack immediately after the return address. The stack size (divided by 4 in
+ 32-bit mode and 8 in 64-bit mode) is encoded in bits 16-23 (mask:
+ ``0x00FF0000``). There is a maximum stack size of 1024 bytes in 32-bit mode
+ and 2048 in 64-bit mode. The number of registers saved is encoded in bits 9-12
+ (mask: ``0x00001C00``). Bits 0-9 (mask: ``0x000003FF``) contain which
+ registers were saved and their order. (See the
+ ``encodeCompactUnwindRegistersWithoutFrame()`` function in
+ ``lib/Target/X86FrameLowering.cpp`` for the encoding algorithm.)
+
+*Frameless with a Large Constant Stack Size (``EBP`` or ``RBP`` is not used as a frame pointer)*
+ This case is like the "Frameless with a Small Constant Stack Size" case, but
+ the stack size is too large to encode in the compact unwind encoding. Instead
+ it requires that the function contains "``subl $nnnnnn, %esp``" in its
+ prolog. The compact encoding contains the offset to the ``$nnnnnn`` value in
+ the function in bits 9-12 (mask: ``0x00001C00``).
+
+.. _Late Machine Code Optimizations:
+
+Late Machine Code Optimizations
+-------------------------------
+
+.. note::
+
+ To Be Written
+
+.. _Code Emission:
+
+Code Emission
+-------------
+
+The code emission step of code generation is responsible for lowering from the
+code generator abstractions (like `MachineFunction`_, `MachineInstr`_, etc) down
+to the abstractions used by the MC layer (`MCInst`_, `MCStreamer`_, etc). This
+is done with a combination of several different classes: the (misnamed)
+target-independent AsmPrinter class, target-specific subclasses of AsmPrinter
+(such as SparcAsmPrinter), and the TargetLoweringObjectFile class.
+
+Since the MC layer works at the level of abstraction of object files, it doesn't
+have a notion of functions, global variables etc. Instead, it thinks about
+labels, directives, and instructions. A key class used at this time is the
+MCStreamer class. This is an abstract API that is implemented in different ways
+(e.g. to output a .s file, output an ELF .o file, etc) that is effectively an
+"assembler API". MCStreamer has one method per directive, such as EmitLabel,
+EmitSymbolAttribute, SwitchSection, etc, which directly correspond to assembly
+level directives.
+
+If you are interested in implementing a code generator for a target, there are
+three important things that you have to implement for your target:
+
+#. First, you need a subclass of AsmPrinter for your target. This class
+ implements the general lowering process converting MachineFunction's into MC
+ label constructs. The AsmPrinter base class provides a number of useful
+ methods and routines, and also allows you to override the lowering process in
+ some important ways. You should get much of the lowering for free if you are
+ implementing an ELF, COFF, or MachO target, because the
+ TargetLoweringObjectFile class implements much of the common logic.
+
+#. Second, you need to implement an instruction printer for your target. The
+ instruction printer takes an `MCInst`_ and renders it to a raw_ostream as
+ text. Most of this is automatically generated from the .td file (when you
+ specify something like "``add $dst, $src1, $src2``" in the instructions), but
+ you need to implement routines to print operands.
+
+#. Third, you need to implement code that lowers a `MachineInstr`_ to an MCInst,
+ usually implemented in "<target>MCInstLower.cpp". This lowering process is
+ often target specific, and is responsible for turning jump table entries,
+ constant pool indices, global variable addresses, etc into MCLabels as
+ appropriate. This translation layer is also responsible for expanding pseudo
+ ops used by the code generator into the actual machine instructions they
+ correspond to. The MCInsts that are generated by this are fed into the
+ instruction printer or the encoder.
+
+Finally, at your choosing, you can also implement a subclass of MCCodeEmitter
+which lowers MCInst's into machine code bytes and relocations. This is
+important if you want to support direct .o file emission, or would like to
+implement an assembler for your target.
+
+VLIW Packetizer
+---------------
+
+In a Very Long Instruction Word (VLIW) architecture, the compiler is responsible
+for mapping instructions to functional-units available on the architecture. To
+that end, the compiler creates groups of instructions called *packets* or
+*bundles*. The VLIW packetizer in LLVM is a target-independent mechanism to
+enable the packetization of machine instructions.
+
+Mapping from instructions to functional units
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Instructions in a VLIW target can typically be mapped to multiple functional
+units. During the process of packetizing, the compiler must be able to reason
+about whether an instruction can be added to a packet. This decision can be
+complex since the compiler has to examine all possible mappings of instructions
+to functional units. Therefore to alleviate compilation-time complexity, the
+VLIW packetizer parses the instruction classes of a target and generates tables
+at compiler build time. These tables can then be queried by the provided
+machine-independent API to determine if an instruction can be accommodated in a
+packet.
+
+How the packetization tables are generated and used
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The packetizer reads instruction classes from a target's itineraries and creates
+a deterministic finite automaton (DFA) to represent the state of a packet. A DFA
+consists of three major elements: inputs, states, and transitions. The set of
+inputs for the generated DFA represents the instruction being added to a
+packet. The states represent the possible consumption of functional units by
+instructions in a packet. In the DFA, transitions from one state to another
+occur on the addition of an instruction to an existing packet. If there is a
+legal mapping of functional units to instructions, then the DFA contains a
+corresponding transition. The absence of a transition indicates that a legal
+mapping does not exist and that the instruction cannot be added to the packet.
+
+To generate tables for a VLIW target, add *Target*\ GenDFAPacketizer.inc as a
+target to the Makefile in the target directory. The exported API provides three
+functions: ``DFAPacketizer::clearResources()``,
+``DFAPacketizer::reserveResources(MachineInstr *MI)``, and
+``DFAPacketizer::canReserveResources(MachineInstr *MI)``. These functions allow
+a target packetizer to add an instruction to an existing packet and to check
+whether an instruction can be added to a packet. See
+``llvm/CodeGen/DFAPacketizer.h`` for more information.
+
+Implementing a Native Assembler
+===============================
+
+Though you're probably reading this because you want to write or maintain a
+compiler backend, LLVM also fully supports building a native assembler.
+We've tried hard to automate the generation of the assembler from the .td files
+(in particular the instruction syntax and encodings), which means that a large
+part of the manual and repetitive data entry can be factored and shared with the
+compiler.
+
+Instruction Parsing
+-------------------
+
+.. note::
+
+ To Be Written
+
+
+Instruction Alias Processing
+----------------------------
+
+Once the instruction is parsed, it enters the MatchInstructionImpl function.
+The MatchInstructionImpl function performs alias processing and then does actual
+matching.
+
+Alias processing is the phase that canonicalizes different lexical forms of the
+same instructions down to one representation. There are several different kinds
+of alias that are possible to implement and they are listed below in the order
+that they are processed (which is in order from simplest/weakest to most
+complex/powerful). Generally you want to use the first alias mechanism that
+meets the needs of your instruction, because it will allow a more concise
+description.
+
+Mnemonic Aliases
+^^^^^^^^^^^^^^^^
+
+The first phase of alias processing is simple instruction mnemonic remapping for
+classes of instructions which are allowed with two different mnemonics. This
+phase is a simple and unconditionally remapping from one input mnemonic to one
+output mnemonic. It isn't possible for this form of alias to look at the
+operands at all, so the remapping must apply for all forms of a given mnemonic.
+Mnemonic aliases are defined simply, for example X86 has:
+
+::
+
+ def : MnemonicAlias<"cbw", "cbtw">;
+ def : MnemonicAlias<"smovq", "movsq">;
+ def : MnemonicAlias<"fldcww", "fldcw">;
+ def : MnemonicAlias<"fucompi", "fucomip">;
+ def : MnemonicAlias<"ud2a", "ud2">;
+
+... and many others. With a MnemonicAlias definition, the mnemonic is remapped
+simply and directly. Though MnemonicAlias's can't look at any aspect of the
+instruction (such as the operands) they can depend on global modes (the same
+ones supported by the matcher), through a Requires clause:
+
+::
+
+ def : MnemonicAlias<"pushf", "pushfq">, Requires<[In64BitMode]>;
+ def : MnemonicAlias<"pushf", "pushfl">, Requires<[In32BitMode]>;
+
+In this example, the mnemonic gets mapped into a different one depending on
+the current instruction set.
+
+Instruction Aliases
+^^^^^^^^^^^^^^^^^^^
+
+The most general phase of alias processing occurs while matching is happening:
+it provides new forms for the matcher to match along with a specific instruction
+to generate. An instruction alias has two parts: the string to match and the
+instruction to generate. For example:
+
+::
+
+ def : InstAlias<"movsx $src, $dst", (MOVSX16rr8W GR16:$dst, GR8 :$src)>;
+ def : InstAlias<"movsx $src, $dst", (MOVSX16rm8W GR16:$dst, i8mem:$src)>;
+ def : InstAlias<"movsx $src, $dst", (MOVSX32rr8 GR32:$dst, GR8 :$src)>;
+ def : InstAlias<"movsx $src, $dst", (MOVSX32rr16 GR32:$dst, GR16 :$src)>;
+ def : InstAlias<"movsx $src, $dst", (MOVSX64rr8 GR64:$dst, GR8 :$src)>;
+ def : InstAlias<"movsx $src, $dst", (MOVSX64rr16 GR64:$dst, GR16 :$src)>;
+ def : InstAlias<"movsx $src, $dst", (MOVSX64rr32 GR64:$dst, GR32 :$src)>;
+
+This shows a powerful example of the instruction aliases, matching the same
+mnemonic in multiple different ways depending on what operands are present in
+the assembly. The result of instruction aliases can include operands in a
+different order than the destination instruction, and can use an input multiple
+times, for example:
+
+::
+
+ def : InstAlias<"clrb $reg", (XOR8rr GR8 :$reg, GR8 :$reg)>;
+ def : InstAlias<"clrw $reg", (XOR16rr GR16:$reg, GR16:$reg)>;
+ def : InstAlias<"clrl $reg", (XOR32rr GR32:$reg, GR32:$reg)>;
+ def : InstAlias<"clrq $reg", (XOR64rr GR64:$reg, GR64:$reg)>;
+
+This example also shows that tied operands are only listed once. In the X86
+backend, XOR8rr has two input GR8's and one output GR8 (where an input is tied
+to the output). InstAliases take a flattened operand list without duplicates
+for tied operands. The result of an instruction alias can also use immediates
+and fixed physical registers which are added as simple immediate operands in the
+result, for example:
+
+::
+
+ // Fixed Immediate operand.
+ def : InstAlias<"aad", (AAD8i8 10)>;
+
+ // Fixed register operand.
+ def : InstAlias<"fcomi", (COM_FIr ST1)>;
+
+ // Simple alias.
+ def : InstAlias<"fcomi $reg", (COM_FIr RST:$reg)>;
+
+Instruction aliases can also have a Requires clause to make them subtarget
+specific.
+
+If the back-end supports it, the instruction printer can automatically emit the
+alias rather than what's being aliased. It typically leads to better, more
+readable code. If it's better to print out what's being aliased, then pass a '0'
+as the third parameter to the InstAlias definition.
+
+Instruction Matching
+--------------------
+
+.. note::
+
+ To Be Written
+
+.. _Implementations of the abstract target description interfaces:
+.. _implement the target description:
+
+Target-specific Implementation Notes
+====================================
+
+This section of the document explains features or design decisions that are
+specific to the code generator for a particular target. First we start with a
+table that summarizes what features are supported by each target.
+
+.. _target-feature-matrix:
+
+Target Feature Matrix
+---------------------
+
+Note that this table does not include the C backend or Cpp backends, since they
+do not use the target independent code generator infrastructure. It also
+doesn't list features that are not supported fully by any target yet. It
+considers a feature to be supported if at least one subtarget supports it. A
+feature being supported means that it is useful and works for most cases, it
+does not indicate that there are zero known bugs in the implementation. Here is
+the key:
+
+:raw-html:`<table border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<th>Unknown</th>`
+:raw-html:`<th>Not Applicable</th>`
+:raw-html:`<th>No support</th>`
+:raw-html:`<th>Partial Support</th>`
+:raw-html:`<th>Complete Support</th>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td class="unknown"></td>`
+:raw-html:`<td class="na"></td>`
+:raw-html:`<td class="no"></td>`
+:raw-html:`<td class="partial"></td>`
+:raw-html:`<td class="yes"></td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+Here is the table:
+
+:raw-html:`<table width="689" border="1" cellspacing="0">`
+:raw-html:`<tr><td></td>`
+:raw-html:`<td colspan="13" align="center" style="background-color:#ffc">Target</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<th>Feature</th>`
+:raw-html:`<th>ARM</th>`
+:raw-html:`<th>Hexagon</th>`
+:raw-html:`<th>MSP430</th>`
+:raw-html:`<th>Mips</th>`
+:raw-html:`<th>NVPTX</th>`
+:raw-html:`<th>PowerPC</th>`
+:raw-html:`<th>Sparc</th>`
+:raw-html:`<th>SystemZ</th>`
+:raw-html:`<th>X86</th>`
+:raw-html:`<th>XCore</th>`
+:raw-html:`<th>eBPF</th>`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_reliable">is generally reliable</a></td>`
+:raw-html:`<td class="yes"></td> <!-- ARM -->`
+:raw-html:`<td class="yes"></td> <!-- Hexagon -->`
+:raw-html:`<td class="unknown"></td> <!-- MSP430 -->`
+:raw-html:`<td class="yes"></td> <!-- Mips -->`
+:raw-html:`<td class="yes"></td> <!-- NVPTX -->`
+:raw-html:`<td class="yes"></td> <!-- PowerPC -->`
+:raw-html:`<td class="yes"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="yes"></td> <!-- XCore -->`
+:raw-html:`<td class="yes"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_asmparser">assembly parser</a></td>`
+:raw-html:`<td class="no"></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="no"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="no"></td> <!-- NVPTX -->`
+:raw-html:`<td class="no"></td> <!-- PowerPC -->`
+:raw-html:`<td class="no"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="no"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_disassembler">disassembler</a></td>`
+:raw-html:`<td class="yes"></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="no"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="na"></td> <!-- NVPTX -->`
+:raw-html:`<td class="no"></td> <!-- PowerPC -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="no"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="yes"></td> <!-- XCore -->`
+:raw-html:`<td class="yes"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_inlineasm">inline asm</a></td>`
+:raw-html:`<td class="yes"></td> <!-- ARM -->`
+:raw-html:`<td class="yes"></td> <!-- Hexagon -->`
+:raw-html:`<td class="unknown"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="yes"></td> <!-- NVPTX -->`
+:raw-html:`<td class="yes"></td> <!-- PowerPC -->`
+:raw-html:`<td class="unknown"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="yes"></td> <!-- XCore -->`
+:raw-html:`<td class="no"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_jit">jit</a></td>`
+:raw-html:`<td class="partial"><a href="#feat_jit_arm">*</a></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="unknown"></td> <!-- MSP430 -->`
+:raw-html:`<td class="yes"></td> <!-- Mips -->`
+:raw-html:`<td class="na"></td> <!-- NVPTX -->`
+:raw-html:`<td class="yes"></td> <!-- PowerPC -->`
+:raw-html:`<td class="unknown"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="yes"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_objectwrite">.o file writing</a></td>`
+:raw-html:`<td class="no"></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="no"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="na"></td> <!-- NVPTX -->`
+:raw-html:`<td class="no"></td> <!-- PowerPC -->`
+:raw-html:`<td class="no"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="yes"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a hr:raw-html:`ef="#feat_tailcall">tail calls</a></td>`
+:raw-html:`<td class="yes"></td> <!-- ARM -->`
+:raw-html:`<td class="yes"></td> <!-- Hexagon -->`
+:raw-html:`<td class="unknown"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="no"></td> <!-- NVPTX -->`
+:raw-html:`<td class="yes"></td> <!-- PowerPC -->`
+:raw-html:`<td class="unknown"></td> <!-- Sparc -->`
+:raw-html:`<td class="no"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="no"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_segstacks">segmented stacks</a></td>`
+:raw-html:`<td class="no"></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="no"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="no"></td> <!-- NVPTX -->`
+:raw-html:`<td class="no"></td> <!-- PowerPC -->`
+:raw-html:`<td class="no"></td> <!-- Sparc -->`
+:raw-html:`<td class="no"></td> <!-- SystemZ -->`
+:raw-html:`<td class="partial"><a href="#feat_segstacks_x86">*</a></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="no"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`</table>`
+
+.. _feat_reliable:
+
+Is Generally Reliable
+^^^^^^^^^^^^^^^^^^^^^
+
+This box indicates whether the target is considered to be production quality.
+This indicates that the target has been used as a static compiler to compile
+large amounts of code by a variety of different people and is in continuous use.
+
+.. _feat_asmparser:
+
+Assembly Parser
+^^^^^^^^^^^^^^^
+
+This box indicates whether the target supports parsing target specific .s files
+by implementing the MCAsmParser interface. This is required for llvm-mc to be
+able to act as a native assembler and is required for inline assembly support in
+the native .o file writer.
+
+.. _feat_disassembler:
+
+Disassembler
+^^^^^^^^^^^^
+
+This box indicates whether the target supports the MCDisassembler API for
+disassembling machine opcode bytes into MCInst's.
+
+.. _feat_inlineasm:
+
+Inline Asm
+^^^^^^^^^^
+
+This box indicates whether the target supports most popular inline assembly
+constraints and modifiers.
+
+.. _feat_jit:
+
+JIT Support
+^^^^^^^^^^^
+
+This box indicates whether the target supports the JIT compiler through the
+ExecutionEngine interface.
+
+.. _feat_jit_arm:
+
+The ARM backend has basic support for integer code in ARM codegen mode, but
+lacks NEON and full Thumb support.
+
+.. _feat_objectwrite:
+
+.o File Writing
+^^^^^^^^^^^^^^^
+
+This box indicates whether the target supports writing .o files (e.g. MachO,
+ELF, and/or COFF) files directly from the target. Note that the target also
+must include an assembly parser and general inline assembly support for full
+inline assembly support in the .o writer.
+
+Targets that don't support this feature can obviously still write out .o files,
+they just rely on having an external assembler to translate from a .s file to a
+.o file (as is the case for many C compilers).
+
+.. _feat_tailcall:
+
+Tail Calls
+^^^^^^^^^^
+
+This box indicates whether the target supports guaranteed tail calls. These are
+calls marked "`tail <LangRef.html#i_call>`_" and use the fastcc calling
+convention. Please see the `tail call section`_ for more details.
+
+.. _feat_segstacks:
+
+Segmented Stacks
+^^^^^^^^^^^^^^^^
+
+This box indicates whether the target supports segmented stacks. This replaces
+the traditional large C stack with many linked segments. It is compatible with
+the `gcc implementation <http://gcc.gnu.org/wiki/SplitStacks>`_ used by the Go
+front end.
+
+.. _feat_segstacks_x86:
+
+Basic support exists on the X86 backend. Currently vararg doesn't work and the
+object files are not marked the way the gold linker expects, but simple Go
+programs can be built by dragonegg.
+
+.. _tail call section:
+
+Tail call optimization
+----------------------
+
+Tail call optimization, callee reusing the stack of the caller, is currently
+supported on x86/x86-64 and PowerPC. It is performed if:
+
+* Caller and callee have the calling convention ``fastcc``, ``cc 10`` (GHC
+ calling convention) or ``cc 11`` (HiPE calling convention).
+
+* The call is a tail call - in tail position (ret immediately follows call and
+ ret uses value of call or is void).
+
+* Option ``-tailcallopt`` is enabled.
+
+* Platform-specific constraints are met.
+
+x86/x86-64 constraints:
+
+* No variable argument lists are used.
+
+* On x86-64 when generating GOT/PIC code only module-local calls (visibility =
+ hidden or protected) are supported.
+
+PowerPC constraints:
+
+* No variable argument lists are used.
+
+* No byval parameters are used.
+
+* On ppc32/64 GOT/PIC only module-local calls (visibility = hidden or protected)
+ are supported.
+
+Example:
+
+Call as ``llc -tailcallopt test.ll``.
+
+.. code-block:: llvm
+
+ declare fastcc i32 @tailcallee(i32 inreg %a1, i32 inreg %a2, i32 %a3, i32 %a4)
+
+ define fastcc i32 @tailcaller(i32 %in1, i32 %in2) {
+ %l1 = add i32 %in1, %in2
+ %tmp = tail call fastcc i32 @tailcallee(i32 %in1 inreg, i32 %in2 inreg, i32 %in1, i32 %l1)
+ ret i32 %tmp
+ }
+
+Implications of ``-tailcallopt``:
+
+To support tail call optimization in situations where the callee has more
+arguments than the caller a 'callee pops arguments' convention is used. This
+currently causes each ``fastcc`` call that is not tail call optimized (because
+one or more of above constraints are not met) to be followed by a readjustment
+of the stack. So performance might be worse in such cases.
+
+Sibling call optimization
+-------------------------
+
+Sibling call optimization is a restricted form of tail call optimization.
+Unlike tail call optimization described in the previous section, it can be
+performed automatically on any tail calls when ``-tailcallopt`` option is not
+specified.
+
+Sibling call optimization is currently performed on x86/x86-64 when the
+following constraints are met:
+
+* Caller and callee have the same calling convention. It can be either ``c`` or
+ ``fastcc``.
+
+* The call is a tail call - in tail position (ret immediately follows call and
+ ret uses value of call or is void).
+
+* Caller and callee have matching return type or the callee result is not used.
+
+* If any of the callee arguments are being passed in stack, they must be
+ available in caller's own incoming argument stack and the frame offsets must
+ be the same.
+
+Example:
+
+.. code-block:: llvm
+
+ declare i32 @bar(i32, i32)
+
+ define i32 @foo(i32 %a, i32 %b, i32 %c) {
+ entry:
+ %0 = tail call i32 @bar(i32 %a, i32 %b)
+ ret i32 %0
+ }
+
+The X86 backend
+---------------
+
+The X86 code generator lives in the ``lib/Target/X86`` directory. This code
+generator is capable of targeting a variety of x86-32 and x86-64 processors, and
+includes support for ISA extensions such as MMX and SSE.
+
+X86 Target Triples supported
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following are the known target triples that are supported by the X86
+backend. This is not an exhaustive list, and it would be useful to add those
+that people test.
+
+* **i686-pc-linux-gnu** --- Linux
+
+* **i386-unknown-freebsd5.3** --- FreeBSD 5.3
+
+* **i686-pc-cygwin** --- Cygwin on Win32
+
+* **i686-pc-mingw32** --- MingW on Win32
+
+* **i386-pc-mingw32msvc** --- MingW crosscompiler on Linux
+
+* **i686-apple-darwin*** --- Apple Darwin on X86
+
+* **x86_64-unknown-linux-gnu** --- Linux
+
+X86 Calling Conventions supported
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following target-specific calling conventions are known to backend:
+
+* **x86_StdCall** --- stdcall calling convention seen on Microsoft Windows
+ platform (CC ID = 64).
+
+* **x86_FastCall** --- fastcall calling convention seen on Microsoft Windows
+ platform (CC ID = 65).
+
+* **x86_ThisCall** --- Similar to X86_StdCall. Passes first argument in ECX,
+ others via stack. Callee is responsible for stack cleaning. This convention is
+ used by MSVC by default for methods in its ABI (CC ID = 70).
+
+.. _X86 addressing mode:
+
+Representing X86 addressing modes in MachineInstrs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The x86 has a very flexible way of accessing memory. It is capable of forming
+memory addresses of the following expression directly in integer instructions
+(which use ModR/M addressing):
+
+::
+
+ SegmentReg: Base + [1,2,4,8] * IndexReg + Disp32
+
+In order to represent this, LLVM tracks no less than 5 operands for each memory
+operand of this form. This means that the "load" form of '``mov``' has the
+following ``MachineOperand``\s in this order:
+
+::
+
+ Index: 0 | 1 2 3 4 5
+ Meaning: DestReg, | BaseReg, Scale, IndexReg, Displacement Segment
+ OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg, SignExtImm PhysReg
+
+Stores, and all other instructions, treat the four memory operands in the same
+way and in the same order. If the segment register is unspecified (regno = 0),
+then no segment override is generated. "Lea" operations do not have a segment
+register specified, so they only have 4 operands for their memory reference.
+
+X86 address spaces supported
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+x86 has a feature which provides the ability to perform loads and stores to
+different address spaces via the x86 segment registers. A segment override
+prefix byte on an instruction causes the instruction's memory access to go to
+the specified segment. LLVM address space 0 is the default address space, which
+includes the stack, and any unqualified memory accesses in a program. Address
+spaces 1-255 are currently reserved for user-defined code. The GS-segment is
+represented by address space 256, while the FS-segment is represented by address
+space 257. Other x86 segments have yet to be allocated address space
+numbers.
+
+While these address spaces may seem similar to TLS via the ``thread_local``
+keyword, and often use the same underlying hardware, there are some fundamental
+differences.
+
+The ``thread_local`` keyword applies to global variables and specifies that they
+are to be allocated in thread-local memory. There are no type qualifiers
+involved, and these variables can be pointed to with normal pointers and
+accessed with normal loads and stores. The ``thread_local`` keyword is
+target-independent at the LLVM IR level (though LLVM doesn't yet have
+implementations of it for some configurations)
+
+Special address spaces, in contrast, apply to static types. Every load and store
+has a particular address space in its address operand type, and this is what
+determines which address space is accessed. LLVM ignores these special address
+space qualifiers on global variables, and does not provide a way to directly
+allocate storage in them. At the LLVM IR level, the behavior of these special
+address spaces depends in part on the underlying OS or runtime environment, and
+they are specific to x86 (and LLVM doesn't yet handle them correctly in some
+cases).
+
+Some operating systems and runtime environments use (or may in the future use)
+the FS/GS-segment registers for various low-level purposes, so care should be
+taken when considering them.
+
+Instruction naming
+^^^^^^^^^^^^^^^^^^
+
+An instruction name consists of the base name, a default operand size, and a a
+character per operand with an optional special size. For example:
+
+::
+
+ ADD8rr -> add, 8-bit register, 8-bit register
+ IMUL16rmi -> imul, 16-bit register, 16-bit memory, 16-bit immediate
+ IMUL16rmi8 -> imul, 16-bit register, 16-bit memory, 8-bit immediate
+ MOVSX32rm16 -> movsx, 32-bit register, 16-bit memory
+
+The PowerPC backend
+-------------------
+
+The PowerPC code generator lives in the lib/Target/PowerPC directory. The code
+generation is retargetable to several variations or *subtargets* of the PowerPC
+ISA; including ppc32, ppc64 and altivec.
+
+LLVM PowerPC ABI
+^^^^^^^^^^^^^^^^
+
+LLVM follows the AIX PowerPC ABI, with two deviations. LLVM uses a PC relative
+(PIC) or static addressing for accessing global values, so no TOC (r2) is
+used. Second, r31 is used as a frame pointer to allow dynamic growth of a stack
+frame. LLVM takes advantage of having no TOC to provide space to save the frame
+pointer in the PowerPC linkage area of the caller frame. Other details of
+PowerPC ABI can be found at `PowerPC ABI
+<http://developer.apple.com/documentation/DeveloperTools/Conceptual/LowLevelABI/Articles/32bitPowerPC.html>`_\
+. Note: This link describes the 32 bit ABI. The 64 bit ABI is similar except
+space for GPRs are 8 bytes wide (not 4) and r13 is reserved for system use.
+
+Frame Layout
+^^^^^^^^^^^^
+
+The size of a PowerPC frame is usually fixed for the duration of a function's
+invocation. Since the frame is fixed size, all references into the frame can be
+accessed via fixed offsets from the stack pointer. The exception to this is
+when dynamic alloca or variable sized arrays are present, then a base pointer
+(r31) is used as a proxy for the stack pointer and stack pointer is free to grow
+or shrink. A base pointer is also used if llvm-gcc is not passed the
+-fomit-frame-pointer flag. The stack pointer is always aligned to 16 bytes, so
+that space allocated for altivec vectors will be properly aligned.
+
+An invocation frame is laid out as follows (low memory at top):
+
+:raw-html:`<table border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<td>Linkage<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Parameter area<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Dynamic area<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Locals area<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Saved registers area<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr style="border-style: none hidden none hidden;">`
+:raw-html:`<td><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Previous Frame<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+The *linkage* area is used by a callee to save special registers prior to
+allocating its own frame. Only three entries are relevant to LLVM. The first
+entry is the previous stack pointer (sp), aka link. This allows probing tools
+like gdb or exception handlers to quickly scan the frames in the stack. A
+function epilog can also use the link to pop the frame from the stack. The
+third entry in the linkage area is used to save the return address from the lr
+register. Finally, as mentioned above, the last entry is used to save the
+previous frame pointer (r31.) The entries in the linkage area are the size of a
+GPR, thus the linkage area is 24 bytes long in 32 bit mode and 48 bytes in 64
+bit mode.
+
+32 bit linkage area:
+
+:raw-html:`<table border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<td>0</td>`
+:raw-html:`<td>Saved SP (r1)</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>4</td>`
+:raw-html:`<td>Saved CR</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>8</td>`
+:raw-html:`<td>Saved LR</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>12</td>`
+:raw-html:`<td>Reserved</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>16</td>`
+:raw-html:`<td>Reserved</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>20</td>`
+:raw-html:`<td>Saved FP (r31)</td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+64 bit linkage area:
+
+:raw-html:`<table border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<td>0</td>`
+:raw-html:`<td>Saved SP (r1)</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>8</td>`
+:raw-html:`<td>Saved CR</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>16</td>`
+:raw-html:`<td>Saved LR</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>24</td>`
+:raw-html:`<td>Reserved</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>32</td>`
+:raw-html:`<td>Reserved</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>40</td>`
+:raw-html:`<td>Saved FP (r31)</td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+The *parameter area* is used to store arguments being passed to a callee
+function. Following the PowerPC ABI, the first few arguments are actually
+passed in registers, with the space in the parameter area unused. However, if
+there are not enough registers or the callee is a thunk or vararg function,
+these register arguments can be spilled into the parameter area. Thus, the
+parameter area must be large enough to store all the parameters for the largest
+call sequence made by the caller. The size must also be minimally large enough
+to spill registers r3-r10. This allows callees blind to the call signature,
+such as thunks and vararg functions, enough space to cache the argument
+registers. Therefore, the parameter area is minimally 32 bytes (64 bytes in 64
+bit mode.) Also note that since the parameter area is a fixed offset from the
+top of the frame, that a callee can access its spilt arguments using fixed
+offsets from the stack pointer (or base pointer.)
+
+Combining the information about the linkage, parameter areas and alignment. A
+stack frame is minimally 64 bytes in 32 bit mode and 128 bytes in 64 bit mode.
+
+The *dynamic area* starts out as size zero. If a function uses dynamic alloca
+then space is added to the stack, the linkage and parameter areas are shifted to
+top of stack, and the new space is available immediately below the linkage and
+parameter areas. The cost of shifting the linkage and parameter areas is minor
+since only the link value needs to be copied. The link value can be easily
+fetched by adding the original frame size to the base pointer. Note that
+allocations in the dynamic space need to observe 16 byte alignment.
+
+The *locals area* is where the llvm compiler reserves space for local variables.
+
+The *saved registers area* is where the llvm compiler spills callee saved
+registers on entry to the callee.
+
+Prolog/Epilog
+^^^^^^^^^^^^^
+
+The llvm prolog and epilog are the same as described in the PowerPC ABI, with
+the following exceptions. Callee saved registers are spilled after the frame is
+created. This allows the llvm epilog/prolog support to be common with other
+targets. The base pointer callee saved register r31 is saved in the TOC slot of
+linkage area. This simplifies allocation of space for the base pointer and
+makes it convenient to locate programatically and during debugging.
+
+Dynamic Allocation
+^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+ TODO - More to come.
+
+The NVPTX backend
+-----------------
+
+The NVPTX code generator under lib/Target/NVPTX is an open-source version of
+the NVIDIA NVPTX code generator for LLVM. It is contributed by NVIDIA and is
+a port of the code generator used in the CUDA compiler (nvcc). It targets the
+PTX 3.0/3.1 ISA and can target any compute capability greater than or equal to
+2.0 (Fermi).
+
+This target is of production quality and should be completely compatible with
+the official NVIDIA toolchain.
+
+Code Generator Options:
+
+:raw-html:`<table border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<th>Option</th>`
+:raw-html:`<th>Description</th>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>sm_20</td>`
+:raw-html:`<td align="left">Set shader model/compute capability to 2.0</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>sm_21</td>`
+:raw-html:`<td align="left">Set shader model/compute capability to 2.1</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>sm_30</td>`
+:raw-html:`<td align="left">Set shader model/compute capability to 3.0</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>sm_35</td>`
+:raw-html:`<td align="left">Set shader model/compute capability to 3.5</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>ptx30</td>`
+:raw-html:`<td align="left">Target PTX 3.0</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>ptx31</td>`
+:raw-html:`<td align="left">Target PTX 3.1</td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+The extended Berkeley Packet Filter (eBPF) backend
+--------------------------------------------------
+
+Extended BPF (or eBPF) is similar to the original ("classic") BPF (cBPF) used
+to filter network packets. The
+`bpf() system call <http://man7.org/linux/man-pages/man2/bpf.2.html>`_
+performs a range of operations related to eBPF. For both cBPF and eBPF
+programs, the Linux kernel statically analyzes the programs before loading
+them, in order to ensure that they cannot harm the running system. eBPF is
+a 64-bit RISC instruction set designed for one to one mapping to 64-bit CPUs.
+Opcodes are 8-bit encoded, and 87 instructions are defined. There are 10
+registers, grouped by function as outlined below.
+
+::
+
+ R0 return value from in-kernel functions; exit value for eBPF program
+ R1 - R5 function call arguments to in-kernel functions
+ R6 - R9 callee-saved registers preserved by in-kernel functions
+ R10 stack frame pointer (read only)
+
+Instruction encoding (arithmetic and jump)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+eBPF is reusing most of the opcode encoding from classic to simplify conversion
+of classic BPF to eBPF. For arithmetic and jump instructions the 8-bit 'code'
+field is divided into three parts:
+
+::
+
+ +----------------+--------+--------------------+
+ | 4 bits | 1 bit | 3 bits |
+ | operation code | source | instruction class |
+ +----------------+--------+--------------------+
+ (MSB) (LSB)
+
+Three LSB bits store instruction class which is one of:
+
+::
+
+ BPF_LD 0x0
+ BPF_LDX 0x1
+ BPF_ST 0x2
+ BPF_STX 0x3
+ BPF_ALU 0x4
+ BPF_JMP 0x5
+ (unused) 0x6
+ BPF_ALU64 0x7
+
+When BPF_CLASS(code) == BPF_ALU or BPF_ALU64 or BPF_JMP,
+4th bit encodes source operand
+
+::
+
+ BPF_X 0x0 use src_reg register as source operand
+ BPF_K 0x1 use 32 bit immediate as source operand
+
+and four MSB bits store operation code
+
+::
+
+ BPF_ADD 0x0 add
+ BPF_SUB 0x1 subtract
+ BPF_MUL 0x2 multiply
+ BPF_DIV 0x3 divide
+ BPF_OR 0x4 bitwise logical OR
+ BPF_AND 0x5 bitwise logical AND
+ BPF_LSH 0x6 left shift
+ BPF_RSH 0x7 right shift (zero extended)
+ BPF_NEG 0x8 arithmetic negation
+ BPF_MOD 0x9 modulo
+ BPF_XOR 0xa bitwise logical XOR
+ BPF_MOV 0xb move register to register
+ BPF_ARSH 0xc right shift (sign extended)
+ BPF_END 0xd endianness conversion
+
+If BPF_CLASS(code) == BPF_JMP, BPF_OP(code) is one of
+
+::
+
+ BPF_JA 0x0 unconditional jump
+ BPF_JEQ 0x1 jump ==
+ BPF_JGT 0x2 jump >
+ BPF_JGE 0x3 jump >=
+ BPF_JSET 0x4 jump if (DST & SRC)
+ BPF_JNE 0x5 jump !=
+ BPF_JSGT 0x6 jump signed >
+ BPF_JSGE 0x7 jump signed >=
+ BPF_CALL 0x8 function call
+ BPF_EXIT 0x9 function return
+
+Instruction encoding (load, store)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For load and store instructions the 8-bit 'code' field is divided as:
+
+::
+
+ +--------+--------+-------------------+
+ | 3 bits | 2 bits | 3 bits |
+ | mode | size | instruction class |
+ +--------+--------+-------------------+
+ (MSB) (LSB)
+
+Size modifier is one of
+
+::
+
+ BPF_W 0x0 word
+ BPF_H 0x1 half word
+ BPF_B 0x2 byte
+ BPF_DW 0x3 double word
+
+Mode modifier is one of
+
+::
+
+ BPF_IMM 0x0 immediate
+ BPF_ABS 0x1 used to access packet data
+ BPF_IND 0x2 used to access packet data
+ BPF_MEM 0x3 memory
+ (reserved) 0x4
+ (reserved) 0x5
+ BPF_XADD 0x6 exclusive add
+
+
+Packet data access (BPF_ABS, BPF_IND)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Two non-generic instructions: (BPF_ABS | <size> | BPF_LD) and
+(BPF_IND | <size> | BPF_LD) which are used to access packet data.
+Register R6 is an implicit input that must contain pointer to sk_buff.
+Register R0 is an implicit output which contains the data fetched
+from the packet. Registers R1-R5 are scratch registers and must not
+be used to store the data across BPF_ABS | BPF_LD or BPF_IND | BPF_LD
+instructions. These instructions have implicit program exit condition
+as well. When eBPF program is trying to access the data beyond
+the packet boundary, the interpreter will abort the execution of the program.
+
+BPF_IND | BPF_W | BPF_LD is equivalent to:
+ R0 = ntohl(\*(u32 \*) (((struct sk_buff \*) R6)->data + src_reg + imm32))
+
+eBPF maps
+^^^^^^^^^
+
+eBPF maps are provided for sharing data between kernel and user-space.
+Currently implemented types are hash and array, with potential extension to
+support bloom filters, radix trees, etc. A map is defined by its type,
+maximum number of elements, key size and value size in bytes. eBPF syscall
+supports create, update, find and delete functions on maps.
+
+Function calls
+^^^^^^^^^^^^^^
+
+Function call arguments are passed using up to five registers (R1 - R5).
+The return value is passed in a dedicated register (R0). Four additional
+registers (R6 - R9) are callee-saved, and the values in these registers
+are preserved within kernel functions. R0 - R5 are scratch registers within
+kernel functions, and eBPF programs must therefor store/restore values in
+these registers if needed across function calls. The stack can be accessed
+using the read-only frame pointer R10. eBPF registers map 1:1 to hardware
+registers on x86_64 and other 64-bit architectures. For example, x86_64
+in-kernel JIT maps them as
+
+::
+
+ R0 - rax
+ R1 - rdi
+ R2 - rsi
+ R3 - rdx
+ R4 - rcx
+ R5 - r8
+ R6 - rbx
+ R7 - r13
+ R8 - r14
+ R9 - r15
+ R10 - rbp
+
+since x86_64 ABI mandates rdi, rsi, rdx, rcx, r8, r9 for argument passing
+and rbx, r12 - r15 are callee saved.
+
+Program start
+^^^^^^^^^^^^^
+
+An eBPF program receives a single argument and contains
+a single eBPF main routine; the program does not contain eBPF functions.
+Function calls are limited to a predefined set of kernel functions. The size
+of a program is limited to 4K instructions: this ensures fast termination and
+a limited number of kernel function calls. Prior to running an eBPF program,
+a verifier performs static analysis to prevent loops in the code and
+to ensure valid register usage and operand types.
More information about the llvm-commits
mailing list