[www-releases] r356539 - Check in the 8.0.0 release
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Wed Mar 20 02:13:34 PDT 2019
Added: www-releases/trunk/8.0.0/docs/ExtendingLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/ExtendingLLVM.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/ExtendingLLVM.html (added)
+++ www-releases/trunk/8.0.0/docs/ExtendingLLVM.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,364 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Extending LLVM: Adding instructions, intrinsics, types, etc. — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="How to set up LLVM-style RTTI for your class hierarchy" href="HowToSetUpLLVMStyleRTTI.html" />
+ <link rel="prev" title="Architecture & Platform Information for Compiler Writers" href="CompilerWriterInfo.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="extending-llvm-adding-instructions-intrinsics-types-etc">
+<h1>Extending LLVM: Adding instructions, intrinsics, types, etc.<a class="headerlink" href="#extending-llvm-adding-instructions-intrinsics-types-etc" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction-and-warning">
+<h2>Introduction and Warning<a class="headerlink" href="#introduction-and-warning" title="Permalink to this headline">¶</a></h2>
+<p>During the course of using LLVM, you may wish to customize it for your research
+project or for experimentation. At this point, you may realize that you need to
+add something to LLVM, whether it be a new fundamental type, a new intrinsic
+function, or a whole new instruction.</p>
+<p>When you come to this realization, stop and think. Do you really need to extend
+LLVM? Is it a new fundamental capability that LLVM does not support at its
+current incarnation or can it be synthesized from already pre-existing LLVM
+elements? If you are not sure, ask on the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">LLVM-dev</a> list. The reason is that
+extending LLVM will get involved as you need to update all the different passes
+that you intend to use with your extension, and there are <code class="docutils literal notranslate"><span class="pre">many</span></code> LLVM analyses
+and transformations, so it may be quite a bit of work.</p>
+<p>Adding an <a class="reference internal" href="#intrinsic-function">intrinsic function</a> is far easier than adding an
+instruction, and is transparent to optimization passes. If your added
+functionality can be expressed as a function call, an intrinsic function is the
+method of choice for LLVM extension.</p>
+<p>Before you invest a significant amount of effort into a non-trivial extension,
+<strong>ask on the list</strong> if what you are looking to do can be done with
+already-existing infrastructure, or if maybe someone else is already working on
+it. You will save yourself a lot of time and effort by doing so.</p>
+</div>
+<div class="section" id="adding-a-new-intrinsic-function">
+<span id="intrinsic-function"></span><h2>Adding a new intrinsic function<a class="headerlink" href="#adding-a-new-intrinsic-function" title="Permalink to this headline">¶</a></h2>
+<p>Adding a new intrinsic function to LLVM is much easier than adding a new
+instruction. Almost all extensions to LLVM should start as an intrinsic
+function and then be turned into an instruction if warranted.</p>
+<ol class="arabic">
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/docs/LangRef.html</span></code>:</p>
+<p>Document the intrinsic. Decide whether it is code generator specific and
+what the restrictions are. Talk to other people about it so that you are
+sure itâs a good idea.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Intrinsics*.td</span></code>:</p>
+<p>Add an entry for your intrinsic. Describe its memory access characteristics
+for optimization (this controls whether it will be DCEâd, CSEâd, etc). Note
+that any intrinsic using one of the <code class="docutils literal notranslate"><span class="pre">llvm_any*_ty</span></code> types for an argument or
+return type will be deemed by <code class="docutils literal notranslate"><span class="pre">tblgen</span></code> as overloaded and the corresponding
+suffix will be required on the intrinsicâs name.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Analysis/ConstantFolding.cpp</span></code>:</p>
+<p>If it is possible to constant fold your intrinsic, add support to it in the
+<code class="docutils literal notranslate"><span class="pre">canConstantFoldCallTo</span></code> and <code class="docutils literal notranslate"><span class="pre">ConstantFoldCall</span></code> functions.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/test/*</span></code>:</p>
+<p>Add test cases for your test cases to the test suite</p>
+</li>
+</ol>
+<p>Once the intrinsic has been added to the system, you must add code generator
+support for it. Generally you must do the following steps:</p>
+<p>Add support to the .td file for the target(s) of your choice in
+<code class="docutils literal notranslate"><span class="pre">lib/Target/*/*.td</span></code>.</p>
+<blockquote>
+<div>This is usually a matter of adding a pattern to the .td file that matches the
+intrinsic, though it may obviously require adding the instructions you want to
+generate as well. There are lots of examples in the PowerPC and X86 backend
+to follow.</div></blockquote>
+</div>
+<div class="section" id="adding-a-new-selectiondag-node">
+<h2>Adding a new SelectionDAG node<a class="headerlink" href="#adding-a-new-selectiondag-node" title="Permalink to this headline">¶</a></h2>
+<p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier than
+adding a new instruction. New nodes are often added to help represent
+instructions common to many targets. These nodes often map to an LLVM
+instruction (add, sub) or intrinsic (byteswap, population count). In other
+cases, new nodes have been added to allow many targets to perform a common task
+(converting between floating point and integer representation) or capture more
+complicated behavior in a single node (rotate).</p>
+<ol class="arabic">
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">include/llvm/CodeGen/ISDOpcodes.h</span></code>:</p>
+<p>Add an enum value for the new SelectionDAG node.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/SelectionDAG.cpp</span></code>:</p>
+<dl class="docutils">
+<dt>Add code to print the node to <code class="docutils literal notranslate"><span class="pre">getOperationName</span></code>. If your new node can be</dt>
+<dd><p class="first last">evaluated at compile time when given constant arguments (such as an add of a
+constant with another constant), find the <code class="docutils literal notranslate"><span class="pre">getNode</span></code> method that takes the
+appropriate number of arguments, and add a case for your node to the switch
+statement that performs constant folding for nodes that take the same number
+of arguments as your new node.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></code>:</p>
+<p>Add code to <a class="reference external" href="CodeGenerator.html#selectiondag_legalize">legalize, promote, and expand</a> the node as necessary. At a
+minimum, you will need to add a case statement for your node in
+<code class="docutils literal notranslate"><span class="pre">LegalizeOp</span></code> which calls LegalizeOp on the nodeâs operands, and returns a
+new node if any of the operands changed as a result of being legalized. It
+is likely that not all targets supported by the SelectionDAG framework will
+natively support the new node. In this case, you must also add code in your
+nodeâs case statement in <code class="docutils literal notranslate"><span class="pre">LegalizeOp</span></code> to Expand your node into simpler,
+legal operations. The case for <code class="docutils literal notranslate"><span class="pre">ISD::UREM</span></code> for expanding a remainder into
+a divide, multiply, and a subtract is a good example.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></code>:</p>
+<dl class="docutils">
+<dt>If targets may support the new node being added only at certain sizes, you</dt>
+<dd><p class="first last">will also need to add code to your nodeâs case statement in <code class="docutils literal notranslate"><span class="pre">LegalizeOp</span></code>
+to Promote your nodeâs operands to a larger size, and perform the correct
+operation. You will also need to add code to <code class="docutils literal notranslate"><span class="pre">PromoteOp</span></code> to do this as
+well. For a good example, see <code class="docutils literal notranslate"><span class="pre">ISD::BSWAP</span></code>, which promotes its operand to
+a wider size, performs the byteswap, and then shifts the correct bytes right
+to emulate the narrower byteswap in the wider type.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></code>:</p>
+<p>Add a case for your node in <code class="docutils literal notranslate"><span class="pre">ExpandOp</span></code> to teach the legalizer how to
+perform the action represented by the new node on a value that has been split
+into high and low halves. This case will be used to support your node with a
+64 bit operand on a 32 bit target.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/DAGCombiner.cpp</span></code>:</p>
+<p>If your node can be combined with itself, or other existing nodes in a
+peephole-like fashion, add a visit function for it, and call that function
+from. There are several good examples for simple combines you can do;
+<code class="docutils literal notranslate"><span class="pre">visitFABS</span></code> and <code class="docutils literal notranslate"><span class="pre">visitSRL</span></code> are good starting places.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/Target/PowerPC/PPCISelLowering.cpp</span></code>:</p>
+<p>Each target has an implementation of the <code class="docutils literal notranslate"><span class="pre">TargetLowering</span></code> class, usually in
+its own file (although some targets include it in the same file as the
+DAGToDAGISel). The default behavior for a target is to assume that your new
+node is legal for all types that are legal for that target. If this target
+does not natively support your node, then tell the target to either Promote
+it (if it is supported at a larger type) or Expand it. This will cause the
+code you wrote in <code class="docutils literal notranslate"><span class="pre">LegalizeOp</span></code> above to decompose your new node into other
+legal nodes for this target.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/Target/TargetSelectionDAG.td</span></code>:</p>
+<p>Most current targets supported by LLVM generate code using the DAGToDAG
+method, where SelectionDAG nodes are pattern matched to target-specific
+nodes, which represent individual instructions. In order for the targets to
+match an instruction to your new node, you must add a def for that node to
+the list in this file, with the appropriate type constraints. Look at
+<code class="docutils literal notranslate"><span class="pre">add</span></code>, <code class="docutils literal notranslate"><span class="pre">bswap</span></code>, and <code class="docutils literal notranslate"><span class="pre">fadd</span></code> for examples.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/Target/PowerPC/PPCInstrInfo.td</span></code>:</p>
+<p>Each target has a tablegen file that describes the targetâs instruction set.
+For targets that use the DAGToDAG instruction selection framework, add a
+pattern for your new node that uses one or more target nodes. Documentation
+for this is a bit sparse right now, but there are several decent examples.
+See the patterns for <code class="docutils literal notranslate"><span class="pre">rotl</span></code> in <code class="docutils literal notranslate"><span class="pre">PPCInstrInfo.td</span></code>.</p>
+</li>
+<li><p class="first">TODO: document complex patterns.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/test/CodeGen/*</span></code>:</p>
+<p>Add test cases for your new node to the test suite.
+<code class="docutils literal notranslate"><span class="pre">llvm/test/CodeGen/X86/bswap.ll</span></code> is a good example.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="adding-a-new-instruction">
+<h2>Adding a new instruction<a class="headerlink" href="#adding-a-new-instruction" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Adding instructions changes the bitcode format, and it will take some effort
+to maintain compatibility with the previous version. Only add an instruction
+if it is absolutely necessary.</p>
+</div>
+<ol class="arabic">
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Instruction.def</span></code>:</p>
+<p>add a number for your instruction and an enum name</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Instructions.h</span></code>:</p>
+<p>add a definition for the class that will represent your instruction</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/InstVisitor.h</span></code>:</p>
+<p>add a prototype for a visitor to your new instruction type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></code>:</p>
+<p>add a new token to parse your instruction from assembly text file</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLParser.cpp</span></code>:</p>
+<p>add the grammar on how your instruction can be read and what it will
+construct as a result</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></code>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></code>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/Instruction.cpp</span></code>:</p>
+<p>add a case for how your instruction will be printed out to assembly</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/Instructions.cpp</span></code>:</p>
+<p>implement the class you defined in <code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/Instructions.h</span></code></p>
+</li>
+<li><p class="first">Test your instruction</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Target/*</span></code>:</p>
+<p>add support for your instruction to code generators, or add a lowering pass.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/test/*</span></code>:</p>
+<p>add your test cases to the test suite.</p>
+</li>
+</ol>
+<p>Also, you need to implement (or modify) any analyses or passes that you want to
+understand this new instruction.</p>
+</div>
+<div class="section" id="adding-a-new-type">
+<h2>Adding a new type<a class="headerlink" href="#adding-a-new-type" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Adding new types changes the bitcode format, and will break compatibility with
+currently-existing LLVM installations. Only add new types if it is absolutely
+necessary.</p>
+</div>
+<div class="section" id="adding-a-fundamental-type">
+<h3>Adding a fundamental type<a class="headerlink" href="#adding-a-fundamental-type" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Type.h</span></code>:</p>
+<p>add enum for the new type; add static <code class="docutils literal notranslate"><span class="pre">Type*</span></code> for this type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/Type.cpp</span></code> and <code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/ValueTypes.cpp</span></code>:</p>
+<p>add mapping from <code class="docutils literal notranslate"><span class="pre">TypeID</span></code> => <code class="docutils literal notranslate"><span class="pre">Type*</span></code>; initialize the static <code class="docutils literal notranslate"><span class="pre">Type*</span></code></p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/llvm/llvm-c/Core.cpp</span></code>:</p>
+<p>add enum <code class="docutils literal notranslate"><span class="pre">LLVMTypeKind</span></code> and modify
+<code class="docutils literal notranslate"><span class="pre">LLVMTypeKind</span> <span class="pre">LLVMGetTypeKind(LLVMTypeRef</span> <span class="pre">Ty)</span></code> for the new type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></code>:</p>
+<p>add ability to parse in the type from text assembly</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLParser.cpp</span></code>:</p>
+<p>add a token for that type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">static</span> <span class="pre">void</span> <span class="pre">WriteTypeTable(const</span> <span class="pre">ValueEnumerator</span> <span class="pre">&VE,</span>
+<span class="pre">BitstreamWriter</span> <span class="pre">&Stream)</span></code> to serialize your type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">BitcodeReader::ParseTypeType()</span></code> to read your data type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">include/llvm/Bitcode/LLVMBitCodes.h</span></code>:</p>
+<p>add enum <code class="docutils literal notranslate"><span class="pre">TypeCodes</span></code> for the new type</p>
+</li>
+</ol>
+</div>
+<div class="section" id="adding-a-derived-type">
+<h3>Adding a derived type<a class="headerlink" href="#adding-a-derived-type" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Type.h</span></code>:</p>
+<p>add enum for the new type; add a forward declaration of the type also</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/DerivedTypes.h</span></code>:</p>
+<p>add new class to represent new class in the hierarchy; add forward
+declaration to the TypeMap value type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/Type.cpp</span></code> and <code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/ValueTypes.cpp</span></code>:</p>
+<p>add support for derived type, notably <cite>enum TypeID</cite> and <cite>is</cite>, <cite>get</cite> methods.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/llvm/llvm-c/Core.cpp</span></code>:</p>
+<p>add enum <code class="docutils literal notranslate"><span class="pre">LLVMTypeKind</span></code> and modify
+<cite>LLVMTypeKind LLVMGetTypeKind(LLVMTypeRef Ty)</cite> for the new type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">lltok::Kind</span> <span class="pre">LLLexer::LexIdentifier()</span></code> to add ability to
+parse in the type from text assembly</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">static</span> <span class="pre">void</span> <span class="pre">WriteTypeTable(const</span> <span class="pre">ValueEnumerator</span> <span class="pre">&VE,</span>
+<span class="pre">BitstreamWriter</span> <span class="pre">&Stream)</span></code> to serialize your type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">BitcodeReader::ParseTypeType()</span></code> to read your data type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">include/llvm/Bitcode/LLVMBitCodes.h</span></code>:</p>
+<p>add enum <code class="docutils literal notranslate"><span class="pre">TypeCodes</span></code> for the new type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/AsmWriter.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">TypePrinting::print(Type</span> <span class="pre">*Ty,</span> <span class="pre">raw_ostream</span> <span class="pre">&OS)</span></code>
+to output the new derived type</p>
+</li>
+</ol>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/Extensions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/Extensions.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/Extensions.html (added)
+++ www-releases/trunk/8.0.0/docs/Extensions.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,604 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>LLVM Extensions — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="libFuzzer â a library for coverage-guided fuzz testing." href="LibFuzzer.html" />
+ <link rel="prev" title="LLVM Programmerâs Manual" href="ProgrammersManual.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-extensions">
+<h1>LLVM Extensions<a class="headerlink" href="#llvm-extensions" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id5">Introduction</a></li>
+<li><a class="reference internal" href="#general-assembly-syntax" id="id6">General Assembly Syntax</a><ul>
+<li><a class="reference internal" href="#c99-style-hexadecimal-floating-point-constants" id="id7">C99-style Hexadecimal Floating-point Constants</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#machine-specific-assembly-syntax" id="id8">Machine-specific Assembly Syntax</a><ul>
+<li><a class="reference internal" href="#x86-coff-dependent" id="id9">X86/COFF-Dependent</a><ul>
+<li><a class="reference internal" href="#relocations" id="id10">Relocations</a></li>
+<li><a class="reference internal" href="#linkonce-directive" id="id11"><code class="docutils literal notranslate"><span class="pre">.linkonce</span></code> Directive</a></li>
+<li><a class="reference internal" href="#section-directive" id="id12"><code class="docutils literal notranslate"><span class="pre">.section</span></code> Directive</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#arm64-coff-dependent" id="id13">ARM64/COFF-Dependent</a><ul>
+<li><a class="reference internal" href="#id1" id="id14">Relocations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#elf-dependent" id="id15">ELF-Dependent</a><ul>
+<li><a class="reference internal" href="#id2" id="id16"><code class="docutils literal notranslate"><span class="pre">.section</span></code> Directive</a></li>
+<li><a class="reference internal" href="#linker-options-section-linker-options" id="id17"><code class="docutils literal notranslate"><span class="pre">.linker-options</span></code> Section (linker options)</a></li>
+<li><a class="reference internal" href="#sht-llvm-call-graph-profile-section-call-graph-profile" id="id18"><code class="docutils literal notranslate"><span class="pre">SHT_LLVM_CALL_GRAPH_PROFILE</span></code> Section (Call Graph Profile)</a></li>
+<li><a class="reference internal" href="#sht-llvm-addrsig-section-address-significance-table" id="id19"><code class="docutils literal notranslate"><span class="pre">SHT_LLVM_ADDRSIG</span></code> Section (address-significance table)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#codeview-dependent" id="id20">CodeView-Dependent</a><ul>
+<li><a class="reference internal" href="#cv-file-directive" id="id21"><code class="docutils literal notranslate"><span class="pre">.cv_file</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-func-id-directive" id="id22"><code class="docutils literal notranslate"><span class="pre">.cv_func_id</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-inline-site-id-directive" id="id23"><code class="docutils literal notranslate"><span class="pre">.cv_inline_site_id</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-loc-directive" id="id24"><code class="docutils literal notranslate"><span class="pre">.cv_loc</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-linetable-directive" id="id25"><code class="docutils literal notranslate"><span class="pre">.cv_linetable</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-inline-linetable-directive" id="id26"><code class="docutils literal notranslate"><span class="pre">.cv_inline_linetable</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-def-range-directive" id="id27"><code class="docutils literal notranslate"><span class="pre">.cv_def_range</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-stringtable-directive" id="id28"><code class="docutils literal notranslate"><span class="pre">.cv_stringtable</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-filechecksums-directive" id="id29"><code class="docutils literal notranslate"><span class="pre">.cv_filechecksums</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-filechecksumoffset-directive" id="id30"><code class="docutils literal notranslate"><span class="pre">.cv_filechecksumoffset</span></code> Directive</a></li>
+<li><a class="reference internal" href="#cv-fpo-data-directive" id="id31"><code class="docutils literal notranslate"><span class="pre">.cv_fpo_data</span></code> Directive</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-specific-behaviour" id="id32">Target Specific Behaviour</a><ul>
+<li><a class="reference internal" href="#x86" id="id33">X86</a><ul>
+<li><a class="reference internal" href="#id3" id="id34">Relocations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#windows-on-arm" id="id35">Windows on ARM</a><ul>
+<li><a class="reference internal" href="#stack-probe-emission" id="id36">Stack Probe Emission</a></li>
+<li><a class="reference internal" href="#variable-length-arrays" id="id37">Variable Length Arrays</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#windows-on-arm64" id="id38">Windows on ARM64</a><ul>
+<li><a class="reference internal" href="#id4" id="id39">Stack Probe Emission</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id5">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes extensions to tools and formats LLVM seeks compatibility
+with.</p>
+</div>
+<div class="section" id="general-assembly-syntax">
+<h2><a class="toc-backref" href="#id6">General Assembly Syntax</a><a class="headerlink" href="#general-assembly-syntax" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="c99-style-hexadecimal-floating-point-constants">
+<h3><a class="toc-backref" href="#id7">C99-style Hexadecimal Floating-point Constants</a><a class="headerlink" href="#c99-style-hexadecimal-floating-point-constants" title="Permalink to this headline">¶</a></h3>
+<p>LLVMâs assemblers allow floating-point constants to be written in C99âs
+hexadecimal format instead of decimal if desired.</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">.data</span>
+<span class="na">.float</span> <span class="mi">0x1c2</span><span class="no">.2ap3</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="machine-specific-assembly-syntax">
+<h2><a class="toc-backref" href="#id8">Machine-specific Assembly Syntax</a><a class="headerlink" href="#machine-specific-assembly-syntax" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="x86-coff-dependent">
+<h3><a class="toc-backref" href="#id9">X86/COFF-Dependent</a><a class="headerlink" href="#x86-coff-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="relocations">
+<h4><a class="toc-backref" href="#id10">Relocations</a><a class="headerlink" href="#relocations" title="Permalink to this headline">¶</a></h4>
+<p>The following additional relocation types are supported:</p>
+<p><strong>@IMGREL</strong> (AT&T syntax only) generates an image-relative relocation that
+corresponds to the COFF relocation types <code class="docutils literal notranslate"><span class="pre">IMAGE_REL_I386_DIR32NB</span></code> (32-bit) or
+<code class="docutils literal notranslate"><span class="pre">IMAGE_REL_AMD64_ADDR32NB</span></code> (64-bit).</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>.text
+fun:
+ mov foo at IMGREL(%ebx, %ecx, 4), %eax
+
+.section .pdata
+ .long fun at IMGREL
+ .long (fun at imgrel + 0x3F)
+ .long $unwind$fun at imgrel
+</pre></div>
+</div>
+<p><strong>.secrel32</strong> generates a relocation that corresponds to the COFF relocation
+types <code class="docutils literal notranslate"><span class="pre">IMAGE_REL_I386_SECREL</span></code> (32-bit) or <code class="docutils literal notranslate"><span class="pre">IMAGE_REL_AMD64_SECREL</span></code> (64-bit).</p>
+<p><strong>.secidx</strong> relocation generates an index of the section that contains
+the target. It corresponds to the COFF relocation types
+<code class="docutils literal notranslate"><span class="pre">IMAGE_REL_I386_SECTION</span></code> (32-bit) or <code class="docutils literal notranslate"><span class="pre">IMAGE_REL_AMD64_SECTION</span></code> (64-bit).</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>.section .debug$S,"rn"
+ .long 4
+ .long 242
+ .long 40
+ .secrel32 _function_name + 0
+ .secidx _function_name
+ ...
+</pre></div>
+</div>
+</div>
+<div class="section" id="linkonce-directive">
+<h4><a class="toc-backref" href="#id11"><code class="docutils literal notranslate"><span class="pre">.linkonce</span></code> Directive</a><a class="headerlink" href="#linkonce-directive" title="Permalink to this headline">¶</a></h4>
+<p>Syntax:</p>
+<blockquote>
+<div><code class="docutils literal notranslate"><span class="pre">.linkonce</span> <span class="pre">[</span> <span class="pre">comdat</span> <span class="pre">type</span> <span class="pre">]</span></code></div></blockquote>
+<p>Supported COMDAT types:</p>
+<dl class="docutils">
+<dt><code class="docutils literal notranslate"><span class="pre">discard</span></code></dt>
+<dd>Discards duplicate sections with the same COMDAT symbol. This is the default
+if no type is specified.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">one_only</span></code></dt>
+<dd>If the symbol is defined multiple times, the linker issues an error.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">same_size</span></code></dt>
+<dd>Duplicates are discarded, but the linker issues an error if any have
+different sizes.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">same_contents</span></code></dt>
+<dd>Duplicates are discarded, but the linker issues an error if any duplicates
+do not have exactly the same content.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">largest</span></code></dt>
+<dd>Links the largest section from among the duplicates.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">newest</span></code></dt>
+<dd>Links the newest section from among the duplicates.</dd>
+</dl>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">.text$foo</span>
+<span class="na">.linkonce</span>
+ <span class="na">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="section-directive">
+<h4><a class="toc-backref" href="#id12"><code class="docutils literal notranslate"><span class="pre">.section</span></code> Directive</a><a class="headerlink" href="#section-directive" title="Permalink to this headline">¶</a></h4>
+<p>MC supports passing the information in <code class="docutils literal notranslate"><span class="pre">.linkonce</span></code> at the end of
+<code class="docutils literal notranslate"><span class="pre">.section</span></code>. For example, these two codes are equivalent</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol1"</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span>
+<span class="na">.linkonce</span> <span class="no">discard</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<p>Note that in the combined form the COMDAT symbol is explicit. This
+extension exists to support multiple sections with the same name in
+different COMDATs:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol1"</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+
+<span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol2"</span>
+<span class="na">.globl</span> <span class="no">Symbol2</span>
+<span class="nl">Symbol2:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<p>In addition to the types allowed with <code class="docutils literal notranslate"><span class="pre">.linkonce</span></code>, <code class="docutils literal notranslate"><span class="pre">.section</span></code> also accepts
+<code class="docutils literal notranslate"><span class="pre">associative</span></code>. The meaning is that the section is linked if a certain other
+COMDAT section is linked. This other section is indicated by the comdat symbol
+in this directive. It can be any symbol defined in the associated section, but
+is usually the associated sectionâs comdat.</p>
+<blockquote>
+<div><p>The following restrictions apply to the associated section:</p>
+<ol class="arabic simple">
+<li>It must be a COMDAT section.</li>
+<li>It cannot be another associative COMDAT section.</li>
+</ol>
+</div></blockquote>
+<p>In the following example the symobl <code class="docutils literal notranslate"><span class="pre">sym</span></code> is the comdat symbol of <code class="docutils literal notranslate"><span class="pre">.foo</span></code>
+and <code class="docutils literal notranslate"><span class="pre">.bar</span></code> is associated to <code class="docutils literal notranslate"><span class="pre">.foo</span></code>.</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"bw"</span><span class="p">,</span><span class="no">discard</span><span class="p">,</span> <span class="s">"sym"</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"rd"</span><span class="p">,</span><span class="no">associative</span><span class="p">,</span> <span class="s">"sym"</span>
+</pre></div>
+</div>
+<p>MC supports these flags in the COFF <code class="docutils literal notranslate"><span class="pre">.section</span></code> directive:</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">b</span></code>: BSS section (<code class="docutils literal notranslate"><span class="pre">IMAGE_SCN_CNT_INITIALIZED_DATA</span></code>)</li>
+<li><code class="docutils literal notranslate"><span class="pre">d</span></code>: Data section (<code class="docutils literal notranslate"><span class="pre">IMAGE_SCN_CNT_UNINITIALIZED_DATA</span></code>)</li>
+<li><code class="docutils literal notranslate"><span class="pre">n</span></code>: Section is not loaded (<code class="docutils literal notranslate"><span class="pre">IMAGE_SCN_LNK_REMOVE</span></code>)</li>
+<li><code class="docutils literal notranslate"><span class="pre">r</span></code>: Read-only</li>
+<li><code class="docutils literal notranslate"><span class="pre">s</span></code>: Shared section</li>
+<li><code class="docutils literal notranslate"><span class="pre">w</span></code>: Writable</li>
+<li><code class="docutils literal notranslate"><span class="pre">x</span></code>: Executable section</li>
+<li><code class="docutils literal notranslate"><span class="pre">y</span></code>: Not readable</li>
+<li><code class="docutils literal notranslate"><span class="pre">D</span></code>: Discardable (<code class="docutils literal notranslate"><span class="pre">IMAGE_SCN_MEM_DISCARDABLE</span></code>)</li>
+</ul>
+</div></blockquote>
+<p>These flags are all compatible with gas, with the exception of the <code class="docutils literal notranslate"><span class="pre">D</span></code> flag,
+which gnu as does not support. For gas compatibility, sections with a name
+starting with â.debugâ are implicitly discardable.</p>
+</div>
+</div>
+<div class="section" id="arm64-coff-dependent">
+<h3><a class="toc-backref" href="#id13">ARM64/COFF-Dependent</a><a class="headerlink" href="#arm64-coff-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id1">
+<h4><a class="toc-backref" href="#id14">Relocations</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>The following additional symbol variants are supported:</p>
+<p><strong>:secrel_lo12:</strong> generates a relocation that corresponds to the COFF relocation
+types <code class="docutils literal notranslate"><span class="pre">IMAGE_REL_ARM64_SECREL_LOW12A</span></code> or <code class="docutils literal notranslate"><span class="pre">IMAGE_REL_ARM64_SECREL_LOW12L</span></code>.</p>
+<p><strong>:secrel_hi12:</strong> generates a relocation that corresponds to the COFF relocation
+type <code class="docutils literal notranslate"><span class="pre">IMAGE_REL_ARM64_SECREL_HIGH12A</span></code>.</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">add</span> <span class="no">x0</span><span class="p">,</span> <span class="no">x0</span><span class="p">,</span> <span class="p">:</span><span class="no">secrel_hi12</span><span class="p">:</span><span class="no">symbol</span>
+<span class="nf">ldr</span> <span class="no">x0</span><span class="p">,</span> <span class="p">[</span><span class="no">x0</span><span class="p">,</span> <span class="p">:</span><span class="no">secrel_lo12</span><span class="p">:</span><span class="no">symbol</span><span class="p">]</span>
+
+<span class="nf">add</span> <span class="no">x1</span><span class="p">,</span> <span class="no">x1</span><span class="p">,</span> <span class="p">:</span><span class="no">secrel_hi12</span><span class="p">:</span><span class="no">symbol</span>
+<span class="nf">add</span> <span class="no">x1</span><span class="p">,</span> <span class="no">x1</span><span class="p">,</span> <span class="p">:</span><span class="no">secrel_lo12</span><span class="p">:</span><span class="no">symbol</span>
+<span class="na">...</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="elf-dependent">
+<h3><a class="toc-backref" href="#id15">ELF-Dependent</a><a class="headerlink" href="#elf-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id2">
+<h4><a class="toc-backref" href="#id16"><code class="docutils literal notranslate"><span class="pre">.section</span></code> Directive</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>In order to support creating multiple sections with the same name and comdat,
+it is possible to add an unique number at the end of the <code class="docutils literal notranslate"><span class="pre">.seciton</span></code> directive.
+For example, the following code creates two sections named <code class="docutils literal notranslate"><span class="pre">.text</span></code>.</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">.text</span><span class="p">,</span><span class="s">"ax"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,</span><span class="no">unique</span><span class="p">,</span><span class="mi">1</span>
+<span class="nf">nop</span>
+
+<span class="na">.section</span> <span class="no">.text</span><span class="p">,</span><span class="s">"ax"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,</span><span class="no">unique</span><span class="p">,</span><span class="mi">2</span>
+<span class="nf">nop</span>
+</pre></div>
+</div>
+<p>The unique number is not present in the resulting object at all. It is just used
+in the assembler to differentiate the sections.</p>
+<p>The âoâ flag is mapped to SHF_LINK_ORDER. If it is present, a symbol
+must be given that identifies the section to be placed is the
+.sh_link.</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"a"</span><span class="p">,</span><span class="na">@progbits</span>
+<span class="nl">.Ltmp:</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"ao"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,.</span><span class="no">Ltmp</span>
+</pre></div>
+</div>
+<p>which is equivalent to just</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"a"</span><span class="p">,</span><span class="na">@progbits</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"ao"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,.</span><span class="no">foo</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="linker-options-section-linker-options">
+<h4><a class="toc-backref" href="#id17"><code class="docutils literal notranslate"><span class="pre">.linker-options</span></code> Section (linker options)</a><a class="headerlink" href="#linker-options-section-linker-options" title="Permalink to this headline">¶</a></h4>
+<p>In order to support passing linker options from the frontend to the linker, a
+special section of type <code class="docutils literal notranslate"><span class="pre">SHT_LLVM_LINKER_OPTIONS</span></code> (usually named
+<code class="docutils literal notranslate"><span class="pre">.linker-options</span></code> though the name is not significant as it is identified by
+the type). The contents of this section is a simple pair-wise encoding of
+directives for consideration by the linker. The strings are encoded as standard
+null-terminated UTF-8 strings. They are emitted inline to avoid having the
+linker traverse the object file for retrieving the value. The linker is
+permitted to not honour the option and instead provide a warning/error to the
+user that the requested option was not honoured.</p>
+<p>The section has type <code class="docutils literal notranslate"><span class="pre">SHT_LLVM_LINKER_OPTIONS</span></code> and has the <code class="docutils literal notranslate"><span class="pre">SHF_EXCLUDE</span></code>
+flag to ensure that the section is treated as opaque by linkers which do not
+support the feature and will not be emitted into the final linked binary.</p>
+<p>This would be equivalent to the follow raw assembly:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.section</span> <span class="s">".linker-options"</span><span class="p">,</span><span class="s">"e"</span><span class="p">,</span><span class="na">@llvm_linker_options</span>
+<span class="na">.asciz</span> <span class="s">"option 1"</span>
+<span class="na">.asciz</span> <span class="s">"value 1"</span>
+<span class="na">.asciz</span> <span class="s">"option 2"</span>
+<span class="na">.asciz</span> <span class="s">"value 2"</span>
+</pre></div>
+</div>
+<p>The following directives are specified:</p>
+<blockquote>
+<div><ul>
+<li><p class="first">lib</p>
+<p>The parameter identifies a library to be linked against. The library will
+be looked up in the default and any specified library search paths
+(specified to this point).</p>
+</li>
+<li><p class="first">libpath</p>
+<p>The paramter identifies an additional library search path to be considered
+when looking up libraries after the inclusion of this option.</p>
+</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="sht-llvm-call-graph-profile-section-call-graph-profile">
+<h4><a class="toc-backref" href="#id18"><code class="docutils literal notranslate"><span class="pre">SHT_LLVM_CALL_GRAPH_PROFILE</span></code> Section (Call Graph Profile)</a><a class="headerlink" href="#sht-llvm-call-graph-profile-section-call-graph-profile" title="Permalink to this headline">¶</a></h4>
+<p>This section is used to pass a call graph profile to the linker which can be
+used to optimize the placement of sections. It contains a sequence of
+(from symbol, to symbol, weight) tuples.</p>
+<p>It shall have a type of <code class="docutils literal notranslate"><span class="pre">SHT_LLVM_CALL_GRAPH_PROFILE</span></code> (0x6fff4c02), shall
+have the <code class="docutils literal notranslate"><span class="pre">SHF_EXCLUDE</span></code> flag set, the <code class="docutils literal notranslate"><span class="pre">sh_link</span></code> member shall hold the section
+header index of the associated symbol table, and shall have a <code class="docutils literal notranslate"><span class="pre">sh_entsize</span></code> of
+16. It should be named <code class="docutils literal notranslate"><span class="pre">.llvm.call-graph-profile</span></code>.</p>
+<p>The contents of the section shall be a sequence of <code class="docutils literal notranslate"><span class="pre">Elf_CGProfile</span></code> entries.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
+ <span class="n">Elf_Word</span> <span class="n">cgp_from</span><span class="p">;</span>
+ <span class="n">Elf_Word</span> <span class="n">cgp_to</span><span class="p">;</span>
+ <span class="n">Elf_Xword</span> <span class="n">cgp_weight</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">Elf_CGProfile</span><span class="p">;</span>
+</pre></div>
+</div>
+<dl class="docutils">
+<dt>cgp_from</dt>
+<dd>The symbol index of the source of the edge.</dd>
+<dt>cgp_to</dt>
+<dd>The symbol index of the destination of the edge.</dd>
+<dt>cgp_weight</dt>
+<dd>The weight of the edge.</dd>
+</dl>
+<p>This is represented in assembly as:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.cg_profile</span> <span class="no">from</span><span class="p">,</span> <span class="no">to</span><span class="p">,</span> <span class="mi">42</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">.cg_profile</span></code> directives are processed at the end of the file. It is an error
+if either <code class="docutils literal notranslate"><span class="pre">from</span></code> or <code class="docutils literal notranslate"><span class="pre">to</span></code> are undefined temporary symbols. If either symbol
+is a temporary symbol, then the section symbol is used instead. If either
+symbol is undefined, then that symbol is defined as if <code class="docutils literal notranslate"><span class="pre">.weak</span> <span class="pre">symbol</span></code> has been
+written at the end of the file. This forces the symbol to show up in the symbol
+table.</p>
+</div>
+<div class="section" id="sht-llvm-addrsig-section-address-significance-table">
+<h4><a class="toc-backref" href="#id19"><code class="docutils literal notranslate"><span class="pre">SHT_LLVM_ADDRSIG</span></code> Section (address-significance table)</a><a class="headerlink" href="#sht-llvm-addrsig-section-address-significance-table" title="Permalink to this headline">¶</a></h4>
+<p>This section is used to mark symbols as address-significant, i.e. the address
+of the symbol is used in a comparison or leaks outside the translation unit. It
+has the same meaning as the absence of the LLVM attributes <code class="docutils literal notranslate"><span class="pre">unnamed_addr</span></code>
+and <code class="docutils literal notranslate"><span class="pre">local_unnamed_addr</span></code>.</p>
+<p>Any sections referred to by symbols that are not marked as address-significant
+in any object file may be safely merged by a linker without breaking the
+address uniqueness guarantee provided by the C and C++ language standards.</p>
+<p>The contents of the section are a sequence of ULEB128-encoded integers
+referring to the symbol table indexes of the address-significant symbols.</p>
+<p>There are two associated assembly directives:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.addrsig</span>
+</pre></div>
+</div>
+<p>This instructs the assembler to emit an address-significance table. Without
+this directive, all symbols are considered address-significant.</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="na">.addrsig_sym</span> <span class="no">sym</span>
+</pre></div>
+</div>
+<p>This marks <code class="docutils literal notranslate"><span class="pre">sym</span></code> as address-significant.</p>
+</div>
+</div>
+<div class="section" id="codeview-dependent">
+<h3><a class="toc-backref" href="#id20">CodeView-Dependent</a><a class="headerlink" href="#codeview-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="cv-file-directive">
+<h4><a class="toc-backref" href="#id21"><code class="docutils literal notranslate"><span class="pre">.cv_file</span></code> Directive</a><a class="headerlink" href="#cv-file-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_file</span></code> <em>FileNumber FileName</em> [ <em>checksum</em> ] [ <em>checksumkind</em> ]</dd>
+</dl>
+</div>
+<div class="section" id="cv-func-id-directive">
+<h4><a class="toc-backref" href="#id22"><code class="docutils literal notranslate"><span class="pre">.cv_func_id</span></code> Directive</a><a class="headerlink" href="#cv-func-id-directive" title="Permalink to this headline">¶</a></h4>
+<p>Introduces a function ID that can be used with <code class="docutils literal notranslate"><span class="pre">.cv_loc</span></code>.</p>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_func_id</span></code> <em>FunctionId</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-inline-site-id-directive">
+<h4><a class="toc-backref" href="#id23"><code class="docutils literal notranslate"><span class="pre">.cv_inline_site_id</span></code> Directive</a><a class="headerlink" href="#cv-inline-site-id-directive" title="Permalink to this headline">¶</a></h4>
+<p>Introduces a function ID that can be used with <code class="docutils literal notranslate"><span class="pre">.cv_loc</span></code>. Includes
+<code class="docutils literal notranslate"><span class="pre">inlined</span> <span class="pre">at</span></code> source location information for use in the line table of the
+caller, whether the caller is a real function or another inlined call site.</p>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_inline_site_id</span></code> <em>FunctionId</em> <code class="docutils literal notranslate"><span class="pre">within</span></code> <em>Function</em> <code class="docutils literal notranslate"><span class="pre">inlined_at</span></code> <em>FileNumber Line</em> [ <em>Colomn</em> ]</dd>
+</dl>
+</div>
+<div class="section" id="cv-loc-directive">
+<h4><a class="toc-backref" href="#id24"><code class="docutils literal notranslate"><span class="pre">.cv_loc</span></code> Directive</a><a class="headerlink" href="#cv-loc-directive" title="Permalink to this headline">¶</a></h4>
+<p>The first number is a file number, must have been previously assigned with a
+<code class="docutils literal notranslate"><span class="pre">.file</span></code> directive, the second number is the line number and optionally the
+third number is a column position (zero if not specified). The remaining
+optional items are <code class="docutils literal notranslate"><span class="pre">.loc</span></code> sub-directives.</p>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_loc</span></code> <em>FunctionId FileNumber</em> [ <em>Line</em> ] [ <em>Column</em> ] [ <em>prologue_end</em> ] [ <code class="docutils literal notranslate"><span class="pre">is_stmt</span></code> <em>value</em> ]</dd>
+</dl>
+</div>
+<div class="section" id="cv-linetable-directive">
+<h4><a class="toc-backref" href="#id25"><code class="docutils literal notranslate"><span class="pre">.cv_linetable</span></code> Directive</a><a class="headerlink" href="#cv-linetable-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_linetable</span></code> <em>FunctionId</em> <code class="docutils literal notranslate"><span class="pre">,</span></code> <em>FunctionStart</em> <code class="docutils literal notranslate"><span class="pre">,</span></code> <em>FunctionEnd</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-inline-linetable-directive">
+<h4><a class="toc-backref" href="#id26"><code class="docutils literal notranslate"><span class="pre">.cv_inline_linetable</span></code> Directive</a><a class="headerlink" href="#cv-inline-linetable-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_inline_linetable</span></code> <em>PrimaryFunctionId</em> <code class="docutils literal notranslate"><span class="pre">,</span></code> <em>FileNumber Line FunctionStart FunctionEnd</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-def-range-directive">
+<h4><a class="toc-backref" href="#id27"><code class="docutils literal notranslate"><span class="pre">.cv_def_range</span></code> Directive</a><a class="headerlink" href="#cv-def-range-directive" title="Permalink to this headline">¶</a></h4>
+<p>The <em>GapStart</em> and <em>GapEnd</em> options may be repeated as needed.</p>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_def_range</span></code> <em>RangeStart RangeEnd</em> [ <em>GapStart GapEnd</em> ] <code class="docutils literal notranslate"><span class="pre">,</span></code> <em>bytes</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-stringtable-directive">
+<h4><a class="toc-backref" href="#id28"><code class="docutils literal notranslate"><span class="pre">.cv_stringtable</span></code> Directive</a><a class="headerlink" href="#cv-stringtable-directive" title="Permalink to this headline">¶</a></h4>
+</div>
+<div class="section" id="cv-filechecksums-directive">
+<h4><a class="toc-backref" href="#id29"><code class="docutils literal notranslate"><span class="pre">.cv_filechecksums</span></code> Directive</a><a class="headerlink" href="#cv-filechecksums-directive" title="Permalink to this headline">¶</a></h4>
+</div>
+<div class="section" id="cv-filechecksumoffset-directive">
+<h4><a class="toc-backref" href="#id30"><code class="docutils literal notranslate"><span class="pre">.cv_filechecksumoffset</span></code> Directive</a><a class="headerlink" href="#cv-filechecksumoffset-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_filechecksumoffset</span></code> <em>FileNumber</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-fpo-data-directive">
+<h4><a class="toc-backref" href="#id31"><code class="docutils literal notranslate"><span class="pre">.cv_fpo_data</span></code> Directive</a><a class="headerlink" href="#cv-fpo-data-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">.cv_fpo_data</span></code> <em>procsym</em></dd>
+</dl>
+</div>
+</div>
+</div>
+<div class="section" id="target-specific-behaviour">
+<h2><a class="toc-backref" href="#id32">Target Specific Behaviour</a><a class="headerlink" href="#target-specific-behaviour" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="x86">
+<h3><a class="toc-backref" href="#id33">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id34">Relocations</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">@ABS8</span></code> can be applied to symbols which appear as immediate operands to
+instructions that have an 8-bit immediate form for that operand. It causes
+the assembler to use the 8-bit form and an 8-bit relocation (e.g. <code class="docutils literal notranslate"><span class="pre">R_386_8</span></code>
+or <code class="docutils literal notranslate"><span class="pre">R_X86_64_8</span></code>) for the symbol.</p>
+<p>For example:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">cmpq</span> <span class="no">$foo at ABS8</span><span class="p">,</span> <span class="nv">%rdi</span>
+</pre></div>
+</div>
+<p>This causes the assembler to select the form of the 64-bit <code class="docutils literal notranslate"><span class="pre">cmpq</span></code> instruction
+that takes an 8-bit immediate operand that is sign extended to 64 bits, as
+opposed to <code class="docutils literal notranslate"><span class="pre">cmpq</span> <span class="pre">$foo,</span> <span class="pre">%rdi</span></code> which takes a 32-bit immediate operand. This
+is also not the same as <code class="docutils literal notranslate"><span class="pre">cmpb</span> <span class="pre">$foo,</span> <span class="pre">%dil</span></code>, which is an 8-bit comparison.</p>
+</div>
+</div>
+<div class="section" id="windows-on-arm">
+<h3><a class="toc-backref" href="#id35">Windows on ARM</a><a class="headerlink" href="#windows-on-arm" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="stack-probe-emission">
+<h4><a class="toc-backref" href="#id36">Stack Probe Emission</a><a class="headerlink" href="#stack-probe-emission" title="Permalink to this headline">¶</a></h4>
+<p>The reference implementation (Microsoft Visual Studio 2012) emits stack probes
+in the following fashion:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">movw</span> <span class="no">r4</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="no">bl</span> <span class="no">__chkstk</span>
+<span class="nf">sub.w</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">r4</span>
+</pre></div>
+</div>
+<p>However, this has the limitation of 32 MiB (±16MiB). In order to accommodate
+larger binaries, LLVM supports the use of <code class="docutils literal notranslate"><span class="pre">-mcode-model=large</span></code> to allow a 4GiB
+range via a slight deviation. It will generate an indirect jump as follows:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">movw</span> <span class="no">r4</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="no">movw</span> <span class="no">r12</span><span class="p">,</span> <span class="p">:</span><span class="no">lower16</span><span class="p">:</span><span class="no">__chkstk</span>
+<span class="nf">movt</span> <span class="no">r12</span><span class="p">,</span> <span class="p">:</span><span class="no">upper16</span><span class="p">:</span><span class="no">__chkstk</span>
+<span class="nf">blx</span> <span class="no">r12</span>
+<span class="nf">sub.w</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">r4</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="variable-length-arrays">
+<h4><a class="toc-backref" href="#id37">Variable Length Arrays</a><a class="headerlink" href="#variable-length-arrays" title="Permalink to this headline">¶</a></h4>
+<p>The reference implementation (Microsoft Visual Studio 2012) does not permit the
+emission of Variable Length Arrays (VLAs).</p>
+<p>The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
+a dynamic stack allocation. When emitting a variable stack allocation, a call
+to <code class="docutils literal notranslate"><span class="pre">__chkstk</span></code> is emitted unconditionally to ensure that guard pages are setup
+properly. The emission of this stack probe emission is handled similar to the
+standard stack probe emission.</p>
+<p>The MSVC environment does not emit code for VLAs currently.</p>
+</div>
+</div>
+<div class="section" id="windows-on-arm64">
+<h3><a class="toc-backref" href="#id38">Windows on ARM64</a><a class="headerlink" href="#windows-on-arm64" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id4">
+<h4><a class="toc-backref" href="#id39">Stack Probe Emission</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>The reference implementation (Microsoft Visual Studio 2017) emits stack probes
+in the following fashion:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">mov</span> <span class="no">x15</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="no">bl</span> <span class="no">__chkstk</span>
+<span class="nf">sub</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">x15</span><span class="p">,</span> <span class="no">lsl</span> <span class="c">#4</span>
+</pre></div>
+</div>
+<p>However, this has the limitation of 256 MiB (±128MiB). In order to accommodate
+larger binaries, LLVM supports the use of <code class="docutils literal notranslate"><span class="pre">-mcode-model=large</span></code> to allow a 8GiB
+(±4GiB) range via a slight deviation. It will generate an indirect jump as
+follows:</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">mov</span> <span class="no">x15</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="no">adrp</span> <span class="no">x16</span><span class="p">,</span> <span class="no">__chkstk</span>
+<span class="nf">add</span> <span class="no">x16</span><span class="p">,</span> <span class="no">x16</span><span class="p">,</span> <span class="p">:</span><span class="no">lo12</span><span class="p">:</span><span class="no">__chkstk</span>
+<span class="nf">blr</span> <span class="no">x16</span>
+<span class="nf">sub</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">x15</span><span class="p">,</span> <span class="no">lsl</span> <span class="c">#4</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/FAQ.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/FAQ.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/FAQ.html (added)
+++ www-releases/trunk/8.0.0/docs/FAQ.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,426 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Frequently Asked Questions (FAQ) — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="The LLVM Lexicon" href="Lexicon.html" />
+ <link rel="prev" title="Getting Started with the LLVM System using Microsoft Visual Studio" href="GettingStartedVS.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="frequently-asked-questions-faq">
+<h1>Frequently Asked Questions (FAQ)<a class="headerlink" href="#frequently-asked-questions-faq" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#license" id="id1">License</a><ul>
+<li><a class="reference internal" href="#does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license" id="id2">Does the University of Illinois Open Source License really qualify as an âopen sourceâ license?</a></li>
+<li><a class="reference internal" href="#can-i-modify-llvm-source-code-and-redistribute-the-modified-source" id="id3">Can I modify LLVM source code and redistribute the modified source?</a></li>
+<li><a class="reference internal" href="#can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source" id="id4">Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#source-code" id="id5">Source Code</a><ul>
+<li><a class="reference internal" href="#in-what-language-is-llvm-written" id="id6">In what language is LLVM written?</a></li>
+<li><a class="reference internal" href="#how-portable-is-the-llvm-source-code" id="id7">How portable is the LLVM source code?</a></li>
+<li><a class="reference internal" href="#what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation" id="id8">What API do I use to store a value to one of the virtual registers in LLVM IRâs SSA representation?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#source-languages" id="id9">Source Languages</a><ul>
+<li><a class="reference internal" href="#what-source-languages-are-supported" id="id10">What source languages are supported?</a></li>
+<li><a class="reference internal" href="#i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators" id="id11">Iâd like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?</a></li>
+<li><a class="reference internal" href="#what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler" id="id12">What support is there for a higher level source language constructs for building a compiler?</a></li>
+<li><a class="reference internal" href="#i-don-t-understand-the-getelementptr-instruction-help" id="id13">I donât understand the <code class="docutils literal notranslate"><span class="pre">GetElementPtr</span></code> instruction. Help!</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#using-the-c-and-c-front-ends" id="id14">Using the C and C++ Front Ends</a><ul>
+<li><a class="reference internal" href="#can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode" id="id15">Can I compile C or C++ code to platform-independent LLVM bitcode?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#questions-about-code-generated-by-the-demo-page" id="id16">Questions about code generated by the demo page</a><ul>
+<li><a class="reference internal" href="#what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream" id="id17">What is this <code class="docutils literal notranslate"><span class="pre">llvm.global_ctors</span></code> and <code class="docutils literal notranslate"><span class="pre">_GLOBAL__I_a...</span></code> stuff that happens when I <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><iostream></span></code>?</a></li>
+<li><a class="reference internal" href="#where-did-all-of-my-code-go" id="id18">Where did all of my code go??</a></li>
+<li><a class="reference internal" href="#what-is-this-undef-thing-that-shows-up-in-my-code" id="id19">What is this â<code class="docutils literal notranslate"><span class="pre">undef</span></code>â thing that shows up in my code?</a></li>
+<li><a class="reference internal" href="#why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it" id="id20">Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into âunreachableâ? Why not make the verifier reject it?</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="license">
+<h2><a class="toc-backref" href="#id1">License</a><a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license">
+<h3><a class="toc-backref" href="#id2">Does the University of Illinois Open Source License really qualify as an âopen sourceâ license?</a><a class="headerlink" href="#does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license" title="Permalink to this headline">¶</a></h3>
+<p>Yes, the license is <a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open Source
+Initiative (OSI).</p>
+</div>
+<div class="section" id="can-i-modify-llvm-source-code-and-redistribute-the-modified-source">
+<h3><a class="toc-backref" href="#id3">Can I modify LLVM source code and redistribute the modified source?</a><a class="headerlink" href="#can-i-modify-llvm-source-code-and-redistribute-the-modified-source" title="Permalink to this headline">¶</a></h3>
+<p>Yes. The modified source distribution must retain the copyright notice and
+follow the three bulleted conditions listed in the <a class="reference external" href="http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT">LLVM license</a>.</p>
+</div>
+<div class="section" id="can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source">
+<h3><a class="toc-backref" href="#id4">Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?</a><a class="headerlink" href="#can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source" title="Permalink to this headline">¶</a></h3>
+<p>Yes. This is why we distribute LLVM under a less restrictive license than GPL,
+as explained in the first question above.</p>
+</div>
+</div>
+<div class="section" id="source-code">
+<h2><a class="toc-backref" href="#id5">Source Code</a><a class="headerlink" href="#source-code" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="in-what-language-is-llvm-written">
+<h3><a class="toc-backref" href="#id6">In what language is LLVM written?</a><a class="headerlink" href="#in-what-language-is-llvm-written" title="Permalink to this headline">¶</a></h3>
+<p>All of the LLVM tools and libraries are written in C++ with extensive use of
+the STL.</p>
+</div>
+<div class="section" id="how-portable-is-the-llvm-source-code">
+<h3><a class="toc-backref" href="#id7">How portable is the LLVM source code?</a><a class="headerlink" href="#how-portable-is-the-llvm-source-code" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM source code should be portable to most modern Unix-like operating
+systems. Most of the code is written in standard C++ with operating system
+services abstracted to a support library. The tools required to build and
+test LLVM have been ported to a plethora of platforms.</p>
+<p>Some porting problems may exist in the following areas:</p>
+<ul class="simple">
+<li>The autoconf/makefile build system relies heavily on UNIX shell tools,
+like the Bourne Shell and sed. Porting to systems without these tools
+(MacOS 9, Plan 9) will require more effort.</li>
+</ul>
+</div>
+<div class="section" id="what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation">
+<h3><a class="toc-backref" href="#id8">What API do I use to store a value to one of the virtual registers in LLVM IRâs SSA representation?</a><a class="headerlink" href="#what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation" title="Permalink to this headline">¶</a></h3>
+<p>In short: you canât. Itâs actually kind of a silly question once you grok
+whatâs going on. Basically, in code like:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="nv">%result</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%foo</span><span class="p">,</span> <span class="nv">%bar</span>
+</pre></div>
+</div>
+<p>, <code class="docutils literal notranslate"><span class="pre">%result</span></code> is just a name given to the <code class="docutils literal notranslate"><span class="pre">Value</span></code> of the <code class="docutils literal notranslate"><span class="pre">add</span></code>
+instruction. In other words, <code class="docutils literal notranslate"><span class="pre">%result</span></code> <em>is</em> the add instruction. The
+âassignmentâ doesnât explicitly âstoreâ anything to any âvirtual registerâ;
+the â<code class="docutils literal notranslate"><span class="pre">=</span></code>â is more like the mathematical sense of equality.</p>
+<p>Longer explanation: In order to generate a textual representation of the
+IR, some kind of name has to be given to each instruction so that other
+instructions can textually reference it. However, the isomorphic in-memory
+representation that you manipulate from C++ has no such restriction since
+instructions can simply keep pointers to any other <code class="docutils literal notranslate"><span class="pre">Value</span></code>âs that they
+reference. In fact, the names of dummy numbered temporaries like <code class="docutils literal notranslate"><span class="pre">%1</span></code> are
+not explicitly represented in the in-memory representation at all (see
+<code class="docutils literal notranslate"><span class="pre">Value::getName()</span></code>).</p>
+</div>
+</div>
+<div class="section" id="source-languages">
+<h2><a class="toc-backref" href="#id9">Source Languages</a><a class="headerlink" href="#source-languages" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-source-languages-are-supported">
+<h3><a class="toc-backref" href="#id10">What source languages are supported?</a><a class="headerlink" href="#what-source-languages-are-supported" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently has full support for C and C++ source languages through
+<a class="reference external" href="http://clang.llvm.org/">Clang</a>. Many other language frontends have
+been written using LLVM, and an incomplete list is available at
+<a class="reference external" href="http://llvm.org/ProjectsWithLLVM/">projects with LLVM</a>.</p>
+</div>
+<div class="section" id="i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators">
+<h3><a class="toc-backref" href="#id11">Iâd like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?</a><a class="headerlink" href="#i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators" title="Permalink to this headline">¶</a></h3>
+<p>Your compiler front-end will communicate with LLVM by creating a module in the
+LLVM intermediate representation (IR) format. Assuming you want to write your
+languageâs compiler in the language itself (rather than C++), there are 3
+major ways to tackle generating LLVM IR from a front-end:</p>
+<ol class="arabic simple">
+<li><strong>Call into the LLVM libraries code using your languageâs FFI (foreign
+function interface).</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc format</li>
+<li><em>for:</em> enables running LLVM optimization passes without a emit/parse
+overhead</li>
+<li><em>for:</em> adapts well to a JIT context</li>
+<li><em>against:</em> lots of ugly glue code to write</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="2">
+<li><strong>Emit LLVM assembly from your compilerâs native language.</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> very straightforward to get started</li>
+<li><em>against:</em> the .ll parser is slower than the bitcode reader when
+interfacing to the middle end</li>
+<li><em>against:</em> it may be harder to track changes to the IR</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="3">
+<li><strong>Emit LLVM bitcode from your compilerâs native language.</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> can use the more-efficient bitcode reader when interfacing to the
+middle end</li>
+<li><em>against:</em> youâll have to re-engineer the LLVM IR object model and bitcode
+writer in your language</li>
+<li><em>against:</em> it may be harder to track changes to the IR</li>
+</ul>
+</div></blockquote>
+<p>If you go with the first option, the C bindings in include/llvm-c should help
+a lot, since most languages have strong support for interfacing with C. The
+most common hurdle with calling C from managed code is interfacing with the
+garbage collector. The C interface was designed to require very little memory
+management, and so is straightforward in this regard.</p>
+</div>
+<div class="section" id="what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler">
+<h3><a class="toc-backref" href="#id12">What support is there for a higher level source language constructs for building a compiler?</a><a class="headerlink" href="#what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler" title="Permalink to this headline">¶</a></h3>
+<p>Currently, there isnât much. LLVM supports an intermediate representation
+which is useful for code representation but will not support the high level
+(abstract syntax tree) representation needed by most compilers. There are no
+facilities for lexical nor semantic analysis.</p>
+</div>
+<div class="section" id="i-don-t-understand-the-getelementptr-instruction-help">
+<h3><a class="toc-backref" href="#id13">I donât understand the <code class="docutils literal notranslate"><span class="pre">GetElementPtr</span></code> instruction. Help!</a><a class="headerlink" href="#i-don-t-understand-the-getelementptr-instruction-help" title="Permalink to this headline">¶</a></h3>
+<p>See <a class="reference external" href="GetElementPtr.html">The Often Misunderstood GEP Instruction</a>.</p>
+</div>
+</div>
+<div class="section" id="using-the-c-and-c-front-ends">
+<h2><a class="toc-backref" href="#id14">Using the C and C++ Front Ends</a><a class="headerlink" href="#using-the-c-and-c-front-ends" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode">
+<h3><a class="toc-backref" href="#id15">Can I compile C or C++ code to platform-independent LLVM bitcode?</a><a class="headerlink" href="#can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode" title="Permalink to this headline">¶</a></h3>
+<p>No. C and C++ are inherently platform-dependent languages. The most obvious
+example of this is the preprocessor. A very common way that C code is made
+portable is by using the preprocessor to include platform-specific code. In
+practice, information about other platforms is lost after preprocessing, so
+the result is inherently dependent on the platform that the preprocessing was
+targeting.</p>
+<p>Another example is <code class="docutils literal notranslate"><span class="pre">sizeof</span></code>. Itâs common for <code class="docutils literal notranslate"><span class="pre">sizeof(long)</span></code> to vary
+between platforms. In most C front-ends, <code class="docutils literal notranslate"><span class="pre">sizeof</span></code> is expanded to a
+constant immediately, thus hard-wiring a platform-specific detail.</p>
+<p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
+lower-level than C, front-ends currently must emit platform-specific IR in
+order to have the result conform to the platform ABI.</p>
+</div>
+</div>
+<div class="section" id="questions-about-code-generated-by-the-demo-page">
+<h2><a class="toc-backref" href="#id16">Questions about code generated by the demo page</a><a class="headerlink" href="#questions-about-code-generated-by-the-demo-page" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream">
+<h3><a class="toc-backref" href="#id17">What is this <code class="docutils literal notranslate"><span class="pre">llvm.global_ctors</span></code> and <code class="docutils literal notranslate"><span class="pre">_GLOBAL__I_a...</span></code> stuff that happens when I <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><iostream></span></code>?</a><a class="headerlink" href="#what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream" title="Permalink to this headline">¶</a></h3>
+<p>If you <code class="docutils literal notranslate"><span class="pre">#include</span></code> the <code class="docutils literal notranslate"><span class="pre"><iostream></span></code> header into a C++ translation unit,
+the file will probably use the <code class="docutils literal notranslate"><span class="pre">std::cin</span></code>/<code class="docutils literal notranslate"><span class="pre">std::cout</span></code>/⦠global objects.
+However, C++ does not guarantee an order of initialization between static
+objects in different translation units, so if a static ctor/dtor in your .cpp
+file used <code class="docutils literal notranslate"><span class="pre">std::cout</span></code>, for example, the object would not necessarily be
+automatically initialized before your use.</p>
+<p>To make <code class="docutils literal notranslate"><span class="pre">std::cout</span></code> and friends work correctly in these scenarios, the STL
+that we use declares a static object that gets created in every translation
+unit that includes <code class="docutils literal notranslate"><span class="pre"><iostream></span></code>. This object has a static constructor
+and destructor that initializes and destroys the global iostream objects
+before they could possibly be used in the file. The code that you see in the
+<code class="docutils literal notranslate"><span class="pre">.ll</span></code> file corresponds to the constructor and destructor registration code.</p>
+<p>If you would like to make it easier to <em>understand</em> the LLVM code generated
+by the compiler in the demo page, consider using <code class="docutils literal notranslate"><span class="pre">printf()</span></code> instead of
+<code class="docutils literal notranslate"><span class="pre">iostream</span></code>s to print values.</p>
+</div>
+<div class="section" id="where-did-all-of-my-code-go">
+<h3><a class="toc-backref" href="#id18">Where did all of my code go??</a><a class="headerlink" href="#where-did-all-of-my-code-go" title="Permalink to this headline">¶</a></h3>
+<p>If you are using the LLVM demo page, you may often wonder what happened to
+all of the code that you typed in. Remember that the demo script is running
+the code through the LLVM optimizers, so if your code doesnât actually do
+anything useful, it might all be deleted.</p>
+<p>To prevent this, make sure that the code is actually needed. For example, if
+you are computing some expression, return the value from the function instead
+of leaving it in a local variable. If you really want to constrain the
+optimizer, you can read from and assign to <code class="docutils literal notranslate"><span class="pre">volatile</span></code> global variables.</p>
+</div>
+<div class="section" id="what-is-this-undef-thing-that-shows-up-in-my-code">
+<h3><a class="toc-backref" href="#id19">What is this â<code class="docutils literal notranslate"><span class="pre">undef</span></code>â thing that shows up in my code?</a><a class="headerlink" href="#what-is-this-undef-thing-that-shows-up-in-my-code" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">undef</span></code> is the LLVM way of representing a value that is not defined. You
+can get these if you do not initialize a variable before you use it. For
+example, the C function:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">X</span><span class="p">()</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="k">return</span> <span class="n">i</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Is compiled to â<code class="docutils literal notranslate"><span class="pre">ret</span> <span class="pre">i32</span> <span class="pre">undef</span></code>â because â<code class="docutils literal notranslate"><span class="pre">i</span></code>â never has a value specified
+for it.</p>
+</div>
+<div class="section" id="why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it">
+<h3><a class="toc-backref" href="#id20">Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into âunreachableâ? Why not make the verifier reject it?</a><a class="headerlink" href="#why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it" title="Permalink to this headline">¶</a></h3>
+<p>This is a common problem run into by authors of front-ends that are using
+custom calling conventions: you need to make sure to set the right calling
+convention on both the function and on each call to the function. For
+example, this code:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Is optimized to:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">unreachable</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>⦠with â<code class="docutils literal notranslate"><span class="pre">opt</span> <span class="pre">-instcombine</span> <span class="pre">-simplifycfg</span></code>â. This often bites people because
+âall their code disappearsâ. Setting the calling convention on the caller and
+callee is required for indirect calls to work, so people often ask why not
+make the verifier reject this sort of thing.</p>
+<p>The answer is that this code has undefined behavior, but it is not illegal.
+If we made it illegal, then every transformation that could potentially create
+this would have to ensure that it doesnât, and there is valid code that can
+create this sort of construct (in dead code). The sorts of things that can
+cause this to happen are fairly contrived, but we still need to accept them.
+Hereâs an example:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="k">internal</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">(</span><span class="kt">void</span><span class="p">()*</span> <span class="nv">%FP</span><span class="p">,</span> <span class="k">i1</span> <span class="nv">%cond</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%cond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F</span>
+<span class="nl">T:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="nv">%FP</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="nl">F:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="nv">%FP</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">or</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">false</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">(</span><span class="kt">void</span><span class="p">()*</span> <span class="vg">@foo</span><span class="p">,</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this example, âtestâ always passes <code class="docutils literal notranslate"><span class="pre">@foo</span></code>/<code class="docutils literal notranslate"><span class="pre">false</span></code> into <code class="docutils literal notranslate"><span class="pre">bar</span></code>, which
+ensures that it is dynamically called with the right calling conv (thus, the
+code is perfectly well defined). If you run this through the inliner, you
+get this (the explicit âorâ is there so that the inliner doesnât dead code
+eliminate a bunch of stuff):</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">or</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">false</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T.i</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F.i</span>
+<span class="nl">T.i:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">bar.exit:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here you can see that the inlining pass made an undefined call to <code class="docutils literal notranslate"><span class="pre">@foo</span></code>
+with the wrong calling convention. We really donât want to make the inliner
+have to know about this sort of thing, so it needs to be valid code. In this
+case, dead code elimination can trivially remove the undefined code. However,
+if <code class="docutils literal notranslate"><span class="pre">%X</span></code> was an input argument to <code class="docutils literal notranslate"><span class="pre">@test</span></code>, the inliner would produce this:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T.i</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F.i</span>
+<span class="nl">T.i:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">bar.exit:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The interesting thing about this is that <code class="docutils literal notranslate"><span class="pre">%X</span></code> <em>must</em> be false for the
+code to be well-defined, but no amount of dead code elimination will be able
+to delete the broken call as unreachable. However, since
+<code class="docutils literal notranslate"><span class="pre">instcombine</span></code>/<code class="docutils literal notranslate"><span class="pre">simplifycfg</span></code> turns the undefined call into unreachable, we
+end up with a branch on a condition that goes to unreachable: a branch to
+unreachable can never happen, so â<code class="docutils literal notranslate"><span class="pre">-inline</span> <span class="pre">-instcombine</span> <span class="pre">-simplifycfg</span></code>â is
+able to produce:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/FaultMaps.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/FaultMaps.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/FaultMaps.html (added)
+++ www-releases/trunk/8.0.0/docs/FaultMaps.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,214 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>FaultMaps and implicit checks — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Machine IR (MIR) Format Reference Manual" href="MIRLangRef.html" />
+ <link rel="prev" title="Code Transformation Metadata" href="TransformMetadata.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TransformMetadata.html" title="Code Transformation Metadata"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="faultmaps-and-implicit-checks">
+<h1>FaultMaps and implicit checks<a class="headerlink" href="#faultmaps-and-implicit-checks" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#motivation" id="id1">Motivation</a></li>
+<li><a class="reference internal" href="#the-fault-map-section" id="id2">The Fault Map Section</a></li>
+<li><a class="reference internal" href="#the-implicitnullchecks-pass" id="id3">The <code class="docutils literal notranslate"><span class="pre">ImplicitNullChecks</span></code> pass</a><ul>
+<li><a class="reference internal" href="#make-implicit-metadata" id="id4"><code class="docutils literal notranslate"><span class="pre">make.implicit</span></code> metadata</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="motivation">
+<h2><a class="toc-backref" href="#id1">Motivation</a><a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2>
+<p>Code generated by managed language runtimes tend to have checks that
+are required for safety but never fail in practice. In such cases, it
+is profitable to make the non-failing case cheaper even if it makes
+the failing case significantly more expensive. This asymmetry can be
+exploited by folding such safety checks into operations that can be
+made to fault reliably if the check would have failed, and recovering
+from such a fault by using a signal handler.</p>
+<p>For example, Java requires null checks on objects before they are read
+from or written to. If the object is <code class="docutils literal notranslate"><span class="pre">null</span></code> then a
+<code class="docutils literal notranslate"><span class="pre">NullPointerException</span></code> has to be thrown, interrupting normal
+execution. In practice, however, dereferencing a <code class="docutils literal notranslate"><span class="pre">null</span></code> pointer is
+extremely rare in well-behaved Java programs, and typically the null
+check can be folded into a nearby memory operation that operates on
+the same memory location.</p>
+</div>
+<div class="section" id="the-fault-map-section">
+<h2><a class="toc-backref" href="#id2">The Fault Map Section</a><a class="headerlink" href="#the-fault-map-section" title="Permalink to this headline">¶</a></h2>
+<p>Information about implicit checks generated by LLVM are put in a
+special âfault mapâ section. On Darwin this section is named
+<code class="docutils literal notranslate"><span class="pre">__llvm_faultmaps</span></code>.</p>
+<p>The format of this section is</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Header {
+ uint8 : Fault Map Version (current version is 1)
+ uint8 : Reserved (expected to be 0)
+ uint16 : Reserved (expected to be 0)
+}
+uint32 : NumFunctions
+FunctionInfo[NumFunctions] {
+ uint64 : FunctionAddress
+ uint32 : NumFaultingPCs
+ uint32 : Reserved (expected to be 0)
+ FunctionFaultInfo[NumFaultingPCs] {
+ uint32 : FaultKind
+ uint32 : FaultingPCOffset
+ uint32 : HandlerPCOffset
+ }
+}
+</pre></div>
+</div>
+<p>FailtKind describes the reason of expected fault. Currently three kind
+of faults are supported:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><code class="docutils literal notranslate"><span class="pre">FaultMaps::FaultingLoad</span></code> - fault due to load from memory.</li>
+<li><code class="docutils literal notranslate"><span class="pre">FaultMaps::FaultingLoadStore</span></code> - fault due to instruction load and store.</li>
+<li><code class="docutils literal notranslate"><span class="pre">FaultMaps::FaultingStore</span></code> - fault due to store to memory.</li>
+</ol>
+</div></blockquote>
+</div>
+<div class="section" id="the-implicitnullchecks-pass">
+<h2><a class="toc-backref" href="#id3">The <code class="docutils literal notranslate"><span class="pre">ImplicitNullChecks</span></code> pass</a><a class="headerlink" href="#the-implicitnullchecks-pass" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">ImplicitNullChecks</span></code> pass transforms explicit control flow for
+checking if a pointer is <code class="docutils literal notranslate"><span class="pre">null</span></code>, like:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span> <span class="nv">%ptr</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@get_ptr</span><span class="p">()</span>
+ <span class="nv">%ptr_is_null</span> <span class="p">=</span> <span class="k">icmp</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">,</span> <span class="k">null</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ptr_is_null</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%is_null</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%not_null</span><span class="p">,</span> <span class="nv">!make.implicit</span> <span class="nv nv-Anonymous">!0</span>
+
+<span class="nl">not_null:</span>
+ <span class="nv">%t</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%ptr</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%do_something_with_t</span>
+
+<span class="nl">is_null:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@HFC</span><span class="p">()</span>
+ <span class="k">unreachable</span>
+
+<span class="nv nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{}</span>
+</pre></div>
+</div>
+<p>to control flow implicit in the instruction loading or storing through
+the pointer being null checked:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span> <span class="nv">%ptr</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@get_ptr</span><span class="p">()</span>
+ <span class="nv">%t</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%ptr</span> <span class="c">;; handler-pc = label %is_null</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%do_something_with_t</span>
+
+<span class="nl">is_null:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@HFC</span><span class="p">()</span>
+ <span class="k">unreachable</span>
+</pre></div>
+</div>
+<p>This transform happens at the <code class="docutils literal notranslate"><span class="pre">MachineInstr</span></code> level, not the LLVM IR
+level (so the above example is only representative, not literal). The
+<code class="docutils literal notranslate"><span class="pre">ImplicitNullChecks</span></code> pass runs during codegen, if
+<code class="docutils literal notranslate"><span class="pre">-enable-implicit-null-checks</span></code> is passed to <code class="docutils literal notranslate"><span class="pre">llc</span></code>.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">ImplicitNullChecks</span></code> pass adds entries to the
+<code class="docutils literal notranslate"><span class="pre">__llvm_faultmaps</span></code> section described above as needed.</p>
+<div class="section" id="make-implicit-metadata">
+<h3><a class="toc-backref" href="#id4"><code class="docutils literal notranslate"><span class="pre">make.implicit</span></code> metadata</a><a class="headerlink" href="#make-implicit-metadata" title="Permalink to this headline">¶</a></h3>
+<p>Making null checks implicit is an aggressive optimization, and it can
+be a net performance pessimization if too many memory operations end
+up faulting because of it. A language runtime typically needs to
+ensure that only a negligible number of implicit null checks actually
+fault once the application has reached a steady state. A standard way
+of doing this is by healing failed implicit null checks into explicit
+null checks via code patching or recompilation. It follows that there
+are two requirements an explicit null check needs to satisfy for it to
+be profitable to convert it to an implicit null check:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li>The case where the pointer is actually null (i.e. the âfailingâ
+case) is extremely rare.</li>
+<li>The failing path heals the implicit null check into an explicit
+null check so that the application does not repeatedly page
+fault.</li>
+</ol>
+</div></blockquote>
+<p>The frontend is expected to mark branches that satisfy (1) and (2)
+using a <code class="docutils literal notranslate"><span class="pre">!make.implicit</span></code> metadata node (the actual content of the
+metadata node is ignored). Only branches that are marked with
+<code class="docutils literal notranslate"><span class="pre">!make.implicit</span></code> metadata are considered as candidates for
+conversion into implicit null checks.</p>
+<p>(Note that while we could deal with (1) using profiling data, dealing
+with (2) requires some information not present in branch profiles.)</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TransformMetadata.html" title="Code Transformation Metadata"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/Frontend/PerformanceTips.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/Frontend/PerformanceTips.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/Frontend/PerformanceTips.html (added)
+++ www-releases/trunk/8.0.0/docs/Frontend/PerformanceTips.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,363 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Performance Tips for Frontend Authors — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="MCJIT Design and Implementation" href="../MCJITDesignAndImplementation.html" />
+ <link rel="prev" title="The Often Misunderstood GEP Instruction" href="../GetElementPtr.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../MCJITDesignAndImplementation.html" title="MCJIT Design and Implementation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="performance-tips-for-frontend-authors">
+<h1>Performance Tips for Frontend Authors<a class="headerlink" href="#performance-tips-for-frontend-authors" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#abstract" id="id2">Abstract</a></li>
+<li><a class="reference internal" href="#ir-best-practices" id="id3">IR Best Practices</a><ul>
+<li><a class="reference internal" href="#the-basics" id="id4">The Basics</a></li>
+<li><a class="reference internal" href="#use-of-allocas" id="id5">Use of allocas</a></li>
+<li><a class="reference internal" href="#avoid-loads-and-stores-of-large-aggregate-type" id="id6">Avoid loads and stores of large aggregate type</a></li>
+<li><a class="reference internal" href="#prefer-zext-over-sext-when-legal" id="id7">Prefer zext over sext when legal</a></li>
+<li><a class="reference internal" href="#zext-gep-indices-to-machine-register-width" id="id8">Zext GEP indices to machine register width</a></li>
+<li><a class="reference internal" href="#when-to-specify-alignment" id="id9">When to specify alignment</a></li>
+<li><a class="reference internal" href="#other-things-to-consider" id="id10">Other Things to Consider</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#describing-language-specific-properties" id="id11">Describing Language Specific Properties</a><ul>
+<li><a class="reference internal" href="#restricted-operation-semantics" id="id12">Restricted Operation Semantics</a></li>
+<li><a class="reference internal" href="#describing-aliasing-properties" id="id13">Describing Aliasing Properties</a></li>
+<li><a class="reference internal" href="#modeling-memory-effects" id="id14">Modeling Memory Effects</a></li>
+<li><a class="reference internal" href="#pass-ordering" id="id15">Pass Ordering</a></li>
+<li><a class="reference internal" href="#i-still-can-t-find-what-i-m-looking-for" id="id16">I Still Canât Find What Iâm Looking For</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#adding-to-this-document" id="id17">Adding to this document</a></li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h2><a class="toc-backref" href="#id2">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>The intended audience of this document is developers of language frontends
+targeting LLVM IR. This document is home to a collection of tips on how to
+generate IR that optimizes well.</p>
+</div>
+<div class="section" id="ir-best-practices">
+<h2><a class="toc-backref" href="#id3">IR Best Practices</a><a class="headerlink" href="#ir-best-practices" title="Permalink to this headline">¶</a></h2>
+<p>As with any optimizer, LLVM has its strengths and weaknesses. In some cases,
+surprisingly small changes in the source IR can have a large effect on the
+generated code.</p>
+<p>Beyond the specific items on the list below, itâs worth noting that the most
+mature frontend for LLVM is Clang. As a result, the further your IR gets from what Clang might emit, the less likely it is to be effectively optimized. It
+can often be useful to write a quick C program with the semantics youâre trying
+to model and see what decisions Clangâs IRGen makes about what IR to emit.
+Studying Clangâs CodeGen directory can also be a good source of ideas. Note
+that Clang and LLVM are explicitly version locked so youâll need to make sure
+youâre using a Clang built from the same svn revision or release as the LLVM
+library youâre using. As always, itâs <em>strongly</em> recommended that you track
+tip of tree development, particularly during bring up of a new project.</p>
+<div class="section" id="the-basics">
+<h3><a class="toc-backref" href="#id4">The Basics</a><a class="headerlink" href="#the-basics" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Make sure that your Modules contain both a data layout specification and
+target triple. Without these pieces, non of the target specific optimization
+will be enabled. This can have a major effect on the generated code quality.</li>
+<li>For each function or global emitted, use the most private linkage type
+possible (private, internal or linkonce_odr preferably). Doing so will
+make LLVMâs inter-procedural optimizations much more effective.</li>
+<li>Avoid high in-degree basic blocks (e.g. basic blocks with dozens or hundreds
+of predecessors). Among other issues, the register allocator is known to
+perform badly with confronted with such structures. The only exception to
+this guidance is that a unified return block with high in-degree is fine.</li>
+</ol>
+</div>
+<div class="section" id="use-of-allocas">
+<h3><a class="toc-backref" href="#id5">Use of allocas</a><a class="headerlink" href="#use-of-allocas" title="Permalink to this headline">¶</a></h3>
+<p>An alloca instruction can be used to represent a function scoped stack slot,
+but can also represent dynamic frame expansion. When representing function
+scoped variables or locations, placing alloca instructions at the beginning of
+the entry block should be preferred. In particular, place them before any
+call instructions. Call instructions might get inlined and replaced with
+multiple basic blocks. The end result is that a following alloca instruction
+would no longer be in the entry basic block afterward.</p>
+<p>The SROA (Scalar Replacement Of Aggregates) and Mem2Reg passes only attempt
+to eliminate alloca instructions that are in the entry basic block. Given
+SSA is the canonical form expected by much of the optimizer; if allocas can
+not be eliminated by Mem2Reg or SROA, the optimizer is likely to be less
+effective than it could be.</p>
+</div>
+<div class="section" id="avoid-loads-and-stores-of-large-aggregate-type">
+<h3><a class="toc-backref" href="#id6">Avoid loads and stores of large aggregate type</a><a class="headerlink" href="#avoid-loads-and-stores-of-large-aggregate-type" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently does not optimize well loads and stores of large <a class="reference internal" href="../LangRef.html#t-aggregate"><span class="std std-ref">aggregate
+types</span></a> (i.e. structs and arrays). As an alternative, consider
+loading individual fields from memory.</p>
+<p>Aggregates that are smaller than the largest (performant) load or store
+instruction supported by the targeted hardware are well supported. These can
+be an effective way to represent collections of small packed fields.</p>
+</div>
+<div class="section" id="prefer-zext-over-sext-when-legal">
+<h3><a class="toc-backref" href="#id7">Prefer zext over sext when legal</a><a class="headerlink" href="#prefer-zext-over-sext-when-legal" title="Permalink to this headline">¶</a></h3>
+<p>On some architectures (X86_64 is one), sign extension can involve an extra
+instruction whereas zero extension can be folded into a load. LLVM will try to
+replace a sext with a zext when it can be proven safe, but if you have
+information in your source language about the range of a integer value, it can
+be profitable to use a zext rather than a sext.</p>
+<p>Alternatively, you can <a class="reference internal" href="../LangRef.html#range-metadata"><span class="std std-ref">specify the range of the value using metadata</span></a> and LLVM can do the sext to zext conversion for you.</p>
+</div>
+<div class="section" id="zext-gep-indices-to-machine-register-width">
+<h3><a class="toc-backref" href="#id8">Zext GEP indices to machine register width</a><a class="headerlink" href="#zext-gep-indices-to-machine-register-width" title="Permalink to this headline">¶</a></h3>
+<p>Internally, LLVM often promotes the width of GEP indices to machine register
+width. When it does so, it will default to using sign extension (sext)
+operations for safety. If your source language provides information about
+the range of the index, you may wish to manually extend indices to machine
+register width using a zext instruction.</p>
+</div>
+<div class="section" id="when-to-specify-alignment">
+<h3><a class="toc-backref" href="#id9">When to specify alignment</a><a class="headerlink" href="#when-to-specify-alignment" title="Permalink to this headline">¶</a></h3>
+<p>LLVM will always generate correct code if you donât specify alignment, but may
+generate inefficient code. For example, if you are targeting MIPS (or older
+ARM ISAs) then the hardware does not handle unaligned loads and stores, and
+so you will enter a trap-and-emulate path if you do a load or store with
+lower-than-natural alignment. To avoid this, LLVM will emit a slower
+sequence of loads, shifts and masks (or load-right + load-left on MIPS) for
+all cases where the load / store does not have a sufficiently high alignment
+in the IR.</p>
+<p>The alignment is used to guarantee the alignment on allocas and globals,
+though in most cases this is unnecessary (most targets have a sufficiently
+high default alignment that theyâll be fine). It is also used to provide a
+contract to the back end saying âeither this load/store has this alignment, or
+it is undefined behaviorâ. This means that the back end is free to emit
+instructions that rely on that alignment (and mid-level optimizers are free to
+perform transforms that require that alignment). For x86, it doesnât make
+much difference, as almost all instructions are alignment-independent. For
+MIPS, it can make a big difference.</p>
+<p>Note that if your loads and stores are atomic, the backend will be unable to
+lower an under aligned access into a sequence of natively aligned accesses.
+As a result, alignment is mandatory for atomic loads and stores.</p>
+</div>
+<div class="section" id="other-things-to-consider">
+<h3><a class="toc-backref" href="#id10">Other Things to Consider</a><a class="headerlink" href="#other-things-to-consider" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Use ptrtoint/inttoptr sparingly (they interfere with pointer aliasing
+analysis), prefer GEPs</li>
+<li>Prefer globals over inttoptr of a constant address - this gives you
+dereferencability information. In MCJIT, use getSymbolAddress to provide
+actual address.</li>
+<li>Be wary of ordered and atomic memory operations. They are hard to optimize
+and may not be well optimized by the current optimizer. Depending on your
+source language, you may consider using fences instead.</li>
+<li>If calling a function which is known to throw an exception (unwind), use
+an invoke with a normal destination which contains an unreachable
+instruction. This form conveys to the optimizer that the call returns
+abnormally. For an invoke which neither returns normally or requires unwind
+code in the current function, you can use a noreturn call instruction if
+desired. This is generally not required because the optimizer will convert
+an invoke with an unreachable unwind destination to a call instruction.</li>
+<li>Use profile metadata to indicate statically known cold paths, even if
+dynamic profiling information is not available. This can make a large
+difference in code placement and thus the performance of tight loops.</li>
+<li>When generating code for loops, try to avoid terminating the header block of
+the loop earlier than necessary. If the terminator of the loop header
+block is a loop exiting conditional branch, the effectiveness of LICM will
+be limited for loads not in the header. (This is due to the fact that LLVM
+may not know such a load is safe to speculatively execute and thus canât
+lift an otherwise loop invariant load unless it can prove the exiting
+condition is not taken.) It can be profitable, in some cases, to emit such
+instructions into the header even if they are not used along a rarely
+executed path that exits the loop. This guidance specifically does not
+apply if the condition which terminates the loop header is itself invariant,
+or can be easily discharged by inspecting the loop index variables.</li>
+<li>In hot loops, consider duplicating instructions from small basic blocks
+which end in highly predictable terminators into their successor blocks.
+If a hot successor block contains instructions which can be vectorized
+with the duplicated ones, this can provide a noticeable throughput
+improvement. Note that this is not always profitable and does involve a
+potentially large increase in code size.</li>
+<li>When checking a value against a constant, emit the check using a consistent
+comparison type. The GVN pass <em>will</em> optimize redundant equalities even if
+the type of comparison is inverted, but GVN only runs late in the pipeline.
+As a result, you may miss the opportunity to run other important
+optimizations. Improvements to EarlyCSE to remove this issue are tracked in
+Bug 23333.</li>
+<li>Avoid using arithmetic intrinsics unless you are <em>required</em> by your source
+language specification to emit a particular code sequence. The optimizer
+is quite good at reasoning about general control flow and arithmetic, it is
+not anywhere near as strong at reasoning about the various intrinsics. If
+profitable for code generation purposes, the optimizer will likely form the
+intrinsics itself late in the optimization pipeline. It is <em>very</em> rarely
+profitable to emit these directly in the language frontend. This item
+explicitly includes the use of the <a class="reference internal" href="../LangRef.html#int-overflow"><span class="std std-ref">overflow intrinsics</span></a>.</li>
+<li>Avoid using the <a class="reference internal" href="../LangRef.html#int-assume"><span class="std std-ref">assume intrinsic</span></a> until youâve
+established that a) thereâs no other way to express the given fact and b)
+that fact is critical for optimization purposes. Assumes are a great
+prototyping mechanism, but they can have negative effects on both compile
+time and optimization effectiveness. The former is fixable with enough
+effort, but the later is fairly fundamental to their designed purpose.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="describing-language-specific-properties">
+<h2><a class="toc-backref" href="#id11">Describing Language Specific Properties</a><a class="headerlink" href="#describing-language-specific-properties" title="Permalink to this headline">¶</a></h2>
+<p>When translating a source language to LLVM, finding ways to express concepts
+and guarantees available in your source language which are not natively
+provided by LLVM IR will greatly improve LLVMâs ability to optimize your code.
+As an example, C/C++âs ability to mark every add as âno signed wrap (nsw)â goes
+a long way to assisting the optimizer in reasoning about loop induction
+variables and thus generating more optimal code for loops.</p>
+<p>The LLVM LangRef includes a number of mechanisms for annotating the IR with
+additional semantic information. It is <em>strongly</em> recommended that you become
+highly familiar with this document. The list below is intended to highlight a
+couple of items of particular interest, but is by no means exhaustive.</p>
+<div class="section" id="restricted-operation-semantics">
+<h3><a class="toc-backref" href="#id12">Restricted Operation Semantics</a><a class="headerlink" href="#restricted-operation-semantics" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Add nsw/nuw flags as appropriate. Reasoning about overflow is
+generally hard for an optimizer so providing these facts from the frontend
+can be very impactful.</li>
+<li>Use fast-math flags on floating point operations if legal. If you donât
+need strict IEEE floating point semantics, there are a number of additional
+optimizations that can be performed. This can be highly impactful for
+floating point intensive computations.</li>
+</ol>
+</div>
+<div class="section" id="describing-aliasing-properties">
+<h3><a class="toc-backref" href="#id13">Describing Aliasing Properties</a><a class="headerlink" href="#describing-aliasing-properties" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Add noalias/align/dereferenceable/nonnull to function arguments and return
+values as appropriate</li>
+<li>Use pointer aliasing metadata, especially tbaa metadata, to communicate
+otherwise-non-deducible pointer aliasing facts</li>
+<li>Use inbounds on geps. This can help to disambiguate some aliasing queries.</li>
+</ol>
+</div>
+<div class="section" id="modeling-memory-effects">
+<h3><a class="toc-backref" href="#id14">Modeling Memory Effects</a><a class="headerlink" href="#modeling-memory-effects" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Mark functions as readnone/readonly/argmemonly or noreturn/nounwind when
+known. The optimizer will try to infer these flags, but may not always be
+able to. Manual annotations are particularly important for external
+functions that the optimizer can not analyze.</li>
+<li>Use the lifetime.start/lifetime.end and invariant.start/invariant.end
+intrinsics where possible. Common profitable uses are for stack like data
+structures (thus allowing dead store elimination) and for describing
+life times of allocas (thus allowing smaller stack sizes).</li>
+<li>Mark invariant locations using !invariant.load and TBAAâs constant flags</li>
+</ol>
+</div>
+<div class="section" id="pass-ordering">
+<h3><a class="toc-backref" href="#id15">Pass Ordering</a><a class="headerlink" href="#pass-ordering" title="Permalink to this headline">¶</a></h3>
+<p>One of the most common mistakes made by new language frontend projects is to
+use the existing -O2 or -O3 pass pipelines as is. These pass pipelines make a
+good starting point for an optimizing compiler for any language, but they have
+been carefully tuned for C and C++, not your target language. You will almost
+certainly need to use a custom pass order to achieve optimal performance. A
+couple specific suggestions:</p>
+<ol class="arabic simple">
+<li>For languages with numerous rarely executed guard conditions (e.g. null
+checks, type checks, range checks) consider adding an extra execution or
+two of LoopUnswith and LICM to your pass order. The standard pass order,
+which is tuned for C and C++ applications, may not be sufficient to remove
+all dischargeable checks from loops.</li>
+<li>If you language uses range checks, consider using the IRCE pass. It is not
+currently part of the standard pass order.</li>
+<li>A useful sanity check to run is to run your optimized IR back through the
+-O2 pipeline again. If you see noticeable improvement in the resulting IR,
+you likely need to adjust your pass order.</li>
+</ol>
+</div>
+<div class="section" id="i-still-can-t-find-what-i-m-looking-for">
+<h3><a class="toc-backref" href="#id16">I Still Canât Find What Iâm Looking For</a><a class="headerlink" href="#i-still-can-t-find-what-i-m-looking-for" title="Permalink to this headline">¶</a></h3>
+<p>If you didnât find what you were looking for above, consider proposing an piece
+of metadata which provides the optimization hint you need. Such extensions are
+relatively common and are generally well received by the community. You will
+need to ensure that your proposal is sufficiently general so that it benefits
+others if you wish to contribute it upstream.</p>
+<p>You should also consider describing the problem youâre facing on <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a> and asking for advice.
+Itâs entirely possible someone has encountered your problem before and can
+give good advice. If there are multiple interested parties, that also
+increases the chances that a metadata extension would be well received by the
+community as a whole.</p>
+</div>
+</div>
+<div class="section" id="adding-to-this-document">
+<h2><a class="toc-backref" href="#id17">Adding to this document</a><a class="headerlink" href="#adding-to-this-document" title="Permalink to this headline">¶</a></h2>
+<p>If you run across a case that you feel deserves to be covered here, please send
+a patch to <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-commits">llvm-commits</a> for review.</p>
+<p>If you have questions on these items, please direct them to <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a>. The more relevant
+context you are able to give to your question, the more likely it is to be
+answered.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../MCJITDesignAndImplementation.html" title="MCJIT Design and Implementation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/FuzzingLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/FuzzingLLVM.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/FuzzingLLVM.html (added)
+++ www-releases/trunk/8.0.0/docs/FuzzingLLVM.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,312 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Fuzzing LLVM libraries and tools — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Scudo Hardened Allocator" href="ScudoHardenedAllocator.html" />
+ <link rel="prev" title="libFuzzer â a library for coverage-guided fuzz testing." href="LibFuzzer.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="ScudoHardenedAllocator.html" title="Scudo Hardened Allocator"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="fuzzing-llvm-libraries-and-tools">
+<h1>Fuzzing LLVM libraries and tools<a class="headerlink" href="#fuzzing-llvm-libraries-and-tools" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id7">Introduction</a></li>
+<li><a class="reference internal" href="#available-fuzzers" id="id8">Available Fuzzers</a><ul>
+<li><a class="reference internal" href="#clang-fuzzer" id="id9">clang-fuzzer</a></li>
+<li><a class="reference internal" href="#clang-proto-fuzzer" id="id10">clang-proto-fuzzer</a></li>
+<li><a class="reference internal" href="#clang-format-fuzzer" id="id11">clang-format-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-as-fuzzer" id="id12">llvm-as-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-dwarfdump-fuzzer" id="id13">llvm-dwarfdump-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-demangle-fuzzer" id="id14">llvm-demangle-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-isel-fuzzer" id="id15">llvm-isel-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-opt-fuzzer" id="id16">llvm-opt-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-mc-assemble-fuzzer" id="id17">llvm-mc-assemble-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-mc-disassemble-fuzzer" id="id18">llvm-mc-disassemble-fuzzer</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#mutators-and-input-generators" id="id19">Mutators and Input Generators</a><ul>
+<li><a class="reference internal" href="#generic-random-fuzzing" id="id20">Generic Random Fuzzing</a></li>
+<li><a class="reference internal" href="#structured-fuzzing-using-libprotobuf-mutator" id="id21">Structured Fuzzing using <code class="docutils literal notranslate"><span class="pre">libprotobuf-mutator</span></code></a></li>
+<li><a class="reference internal" href="#structured-fuzzing-of-llvm-ir" id="id22">Structured Fuzzing of LLVM IR</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#building-and-running" id="id23">Building and Running</a><ul>
+<li><a class="reference internal" href="#configuring-llvm-to-build-fuzzers" id="id24">Configuring LLVM to Build Fuzzers</a></li>
+<li><a class="reference internal" href="#continuously-running-and-finding-bugs" id="id25">Continuously Running and Finding Bugs</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#utilities-for-writing-fuzzers" id="id26">Utilities for Writing Fuzzers</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id7">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM tree includes a number of fuzzers for various components. These are
+built on top of <a class="reference internal" href="LibFuzzer.html"><span class="doc">LibFuzzer</span></a>. In order to build and run these
+fuzzers, see <a class="reference internal" href="#building-fuzzers"><span class="std std-ref">Configuring LLVM to Build Fuzzers</span></a>.</p>
+</div>
+<div class="section" id="available-fuzzers">
+<h2><a class="toc-backref" href="#id8">Available Fuzzers</a><a class="headerlink" href="#available-fuzzers" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="clang-fuzzer">
+<h3><a class="toc-backref" href="#id9">clang-fuzzer</a><a class="headerlink" href="#clang-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><span class="std std-ref">generic fuzzer</span></a> that tries to compile textual input as C++ code. Some of the
+bugs this fuzzer has reported are <a class="reference external" href="https://llvm.org/pr23057">on bugzilla</a> and <a class="reference external" href="https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+clang-fuzzer">on OSS Fuzzâs
+tracker</a>.</p>
+</div>
+<div class="section" id="clang-proto-fuzzer">
+<h3><a class="toc-backref" href="#id10">clang-proto-fuzzer</a><a class="headerlink" href="#clang-proto-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-protobuf"><span class="std std-ref">libprotobuf-mutator based fuzzer</span></a> that compiles valid C++ programs generated from a protobuf
+class that describes a subset of the C++ language.</p>
+<p>This fuzzer accepts clang command line options after <cite>ignore_remaining_args=1</cite>.
+For example, the following command will fuzz clang with a higher optimization
+level:</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>% bin/clang-proto-fuzzer <corpus-dir> -ignore_remaining_args<span class="o">=</span><span class="m">1</span> -O3
+</pre></div>
+</div>
+</div>
+<div class="section" id="clang-format-fuzzer">
+<h3><a class="toc-backref" href="#id11">clang-format-fuzzer</a><a class="headerlink" href="#clang-format-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><span class="std std-ref">generic fuzzer</span></a> that runs <a class="reference external" href="https://clang.llvm.org/docs/ClangFormat.html">clang-format</a> on C++ text fragments. Some of the
+bugs this fuzzer has reported are <a class="reference external" href="https://llvm.org/pr23052">on bugzilla</a>
+and <a class="reference external" href="https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+clang-format-fuzzer">on OSS Fuzzâs tracker</a>.</p>
+</div>
+<div class="section" id="llvm-as-fuzzer">
+<h3><a class="toc-backref" href="#id12">llvm-as-fuzzer</a><a class="headerlink" href="#llvm-as-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><span class="std std-ref">generic fuzzer</span></a> that tries to parse text as <a class="reference internal" href="LangRef.html"><span class="doc">LLVM assembly</span></a>.
+Some of the bugs this fuzzer has reported are <a class="reference external" href="https://llvm.org/pr24639">on bugzilla</a>.</p>
+</div>
+<div class="section" id="llvm-dwarfdump-fuzzer">
+<h3><a class="toc-backref" href="#id13">llvm-dwarfdump-fuzzer</a><a class="headerlink" href="#llvm-dwarfdump-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><span class="std std-ref">generic fuzzer</span></a> that interprets inputs as object files and runs
+<a class="reference internal" href="CommandGuide/llvm-dwarfdump.html"><span class="doc">llvm-dwarfdump</span></a> on them. Some of the bugs
+this fuzzer has reported are <a class="reference external" href="https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+llvm-dwarfdump-fuzzer">on OSS Fuzzâs tracker</a></p>
+</div>
+<div class="section" id="llvm-demangle-fuzzer">
+<h3><a class="toc-backref" href="#id14">llvm-demangle-fuzzer</a><a class="headerlink" href="#llvm-demangle-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><span class="std std-ref">generic fuzzer</span></a> for the Itanium demangler used in various LLVM tools. Weâve
+fuzzed __cxa_demangle to death, why not fuzz LLVMâs implementation of the same
+function!</p>
+</div>
+<div class="section" id="llvm-isel-fuzzer">
+<h3><a class="toc-backref" href="#id15">llvm-isel-fuzzer</a><a class="headerlink" href="#llvm-isel-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-ir"><span class="std std-ref">structured LLVM IR fuzzer</span></a> aimed at finding bugs in instruction selection.</p>
+<p>This fuzzer accepts flags after <cite>ignore_remaining_args=1</cite>. The flags match
+those of <a class="reference internal" href="CommandGuide/llc.html"><span class="doc">llc</span></a> and the triple is required. For example,
+the following command would fuzz AArch64 with <a class="reference internal" href="GlobalISel.html"><span class="doc">Global Instruction Selection</span></a>:</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>% bin/llvm-isel-fuzzer <corpus-dir> -ignore_remaining_args<span class="o">=</span><span class="m">1</span> -mtriple aarch64 -global-isel -O0
+</pre></div>
+</div>
+<p>Some flags can also be specified in the binary name itself in order to support
+OSS Fuzz, which has trouble with required arguments. To do this, you can copy
+or move <code class="docutils literal notranslate"><span class="pre">llvm-isel-fuzzer</span></code> to <code class="docutils literal notranslate"><span class="pre">llvm-isel-fuzzer--x-y-z</span></code>, separating options
+from the binary name using âââ. The valid options are architecture names
+(<code class="docutils literal notranslate"><span class="pre">aarch64</span></code>, <code class="docutils literal notranslate"><span class="pre">x86_64</span></code>), optimization levels (<code class="docutils literal notranslate"><span class="pre">O0</span></code>, <code class="docutils literal notranslate"><span class="pre">O2</span></code>), or specific
+keywords, like <code class="docutils literal notranslate"><span class="pre">gisel</span></code> for enabling global instruction selection. In this
+mode, the same example could be run like so:</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>% bin/llvm-isel-fuzzer--aarch64-O0-gisel <corpus-dir>
+</pre></div>
+</div>
+</div>
+<div class="section" id="llvm-opt-fuzzer">
+<h3><a class="toc-backref" href="#id16">llvm-opt-fuzzer</a><a class="headerlink" href="#llvm-opt-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-ir"><span class="std std-ref">structured LLVM IR fuzzer</span></a> aimed at finding bugs in optimization passes.</p>
+<p>It receives optimzation pipeline and runs it for each fuzzer input.</p>
+<p>Interface of this fuzzer almost directly mirrors <code class="docutils literal notranslate"><span class="pre">llvm-isel-fuzzer</span></code>. Both
+<code class="docutils literal notranslate"><span class="pre">mtriple</span></code> and <code class="docutils literal notranslate"><span class="pre">passes</span></code> arguments are required. Passes are specified in a
+format suitable for the new pass manager. You can find some documentation about
+this format in the doxygen for <code class="docutils literal notranslate"><span class="pre">PassBuilder::parsePassPipeline</span></code>.</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>% bin/llvm-opt-fuzzer <corpus-dir> -ignore_remaining_args<span class="o">=</span><span class="m">1</span> -mtriple x86_64 -passes instcombine
+</pre></div>
+</div>
+<p>Similarly to the <code class="docutils literal notranslate"><span class="pre">llvm-isel-fuzzer</span></code> arguments in some predefined configurations
+might be embedded directly into the binary file name:</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>% bin/llvm-opt-fuzzer--x86_64-instcombine <corpus-dir>
+</pre></div>
+</div>
+</div>
+<div class="section" id="llvm-mc-assemble-fuzzer">
+<h3><a class="toc-backref" href="#id17">llvm-mc-assemble-fuzzer</a><a class="headerlink" href="#llvm-mc-assemble-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><span class="std std-ref">generic fuzzer</span></a> that fuzzes the MC layerâs assemblers by treating inputs as
+target specific assembly.</p>
+<p>Note that this fuzzer has an unusual command line interface which is not fully
+compatible with all of libFuzzerâs features. Fuzzer arguments must be passed
+after <code class="docutils literal notranslate"><span class="pre">--fuzzer-args</span></code>, and any <code class="docutils literal notranslate"><span class="pre">llc</span></code> flags must use two dashes. For
+example, to fuzz the AArch64 assembler you might use the following command:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">llvm-mc-fuzzer --triple=aarch64-linux-gnu --fuzzer-args -max_len=4</span>
+</pre></div>
+</div>
+<p>This scheme will likely change in the future.</p>
+</div>
+<div class="section" id="llvm-mc-disassemble-fuzzer">
+<h3><a class="toc-backref" href="#id18">llvm-mc-disassemble-fuzzer</a><a class="headerlink" href="#llvm-mc-disassemble-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><span class="std std-ref">generic fuzzer</span></a> that fuzzes the MC layerâs disassemblers by treating inputs
+as assembled binary data.</p>
+<p>Note that this fuzzer has an unusual command line interface which is not fully
+compatible with all of libFuzzerâs features. See the notes above about
+<code class="docutils literal notranslate"><span class="pre">llvm-mc-assemble-fuzzer</span></code> for details.</p>
+</div>
+</div>
+<div class="section" id="mutators-and-input-generators">
+<h2><a class="toc-backref" href="#id19">Mutators and Input Generators</a><a class="headerlink" href="#mutators-and-input-generators" title="Permalink to this headline">¶</a></h2>
+<p>The inputs for a fuzz target are generated via random mutations of a
+<a class="reference internal" href="LibFuzzer.html#libfuzzer-corpus"><span class="std std-ref">corpus</span></a>. There are a few options for the kinds of
+mutations that a fuzzer in LLVM might want.</p>
+<div class="section" id="generic-random-fuzzing">
+<span id="fuzzing-llvm-generic"></span><h3><a class="toc-backref" href="#id20">Generic Random Fuzzing</a><a class="headerlink" href="#generic-random-fuzzing" title="Permalink to this headline">¶</a></h3>
+<p>The most basic form of input mutation is to use the built in mutators of
+LibFuzzer. These simply treat the input corpus as a bag of bits and make random
+mutations. This type of fuzzer is good for stressing the surface layers of a
+program, and is good at testing things like lexers, parsers, or binary
+protocols.</p>
+<p>Some of the in-tree fuzzers that use this type of mutator are <a class="reference internal" href="#clang-fuzzer">clang-fuzzer</a>,
+<a class="reference internal" href="#clang-format-fuzzer">clang-format-fuzzer</a>, <a class="reference internal" href="#llvm-as-fuzzer">llvm-as-fuzzer</a>, <a class="reference internal" href="#llvm-dwarfdump-fuzzer">llvm-dwarfdump-fuzzer</a>,
+<a class="reference internal" href="#llvm-mc-assemble-fuzzer">llvm-mc-assemble-fuzzer</a>, and <a class="reference internal" href="#llvm-mc-disassemble-fuzzer">llvm-mc-disassemble-fuzzer</a>.</p>
+</div>
+<div class="section" id="structured-fuzzing-using-libprotobuf-mutator">
+<span id="fuzzing-llvm-protobuf"></span><h3><a class="toc-backref" href="#id21">Structured Fuzzing using <code class="docutils literal notranslate"><span class="pre">libprotobuf-mutator</span></code></a><a class="headerlink" href="#structured-fuzzing-using-libprotobuf-mutator" title="Permalink to this headline">¶</a></h3>
+<p>We can use <a class="reference external" href="https://github.com/google/libprotobuf-mutator">libprotobuf-mutator</a> in order to perform structured fuzzing and
+stress deeper layers of programs. This works by defining a protobuf class that
+translates arbitrary data into structurally interesting input. Specifically, we
+use this to work with a subset of the C++ language and perform mutations that
+produce valid C++ programs in order to exercise parts of clang that are more
+interesting than parser error handling.</p>
+<p>To build this kind of fuzzer you need <a class="reference external" href="https://github.com/google/protobuf">protobuf</a> and its dependencies
+installed, and you need to specify some extra flags when configuring the build
+with <a class="reference internal" href="CMake.html"><span class="doc">CMake</span></a>. For example, <a class="reference internal" href="#clang-proto-fuzzer">clang-proto-fuzzer</a> can be enabled by
+adding <code class="docutils literal notranslate"><span class="pre">-DCLANG_ENABLE_PROTO_FUZZER=ON</span></code> to the flags described in
+<a class="reference internal" href="#building-fuzzers"><span class="std std-ref">Configuring LLVM to Build Fuzzers</span></a>.</p>
+<p>The only in-tree fuzzer that uses <code class="docutils literal notranslate"><span class="pre">libprotobuf-mutator</span></code> today is
+<a class="reference internal" href="#clang-proto-fuzzer">clang-proto-fuzzer</a>.</p>
+</div>
+<div class="section" id="structured-fuzzing-of-llvm-ir">
+<span id="fuzzing-llvm-ir"></span><h3><a class="toc-backref" href="#id22">Structured Fuzzing of LLVM IR</a><a class="headerlink" href="#structured-fuzzing-of-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<p>We also use a more direct form of structured fuzzing for fuzzers that take
+<a class="reference internal" href="LangRef.html"><span class="doc">LLVM IR</span></a> as input. This is achieved through the <code class="docutils literal notranslate"><span class="pre">FuzzMutate</span></code>
+library, which was <a class="reference external" href="https://www.youtube.com/watch?v=UBbQ_s6hNgg">discussed at EuroLLVM 2017</a>.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">FuzzMutate</span></code> library is used to structurally fuzz backends in
+<a class="reference internal" href="#llvm-isel-fuzzer">llvm-isel-fuzzer</a>.</p>
+</div>
+</div>
+<div class="section" id="building-and-running">
+<h2><a class="toc-backref" href="#id23">Building and Running</a><a class="headerlink" href="#building-and-running" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="configuring-llvm-to-build-fuzzers">
+<span id="building-fuzzers"></span><h3><a class="toc-backref" href="#id24">Configuring LLVM to Build Fuzzers</a><a class="headerlink" href="#configuring-llvm-to-build-fuzzers" title="Permalink to this headline">¶</a></h3>
+<p>Fuzzers will be built and linked to libFuzzer by default as long as you build
+LLVM with sanitizer coverage enabled. You would typically also enable at least
+one sanitizer to find bugs faster. The most common way to build the fuzzers is
+by adding the following two flags to your CMake invocation:
+<code class="docutils literal notranslate"><span class="pre">-DLLVM_USE_SANITIZER=Address</span> <span class="pre">-DLLVM_USE_SANITIZE_COVERAGE=On</span></code>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you have <code class="docutils literal notranslate"><span class="pre">compiler-rt</span></code> checked out in an LLVM tree when building
+with sanitizers, youâll want to specify <code class="docutils literal notranslate"><span class="pre">-DLLVM_BUILD_RUNTIME=Off</span></code>
+to avoid building the sanitizers themselves with sanitizers enabled.</p>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">You may run into issues if you build with BFD ld, which is the
+default linker on many unix systems. These issues are being tracked
+in <a class="reference external" href="https://llvm.org/PR34636">https://llvm.org/PR34636</a>.</p>
+</div>
+</div>
+<div class="section" id="continuously-running-and-finding-bugs">
+<h3><a class="toc-backref" href="#id25">Continuously Running and Finding Bugs</a><a class="headerlink" href="#continuously-running-and-finding-bugs" title="Permalink to this headline">¶</a></h3>
+<p>There used to be a public buildbot running LLVM fuzzers continuously, and while
+this did find issues, it didnât have a very good way to report problems in an
+actionable way. Because of this, weâre moving towards using <a class="reference external" href="https://github.com/google/oss-fuzz">OSS Fuzz</a> more
+instead.</p>
+<p>You can browse the <a class="reference external" href="https://bugs.chromium.org/p/oss-fuzz/issues/list?q=Proj-llvm">LLVM project issue list</a> for the bugs found by
+<a class="reference external" href="https://github.com/google/oss-fuzz/blob/master/projects/llvm">LLVM on OSS Fuzz</a>. These are also mailed to the <a class="reference external" href="http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-bugs">llvm-bugs mailing
+list</a>.</p>
+</div>
+</div>
+<div class="section" id="utilities-for-writing-fuzzers">
+<h2><a class="toc-backref" href="#id26">Utilities for Writing Fuzzers</a><a class="headerlink" href="#utilities-for-writing-fuzzers" title="Permalink to this headline">¶</a></h2>
+<p>There are some utilities available for writing fuzzers in LLVM.</p>
+<p>Some helpers for handling the command line interface are available in
+<code class="docutils literal notranslate"><span class="pre">include/llvm/FuzzMutate/FuzzerCLI.h</span></code>, including functions to parse command
+line options in a consistent way and to implement standalone main functions so
+your fuzzer can be built and tested when not built against libFuzzer.</p>
+<p>There is also some handling of the CMake config for fuzzers, where you should
+use the <code class="docutils literal notranslate"><span class="pre">add_llvm_fuzzer</span></code> to set up fuzzer targets. This function works
+similarly to functions such as <code class="docutils literal notranslate"><span class="pre">add_llvm_tool</span></code>, but they take care of linking
+to LibFuzzer when appropriate and can be passed the <code class="docutils literal notranslate"><span class="pre">DUMMY_MAIN</span></code> argument to
+enable standalone testing.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="ScudoHardenedAllocator.html" title="Scudo Hardened Allocator"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/GarbageCollection.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/GarbageCollection.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/GarbageCollection.html (added)
+++ www-releases/trunk/8.0.0/docs/GarbageCollection.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,1156 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Garbage Collection with LLVM — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Writing an LLVM Pass" href="WritingAnLLVMPass.html" />
+ <link rel="prev" title="How To Use Instruction Mappings" href="HowToUseInstrMappings.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="garbage-collection-with-llvm">
+<h1>Garbage Collection with LLVM<a class="headerlink" href="#garbage-collection-with-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#abstract" id="id1">Abstract</a></li>
+<li><a class="reference internal" href="#quick-start" id="id2">Quick Start</a></li>
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a><ul>
+<li><a class="reference internal" href="#what-is-garbage-collection" id="id4">What is Garbage Collection?</a></li>
+<li><a class="reference internal" href="#goals-and-non-goals" id="id5">Goals and non-goals</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#llvm-ir-features" id="id6">LLVM IR Features</a><ul>
+<li><a class="reference internal" href="#specifying-gc-code-generation-gc" id="id7">Specifying GC code generation: <code class="docutils literal notranslate"><span class="pre">gc</span> <span class="pre">"..."</span></code></a></li>
+<li><a class="reference internal" href="#gcroot" id="id8">Identifying GC roots on the stack</a><ul>
+<li><a class="reference internal" href="#using-gc-statepoint" id="id9">Using <code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code></a></li>
+<li><a class="reference internal" href="#using-llvm-gcwrite" id="id10">Using <code class="docutils literal notranslate"><span class="pre">llvm.gcwrite</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reading-and-writing-references-in-the-heap" id="id11">Reading and writing references in the heap</a><ul>
+<li><a class="reference internal" href="#write-barrier-llvm-gcwrite" id="id12">Write barrier: <code class="docutils literal notranslate"><span class="pre">llvm.gcwrite</span></code></a></li>
+<li><a class="reference internal" href="#read-barrier-llvm-gcread" id="id13">Read barrier: <code class="docutils literal notranslate"><span class="pre">llvm.gcread</span></code></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#built-in-gc-strategies" id="id14">Built In GC Strategies</a><ul>
+<li><a class="reference internal" href="#the-shadow-stack-gc" id="id15">The Shadow Stack GC</a></li>
+<li><a class="reference internal" href="#the-erlang-and-ocaml-gcs" id="id16">The âErlangâ and âOcamlâ GCs</a></li>
+<li><a class="reference internal" href="#the-statepoint-example-gc" id="id17">The Statepoint Example GC</a></li>
+<li><a class="reference internal" href="#the-coreclr-gc" id="id18">The CoreCLR GC</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#custom-gc-strategies" id="id19">Custom GC Strategies</a><ul>
+<li><a class="reference internal" href="#collector-requirements" id="id20">Collector Requirements</a></li>
+<li><a class="reference internal" href="#implementing-a-collector-plugin" id="id21">Implementing a collector plugin</a></li>
+<li><a class="reference internal" href="#overview-of-available-features" id="id22">Overview of available features</a></li>
+<li><a class="reference internal" href="#computing-stack-maps" id="id23">Computing stack maps</a></li>
+<li><a class="reference internal" href="#initializing-roots-to-null" id="id24">Initializing roots to null</a></li>
+<li><a class="reference internal" href="#custom-lowering-of-intrinsics" id="id25">Custom lowering of intrinsics</a></li>
+<li><a class="reference internal" href="#generating-safe-points" id="id26">Generating safe points</a></li>
+<li><a class="reference internal" href="#emitting-assembly-code-gcmetadataprinter" id="id27">Emitting assembly code: <code class="docutils literal notranslate"><span class="pre">GCMetadataPrinter</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#references" id="id28">References</a></li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h2><a class="toc-backref" href="#id1">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>This document covers how to integrate LLVM into a compiler for a language which
+supports garbage collection. <strong>Note that LLVM itself does not provide a
+garbage collector.</strong> You must provide your own.</p>
+</div>
+<div class="section" id="quick-start">
+<h2><a class="toc-backref" href="#id2">Quick Start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
+<p>First, you should pick a collector strategy. LLVM includes a number of built
+in ones, but you can also implement a loadable plugin with a custom definition.
+Note that the collector strategy is a description of how LLVM should generate
+code such that it interacts with your collector and runtime, not a description
+of the collector itself.</p>
+<p>Next, mark your generated functions as using your chosen collector strategy.
+From c++, you can call:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="o"><</span><span class="n">collector</span> <span class="n">description</span> <span class="n">name</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This will produce IR like the following fragment:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="k">gc</span> <span class="s">"<collector description name>"</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>When generating LLVM IR for your functions, you will need to:</p>
+<ul class="simple">
+<li>Use <code class="docutils literal notranslate"><span class="pre">@llvm.gcread</span></code> and/or <code class="docutils literal notranslate"><span class="pre">@llvm.gcwrite</span></code> in place of standard load and
+store instructions. These intrinsics are used to represent load and store
+barriers. If you collector does not require such barriers, you can skip
+this step.</li>
+<li>Use the memory allocation routines provided by your garbage collectorâs
+runtime library.</li>
+<li>If your collector requires them, generate type maps according to your
+runtimeâs binary interface. LLVM is not involved in the process. In
+particular, the LLVM type system is not suitable for conveying such
+information though the compiler.</li>
+<li>Insert any coordination code required for interacting with your collector.
+Many collectors require running application code to periodically check a
+flag and conditionally call a runtime function. This is often referred to
+as a safepoint poll.</li>
+</ul>
+<p>You will need to identify roots (i.e. references to heap objects your collector
+needs to know about) in your generated IR, so that LLVM can encode them into
+your final stack maps. Depending on the collector strategy chosen, this is
+accomplished by using either the <code class="docutils literal notranslate"><span class="pre">@llvm.gcroot</span></code> intrinsics or an
+<code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code> relocation sequence.</p>
+<p>Donât forget to create a root for each intermediate value that is generated when
+evaluating an expression. In <code class="docutils literal notranslate"><span class="pre">h(f(),</span> <span class="pre">g())</span></code>, the result of <code class="docutils literal notranslate"><span class="pre">f()</span></code> could
+easily be collected if evaluating <code class="docutils literal notranslate"><span class="pre">g()</span></code> triggers a collection.</p>
+<p>Finally, you need to link your runtime library with the generated program
+executable (for a static compiler) or ensure the appropriate symbols are
+available for the runtime linker (for a JIT compiler).</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-is-garbage-collection">
+<h3><a class="toc-backref" href="#id4">What is Garbage Collection?</a><a class="headerlink" href="#what-is-garbage-collection" title="Permalink to this headline">¶</a></h3>
+<p>Garbage collection is a widely used technique that frees the programmer from
+having to know the lifetimes of heap objects, making software easier to produce
+and maintain. Many programming languages rely on garbage collection for
+automatic memory management. There are two primary forms of garbage collection:
+conservative and accurate.</p>
+<p>Conservative garbage collection often does not require any special support from
+either the language or the compiler: it can handle non-type-safe programming
+languages (such as C/C++) and does not require any special information from the
+compiler. The <a class="reference external" href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm collector</a> is an example of a
+state-of-the-art conservative collector.</p>
+<p>Accurate garbage collection requires the ability to identify all pointers in the
+program at run-time (which requires that the source-language be type-safe in
+most cases). Identifying pointers at run-time requires compiler support to
+locate all places that hold live pointer variables at run-time, including the
+<a class="reference internal" href="#gcroot"><span class="std std-ref">processor stack and registers</span></a>.</p>
+<p>Conservative garbage collection is attractive because it does not require any
+special compiler support, but it does have problems. In particular, because the
+conservative garbage collector cannot <em>know</em> that a particular word in the
+machine is a pointer, it cannot move live objects in the heap (preventing the
+use of compacting and generational GC algorithms) and it can occasionally suffer
+from memory leaks due to integer values that happen to point to objects in the
+program. In addition, some aggressive compiler transformations can break
+conservative garbage collectors (though these seem rare in practice).</p>
+<p>Accurate garbage collectors do not suffer from any of these problems, but they
+can suffer from degraded scalar optimization of the program. In particular,
+because the runtime must be able to identify and update all pointers active in
+the program, some optimizations are less effective. In practice, however, the
+locality and performance benefits of using aggressive garbage collection
+techniques dominates any low-level losses.</p>
+<p>This document describes the mechanisms and interfaces provided by LLVM to
+support accurate garbage collection.</p>
+</div>
+<div class="section" id="goals-and-non-goals">
+<h3><a class="toc-backref" href="#id5">Goals and non-goals</a><a class="headerlink" href="#goals-and-non-goals" title="Permalink to this headline">¶</a></h3>
+<p>LLVMâs intermediate representation provides <a class="reference internal" href="#gc-intrinsics"><span class="std std-ref">garbage collection intrinsics</span></a> that offer support for a broad class of collector models. For
+instance, the intrinsics permit:</p>
+<ul class="simple">
+<li>semi-space collectors</li>
+<li>mark-sweep collectors</li>
+<li>generational collectors</li>
+<li>incremental collectors</li>
+<li>concurrent collectors</li>
+<li>cooperative collectors</li>
+<li>reference counting</li>
+</ul>
+<p>We hope that the support built into the LLVM IR is sufficient to support a
+broad class of garbage collected languages including Scheme, ML, Java, C#,
+Perl, Python, Lua, Ruby, other scripting languages, and more.</p>
+<p>Note that LLVM <strong>does not itself provide a garbage collector</strong> â this should
+be part of your languageâs runtime library. LLVM provides a framework for
+describing the garbage collectors requirements to the compiler. In particular,
+LLVM provides support for generating stack maps at call sites, polling for a
+safepoint, and emitting load and store barriers. You can also extend LLVM -
+possibly through a loadable <a class="reference internal" href="#plugin"><span class="std std-ref">code generation plugins</span></a> - to
+generate code and data structures which conforms to the <em>binary interface</em>
+specified by the <em>runtime library</em>. This is similar to the relationship between
+LLVM and DWARF debugging info, for example. The difference primarily lies in
+the lack of an established standard in the domain of garbage collection â thus
+the need for a flexible extension mechanism.</p>
+<p>The aspects of the binary interface with which LLVMâs GC support is
+concerned are:</p>
+<ul class="simple">
+<li>Creation of GC safepoints within code where collection is allowed to execute
+safely.</li>
+<li>Computation of the stack map. For each safe point in the code, object
+references within the stack frame must be identified so that the collector may
+traverse and perhaps update them.</li>
+<li>Write barriers when storing object references to the heap. These are commonly
+used to optimize incremental scans in generational collectors.</li>
+<li>Emission of read barriers when loading object references. These are useful
+for interoperating with concurrent collectors.</li>
+</ul>
+<p>There are additional areas that LLVM does not directly address:</p>
+<ul class="simple">
+<li>Registration of global roots with the runtime.</li>
+<li>Registration of stack map entries with the runtime.</li>
+<li>The functions used by the program to allocate memory, trigger a collection,
+etc.</li>
+<li>Computation or compilation of type maps, or registration of them with the
+runtime. These are used to crawl the heap for object references.</li>
+</ul>
+<p>In general, LLVMâs support for GC does not include features which can be
+adequately addressed with other features of the IR and does not specify a
+particular binary interface. On the plus side, this means that you should be
+able to integrate LLVM with an existing runtime. On the other hand, it can
+have the effect of leaving a lot of work for the developer of a novel
+language. We try to mitigate this by providing built in collector strategy
+descriptions that can work with many common collector designs and easy
+extension points. If you donât already have a specific binary interface
+you need to support, we recommend trying to use one of these built in collector
+strategies.</p>
+</div>
+</div>
+<div class="section" id="llvm-ir-features">
+<span id="gc-intrinsics"></span><h2><a class="toc-backref" href="#id6">LLVM IR Features</a><a class="headerlink" href="#llvm-ir-features" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the garbage collection facilities provided by the
+<a class="reference internal" href="LangRef.html"><span class="doc">LLVM intermediate representation</span></a>. The exact behavior of these
+IR features is specified by the selected <a class="reference internal" href="#plugin"><span class="std std-ref">GC strategy description</span></a>.</p>
+<div class="section" id="specifying-gc-code-generation-gc">
+<h3><a class="toc-backref" href="#id7">Specifying GC code generation: <code class="docutils literal notranslate"><span class="pre">gc</span> <span class="pre">"..."</span></code></a><a class="headerlink" href="#specifying-gc-code-generation-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>define <returntype> @name(...) gc "name" { ... }
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">gc</span></code> function attribute is used to specify the desired GC strategy to the
+compiler. Its programmatic equivalent is the <code class="docutils literal notranslate"><span class="pre">setGC</span></code> method of <code class="docutils literal notranslate"><span class="pre">Function</span></code>.</p>
+<p>Setting <code class="docutils literal notranslate"><span class="pre">gc</span> <span class="pre">"name"</span></code> on a function triggers a search for a matching subclass
+of GCStrategy. Some collector strategies are built in. You can add others
+using either the loadable plugin mechanism, or by patching your copy of LLVM.
+It is the selected GC strategy which defines the exact nature of the code
+generated to support GC. If none is found, the compiler will raise an error.</p>
+<p>Specifying the GC style on a per-function basis allows LLVM to link together
+programs that use different garbage collection algorithms (or none at all).</p>
+</div>
+<div class="section" id="gcroot">
+<span id="identifying-gc-roots-on-the-stack"></span><h3><a class="toc-backref" href="#id8">Identifying GC roots on the stack</a><a class="headerlink" href="#gcroot" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently supports two different mechanisms for describing references in
+compiled code at safepoints. <code class="docutils literal notranslate"><span class="pre">llvm.gcroot</span></code> is the older mechanism;
+<code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code> has been added more recently. At the moment, you can choose
+either implementation (on a per <a class="reference internal" href="#plugin"><span class="std std-ref">GC strategy</span></a> basis). Longer
+term, we will probably either migrate away from <code class="docutils literal notranslate"><span class="pre">llvm.gcroot</span></code> entirely, or
+substantially merge their implementations. Note that most new development
+work is focused on <code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code>.</p>
+<div class="section" id="using-gc-statepoint">
+<h4><a class="toc-backref" href="#id9">Using <code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code></a><a class="headerlink" href="#using-gc-statepoint" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference internal" href="Statepoints.html"><span class="doc">This page</span></a> contains detailed documentation for
+<code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code>.</p>
+</div>
+<div class="section" id="using-llvm-gcwrite">
+<h4><a class="toc-backref" href="#id10">Using <code class="docutils literal notranslate"><span class="pre">llvm.gcwrite</span></code></a><a class="headerlink" href="#using-llvm-gcwrite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="vg">@llvm.gcroot</span><span class="p">(</span><span class="k">i8</span><span class="p">**</span> <span class="nv">%ptrloc</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">llvm.gcroot</span></code> intrinsic is used to inform LLVM that a stack variable
+references an object on the heap and is to be tracked for garbage collection.
+The exact impact on generated code is specified by the Functionâs selected
+<a class="reference internal" href="#plugin"><span class="std std-ref">GC strategy</span></a>. All calls to <code class="docutils literal notranslate"><span class="pre">llvm.gcroot</span></code> <strong>must</strong> reside
+inside the first basic block.</p>
+<p>The first argument <strong>must</strong> be a value referring to an alloca instruction or a
+bitcast of an alloca. The second contains a pointer to metadata that should be
+associated with the pointer, and <strong>must</strong> be a constant or global value
+address. If your target collector uses tags, use a null pointer for metadata.</p>
+<p>A compiler which performs manual SSA construction <strong>must</strong> ensure that SSA
+values representing GC references are stored in to the alloca passed to the
+respective <code class="docutils literal notranslate"><span class="pre">gcroot</span></code> before every call site and reloaded after every call.
+A compiler which uses mem2reg to raise imperative code using <code class="docutils literal notranslate"><span class="pre">alloca</span></code> into
+SSA form need only add a call to <code class="docutils literal notranslate"><span class="pre">@llvm.gcroot</span></code> for those variables which
+are pointers into the GC heap.</p>
+<p>It is also important to mark intermediate values with <code class="docutils literal notranslate"><span class="pre">llvm.gcroot</span></code>. For
+example, consider <code class="docutils literal notranslate"><span class="pre">h(f(),</span> <span class="pre">g())</span></code>. Beware leaking the result of <code class="docutils literal notranslate"><span class="pre">f()</span></code> in the
+case that <code class="docutils literal notranslate"><span class="pre">g()</span></code> triggers a collection. Note, that stack variables must be
+initialized and marked with <code class="docutils literal notranslate"><span class="pre">llvm.gcroot</span></code> in functionâs prologue.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">%metadata</span></code> argument can be used to avoid requiring heap objects to have
+âisaâ pointers or tag bits. [<a class="reference internal" href="#appel89">Appel89</a>, <a class="reference internal" href="#goldberg91">Goldberg91</a>, <a class="reference internal" href="#tolmach94">Tolmach94</a>] If specified,
+its value will be tracked along with the location of the pointer in the stack
+frame.</p>
+<p>Consider the following fragment of Java code:</p>
+<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="o">{</span>
+ <span class="n">Object</span> <span class="n">X</span><span class="o">;</span> <span class="c1">// A null-initialized reference to an object</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+</pre></div>
+</div>
+<p>This block (which may be located in the middle of a function or in a loop nest),
+could be compiled to this LLVM code:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="nl">Entry:</span>
+ <span class="c">;; In the entry block for the function, allocate the</span>
+ <span class="c">;; stack space for X, which is an LLVM pointer.</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="nv">%Object</span><span class="p">*</span>
+
+ <span class="c">;; Tell LLVM that the stack space is a stack root.</span>
+ <span class="c">;; Java has type-tags on objects, so we pass null as metadata.</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span> <span class="k">to</span> <span class="k">i8</span><span class="p">**</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.gcroot</span><span class="p">(</span><span class="k">i8</span><span class="p">**</span> <span class="nv">%tmp</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="k">null</span><span class="p">)</span>
+ <span class="p">...</span>
+
+ <span class="c">;; "CodeBlock" is the block corresponding to the start</span>
+ <span class="c">;; of the scope above.</span>
+<span class="nl">CodeBlock:</span>
+ <span class="c">;; Java null-initializes pointers.</span>
+ <span class="k">store</span> <span class="nv">%Object</span><span class="p">*</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span>
+
+ <span class="p">...</span>
+
+ <span class="c">;; As the pointer goes out of scope, store a null value into</span>
+ <span class="c">;; it, to indicate that the value is no longer live.</span>
+ <span class="k">store</span> <span class="nv">%Object</span><span class="p">*</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="reading-and-writing-references-in-the-heap">
+<h3><a class="toc-backref" href="#id11">Reading and writing references in the heap</a><a class="headerlink" href="#reading-and-writing-references-in-the-heap" title="Permalink to this headline">¶</a></h3>
+<p>Some collectors need to be informed when the mutator (the program that needs
+garbage collection) either reads a pointer from or writes a pointer to a field
+of a heap object. The code fragments inserted at these points are called <em>read
+barriers</em> and <em>write barriers</em>, respectively. The amount of code that needs to
+be executed is usually quite small and not on the critical path of any
+computation, so the overall performance impact of the barrier is tolerable.</p>
+<p>Barriers often require access to the <em>object pointer</em> rather than the <em>derived
+pointer</em> (which is a pointer to the field within the object). Accordingly,
+these intrinsics take both pointers as separate arguments for completeness. In
+this snippet, <code class="docutils literal notranslate"><span class="pre">%object</span></code> is the object pointer, and <code class="docutils literal notranslate"><span class="pre">%derived</span></code> is the derived
+pointer:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">;; An array type.</span>
+<span class="nv">%class.Array</span> <span class="p">=</span> <span class="k">type</span> <span class="p">{</span> <span class="nv">%class.Object</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="p">[</span><span class="m">0</span> <span class="k">x</span> <span class="nv">%class.Object</span><span class="p">*]</span> <span class="p">}</span>
+<span class="p">...</span>
+
+<span class="c">;; Load the object pointer from a gcroot.</span>
+<span class="nv">%object</span> <span class="p">=</span> <span class="k">load</span> <span class="nv">%class.Array</span><span class="p">**</span> <span class="nv">%object_addr</span>
+
+<span class="c">;; Compute the derived pointer.</span>
+<span class="nv">%derived</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%n</span>
+</pre></div>
+</div>
+<p>LLVM does not enforce this relationship between the object and derived pointer
+(although a particular <a class="reference internal" href="#plugin"><span class="std std-ref">collector strategy</span></a> might). However, it
+would be an unusual collector that violated it.</p>
+<p>The use of these intrinsics is naturally optional if the target GC does not
+require the corresponding barrier. The GC strategy used with such a collector
+should replace the intrinsic calls with the corresponding <code class="docutils literal notranslate"><span class="pre">load</span></code> or
+<code class="docutils literal notranslate"><span class="pre">store</span></code> instruction if they are used.</p>
+<p>One known deficiency with the current design is that the barrier intrinsics do
+not include the size or alignment of the underlying operation performed. It is
+currently assumed that the operation is of pointer size and the alignment is
+assumed to be the target machineâs default alignment.</p>
+<div class="section" id="write-barrier-llvm-gcwrite">
+<h4><a class="toc-backref" href="#id12">Write barrier: <code class="docutils literal notranslate"><span class="pre">llvm.gcwrite</span></code></a><a class="headerlink" href="#write-barrier-llvm-gcwrite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="vg">@llvm.gcwrite</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%value</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%derived</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For write barriers, LLVM provides the <code class="docutils literal notranslate"><span class="pre">llvm.gcwrite</span></code> intrinsic function. It
+has exactly the same semantics as a non-volatile <code class="docutils literal notranslate"><span class="pre">store</span></code> to the derived
+pointer (the third argument). The exact code generated is specified by the
+Functionâs selected <a class="reference internal" href="#plugin"><span class="std std-ref">GC strategy</span></a>.</p>
+<p>Many important algorithms require write barriers, including generational and
+concurrent collectors. Additionally, write barriers could be used to implement
+reference counting.</p>
+</div>
+<div class="section" id="read-barrier-llvm-gcread">
+<h4><a class="toc-backref" href="#id13">Read barrier: <code class="docutils literal notranslate"><span class="pre">llvm.gcread</span></code></a><a class="headerlink" href="#read-barrier-llvm-gcread" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.gcread</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%derived</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For read barriers, LLVM provides the <code class="docutils literal notranslate"><span class="pre">llvm.gcread</span></code> intrinsic function. It has
+exactly the same semantics as a non-volatile <code class="docutils literal notranslate"><span class="pre">load</span></code> from the derived pointer
+(the second argument). The exact code generated is specified by the Functionâs
+selected <a class="reference internal" href="#plugin"><span class="std std-ref">GC strategy</span></a>.</p>
+<p>Read barriers are needed by fewer algorithms than write barriers, and may have a
+greater performance impact since pointer reads are more frequent than writes.</p>
+</div>
+</div>
+</div>
+<div class="section" id="built-in-gc-strategies">
+<span id="builtin-gc-strategies"></span><span id="plugin"></span><h2><a class="toc-backref" href="#id14">Built In GC Strategies</a><a class="headerlink" href="#built-in-gc-strategies" title="Permalink to this headline">¶</a></h2>
+<p>LLVM includes built in support for several varieties of garbage collectors.</p>
+<div class="section" id="the-shadow-stack-gc">
+<h3><a class="toc-backref" href="#id15">The Shadow Stack GC</a><a class="headerlink" href="#the-shadow-stack-gc" title="Permalink to this headline">¶</a></h3>
+<p>To use this collector strategy, mark your functions with:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"shadow-stack"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Unlike many GC algorithms which rely on a cooperative code generator to compile
+stack maps, this algorithm carefully maintains a linked list of stack roots
+[<a class="reference internal" href="#henderson02"><span class="std std-ref">Henderson2002</span></a>]. This so-called âshadow stackâ mirrors the
+machine stack. Maintaining this data structure is slower than using a stack map
+compiled into the executable as constant data, but has a significant portability
+advantage because it requires no special support from the target code generator,
+and does not require tricky platform-specific code to crawl the machine stack.</p>
+<p>The tradeoff for this simplicity and portability is:</p>
+<ul class="simple">
+<li>High overhead per function call.</li>
+<li>Not thread-safe.</li>
+</ul>
+<p>Still, itâs an easy way to get started. After your compiler and runtime are up
+and running, writing a <a class="reference internal" href="#plugin"><span class="std std-ref">plugin</span></a> will allow you to take advantage
+of <a class="reference internal" href="#collector-algos"><span class="std std-ref">more advanced GC features</span></a> of LLVM in order to
+improve performance.</p>
+<p>The shadow stack doesnât imply a memory allocation algorithm. A semispace
+collector or building atop <code class="docutils literal notranslate"><span class="pre">malloc</span></code> are great places to start, and can be
+implemented with very little code.</p>
+<p>When it comes time to collect, however, your runtime needs to traverse the stack
+roots, and for this it needs to integrate with the shadow stack. Luckily, doing
+so is very simple. (This code is heavily commented to help you understand the
+data structure, but there are only 20 lines of meaningful code.)</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">/// The map for a single function's stack frame. One of these is</span>
+<span class="c1">/// compiled as constant data into the executable for each function.</span>
+<span class="c1">///</span>
+<span class="c1">/// Storage of metadata values is elided if the %metadata parameter to</span>
+<span class="c1">/// @llvm.gcroot is null.</span>
+<span class="k">struct</span> <span class="n">FrameMap</span> <span class="p">{</span>
+ <span class="kt">int32_t</span> <span class="n">NumRoots</span><span class="p">;</span> <span class="c1">//< Number of roots in stack frame.</span>
+ <span class="kt">int32_t</span> <span class="n">NumMeta</span><span class="p">;</span> <span class="c1">//< Number of metadata entries. May be < NumRoots.</span>
+ <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Meta</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> <span class="c1">//< Metadata for each root.</span>
+<span class="p">};</span>
+
+<span class="c1">/// A link in the dynamic shadow stack. One of these is embedded in</span>
+<span class="c1">/// the stack frame of each function on the call stack.</span>
+<span class="k">struct</span> <span class="n">StackEntry</span> <span class="p">{</span>
+ <span class="n">StackEntry</span> <span class="o">*</span><span class="n">Next</span><span class="p">;</span> <span class="c1">//< Link to next stack entry (the caller's).</span>
+ <span class="k">const</span> <span class="n">FrameMap</span> <span class="o">*</span><span class="n">Map</span><span class="p">;</span> <span class="c1">//< Pointer to constant FrameMap.</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">Roots</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> <span class="c1">//< Stack roots (in-place array).</span>
+<span class="p">};</span>
+
+<span class="c1">/// The head of the singly-linked list of StackEntries. Functions push</span>
+<span class="c1">/// and pop onto this in their prologue and epilogue.</span>
+<span class="c1">///</span>
+<span class="c1">/// Since there is only a global list, this technique is not threadsafe.</span>
+<span class="n">StackEntry</span> <span class="o">*</span><span class="n">llvm_gc_root_chain</span><span class="p">;</span>
+
+<span class="c1">/// Calls Visitor(root, meta) for each GC root on the stack.</span>
+<span class="c1">/// root and meta are exactly the values passed to</span>
+<span class="c1">/// @llvm.gcroot.</span>
+<span class="c1">///</span>
+<span class="c1">/// Visitor could be a function to recursively mark live objects. Or it</span>
+<span class="c1">/// might copy them to another heap or generation.</span>
+<span class="c1">///</span>
+<span class="c1">/// @param Visitor A function to invoke for every GC root on the stack.</span>
+<span class="kt">void</span> <span class="nf">visitGCRoots</span><span class="p">(</span><span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">Visitor</span><span class="p">)(</span><span class="kt">void</span> <span class="o">**</span><span class="n">Root</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Meta</span><span class="p">))</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">StackEntry</span> <span class="o">*</span><span class="n">R</span> <span class="o">=</span> <span class="n">llvm_gc_root_chain</span><span class="p">;</span> <span class="n">R</span><span class="p">;</span> <span class="n">R</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Next</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="c1">// For roots [0, NumMeta), the metadata pointer is in the FrameMap.</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">e</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">NumMeta</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Visitor</span><span class="p">(</span><span class="o">&</span><span class="n">R</span><span class="o">-></span><span class="n">Roots</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">Meta</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+
+ <span class="c1">// For roots [NumMeta, NumRoots), the metadata pointer is null.</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">e</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">NumRoots</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Visitor</span><span class="p">(</span><span class="o">&</span><span class="n">R</span><span class="o">-></span><span class="n">Roots</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="nb">NULL</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-erlang-and-ocaml-gcs">
+<h3><a class="toc-backref" href="#id16">The âErlangâ and âOcamlâ GCs</a><a class="headerlink" href="#the-erlang-and-ocaml-gcs" title="Permalink to this headline">¶</a></h3>
+<p>LLVM ships with two example collectors which leverage the <code class="docutils literal notranslate"><span class="pre">gcroot</span></code>
+mechanisms. To our knowledge, these are not actually used by any language
+runtime, but they do provide a reasonable starting point for someone interested
+in writing an <code class="docutils literal notranslate"><span class="pre">gcroot</span></code> compatible GC plugin. In particular, these are the
+only in tree examples of how to produce a custom binary stack map format using
+a <code class="docutils literal notranslate"><span class="pre">gcroot</span></code> strategy.</p>
+<p>As there names imply, the binary format produced is intended to model that
+used by the Erlang and OCaml compilers respectively.</p>
+</div>
+<div class="section" id="the-statepoint-example-gc">
+<span id="statepoint-example-gc"></span><h3><a class="toc-backref" href="#id17">The Statepoint Example GC</a><a class="headerlink" href="#the-statepoint-example-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"statepoint-example"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This GC provides an example of how one might use the infrastructure provided
+by <code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code>. This example GC is compatible with the
+<a class="reference internal" href="Statepoints.html#placesafepoints"><span class="std std-ref">PlaceSafepoints</span></a> and <a class="reference internal" href="Statepoints.html#rewritestatepointsforgc"><span class="std std-ref">RewriteStatepointsForGC</span></a> utility passes
+which simplify <code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code> sequence insertion. If you need to build a
+custom GC strategy around the <code class="docutils literal notranslate"><span class="pre">gc.statepoints</span></code> mechanisms, it is recommended
+that you use this one as a starting point.</p>
+<p>This GC strategy does not support read or write barriers. As a result, these
+intrinsics are lowered to normal loads and stores.</p>
+<p>The stack map format generated by this GC strategy can be found in the
+<a class="reference internal" href="StackMaps.html#stackmap-section"><span class="std std-ref">Stack Map Section</span></a> using a format documented <a class="reference internal" href="Statepoints.html#statepoint-stackmap-format"><span class="std std-ref">here</span></a>. This format is intended to be the standard
+format supported by LLVM going forward.</p>
+</div>
+<div class="section" id="the-coreclr-gc">
+<h3><a class="toc-backref" href="#id18">The CoreCLR GC</a><a class="headerlink" href="#the-coreclr-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"coreclr"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This GC leverages the <code class="docutils literal notranslate"><span class="pre">gc.statepoint</span></code> mechanism to support the
+<a class="reference external" href="https://github.com/dotnet/coreclr">CoreCLR</a> runtime.</p>
+<p>Support for this GC strategy is a work in progress. This strategy will
+differ from
+<a class="reference internal" href="#statepoint-example-gc"><span class="std std-ref">statepoint-example GC</span></a> strategy in
+certain aspects like:</p>
+<ul class="simple">
+<li>Base-pointers of interior pointers are not explicitly
+tracked and reported.</li>
+<li>A different format is used for encoding stack maps.</li>
+<li>Safe-point polls are only needed before loop-back edges
+and before tail-calls (not needed at function-entry).</li>
+</ul>
+</div>
+</div>
+<div class="section" id="custom-gc-strategies">
+<h2><a class="toc-backref" href="#id19">Custom GC Strategies</a><a class="headerlink" href="#custom-gc-strategies" title="Permalink to this headline">¶</a></h2>
+<p>If none of the built in GC strategy descriptions met your needs above, you will
+need to define a custom GCStrategy and possibly, a custom LLVM pass to perform
+lowering. Your best example of where to start defining a custom GCStrategy
+would be to look at one of the built in strategies.</p>
+<p>You may be able to structure this additional code as a loadable plugin library.
+Loadable plugins are sufficient if all you need is to enable a different
+combination of built in functionality, but if you need to provide a custom
+lowering pass, you will need to build a patched version of LLVM. If you think
+you need a patched build, please ask for advice on llvm-dev. There may be an
+easy way we can extend the support to make it work for your use case without
+requiring a custom build.</p>
+<div class="section" id="collector-requirements">
+<h3><a class="toc-backref" href="#id20">Collector Requirements</a><a class="headerlink" href="#collector-requirements" title="Permalink to this headline">¶</a></h3>
+<p>You should be able to leverage any existing collector library that includes the following elements:</p>
+<ol class="arabic simple">
+<li>A memory allocator which exposes an allocation function your compiled
+code can call.</li>
+<li>A binary format for the stack map. A stack map describes the location
+of references at a safepoint and is used by precise collectors to identify
+references within a stack frame on the machine stack. Note that collectors
+which conservatively scan the stack donât require such a structure.</li>
+<li>A stack crawler to discover functions on the call stack, and enumerate the
+references listed in the stack map for each call site.</li>
+<li>A mechanism for identifying references in global locations (e.g. global
+variables).</li>
+<li>If you collector requires them, an LLVM IR implementation of your collectors
+load and store barriers. Note that since many collectors donât require
+barriers at all, LLVM defaults to lowering such barriers to normal loads
+and stores unless you arrange otherwise.</li>
+</ol>
+</div>
+<div class="section" id="implementing-a-collector-plugin">
+<h3><a class="toc-backref" href="#id21">Implementing a collector plugin</a><a class="headerlink" href="#implementing-a-collector-plugin" title="Permalink to this headline">¶</a></h3>
+<p>User code specifies which GC code generation to use with the <code class="docutils literal notranslate"><span class="pre">gc</span></code> function
+attribute or, equivalently, with the <code class="docutils literal notranslate"><span class="pre">setGC</span></code> method of <code class="docutils literal notranslate"><span class="pre">Function</span></code>.</p>
+<p>To implement a GC plugin, it is necessary to subclass <code class="docutils literal notranslate"><span class="pre">llvm::GCStrategy</span></code>,
+which can be accomplished in a few lines of boilerplate code. LLVMâs
+infrastructure provides access to several important algorithms. For an
+uncontroversial collector, all that remains may be to compile LLVMâs computed
+stack map to assembly code (using the binary representation expected by the
+runtime library). This can be accomplished in about 100 lines of code.</p>
+<p>This is not the appropriate place to implement a garbage collected heap or a
+garbage collector itself. That code should exist in the languageâs runtime
+library. The compiler plugin is responsible for generating code which conforms
+to the binary interface defined by library, most essentially the <a class="reference internal" href="#stack-map"><span class="std std-ref">stack map</span></a>.</p>
+<p>To subclass <code class="docutils literal notranslate"><span class="pre">llvm::GCStrategy</span></code> and register it with the compiler:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// lib/MyGC/MyGC.cpp - Example LLVM GC plugin</span>
+
+<span class="cp">#include</span> <span class="cpf">"llvm/CodeGen/GCStrategy.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"llvm/CodeGen/GCMetadata.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"llvm/Support/Compiler.h"</span><span class="cp"></span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">LLVM_LIBRARY_VISIBILITY</span> <span class="nl">MyGC</span> <span class="p">:</span> <span class="k">public</span> <span class="n">GCStrategy</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="n">MyGC</span><span class="p">()</span> <span class="p">{}</span>
+ <span class="p">};</span>
+
+ <span class="n">GCRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyGC</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="s">"mygc"</span><span class="p">,</span> <span class="s">"My bespoke garbage collector."</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This boilerplate collector does nothing. More specifically:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">llvm.gcread</span></code> calls are replaced with the corresponding <code class="docutils literal notranslate"><span class="pre">load</span></code>
+instruction.</li>
+<li><code class="docutils literal notranslate"><span class="pre">llvm.gcwrite</span></code> calls are replaced with the corresponding <code class="docutils literal notranslate"><span class="pre">store</span></code>
+instruction.</li>
+<li>No safe points are added to the code.</li>
+<li>The stack map is not compiled into the executable.</li>
+</ul>
+<p>Using the LLVM makefiles, this code
+can be compiled as a plugin using a simple makefile:</p>
+<div class="highlight-make notranslate"><div class="highlight"><pre><span></span><span class="c"># lib/MyGC/Makefile</span>
+
+<span class="nv">LEVEL</span> <span class="o">:=</span> ../..
+<span class="nv">LIBRARYNAME</span> <span class="o">=</span> MyGC
+<span class="nv">LOADABLE_MODULE</span> <span class="o">=</span> <span class="m">1</span>
+
+<span class="cp">include $(LEVEL)/Makefile.common</span>
+</pre></div>
+</div>
+<p>Once the plugin is compiled, code using it may be compiled using <code class="docutils literal notranslate"><span class="pre">llc</span>
+<span class="pre">-load=MyGC.so</span></code> (though MyGC.so may have some other platform-specific
+extension):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cat sample.ll
+define void @f() gc "mygc" {
+entry:
+ ret void
+}
+$ llvm-as < sample.ll | llc -load=MyGC.so
+</pre></div>
+</div>
+<p>It is also possible to statically link the collector plugin into tools, such as
+a language-specific compiler front-end.</p>
+</div>
+<div class="section" id="overview-of-available-features">
+<span id="collector-algos"></span><h3><a class="toc-backref" href="#id22">Overview of available features</a><a class="headerlink" href="#overview-of-available-features" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">GCStrategy</span></code> provides a range of features through which a plugin may do useful
+work. Some of these are callbacks, some are algorithms that can be enabled,
+disabled, or customized. This matrix summarizes the supported (and planned)
+features and correlates them with the collection techniques which typically
+require them.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="14%" />
+<col width="7%" />
+<col width="9%" />
+<col width="11%" />
+<col width="8%" />
+<col width="10%" />
+<col width="15%" />
+<col width="11%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Algorithm</th>
+<th class="head">Done</th>
+<th class="head">Shadow
+stack</th>
+<th class="head">refcount</th>
+<th class="head">mark-
+sweep</th>
+<th class="head">copying</th>
+<th class="head">incremental</th>
+<th class="head">threaded</th>
+<th class="head">concurrent</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>stack map</td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td>initialize
+roots</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>derived
+pointers</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong>*</td>
+<td><strong>N</strong>*</td>
+</tr>
+<tr class="row-odd"><td><strong>custom
+lowering</strong></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>gcroot</em></td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-odd"><td><em>gcwrite</em></td>
+<td>â</td>
+<td> </td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td> </td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td><em>gcread</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><strong>safe
+points</strong></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>in
+calls</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><em>before
+calls</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td><em>for
+loops</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong></td>
+<td><strong>N</strong></td>
+</tr>
+<tr class="row-odd"><td><em>before
+escape</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>emit code
+at safe
+points</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong></td>
+<td><strong>N</strong></td>
+</tr>
+<tr class="row-odd"><td><strong>output</strong></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>assembly</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><em>JIT</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-even"><td><em>obj</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-odd"><td>live
+analysis</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-even"><td>register
+map</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-odd"><td colspan="9">* Derived pointers only pose a hasard to copying collections.</td>
+</tr>
+<tr class="row-even"><td colspan="9"><strong>?</strong> denotes a feature which could be utilized if available.</td>
+</tr>
+</tbody>
+</table>
+<p>To be clear, the collection techniques above are defined as:</p>
+<dl class="docutils">
+<dt>Shadow Stack</dt>
+<dd>The mutator carefully maintains a linked list of stack roots.</dd>
+<dt>Reference Counting</dt>
+<dd>The mutator maintains a reference count for each object and frees an object
+when its count falls to zero.</dd>
+<dt>Mark-Sweep</dt>
+<dd>When the heap is exhausted, the collector marks reachable objects starting
+from the roots, then deallocates unreachable objects in a sweep phase.</dd>
+<dt>Copying</dt>
+<dd>As reachability analysis proceeds, the collector copies objects from one heap
+area to another, compacting them in the process. Copying collectors enable
+highly efficient âbump pointerâ allocation and can improve locality of
+reference.</dd>
+<dt>Incremental</dt>
+<dd>(Including generational collectors.) Incremental collectors generally have all
+the properties of a copying collector (regardless of whether the mature heap
+is compacting), but bring the added complexity of requiring write barriers.</dd>
+<dt>Threaded</dt>
+<dd>Denotes a multithreaded mutator; the collector must still stop the mutator
+(âstop the worldâ) before beginning reachability analysis. Stopping a
+multithreaded mutator is a complicated problem. It generally requires highly
+platform-specific code in the runtime, and the production of carefully
+designed machine code at safe points.</dd>
+<dt>Concurrent</dt>
+<dd>In this technique, the mutator and the collector run concurrently, with the
+goal of eliminating pause times. In a <em>cooperative</em> collector, the mutator
+further aids with collection should a pause occur, allowing collection to take
+advantage of multiprocessor hosts. The âstop the worldâ problem of threaded
+collectors is generally still present to a limited extent. Sophisticated
+marking algorithms are necessary. Read barriers may be necessary.</dd>
+</dl>
+<p>As the matrix indicates, LLVMâs garbage collection infrastructure is already
+suitable for a wide variety of collectors, but does not currently extend to
+multithreaded programs. This will be added in the future as there is
+interest.</p>
+</div>
+<div class="section" id="computing-stack-maps">
+<span id="stack-map"></span><h3><a class="toc-backref" href="#id23">Computing stack maps</a><a class="headerlink" href="#computing-stack-maps" title="Permalink to this headline">¶</a></h3>
+<p>LLVM automatically computes a stack map. One of the most important features
+of a <code class="docutils literal notranslate"><span class="pre">GCStrategy</span></code> is to compile this information into the executable in
+the binary representation expected by the runtime library.</p>
+<p>The stack map consists of the location and identity of each GC root in the
+each function in the module. For each root:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">RootNum</span></code>: The index of the root.</li>
+<li><code class="docutils literal notranslate"><span class="pre">StackOffset</span></code>: The offset of the object relative to the frame pointer.</li>
+<li><code class="docutils literal notranslate"><span class="pre">RootMetadata</span></code>: The value passed as the <code class="docutils literal notranslate"><span class="pre">%metadata</span></code> parameter to the
+<code class="docutils literal notranslate"><span class="pre">@llvm.gcroot</span></code> intrinsic.</li>
+</ul>
+<p>Also, for the function as a whole:</p>
+<ul class="simple">
+<li><dl class="first docutils">
+<dt><code class="docutils literal notranslate"><span class="pre">getFrameSize()</span></code>: The overall size of the functionâs initial stack frame,</dt>
+<dd>not accounting for any dynamic allocation.</dd>
+</dl>
+</li>
+<li><code class="docutils literal notranslate"><span class="pre">roots_size()</span></code>: The count of roots in the function.</li>
+</ul>
+<p>To access the stack map, use <code class="docutils literal notranslate"><span class="pre">GCFunctionMetadata::roots_begin()</span></code> and
+-<code class="docutils literal notranslate"><span class="pre">end()</span></code> from the <a class="reference internal" href="#assembly"><span class="std std-ref">GCMetadataPrinter</span></a>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">*</span><span class="n">FI</span> <span class="o">=</span> <span class="o">*</span><span class="n">I</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">FrameSize</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">getFrameSize</span><span class="p">();</span>
+ <span class="kt">size_t</span> <span class="n">RootCount</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_size</span><span class="p">();</span>
+
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">roots_iterator</span> <span class="n">RI</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_begin</span><span class="p">(),</span>
+ <span class="n">RE</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_end</span><span class="p">();</span>
+ <span class="n">RI</span> <span class="o">!=</span> <span class="n">RE</span><span class="p">;</span> <span class="o">++</span><span class="n">RI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">RootNum</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">Num</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">RootStackOffset</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">StackOffset</span><span class="p">;</span>
+ <span class="n">Constant</span> <span class="o">*</span><span class="n">RootMetadata</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">Metadata</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the <code class="docutils literal notranslate"><span class="pre">llvm.gcroot</span></code> intrinsic is eliminated before code generation by a
+custom lowering pass, LLVM will compute an empty stack map. This may be useful
+for collector plugins which implement reference counting or a shadow stack.</p>
+</div>
+<div class="section" id="initializing-roots-to-null">
+<span id="init-roots"></span><h3><a class="toc-backref" href="#id24">Initializing roots to null</a><a class="headerlink" href="#initializing-roots-to-null" title="Permalink to this headline">¶</a></h3>
+<p>It is recommended that frontends initialize roots explicitly to avoid
+potentially confusing the optimizer. This prevents the GC from visiting
+uninitialized pointers, which will almost certainly cause it to crash.</p>
+<p>As a fallback, LLVM will automatically initialize each root to <code class="docutils literal notranslate"><span class="pre">null</span></code>
+upon entry to the function. Support for this mode in code generation is
+largely a legacy detail to keep old collector implementations working.</p>
+</div>
+<div class="section" id="custom-lowering-of-intrinsics">
+<h3><a class="toc-backref" href="#id25">Custom lowering of intrinsics</a><a class="headerlink" href="#custom-lowering-of-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>For GCs which use barriers or unusual treatment of stack roots, the
+implementor is responsibly for providing a custom pass to lower the
+intrinsics with the desired semantics. If you have opted in to custom
+lowering of a particular intrinsic your pass <strong>must</strong> eliminate all
+instances of the corresponding intrinsic in functions which opt in to
+your GC. The best example of such a pass is the ShadowStackGC and itâs
+ShadowStackGCLowering pass.</p>
+<p>There is currently no way to register such a custom lowering pass
+without building a custom copy of LLVM.</p>
+</div>
+<div class="section" id="generating-safe-points">
+<span id="safe-points"></span><h3><a class="toc-backref" href="#id26">Generating safe points</a><a class="headerlink" href="#generating-safe-points" title="Permalink to this headline">¶</a></h3>
+<p>LLVM provides support for associating stackmaps with the return address of
+a call. Any loop or return safepoints required by a given collector design
+can be modeled via calls to runtime routines, or potentially patchable call
+sequences. Using gcroot, all call instructions are inferred to be possible
+safepoints and will thus have an associated stackmap.</p>
+</div>
+<div class="section" id="emitting-assembly-code-gcmetadataprinter">
+<span id="assembly"></span><h3><a class="toc-backref" href="#id27">Emitting assembly code: <code class="docutils literal notranslate"><span class="pre">GCMetadataPrinter</span></code></a><a class="headerlink" href="#emitting-assembly-code-gcmetadataprinter" title="Permalink to this headline">¶</a></h3>
+<p>LLVM allows a plugin to print arbitrary assembly code before and after the rest
+of a moduleâs assembly code. At the end of the module, the GC can compile the
+LLVM stack map into assembly code. (At the beginning, this information is not
+yet computed.)</p>
+<p>Since AsmWriter and CodeGen are separate components of LLVM, a separate abstract
+base class and registry is provided for printing assembly code, the
+<code class="docutils literal notranslate"><span class="pre">GCMetadaPrinter</span></code> and <code class="docutils literal notranslate"><span class="pre">GCMetadataPrinterRegistry</span></code>. The AsmWriter will look
+for such a subclass if the <code class="docutils literal notranslate"><span class="pre">GCStrategy</span></code> sets <code class="docutils literal notranslate"><span class="pre">UsesMetadata</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">UsesMetadata</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This separation allows JIT-only clients to be smaller.</p>
+<p>Note that LLVM does not currently have analogous APIs to support code generation
+in the JIT, nor using the object writers.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// lib/MyGC/MyGCPrinter.cpp - Example LLVM GC printer</span>
+
+<span class="cp">#include</span> <span class="cpf">"llvm/CodeGen/GCMetadataPrinter.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"llvm/Support/Compiler.h"</span><span class="cp"></span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">LLVM_LIBRARY_VISIBILITY</span> <span class="nl">MyGCPrinter</span> <span class="p">:</span> <span class="k">public</span> <span class="n">GCMetadataPrinter</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">beginAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">);</span>
+
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">finishAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">);</span>
+ <span class="p">};</span>
+
+ <span class="n">GCMetadataPrinterRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyGCPrinter</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="s">"mygc"</span><span class="p">,</span> <span class="s">"My bespoke garbage collector."</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The collector should use <code class="docutils literal notranslate"><span class="pre">AsmPrinter</span></code> to print portable assembly code. The
+collector itself contains the stack map for the entire module, and may access
+the <code class="docutils literal notranslate"><span class="pre">GCFunctionInfo</span></code> using its own <code class="docutils literal notranslate"><span class="pre">begin()</span></code> and <code class="docutils literal notranslate"><span class="pre">end()</span></code> methods. Hereâs
+a realistic example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"llvm/CodeGen/AsmPrinter.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"llvm/IR/Function.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"llvm/IR/DataLayout.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"llvm/Target/TargetAsmInfo.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"llvm/Target/TargetMachine.h"</span><span class="cp"></span>
+
+<span class="kt">void</span> <span class="n">MyGCPrinter</span><span class="o">::</span><span class="n">beginAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Nothing to do.</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="n">MyGCPrinter</span><span class="o">::</span><span class="n">finishAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MCStreamer</span> <span class="o">&</span><span class="n">OS</span> <span class="o">=</span> <span class="n">AP</span><span class="p">.</span><span class="n">OutStreamer</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">IntPtrSize</span> <span class="o">=</span> <span class="n">AP</span><span class="p">.</span><span class="n">getPointerSize</span><span class="p">();</span>
+
+ <span class="c1">// Put this in the data section.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">SwitchSection</span><span class="p">(</span><span class="n">AP</span><span class="p">.</span><span class="n">getObjFileLowering</span><span class="p">().</span><span class="n">getDataSection</span><span class="p">());</span>
+
+ <span class="c1">// For each function...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">FI</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">FE</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">FI</span> <span class="o">!=</span> <span class="n">FE</span><span class="p">;</span> <span class="o">++</span><span class="n">FI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">&</span><span class="n">MD</span> <span class="o">=</span> <span class="o">**</span><span class="n">FI</span><span class="p">;</span>
+
+ <span class="c1">// A compact GC layout. Emit this data structure:</span>
+ <span class="c1">//</span>
+ <span class="c1">// struct {</span>
+ <span class="c1">// int32_t PointCount;</span>
+ <span class="c1">// void *SafePointAddress[PointCount];</span>
+ <span class="c1">// int32_t StackFrameSize; // in words</span>
+ <span class="c1">// int32_t StackArity;</span>
+ <span class="c1">// int32_t LiveCount;</span>
+ <span class="c1">// int32_t LiveOffsets[LiveCount];</span>
+ <span class="c1">// } __gcmap_<FUNCTIONNAME>;</span>
+
+ <span class="c1">// Align to address width.</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitAlignment</span><span class="p">(</span><span class="n">IntPtrSize</span> <span class="o">==</span> <span class="mi">4</span> <span class="o">?</span> <span class="mi">2</span> <span class="o">:</span> <span class="mi">3</span><span class="p">);</span>
+
+ <span class="c1">// Emit PointCount.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"safe point count"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">size</span><span class="p">());</span>
+
+ <span class="c1">// And each safe point...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span>
+ <span class="n">PE</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">end</span><span class="p">();</span> <span class="n">PI</span> <span class="o">!=</span> <span class="n">PE</span><span class="p">;</span> <span class="o">++</span><span class="n">PI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Emit the address of the safe point.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"safe point address"</span><span class="p">);</span>
+ <span class="n">MCSymbol</span> <span class="o">*</span><span class="n">Label</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Label</span><span class="p">;</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitLabelPlusOffset</span><span class="p">(</span><span class="n">Label</span><span class="cm">/*Hi*/</span><span class="p">,</span> <span class="mi">0</span><span class="cm">/*Offset*/</span><span class="p">,</span> <span class="mi">4</span><span class="cm">/*Size*/</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="c1">// Stack information never change in safe points! Only print info from the</span>
+ <span class="c1">// first call-site.</span>
+ <span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
+
+ <span class="c1">// Emit the stack frame size.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack frame size (in words)"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">getFrameSize</span><span class="p">()</span> <span class="o">/</span> <span class="n">IntPtrSize</span><span class="p">);</span>
+
+ <span class="c1">// Emit stack arity, i.e. the number of stacked arguments.</span>
+ <span class="kt">unsigned</span> <span class="n">RegisteredArgs</span> <span class="o">=</span> <span class="n">IntPtrSize</span> <span class="o">==</span> <span class="mi">4</span> <span class="o">?</span> <span class="mi">5</span> <span class="o">:</span> <span class="mi">6</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">StackArity</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">getFunction</span><span class="p">().</span><span class="n">arg_size</span><span class="p">()</span> <span class="o">></span> <span class="n">RegisteredArgs</span> <span class="o">?</span>
+ <span class="n">MD</span><span class="p">.</span><span class="n">getFunction</span><span class="p">().</span><span class="n">arg_size</span><span class="p">()</span> <span class="o">-</span> <span class="nl">RegisteredArgs</span> <span class="p">:</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack arity"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">StackArity</span><span class="p">);</span>
+
+ <span class="c1">// Emit the number of live roots in the function.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"live root count"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">live_size</span><span class="p">(</span><span class="n">PI</span><span class="p">));</span>
+
+ <span class="c1">// And for each live root...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">live_iterator</span> <span class="n">LI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">live_begin</span><span class="p">(</span><span class="n">PI</span><span class="p">),</span>
+ <span class="n">LE</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">live_end</span><span class="p">(</span><span class="n">PI</span><span class="p">);</span>
+ <span class="n">LI</span> <span class="o">!=</span> <span class="n">LE</span><span class="p">;</span> <span class="o">++</span><span class="n">LI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Emit live root's offset within the stack frame.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack index (offset / wordsize)"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">LI</span><span class="o">-></span><span class="n">StackOffset</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="references">
+<h2><a class="toc-backref" href="#id28">References</a><a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
+<p id="appel89">[Appel89] Runtime Tags Arenât Necessary. Andrew W. Appel. Lisp and Symbolic
+Computation 19(7):703-705, July 1989.</p>
+<p id="goldberg91">[Goldberg91] Tag-free garbage collection for strongly typed programming
+languages. Benjamin Goldberg. ACM SIGPLAN PLDIâ91.</p>
+<p id="tolmach94">[Tolmach94] Tag-free garbage collection using explicit type parameters. Andrew
+Tolmach. Proceedings of the 1994 ACM conference on LISP and functional
+programming.</p>
+<p id="henderson02">[Henderson2002] <a class="reference external" href="http://citeseer.ist.psu.edu/henderson02accurate.html">Accurate Garbage Collection in an Uncooperative Environment</a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/GetElementPtr.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/GetElementPtr.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/GetElementPtr.html (added)
+++ www-releases/trunk/8.0.0/docs/GetElementPtr.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,561 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>The Often Misunderstood GEP Instruction — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Performance Tips for Frontend Authors" href="Frontend/PerformanceTips.html" />
+ <link rel="prev" title="YAML I/O" href="YamlIO.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="YamlIO.html" title="YAML I/O"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-often-misunderstood-gep-instruction">
+<h1>The Often Misunderstood GEP Instruction<a class="headerlink" href="#the-often-misunderstood-gep-instruction" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
+<li><a class="reference internal" href="#address-computation" id="id3">Address Computation</a><ul>
+<li><a class="reference internal" href="#what-is-the-first-index-of-the-gep-instruction" id="id4">What is the first index of the GEP instruction?</a></li>
+<li><a class="reference internal" href="#why-is-the-extra-0-index-required" id="id5">Why is the extra 0 index required?</a></li>
+<li><a class="reference internal" href="#what-is-dereferenced-by-gep" id="id6">What is dereferenced by GEP?</a></li>
+<li><a class="reference internal" href="#why-don-t-gep-x-0-0-1-and-gep-x-1-alias" id="id7">Why donât GEP x,0,0,1 and GEP x,1 alias?</a></li>
+<li><a class="reference internal" href="#why-do-gep-x-1-0-0-and-gep-x-1-alias" id="id8">Why do GEP x,1,0,0 and GEP x,1 alias?</a></li>
+<li><a class="reference internal" href="#can-gep-index-into-vector-elements" id="id9">Can GEP index into vector elements?</a></li>
+<li><a class="reference internal" href="#what-effect-do-address-spaces-have-on-geps" id="id10">What effect do address spaces have on GEPs?</a></li>
+<li><a class="reference internal" href="#how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr" id="id11">How is GEP different from <code class="docutils literal notranslate"><span class="pre">ptrtoint</span></code>, arithmetic, and <code class="docutils literal notranslate"><span class="pre">inttoptr</span></code>?</a></li>
+<li><a class="reference internal" href="#i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this" id="id12">Iâm writing a backend for a target which needs custom lowering for GEP. How do I do this?</a></li>
+<li><a class="reference internal" href="#how-does-vla-addressing-work-with-geps" id="id13">How does VLA addressing work with GEPs?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rules" id="id14">Rules</a><ul>
+<li><a class="reference internal" href="#what-happens-if-an-array-index-is-out-of-bounds" id="id15">What happens if an array index is out of bounds?</a></li>
+<li><a class="reference internal" href="#can-array-indices-be-negative" id="id16">Can array indices be negative?</a></li>
+<li><a class="reference internal" href="#can-i-compare-two-values-computed-with-geps" id="id17">Can I compare two values computed with GEPs?</a></li>
+<li><a class="reference internal" href="#can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object" id="id18">Can I do GEP with a different pointer type than the type of the underlying object?</a></li>
+<li><a class="reference internal" href="#can-i-cast-an-object-s-address-to-integer-and-add-it-to-null" id="id19">Can I cast an objectâs address to integer and add it to null?</a></li>
+<li><a class="reference internal" href="#can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address" id="id20">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a></li>
+<li><a class="reference internal" href="#can-i-do-type-based-alias-analysis-on-llvm-ir" id="id21">Can I do type-based alias analysis on LLVM IR?</a></li>
+<li><a class="reference internal" href="#what-happens-if-a-gep-computation-overflows" id="id22">What happens if a GEP computation overflows?</a></li>
+<li><a class="reference internal" href="#how-can-i-tell-if-my-front-end-is-following-the-rules" id="id23">How can I tell if my front-end is following the rules?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rationale" id="id24">Rationale</a><ul>
+<li><a class="reference internal" href="#why-is-gep-designed-this-way" id="id25">Why is GEP designed this way?</a></li>
+<li><a class="reference internal" href="#why-do-struct-member-indices-always-use-i32" id="id26">Why do struct member indices always use <code class="docutils literal notranslate"><span class="pre">i32</span></code>?</a></li>
+<li><a class="reference internal" href="#what-s-an-uglygep" id="id27">Whatâs an uglygep?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#summary" id="id28">Summary</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document seeks to dispel the mystery and confusion surrounding LLVMâs
+<a class="reference external" href="LangRef.html#getelementptr-instruction">GetElementPtr</a> (GEP) instruction.
+Questions about the wily GEP instruction are probably the most frequently
+occurring questions once a developer gets down to coding with LLVM. Here we lay
+out the sources of confusion and show that the GEP instruction is really quite
+simple.</p>
+</div>
+<div class="section" id="address-computation">
+<h2><a class="toc-backref" href="#id3">Address Computation</a><a class="headerlink" href="#address-computation" title="Permalink to this headline">¶</a></h2>
+<p>When people are first confronted with the GEP instruction, they tend to relate
+it to known concepts from other programming paradigms, most notably C array
+indexing and field selection. GEP closely resembles C array indexing and field
+selection, however it is a little different and this leads to the following
+questions.</p>
+<div class="section" id="what-is-the-first-index-of-the-gep-instruction">
+<h3><a class="toc-backref" href="#id4">What is the first index of the GEP instruction?</a><a class="headerlink" href="#what-is-the-first-index-of-the-gep-instruction" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: The index stepping through the second operand.</p>
+<p>The confusion with the first index usually arises from thinking about the
+GetElementPtr instruction as if it was a C index operator. They arenât the
+same. For example, when we write, in âCâ:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">AType</span> <span class="o">*</span><span class="n">Foo</span><span class="p">;</span>
+<span class="p">...</span>
+<span class="n">X</span> <span class="o">=</span> <span class="o">&</span><span class="n">Foo</span><span class="o">-></span><span class="n">F</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>it is natural to think that there is only one index, the selection of the field
+<code class="docutils literal notranslate"><span class="pre">F</span></code>. However, in this example, <code class="docutils literal notranslate"><span class="pre">Foo</span></code> is a pointer. That pointer
+must be indexed explicitly in LLVM. C, on the other hand, indices through it
+transparently. To arrive at the same address location as the C code, you would
+provide the GEP instruction with two index operands. The first operand indexes
+through the pointer; the second operand indexes the field <code class="docutils literal notranslate"><span class="pre">F</span></code> of the
+structure, just as if you wrote:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">X</span> <span class="o">=</span> <span class="o">&</span><span class="n">Foo</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">F</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Sometimes this question gets rephrased as:</p>
+<blockquote id="gep-index-through-first-pointer">
+<div><em>Why is it okay to index through the first pointer, but subsequent pointers
+wonât be dereferenced?</em></div></blockquote>
+<p>The answer is simply because memory does not have to be accessed to perform the
+computation. The second operand to the GEP instruction must be a value of a
+pointer type. The value of the pointer is provided directly to the GEP
+instruction as an operand without any need for accessing memory. It must,
+therefore be indexed and requires an index operand. Consider this example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">munger_struct</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">f1</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">f2</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="kt">void</span> <span class="nf">munge</span><span class="p">(</span><span class="k">struct</span> <span class="n">munger_struct</span> <span class="o">*</span><span class="n">P</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">P</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">f1</span> <span class="o">=</span> <span class="n">P</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span><span class="n">f1</span> <span class="o">+</span> <span class="n">P</span><span class="p">[</span><span class="mi">2</span><span class="p">].</span><span class="n">f2</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="p">...</span>
+<span class="n">munger_struct</span> <span class="n">Array</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span>
+<span class="p">...</span>
+<span class="n">munge</span><span class="p">(</span><span class="n">Array</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In this âCâ example, the front end compiler (Clang) will generate three GEP
+instructions for the three indices through âPâ in the assignment statement. The
+function argument <code class="docutils literal notranslate"><span class="pre">P</span></code> will be the second operand of each of these GEP
+instructions. The third operand indexes through that pointer. The fourth
+operand will be the field offset into the <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">munger_struct</span></code> type, for
+either the <code class="docutils literal notranslate"><span class="pre">f1</span></code> or <code class="docutils literal notranslate"><span class="pre">f2</span></code> field. So, in LLVM assembly the <code class="docutils literal notranslate"><span class="pre">munge</span></code> function
+looks like:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nv">%munge</span><span class="p">(</span><span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp</span>
+ <span class="nv">%tmp6</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span>
+ <span class="nv">%tmp7</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp6</span>
+ <span class="nv">%tmp8</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%tmp7</span><span class="p">,</span> <span class="nv">%tmp</span>
+ <span class="nv">%tmp9</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%tmp8</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp9</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In each case the second operand is the pointer through which the GEP instruction
+starts. The same is true whether the second operand is an argument, allocated
+memory, or a global variable.</p>
+<p>To make this clear, letâs consider a more obtuse example:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>%MyVar = uninitialized global i32
+...
+%idx1 = getelementptr i32, i32* %MyVar, i64 0
+%idx2 = getelementptr i32, i32* %MyVar, i64 1
+%idx3 = getelementptr i32, i32* %MyVar, i64 2
+</pre></div>
+</div>
+<p>These GEP instructions are simply making address computations from the base
+address of <code class="docutils literal notranslate"><span class="pre">MyVar</span></code>. They compute, as follows (using C syntax):</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">idx1</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">0</span>
+<span class="n">idx2</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">4</span>
+<span class="n">idx3</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">8</span>
+</pre></div>
+</div>
+<p>Since the type <code class="docutils literal notranslate"><span class="pre">i32</span></code> is known to be four bytes long, the indices 0, 1 and 2
+translate into memory offsets of 0, 4, and 8, respectively. No memory is
+accessed to make these computations because the address of <code class="docutils literal notranslate"><span class="pre">%MyVar</span></code> is passed
+directly to the GEP instructions.</p>
+<p>The obtuse part of this example is in the cases of <code class="docutils literal notranslate"><span class="pre">%idx2</span></code> and <code class="docutils literal notranslate"><span class="pre">%idx3</span></code>. They
+result in the computation of addresses that point to memory past the end of the
+<code class="docutils literal notranslate"><span class="pre">%MyVar</span></code> global, which is only one <code class="docutils literal notranslate"><span class="pre">i32</span></code> long, not three <code class="docutils literal notranslate"><span class="pre">i32</span></code>s long.
+While this is legal in LLVM, it is inadvisable because any load or store with
+the pointer that results from these GEP instructions would produce undefined
+results.</p>
+</div>
+<div class="section" id="why-is-the-extra-0-index-required">
+<h3><a class="toc-backref" href="#id5">Why is the extra 0 index required?</a><a class="headerlink" href="#why-is-the-extra-0-index-required" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: there are no superfluous indices.</p>
+<p>This question arises most often when the GEP instruction is applied to a global
+variable which is always a pointer type. For example, consider this:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>%MyStruct = uninitialized global { float*, i32 }
+...
+%idx = getelementptr { float*, i32 }, { float*, i32 }* %MyStruct, i64 0, i32 1
+</pre></div>
+</div>
+<p>The GEP above yields an <code class="docutils literal notranslate"><span class="pre">i32*</span></code> by indexing the <code class="docutils literal notranslate"><span class="pre">i32</span></code> typed field of the
+structure <code class="docutils literal notranslate"><span class="pre">%MyStruct</span></code>. When people first look at it, they wonder why the <code class="docutils literal notranslate"><span class="pre">i64</span>
+<span class="pre">0</span></code> index is needed. However, a closer inspection of how globals and GEPs work
+reveals the need. Becoming aware of the following facts will dispel the
+confusion:</p>
+<ol class="arabic simple">
+<li>The type of <code class="docutils literal notranslate"><span class="pre">%MyStruct</span></code> is <em>not</em> <code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">float*,</span> <span class="pre">i32</span> <span class="pre">}</span></code> but rather <code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">float*,</span>
+<span class="pre">i32</span> <span class="pre">}*</span></code>. That is, <code class="docutils literal notranslate"><span class="pre">%MyStruct</span></code> is a pointer to a structure containing a
+pointer to a <code class="docutils literal notranslate"><span class="pre">float</span></code> and an <code class="docutils literal notranslate"><span class="pre">i32</span></code>.</li>
+<li>Point #1 is evidenced by noticing the type of the second operand of the GEP
+instruction (<code class="docutils literal notranslate"><span class="pre">%MyStruct</span></code>) which is <code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">float*,</span> <span class="pre">i32</span> <span class="pre">}*</span></code>.</li>
+<li>The first index, <code class="docutils literal notranslate"><span class="pre">i64</span> <span class="pre">0</span></code> is required to step over the global variable
+<code class="docutils literal notranslate"><span class="pre">%MyStruct</span></code>. Since the second argument to the GEP instruction must always
+be a value of pointer type, the first index steps through that pointer. A
+value of 0 means 0 elements offset from that pointer.</li>
+<li>The second index, <code class="docutils literal notranslate"><span class="pre">i32</span> <span class="pre">1</span></code> selects the second field of the structure (the
+<code class="docutils literal notranslate"><span class="pre">i32</span></code>).</li>
+</ol>
+</div>
+<div class="section" id="what-is-dereferenced-by-gep">
+<h3><a class="toc-backref" href="#id6">What is dereferenced by GEP?</a><a class="headerlink" href="#what-is-dereferenced-by-gep" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: nothing.</p>
+<p>The GetElementPtr instruction dereferences nothing. That is, it doesnât access
+memory in any way. Thatâs what the Load and Store instructions are for. GEP is
+only involved in the computation of addresses. For example, consider this:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>%MyVar = uninitialized global { [40 x i32 ]* }
+...
+%idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+</pre></div>
+</div>
+<p>In this example, we have a global variable, <code class="docutils literal notranslate"><span class="pre">%MyVar</span></code> that is a pointer to a
+structure containing a pointer to an array of 40 ints. The GEP instruction seems
+to be accessing the 18th integer of the structureâs array of ints. However, this
+is actually an illegal GEP instruction. It wonât compile. The reason is that the
+pointer in the structure <em>must</em> be dereferenced in order to index into the
+array of 40 ints. Since the GEP instruction never accesses memory, it is
+illegal.</p>
+<p>In order to access the 18th integer in the array, you would need to do the
+following:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>%idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %, i64 0, i32 0
+%arr = load [40 x i32]** %idx
+%idx = getelementptr [40 x i32], [40 x i32]* %arr, i64 0, i64 17
+</pre></div>
+</div>
+<p>In this case, we have to load the pointer in the structure with a load
+instruction before we can index into the array. If the example was changed to:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>%MyVar = uninitialized global { [40 x i32 ] }
+...
+%idx = getelementptr { [40 x i32] }, { [40 x i32] }*, i64 0, i32 0, i64 17
+</pre></div>
+</div>
+<p>then everything works fine. In this case, the structure does not contain a
+pointer and the GEP instruction can index through the global variable, into the
+first field of the structure and access the 18th <code class="docutils literal notranslate"><span class="pre">i32</span></code> in the array there.</p>
+</div>
+<div class="section" id="why-don-t-gep-x-0-0-1-and-gep-x-1-alias">
+<h3><a class="toc-backref" href="#id7">Why donât GEP x,0,0,1 and GEP x,1 alias?</a><a class="headerlink" href="#why-don-t-gep-x-0-0-1-and-gep-x-1-alias" title="Permalink to this headline">¶</a></h3>
+<p>Quick Answer: They compute different address locations.</p>
+<p>If you look at the first indices in these GEP instructions you find that they
+are different (0 and 1), therefore the address computation diverges with that
+index. Consider this example:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="nv">%MyVar</span> <span class="p">=</span> <span class="k">global</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}</span>
+<span class="nv">%idx1</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+<span class="nv">%idx2</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>In this example, <code class="docutils literal notranslate"><span class="pre">idx1</span></code> computes the address of the second integer in the
+array that is in the structure in <code class="docutils literal notranslate"><span class="pre">%MyVar</span></code>, that is <code class="docutils literal notranslate"><span class="pre">MyVar+4</span></code>. The type of
+<code class="docutils literal notranslate"><span class="pre">idx1</span></code> is <code class="docutils literal notranslate"><span class="pre">i32*</span></code>. However, <code class="docutils literal notranslate"><span class="pre">idx2</span></code> computes the address of <em>the next</em>
+structure after <code class="docutils literal notranslate"><span class="pre">%MyVar</span></code>. The type of <code class="docutils literal notranslate"><span class="pre">idx2</span></code> is <code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">[10</span> <span class="pre">x</span> <span class="pre">i32]</span> <span class="pre">}*</span></code> and its
+value is equivalent to <code class="docutils literal notranslate"><span class="pre">MyVar</span> <span class="pre">+</span> <span class="pre">40</span></code> because it indexes past the ten 4-byte
+integers in <code class="docutils literal notranslate"><span class="pre">MyVar</span></code>. Obviously, in such a situation, the pointers donât
+alias.</p>
+</div>
+<div class="section" id="why-do-gep-x-1-0-0-and-gep-x-1-alias">
+<h3><a class="toc-backref" href="#id8">Why do GEP x,1,0,0 and GEP x,1 alias?</a><a class="headerlink" href="#why-do-gep-x-1-0-0-and-gep-x-1-alias" title="Permalink to this headline">¶</a></h3>
+<p>Quick Answer: They compute the same address location.</p>
+<p>These two GEP instructions will compute the same address because indexing
+through the 0th element does not change the address. However, it does change the
+type. Consider this example:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="nv">%MyVar</span> <span class="p">=</span> <span class="k">global</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}</span>
+<span class="nv">%idx1</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span>
+<span class="nv">%idx2</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>In this example, the value of <code class="docutils literal notranslate"><span class="pre">%idx1</span></code> is <code class="docutils literal notranslate"><span class="pre">%MyVar+40</span></code> and its type is
+<code class="docutils literal notranslate"><span class="pre">i32*</span></code>. The value of <code class="docutils literal notranslate"><span class="pre">%idx2</span></code> is also <code class="docutils literal notranslate"><span class="pre">MyVar+40</span></code> but its type is <code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">[10</span> <span class="pre">x</span>
+<span class="pre">i32]</span> <span class="pre">}*</span></code>.</p>
+</div>
+<div class="section" id="can-gep-index-into-vector-elements">
+<h3><a class="toc-backref" href="#id9">Can GEP index into vector elements?</a><a class="headerlink" href="#can-gep-index-into-vector-elements" title="Permalink to this headline">¶</a></h3>
+<p>This hasnât always been forcefully disallowed, though itâs not recommended. It
+leads to awkward special cases in the optimizers, and fundamental inconsistency
+in the IR. In the future, it will probably be outright disallowed.</p>
+</div>
+<div class="section" id="what-effect-do-address-spaces-have-on-geps">
+<h3><a class="toc-backref" href="#id10">What effect do address spaces have on GEPs?</a><a class="headerlink" href="#what-effect-do-address-spaces-have-on-geps" title="Permalink to this headline">¶</a></h3>
+<p>None, except that the address space qualifier on the second operand pointer type
+always matches the address space qualifier on the result type.</p>
+</div>
+<div class="section" id="how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr">
+<h3><a class="toc-backref" href="#id11">How is GEP different from <code class="docutils literal notranslate"><span class="pre">ptrtoint</span></code>, arithmetic, and <code class="docutils literal notranslate"><span class="pre">inttoptr</span></code>?</a><a class="headerlink" href="#how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr" title="Permalink to this headline">¶</a></h3>
+<p>Itâs very similar; there are only subtle differences.</p>
+<p>With ptrtoint, you have to pick an integer type. One approach is to pick i64;
+this is safe on everything LLVM supports (LLVM internally assumes pointers are
+never wider than 64 bits in many places), and the optimizer will actually narrow
+the i64 arithmetic down to the actual pointer size on targets which donât
+support 64-bit arithmetic in most cases. However, there are some cases where it
+doesnât do this. With GEP you can avoid this problem.</p>
+<p>Also, GEP carries additional pointer aliasing rules. Itâs invalid to take a GEP
+from one object, address into a different separately allocated object, and
+dereference it. IR producers (front-ends) must follow this rule, and consumers
+(optimizers, specifically alias analysis) benefit from being able to rely on
+it. See the <a class="reference internal" href="#rules">Rules</a> section for more information.</p>
+<p>And, GEP is more concise in common cases.</p>
+<p>However, for the underlying integer computation implied, there is no
+difference.</p>
+</div>
+<div class="section" id="i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this">
+<h3><a class="toc-backref" href="#id12">Iâm writing a backend for a target which needs custom lowering for GEP. How do I do this?</a><a class="headerlink" href="#i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this" title="Permalink to this headline">¶</a></h3>
+<p>You donât. The integer computation implied by a GEP is target-independent.
+Typically what youâll need to do is make your backend pattern-match expressions
+trees involving ADD, MUL, etc., which are what GEP is lowered into. This has the
+advantage of letting your code work correctly in more cases.</p>
+<p>GEP does use target-dependent parameters for the size and layout of data types,
+which targets can customize.</p>
+<p>If you require support for addressing units which are not 8 bits, youâll need to
+fix a lot of code in the backend, with GEP lowering being only a small piece of
+the overall picture.</p>
+</div>
+<div class="section" id="how-does-vla-addressing-work-with-geps">
+<h3><a class="toc-backref" href="#id13">How does VLA addressing work with GEPs?</a><a class="headerlink" href="#how-does-vla-addressing-work-with-geps" title="Permalink to this headline">¶</a></h3>
+<p>GEPs donât natively support VLAs. LLVMâs type system is entirely static, and GEP
+address computations are guided by an LLVM type.</p>
+<p>VLA indices can be implemented as linearized indices. For example, an expression
+like <code class="docutils literal notranslate"><span class="pre">X[a][b][c]</span></code>, must be effectively lowered into a form like
+<code class="docutils literal notranslate"><span class="pre">X[a*m+b*n+c]</span></code>, so that it appears to the GEP as a single-dimensional array
+reference.</p>
+<p>This means if you want to write an analysis which understands array indices and
+you want to support VLAs, your code will have to be prepared to reverse-engineer
+the linearization. One way to solve this problem is to use the ScalarEvolution
+library, which always presents VLA and non-VLA indexing in the same manner.</p>
+</div>
+</div>
+<div class="section" id="rules">
+<span id="id1"></span><h2><a class="toc-backref" href="#id14">Rules</a><a class="headerlink" href="#rules" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-happens-if-an-array-index-is-out-of-bounds">
+<h3><a class="toc-backref" href="#id15">What happens if an array index is out of bounds?</a><a class="headerlink" href="#what-happens-if-an-array-index-is-out-of-bounds" title="Permalink to this headline">¶</a></h3>
+<p>There are two senses in which an array index can be out of bounds.</p>
+<p>First, thereâs the array type which comes from the (static) type of the first
+operand to the GEP. Indices greater than the number of elements in the
+corresponding static array type are valid. There is no problem with out of
+bounds indices in this sense. Indexing into an array only depends on the size of
+the array element, not the number of elements.</p>
+<p>A common example of how this is used is arrays where the size is not known.
+Itâs common to use array types with zero length to represent these. The fact
+that the static type says there are zero elements is irrelevant; itâs perfectly
+valid to compute arbitrary element indices, as the computation only depends on
+the size of the array element, not the number of elements. Note that zero-sized
+arrays are not a special case here.</p>
+<p>This sense is unconnected with <code class="docutils literal notranslate"><span class="pre">inbounds</span></code> keyword. The <code class="docutils literal notranslate"><span class="pre">inbounds</span></code> keyword is
+designed to describe low-level pointer arithmetic overflow conditions, rather
+than high-level array indexing rules.</p>
+<p>Analysis passes which wish to understand array indexing should not assume that
+the static array type bounds are respected.</p>
+<p>The second sense of being out of bounds is computing an address thatâs beyond
+the actual underlying allocated object.</p>
+<p>With the <code class="docutils literal notranslate"><span class="pre">inbounds</span></code> keyword, the result value of the GEP is undefined if the
+address is outside the actual underlying allocated object and not the address
+one-past-the-end.</p>
+<p>Without the <code class="docutils literal notranslate"><span class="pre">inbounds</span></code> keyword, there are no restrictions on computing
+out-of-bounds addresses. Obviously, performing a load or a store requires an
+address of allocated and sufficiently aligned memory. But the GEP itself is only
+concerned with computing addresses.</p>
+</div>
+<div class="section" id="can-array-indices-be-negative">
+<h3><a class="toc-backref" href="#id16">Can array indices be negative?</a><a class="headerlink" href="#can-array-indices-be-negative" title="Permalink to this headline">¶</a></h3>
+<p>Yes. This is basically a special case of array indices being out of bounds.</p>
+</div>
+<div class="section" id="can-i-compare-two-values-computed-with-geps">
+<h3><a class="toc-backref" href="#id17">Can I compare two values computed with GEPs?</a><a class="headerlink" href="#can-i-compare-two-values-computed-with-geps" title="Permalink to this headline">¶</a></h3>
+<p>Yes. If both addresses are within the same allocated object, or
+one-past-the-end, youâll get the comparison result you expect. If either is
+outside of it, integer arithmetic wrapping may occur, so the comparison may not
+be meaningful.</p>
+</div>
+<div class="section" id="can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object">
+<h3><a class="toc-backref" href="#id18">Can I do GEP with a different pointer type than the type of the underlying object?</a><a class="headerlink" href="#can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object" title="Permalink to this headline">¶</a></h3>
+<p>Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
+pointer type. The types in a GEP serve only to define the parameters for the
+underlying integer computation. They need not correspond with the actual type of
+the underlying object.</p>
+<p>Furthermore, loads and stores donât have to use the same types as the type of
+the underlying object. Types in this context serve only to specify memory size
+and alignment. Beyond that there are merely a hint to the optimizer indicating
+how the value will likely be used.</p>
+</div>
+<div class="section" id="can-i-cast-an-object-s-address-to-integer-and-add-it-to-null">
+<h3><a class="toc-backref" href="#id19">Can I cast an objectâs address to integer and add it to null?</a><a class="headerlink" href="#can-i-cast-an-object-s-address-to-integer-and-add-it-to-null" title="Permalink to this headline">¶</a></h3>
+<p>You can compute an address that way, but if you use GEP to do the add, you canât
+use that pointer to actually access the object, unless the object is managed
+outside of LLVM.</p>
+<p>The underlying integer computation is sufficiently defined; null has a defined
+value â zero â and you can add whatever value you want to it.</p>
+<p>However, itâs invalid to access (load from or store to) an LLVM-aware object
+with such a pointer. This includes <code class="docutils literal notranslate"><span class="pre">GlobalVariables</span></code>, <code class="docutils literal notranslate"><span class="pre">Allocas</span></code>, and objects
+pointed to by noalias pointers.</p>
+<p>If you really need this functionality, you can do the arithmetic with explicit
+integer instructions, and use inttoptr to convert the result to an address. Most
+of GEPâs special aliasing rules do not apply to pointers computed from ptrtoint,
+arithmetic, and inttoptr sequences.</p>
+</div>
+<div class="section" id="can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address">
+<h3><a class="toc-backref" href="#id20">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a><a class="headerlink" href="#can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address" title="Permalink to this headline">¶</a></h3>
+<p>As with arithmetic on null, you can use GEP to compute an address that way, but
+you canât use that pointer to actually access the object if you do, unless the
+object is managed outside of LLVM.</p>
+<p>Also as above, ptrtoint and inttoptr provide an alternative way to do this which
+do not have this restriction.</p>
+</div>
+<div class="section" id="can-i-do-type-based-alias-analysis-on-llvm-ir">
+<h3><a class="toc-backref" href="#id21">Can I do type-based alias analysis on LLVM IR?</a><a class="headerlink" href="#can-i-do-type-based-alias-analysis-on-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<p>You canât do type-based alias analysis using LLVMâs built-in type system,
+because LLVM has no restrictions on mixing types in addressing, loads or stores.</p>
+<p>LLVMâs type-based alias analysis pass uses metadata to describe a different type
+system (such as the C type system), and performs type-based aliasing on top of
+that. Further details are in the
+<a class="reference external" href="LangRef.html#tbaa-metadata">language reference</a>.</p>
+</div>
+<div class="section" id="what-happens-if-a-gep-computation-overflows">
+<h3><a class="toc-backref" href="#id22">What happens if a GEP computation overflows?</a><a class="headerlink" href="#what-happens-if-a-gep-computation-overflows" title="Permalink to this headline">¶</a></h3>
+<p>If the GEP lacks the <code class="docutils literal notranslate"><span class="pre">inbounds</span></code> keyword, the value is the result from
+evaluating the implied twoâs complement integer computation. However, since
+thereâs no guarantee of where an object will be allocated in the address space,
+such values have limited meaning.</p>
+<p>If the GEP has the <code class="docutils literal notranslate"><span class="pre">inbounds</span></code> keyword, the result value is undefined (a âtrap
+valueâ) if the GEP overflows (i.e. wraps around the end of the address space).</p>
+<p>As such, there are some ramifications of this for inbounds GEPs: scales implied
+by array/vector/pointer indices are always known to be ânswâ since they are
+signed values that are scaled by the element size. These values are also
+allowed to be negative (e.g. â<code class="docutils literal notranslate"><span class="pre">gep</span> <span class="pre">i32</span> <span class="pre">*%P,</span> <span class="pre">i32</span> <span class="pre">-1</span></code>â) but the pointer itself
+is logically treated as an unsigned value. This means that GEPs have an
+asymmetric relation between the pointer base (which is treated as unsigned) and
+the offset applied to it (which is treated as signed). The result of the
+additions within the offset calculation cannot have signed overflow, but when
+applied to the base pointer, there can be signed overflow.</p>
+</div>
+<div class="section" id="how-can-i-tell-if-my-front-end-is-following-the-rules">
+<h3><a class="toc-backref" href="#id23">How can I tell if my front-end is following the rules?</a><a class="headerlink" href="#how-can-i-tell-if-my-front-end-is-following-the-rules" title="Permalink to this headline">¶</a></h3>
+<p>There is currently no checker for the getelementptr rules. Currently, the only
+way to do this is to manually check each place in your front-end where
+GetElementPtr operators are created.</p>
+<p>Itâs not possible to write a checker which could find all rule violations
+statically. It would be possible to write a checker which works by instrumenting
+the code with dynamic checks though. Alternatively, it would be possible to
+write a static checker which catches a subset of possible problems. However, no
+such checker exists today.</p>
+</div>
+</div>
+<div class="section" id="rationale">
+<h2><a class="toc-backref" href="#id24">Rationale</a><a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="why-is-gep-designed-this-way">
+<h3><a class="toc-backref" href="#id25">Why is GEP designed this way?</a><a class="headerlink" href="#why-is-gep-designed-this-way" title="Permalink to this headline">¶</a></h3>
+<p>The design of GEP has the following goals, in rough unofficial order of
+priority:</p>
+<ul class="simple">
+<li>Support C, C-like languages, and languages which can be conceptually lowered
+into C (this covers a lot).</li>
+<li>Support optimizations such as those that are common in C compilers. In
+particular, GEP is a cornerstone of LLVMâs <a class="reference external" href="LangRef.html#pointeraliasing">pointer aliasing
+model</a>.</li>
+<li>Provide a consistent method for computing addresses so that address
+computations donât need to be a part of load and store instructions in the IR.</li>
+<li>Support non-C-like languages, to the extent that it doesnât interfere with
+other goals.</li>
+<li>Minimize target-specific information in the IR.</li>
+</ul>
+</div>
+<div class="section" id="why-do-struct-member-indices-always-use-i32">
+<h3><a class="toc-backref" href="#id26">Why do struct member indices always use <code class="docutils literal notranslate"><span class="pre">i32</span></code>?</a><a class="headerlink" href="#why-do-struct-member-indices-always-use-i32" title="Permalink to this headline">¶</a></h3>
+<p>The specific type i32 is probably just a historical artifact, however itâs wide
+enough for all practical purposes, so thereâs been no need to change it. It
+doesnât necessarily imply i32 address arithmetic; itâs just an identifier which
+identifies a field in a struct. Requiring that all struct indices be the same
+reduces the range of possibilities for cases where two GEPs are effectively the
+same but have distinct operand types.</p>
+</div>
+<div class="section" id="what-s-an-uglygep">
+<h3><a class="toc-backref" href="#id27">Whatâs an uglygep?</a><a class="headerlink" href="#what-s-an-uglygep" title="Permalink to this headline">¶</a></h3>
+<p>Some LLVM optimizers operate on GEPs by internally lowering them into more
+primitive integer expressions, which allows them to be combined with other
+integer expressions and/or split into multiple separate integer expressions. If
+theyâve made non-trivial changes, translating back into LLVM IR can involve
+reverse-engineering the structure of the addressing in order to fit it into the
+static type of the original first operand. It isnât always possibly to fully
+reconstruct this structure; sometimes the underlying addressing doesnât
+correspond with the static type at all. In such cases the optimizer instead will
+emit a GEP with the base pointer casted to a simple address-unit pointer, using
+the name âuglygepâ. This isnât pretty, but itâs just as valid, and itâs
+sufficient to preserve the pointer aliasing guarantees that GEP provides.</p>
+</div>
+</div>
+<div class="section" id="summary">
+<h2><a class="toc-backref" href="#id28">Summary</a><a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2>
+<p>In summary, hereâs some things to always remember about the GetElementPtr
+instruction:</p>
+<ol class="arabic simple">
+<li>The GEP instruction never accesses memory, it only provides pointer
+computations.</li>
+<li>The second operand to the GEP instruction is always a pointer and it must be
+indexed.</li>
+<li>There are no superfluous indices for the GEP instruction.</li>
+<li>Trailing zero indices are superfluous for pointer aliasing, but not for the
+types of the pointers.</li>
+<li>Leading zero indices are not superfluous for pointer aliasing nor the types
+of the pointers.</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="YamlIO.html" title="YAML I/O"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/GettingStarted.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/GettingStarted.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/GettingStarted.html (added)
+++ www-releases/trunk/8.0.0/docs/GettingStarted.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,1174 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Getting Started with the LLVM System — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Getting Started with the LLVM System using Microsoft Visual Studio" href="GettingStartedVS.html" />
+ <link rel="prev" title="llvm-readobj - LLVM Object Reader" href="CommandGuide/llvm-readobj.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CommandGuide/llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="getting-started-with-the-llvm-system">
+<h1>Getting Started with the LLVM System<a class="headerlink" href="#getting-started-with-the-llvm-system" 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="id3">Overview</a></li>
+<li><a class="reference internal" href="#getting-started-quickly-a-summary" id="id4">Getting Started Quickly (A Summary)</a></li>
+<li><a class="reference internal" href="#requirements" id="id5">Requirements</a><ul>
+<li><a class="reference internal" href="#hardware" id="id6">Hardware</a></li>
+<li><a class="reference internal" href="#software" id="id7">Software</a></li>
+<li><a class="reference internal" href="#host-c-toolchain-both-compiler-and-standard-library" id="id8">Host C++ Toolchain, both Compiler and Standard Library</a><ul>
+<li><a class="reference internal" href="#getting-a-modern-host-c-toolchain" id="id9">Getting a Modern Host C++ Toolchain</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#getting-started-with-llvm" id="id10">Getting Started with LLVM</a><ul>
+<li><a class="reference internal" href="#terminology-and-notation" id="id11">Terminology and Notation</a></li>
+<li><a class="reference internal" href="#unpacking-the-llvm-archives" id="id12">Unpacking the LLVM Archives</a></li>
+<li><a class="reference internal" href="#checkout-llvm-from-git" id="id13">Checkout LLVM from Git</a><ul>
+<li><a class="reference internal" href="#sending-patches" id="id14">Sending patches</a></li>
+<li><a class="reference internal" href="#for-developers-to-commit-changes-from-git" id="id15">For developers to commit changes from Git</a></li>
+<li><a class="reference internal" href="#checkout-via-svn-deprecated" id="id16">Checkout via SVN (deprecated)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#local-llvm-configuration" id="id17">Local LLVM Configuration</a></li>
+<li><a class="reference internal" href="#compiling-the-llvm-suite-source-code" id="id18">Compiling the LLVM Suite Source Code</a></li>
+<li><a class="reference internal" href="#cross-compiling-llvm" id="id19">Cross-Compiling LLVM</a></li>
+<li><a class="reference internal" href="#the-location-of-llvm-object-files" id="id20">The Location of LLVM Object Files</a></li>
+<li><a class="reference internal" href="#optional-configuration-items" id="id21">Optional Configuration Items</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#directory-layout" id="id22">Directory Layout</a><ul>
+<li><a class="reference internal" href="#llvm-examples" id="id23"><code class="docutils literal notranslate"><span class="pre">llvm/examples</span></code></a></li>
+<li><a class="reference internal" href="#llvm-include" id="id24"><code class="docutils literal notranslate"><span class="pre">llvm/include</span></code></a></li>
+<li><a class="reference internal" href="#llvm-lib" id="id25"><code class="docutils literal notranslate"><span class="pre">llvm/lib</span></code></a></li>
+<li><a class="reference internal" href="#llvm-projects" id="id26"><code class="docutils literal notranslate"><span class="pre">llvm/projects</span></code></a></li>
+<li><a class="reference internal" href="#llvm-test" id="id27"><code class="docutils literal notranslate"><span class="pre">llvm/test</span></code></a></li>
+<li><a class="reference internal" href="#test-suite" id="id28"><code class="docutils literal notranslate"><span class="pre">test-suite</span></code></a></li>
+<li><a class="reference internal" href="#llvm-tools" id="id29"><code class="docutils literal notranslate"><span class="pre">llvm/tools</span></code></a></li>
+<li><a class="reference internal" href="#llvm-utils" id="id30"><code class="docutils literal notranslate"><span class="pre">llvm/utils</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#an-example-using-the-llvm-tool-chain" id="id31">An Example Using the LLVM Tool Chain</a><ul>
+<li><a class="reference internal" href="#example-with-clang" id="id32">Example with clang</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#common-problems" id="id33">Common Problems</a></li>
+<li><a class="reference internal" href="#links" id="id34">Links</a></li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id3">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to the LLVM project! In order to get started, you first need to know
+some basic information.</p>
+<p>First, the LLVM project has multiple components. The core of the project is
+itself called âLLVMâ. This contains all of the tools, libraries, and header
+files needed to process an intermediate representation and convert it into
+object files. It contains an assembler, disassembler, bitcode analyzer and
+bitcode optimizer. It also contains basic regression tests.</p>
+<p>Another piece is the <a class="reference external" href="http://clang.llvm.org/">Clang</a> front end. This
+component compiles C, C++, Objective C, and Objective C++ code into LLVM bitcode
+â and from there into object files, using LLVM.</p>
+<p>There are other components as well:
+the <a class="reference external" href="https://libcxx.llvm.org">libc++ C++ standard library</a>,
+the <a class="reference external" href="https://lld.llvm.org">LLD linker</a>, and more.</p>
+</div>
+<div class="section" id="getting-started-quickly-a-summary">
+<h2><a class="toc-backref" href="#id4">Getting Started Quickly (A Summary)</a><a class="headerlink" href="#getting-started-quickly-a-summary" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM Getting Started documentation may be out of date. So, the <a class="reference external" href="http://clang.llvm.org/get_started.html">Clang
+Getting Started</a> page might also be a
+good place to start.</p>
+<p>Hereâs the short story for getting up and running quickly with LLVM:</p>
+<ol class="arabic">
+<li><p class="first">Read the documentation.</p>
+</li>
+<li><p class="first">Read the documentation.</p>
+</li>
+<li><p class="first">Remember that you were warned twice about reading the documentation.</p>
+</li>
+<li><p class="first">Checkout LLVM (including related subprojects like Clang):</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">https://github.com/llvm/llvm-project.git</span></code></li>
+<li>Or, on windows, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">--config</span> <span class="pre">core.autocrlf=false</span>
+<span class="pre">https://github.com/llvm/llvm-project.git</span></code></li>
+</ul>
+</li>
+<li><p class="first">Configure and build LLVM and Clang:.</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">llvm-project</span></code></p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">mkdir</span> <span class="pre">build</span></code></p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">build</span></code></p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">-G</span> <span class="pre"><generator></span> <span class="pre">[options]</span> <span class="pre">../llvm</span></code></p>
+<p>Some common generators are:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">Ninja</span></code> â for generating <a class="reference external" href="https://ninja-build.org">Ninja</a>
+build files. Most llvm developers use Ninja.</li>
+<li><code class="docutils literal notranslate"><span class="pre">Unix</span> <span class="pre">Makefiles</span></code> â for generating make-compatible parallel makefiles.</li>
+<li><code class="docutils literal notranslate"><span class="pre">Visual</span> <span class="pre">Studio</span></code> â for generating Visual Studio projects and
+solutions.</li>
+<li><code class="docutils literal notranslate"><span class="pre">Xcode</span></code> â for generating Xcode projects.</li>
+</ul>
+<p>Some Common options:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_PROJECTS='...'</span></code> â semicolon-separated list of the LLVM
+subprojects youâd like to additionally build. Can include any of: clang,
+libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld, polly, or
+debuginfo-tests.</p>
+<p>For example, to build LLVM, Clang, libcxx, and libcxxabi, use
+<code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"</span></code>.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">-DCMAKE_INSTALL_PREFIX=directory</span></code> â Specify for <em>directory</em> the full
+pathname of where you want the LLVM tools and libraries to be installed
+(default <code class="docutils literal notranslate"><span class="pre">/usr/local</span></code>).</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">-DCMAKE_BUILD_TYPE=type</span></code> â Valid options for <em>type</em> are Debug,
+Release, RelWithDebInfo, and MinSizeRel. Default is Debug.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_ASSERTIONS=On</span></code> â Compile with assertion checks enabled
+(default is Yes for Debug builds, No for all other build types).</p>
+</li>
+</ul>
+</li>
+<li><p class="first">Run your build tool of choice!</p>
+<ul class="simple">
+<li>The default target (i.e. <code class="docutils literal notranslate"><span class="pre">ninja</span></code> or <code class="docutils literal notranslate"><span class="pre">make</span></code>) will build all of LLVM.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">check-all</span></code> target (i.e. <code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">check-all</span></code>) will run the
+regression tests to ensure everything is in working order.</li>
+<li>CMake will generate build targets for each tool and library, and most
+LLVM sub-projects generate their own <code class="docutils literal notranslate"><span class="pre">check-<project></span></code> target.</li>
+<li>Running a serial build will be <em>slow</em>. Make sure you run a parallel
+build. Thatâs already done by default in Ninja; for <code class="docutils literal notranslate"><span class="pre">make</span></code>, use
+<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-j</span> <span class="pre">NNN</span></code> (with an appropriate value of NNN, e.g. number of CPUs
+you have.)</li>
+</ul>
+</li>
+<li><p class="first">For more information see <a class="reference external" href="CMake.html">CMake</a></p>
+</li>
+<li><p class="first">If you get an âinternal compiler error (ICE)â or test failures, see
+<a class="reference internal" href="#below">below</a>.</p>
+</li>
+</ul>
+</li>
+</ol>
+<p>Consult the <a class="reference internal" href="#getting-started-with-llvm">Getting Started with LLVM</a> section for detailed information on
+configuring and compiling LLVM. Go to <a class="reference internal" href="#directory-layout">Directory Layout</a> to learn about the
+layout of the source code tree.</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>Before you begin to use the LLVM system, review the requirements given below.
+This may save you some trouble by knowing ahead of time what hardware and
+software you will need.</p>
+<div class="section" id="hardware">
+<h3><a class="toc-backref" href="#id6">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h3>
+<p>LLVM is known to work on the following host platforms:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="35%" />
+<col width="40%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">OS</th>
+<th class="head">Arch</th>
+<th class="head">Compilers</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>Linux</td>
+<td>x86<sup>1</sup></td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-odd"><td>Linux</td>
+<td>amd64</td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-even"><td>Linux</td>
+<td>ARM</td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-odd"><td>Linux</td>
+<td>PowerPC</td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-even"><td>Solaris</td>
+<td>V9 (Ultrasparc)</td>
+<td>GCC</td>
+</tr>
+<tr class="row-odd"><td>FreeBSD</td>
+<td>x86<sup>1</sup></td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-even"><td>FreeBSD</td>
+<td>amd64</td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-odd"><td>NetBSD</td>
+<td>x86<sup>1</sup></td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-even"><td>NetBSD</td>
+<td>amd64</td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-odd"><td>MacOS X<sup>2</sup></td>
+<td>PowerPC</td>
+<td>GCC</td>
+</tr>
+<tr class="row-even"><td>MacOS X</td>
+<td>x86</td>
+<td>GCC, Clang</td>
+</tr>
+<tr class="row-odd"><td>Cygwin/Win32</td>
+<td>x86<sup>1, 3</sup></td>
+<td>GCC</td>
+</tr>
+<tr class="row-even"><td>Windows</td>
+<td>x86<sup>1</sup></td>
+<td>Visual Studio</td>
+</tr>
+<tr class="row-odd"><td>Windows x64</td>
+<td>x86-64</td>
+<td>Visual Studio</td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<ol class="last arabic simple">
+<li>Code generation supported for Pentium processors and up</li>
+<li>Code generation supported for 32-bit ABI only</li>
+<li>To use LLVM modules on Win32-based system, you may configure LLVM
+with <code class="docutils literal notranslate"><span class="pre">-DBUILD_SHARED_LIBS=On</span></code>.</li>
+</ol>
+</div>
+<p>Note that Debug builds require a lot of time and disk space. An LLVM-only build
+will need about 1-3 GB of space. A full build of LLVM and Clang will need around
+15-20 GB of disk space. The exact space requirements will vary by system. (It
+is so large because of all the debugging information and the fact that the
+libraries are statically linked into multiple tools).</p>
+<p>If you are space-constrained, you can build only selected tools or only
+selected targets. The Release build requires considerably less space.</p>
+<p>The LLVM suite <em>may</em> compile on other platforms, but it is not guaranteed to do
+so. If compilation is successful, the LLVM utilities should be able to
+assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation
+should work as well, although the generated native code may not work on your
+platform.</p>
+</div>
+<div class="section" id="software">
+<h3><a class="toc-backref" href="#id7">Software</a><a class="headerlink" href="#software" title="Permalink to this headline">¶</a></h3>
+<p>Compiling LLVM requires that you have several software packages installed. The
+table below lists those required packages. The Package column is the usual name
+for the software package that LLVM depends on. The Version column provides
+âknown to workâ versions of the package. The Notes column describes how LLVM
+uses the package and provides other details.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="52%" />
+<col width="11%" />
+<col width="37%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Package</th>
+<th class="head">Version</th>
+<th class="head">Notes</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><a class="reference external" href="http://savannah.gnu.org/projects/make">GNU Make</a></td>
+<td>3.79, 3.79.1</td>
+<td>Makefile/build processor</td>
+</tr>
+<tr class="row-odd"><td><a class="reference external" href="http://gcc.gnu.org/">GCC</a></td>
+<td>>=5.1.0</td>
+<td>C/C++ compiler<sup>1</sup></td>
+</tr>
+<tr class="row-even"><td><a class="reference external" href="http://www.python.org/">python</a></td>
+<td>>=2.7</td>
+<td>Automated test suite<sup>2</sup></td>
+</tr>
+<tr class="row-odd"><td><a class="reference external" href="http://zlib.net">zlib</a></td>
+<td>>=1.2.3.4</td>
+<td>Compression library<sup>3</sup></td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<ol class="last arabic simple">
+<li>Only the C and C++ languages are needed so thereâs no need to build the
+other languages for LLVMâs purposes. See <cite>below</cite> for specific version
+info.</li>
+<li>Only needed if you want to run the automated test suite in the
+<code class="docutils literal notranslate"><span class="pre">llvm/test</span></code> directory.</li>
+<li>Optional, adds compression / uncompression capabilities to selected LLVM
+tools.</li>
+</ol>
+</div>
+<p>Additionally, your compilation host is expected to have the usual plethora of
+Unix utilities. Specifically:</p>
+<ul class="simple">
+<li><strong>ar</strong> â archive library builder</li>
+<li><strong>bzip2</strong> â bzip2 command for distribution generation</li>
+<li><strong>bunzip2</strong> â bunzip2 command for distribution checking</li>
+<li><strong>chmod</strong> â change permissions on a file</li>
+<li><strong>cat</strong> â output concatenation utility</li>
+<li><strong>cp</strong> â copy files</li>
+<li><strong>date</strong> â print the current date/time</li>
+<li><strong>echo</strong> â print to standard output</li>
+<li><strong>egrep</strong> â extended regular expression search utility</li>
+<li><strong>find</strong> â find files/dirs in a file system</li>
+<li><strong>grep</strong> â regular expression search utility</li>
+<li><strong>gzip</strong> â gzip command for distribution generation</li>
+<li><strong>gunzip</strong> â gunzip command for distribution checking</li>
+<li><strong>install</strong> â install directories/files</li>
+<li><strong>mkdir</strong> â create a directory</li>
+<li><strong>mv</strong> â move (rename) files</li>
+<li><strong>ranlib</strong> â symbol table builder for archive libraries</li>
+<li><strong>rm</strong> â remove (delete) files and directories</li>
+<li><strong>sed</strong> â stream editor for transforming output</li>
+<li><strong>sh</strong> â Bourne shell for make build scripts</li>
+<li><strong>tar</strong> â tape archive for distribution generation</li>
+<li><strong>test</strong> â test things in file system</li>
+<li><strong>unzip</strong> â unzip command for distribution checking</li>
+<li><strong>zip</strong> â zip command for distribution generation</li>
+</ul>
+</div>
+<div class="section" id="host-c-toolchain-both-compiler-and-standard-library">
+<span id="check-here"></span><span id="below"></span><h3><a class="toc-backref" href="#id8">Host C++ Toolchain, both Compiler and Standard Library</a><a class="headerlink" href="#host-c-toolchain-both-compiler-and-standard-library" title="Permalink to this headline">¶</a></h3>
+<p>LLVM is very demanding of the host C++ compiler, and as such tends to expose
+bugs in the compiler. We also attempt to follow improvements and developments in
+the C++ language and library reasonably closely. As such, we require a modern
+host C++ toolchain, both compiler and standard library, in order to build LLVM.</p>
+<p>LLVM is written using the subset of C++ documented in <a class="reference internal" href="CodingStandards.html"><span class="doc">coding
+standards</span></a>. To enforce this language version, we check the most
+popular host toolchains for specific minimum versions in our build systems:</p>
+<ul class="simple">
+<li>Clang 3.5</li>
+<li>Apple Clang 6.0</li>
+<li>GCC 5.1</li>
+<li>Visual Studio 2017</li>
+</ul>
+<p>The below versions currently soft-error as we transition to the new compiler
+versions listed above. The LLVM codebase is currently known to compile correctly
+with the following compilers, though this will change in the near future:</p>
+<ul class="simple">
+<li>Clang 3.1</li>
+<li>Apple Clang 3.1</li>
+<li>GCC 4.8</li>
+<li>Visual Studio 2015 (Update 3)</li>
+</ul>
+<p>Anything older than these toolchains <em>may</em> work, but will require forcing the
+build system with a special option and is not really a supported host platform.
+Also note that older versions of these compilers have often crashed or
+miscompiled LLVM.</p>
+<p>For less widely used host toolchains such as ICC or xlC, be aware that a very
+recent version may be required to support all of the C++ features used in LLVM.</p>
+<p>We track certain versions of software that are <em>known</em> to fail when used as
+part of the host toolchain. These even include linkers at times.</p>
+<p><strong>GNU ld 2.16.X</strong>. Some 2.16.X versions of the ld linker will produce very long
+warning messages complaining that some â<code class="docutils literal notranslate"><span class="pre">.gnu.linkonce.t.*</span></code>â symbol was
+defined in a discarded section. You can safely ignore these messages as they are
+erroneous and the linkage is correct. These messages disappear using ld 2.17.</p>
+<p><strong>GNU binutils 2.17</strong>: Binutils 2.17 contains <a class="reference external" href="http://sourceware.org/bugzilla/show_bug.cgi?id=3111">a bug</a> which causes huge link
+times (minutes instead of seconds) when building LLVM. We recommend upgrading
+to a newer version (2.17.50.0.4 or later).</p>
+<p><strong>GNU Binutils 2.19.1 Gold</strong>: This version of Gold contained <a class="reference external" href="http://sourceware.org/bugzilla/show_bug.cgi?id=9836">a bug</a> which causes
+intermittent failures when building LLVM with position independent code. The
+symptom is an error about cyclic dependencies. We recommend upgrading to a
+newer version of Gold.</p>
+<div class="section" id="getting-a-modern-host-c-toolchain">
+<h4><a class="toc-backref" href="#id9">Getting a Modern Host C++ Toolchain</a><a class="headerlink" href="#getting-a-modern-host-c-toolchain" title="Permalink to this headline">¶</a></h4>
+<p>This section mostly applies to Linux and older BSDs. On Mac OS X, you should
+have a sufficiently modern Xcode, or you will likely need to upgrade until you
+do. Windows does not have a âsystem compilerâ, so you must install either Visual
+Studio 2015 or a recent version of mingw64. FreeBSD 10.0 and newer have a modern
+Clang as the system compiler.</p>
+<p>However, some Linux distributions and some other or older BSDs sometimes have
+extremely old versions of GCC. These steps attempt to help you upgrade you
+compiler even on such a system. However, if at all possible, we encourage you
+to use a recent version of a distribution with a modern system compiler that
+meets these requirements. Note that it is tempting to install a prior
+version of Clang and libc++ to be the host compiler, however libc++ was not
+well tested or set up to build on Linux until relatively recently. As
+a consequence, this guide suggests just using libstdc++ and a modern GCC as the
+initial host in a bootstrap, and then using Clang (and potentially libc++).</p>
+<p>The first step is to get a recent GCC toolchain installed. The most common
+distribution on which users have struggled with the version requirements is
+Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
+the <a class="reference external" href="https://launchpad.net/~ubuntu-toolchain-r/+archive/test">toolchain testing PPA</a> and use it to install a modern GCC. There is
+a really nice discussions of this on the <a class="reference external" href="https://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu/581497#58149">ask ubuntu stack exchange</a> and a
+<a class="reference external" href="https://gist.github.com/application2000/73fd6f4bf1be6600a2cf9f56315a2d91">github gist</a> with updated commands. However, not all users can use PPAs and
+there are many other distributions, so it may be necessary (or just useful, if
+youâre here you <em>are</em> doing compiler development after all) to build and install
+GCC from source. It is also quite easy to do these days.</p>
+<p>Easy steps for installing GCC 5.1.0:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nv">gcc_version</span><span class="o">=</span><span class="m">5</span>.1.0
+<span class="gp">%</span> wget https://ftp.gnu.org/gnu/gcc/gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>/gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>.tar.bz2
+<span class="gp">%</span> wget https://ftp.gnu.org/gnu/gcc/gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>/gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>.tar.bz2.sig
+<span class="gp">%</span> wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
+<span class="gp">%</span> <span class="nv">signature_invalid</span><span class="o">=</span><span class="sb">`</span>gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>.tar.bz2.sig<span class="sb">`</span>
+<span class="gp">%</span> <span class="k">if</span> <span class="o">[</span> <span class="nv">$signature_invalid</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span> <span class="nb">echo</span> <span class="s2">"Invalid signature"</span> <span class="p">;</span> <span class="nb">exit</span> <span class="m">1</span> <span class="p">;</span> <span class="k">fi</span>
+<span class="gp">%</span> tar -xvjf gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>.tar.bz2
+<span class="gp">%</span> <span class="nb">cd</span> gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>
+<span class="gp">%</span> ./contrib/download_prerequisites
+<span class="gp">%</span> <span class="nb">cd</span> ..
+<span class="gp">%</span> mkdir gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>-build
+<span class="gp">%</span> <span class="nb">cd</span> gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>-build
+<span class="gp">%</span> <span class="nv">$PWD</span>/../gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>/configure --prefix<span class="o">=</span><span class="nv">$HOME</span>/toolchains --enable-languages<span class="o">=</span>c,c++
+<span class="gp">%</span> make -j<span class="k">$(</span>nproc<span class="k">)</span>
+<span class="gp">%</span> make install
+</pre></div>
+</div>
+<p>For more details, check out the excellent <a class="reference external" href="https://gcc.gnu.org/wiki/InstallingGCC">GCC wiki entry</a>, where I got most
+of this information from.</p>
+<p>Once you have a GCC toolchain, configure your build of LLVM to use the new
+toolchain for your host compiler and C++ standard library. Because the new
+version of libstdc++ is not on the system library search path, you need to pass
+extra linker flags so that it can be found at link time (<code class="docutils literal notranslate"><span class="pre">-L</span></code>) and at runtime
+(<code class="docutils literal notranslate"><span class="pre">-rpath</span></code>). If you are using CMake, this invocation should produce working
+binaries:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> mkdir build
+<span class="gp">%</span> <span class="nb">cd</span> build
+<span class="gp">%</span> <span class="nv">CC</span><span class="o">=</span><span class="nv">$HOME</span>/toolchains/bin/gcc <span class="nv">CXX</span><span class="o">=</span><span class="nv">$HOME</span>/toolchains/bin/g++ <span class="se">\</span>
+ cmake .. -DCMAKE_CXX_LINK_FLAGS<span class="o">=</span><span class="s2">"-Wl,-rpath,</span><span class="nv">$HOME</span><span class="s2">/toolchains/lib64 -L</span><span class="nv">$HOME</span><span class="s2">/toolchains/lib64"</span>
+</pre></div>
+</div>
+<p>If you fail to set rpath, most LLVM binaries will fail on startup with a message
+from the loader similar to <code class="docutils literal notranslate"><span class="pre">libstdc++.so.6:</span> <span class="pre">version</span> <span class="pre">`GLIBCXX_3.4.20'</span> <span class="pre">not</span>
+<span class="pre">found</span></code>. This means you need to tweak the -rpath linker flag.</p>
+<p>When you build Clang, you will need to give <em>it</em> access to modern C++
+standard library in order to use it as your new host in part of a bootstrap.
+There are two easy ways to do this, either build (and install) libc++ along
+with Clang and then use it with the <code class="docutils literal notranslate"><span class="pre">-stdlib=libc++</span></code> compile and link flag,
+or install Clang into the same prefix (<code class="docutils literal notranslate"><span class="pre">$HOME/toolchains</span></code> above) as GCC.
+Clang will look within its own prefix for libstdc++ and use it if found. You
+can also add an explicit prefix for Clang to look in for a GCC toolchain with
+the <code class="docutils literal notranslate"><span class="pre">--gcc-toolchain=/opt/my/gcc/prefix</span></code> flag, passing it to both compile and
+link commands when using your just-built-Clang to bootstrap.</p>
+</div>
+</div>
+</div>
+<div class="section" id="getting-started-with-llvm">
+<span id="id1"></span><h2><a class="toc-backref" href="#id10">Getting Started with LLVM</a><a class="headerlink" href="#getting-started-with-llvm" title="Permalink to this headline">¶</a></h2>
+<p>The remainder of this guide is meant to get you up and running with LLVM and to
+give you some basic information about the LLVM environment.</p>
+<p>The later sections of this guide describe the <a class="reference internal" href="#general-layout">general layout</a> of the LLVM
+source tree, a <a class="reference internal" href="#simple-example">simple example</a> using the LLVM tool chain, and <a class="reference internal" href="#links">links</a> to find
+more information about LLVM or to get help via e-mail.</p>
+<div class="section" id="terminology-and-notation">
+<h3><a class="toc-backref" href="#id11">Terminology and Notation</a><a class="headerlink" href="#terminology-and-notation" title="Permalink to this headline">¶</a></h3>
+<p>Throughout this manual, the following names are used to denote paths specific to
+the local system and working environment. <em>These are not environment variables
+you need to set but just strings used in the rest of this document below</em>. In
+any of the examples below, simply replace each of these names with the
+appropriate pathname on your local system. All these paths are absolute:</p>
+<p><code class="docutils literal notranslate"><span class="pre">SRC_ROOT</span></code></p>
+<blockquote>
+<div>This is the top level directory of the LLVM source tree.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">OBJ_ROOT</span></code></p>
+<blockquote>
+<div>This is the top level directory of the LLVM object tree (i.e. the tree where
+object files and compiled programs will be placed. It can be the same as
+SRC_ROOT).</div></blockquote>
+</div>
+<div class="section" id="unpacking-the-llvm-archives">
+<h3><a class="toc-backref" href="#id12">Unpacking the LLVM Archives</a><a class="headerlink" href="#unpacking-the-llvm-archives" title="Permalink to this headline">¶</a></h3>
+<p>If you have the LLVM distribution, you will need to unpack it before you can
+begin to compile it. LLVM is distributed as a number of different
+subprojects. Each one has its own download which is a TAR archive that is
+compressed with the gzip program.</p>
+<p>The files are as follows, with <em>x.y</em> marking the version number:</p>
+<p><code class="docutils literal notranslate"><span class="pre">llvm-x.y.tar.gz</span></code></p>
+<blockquote>
+<div>Source release for the LLVM libraries and tools.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">cfe-x.y.tar.gz</span></code></p>
+<blockquote>
+<div>Source release for the Clang frontend.</div></blockquote>
+</div>
+<div class="section" id="checkout-llvm-from-git">
+<span id="checkout"></span><h3><a class="toc-backref" href="#id13">Checkout LLVM from Git</a><a class="headerlink" href="#checkout-llvm-from-git" title="Permalink to this headline">¶</a></h3>
+<p>You can also checkout the source code for LLVM from Git. While the LLVM
+projectâs official source-code repository is Subversion, we are in the process
+of migrating to git. We currently recommend that all developers use Git for
+day-to-day development.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Passing <code class="docutils literal notranslate"><span class="pre">--config</span> <span class="pre">core.autocrlf=false</span></code> should not be required in
+the future after we adjust the .gitattribute settings correctly, but
+is required for Windows users at the time of this writing.</p>
+</div>
+<p>Simply run:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> git clone https://github.com/llvm/llvm-project.git<span class="sb">`</span>
+</pre></div>
+</div>
+<p>or on Windows,</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> git clone --config core.autocrlf<span class="o">=</span><span class="nb">false</span> https://github.com/llvm/llvm-project.git
+</pre></div>
+</div>
+<p>This will create an â<code class="docutils literal notranslate"><span class="pre">llvm-project</span></code>â directory in the current directory and
+fully populate it with all of the source code, test directories, and local
+copies of documentation files for LLVM and all the related subprojects. Note
+that unlike the tarballs, which contain each subproject in a separate file, the
+git repository contains all of the projects together.</p>
+<p>If you want to get a specific release (as opposed to the most recent revision),
+you can check out a tag after cloning the repository. E.g., <cite>git checkout
+llvmorg-6.0.1</cite> inside the <code class="docutils literal notranslate"><span class="pre">llvm-project</span></code> directory created by the above
+command. Use <cite>git tag -l</cite> to list all of them.</p>
+<div class="section" id="sending-patches">
+<h4><a class="toc-backref" href="#id14">Sending patches</a><a class="headerlink" href="#sending-patches" title="Permalink to this headline">¶</a></h4>
+<p>Please read <a class="reference external" href="DeveloperPolicy.html#one-off-patches">Developer Policy</a>, too.</p>
+<p>We donât currently accept github pull requests, so youâll need to send patches
+either via emailing to llvm-commits, or, preferably, via <a class="reference internal" href="Phabricator.html#phabricator-reviews"><span class="std std-ref">Phabricator</span></a>.</p>
+<p>Youâll generally want to make sure your branch has a single commit,
+corresponding to the review you wish to send, up-to-date with the upstream
+<code class="docutils literal notranslate"><span class="pre">origin/master</span></code> branch, and doesnât contain merges. Once you have that, you
+can use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">show</span></code> or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">format-patch</span></code> to output the diff, and attach it
+to a Phabricator review (or to an email message).</p>
+<p>However, using the âArcanistâ tool is often easier. After <a class="reference external" href="https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/">installing
+arcanist</a>, you can upload the latest commit using:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> arc diff HEAD~1
+</pre></div>
+</div>
+<p>Additionally, before sending a patch for review, please also try to ensure itâs
+formatted properly. We use <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> for this, which has git integration
+through the <code class="docutils literal notranslate"><span class="pre">git-clang-format</span></code> script. On some systems, it may already be
+installed (or be installable via your package manager). If so, you can simply
+run it â the following command will format only the code changed in the most
+recent commit:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> git clang-format HEAD~1
+</pre></div>
+</div>
+<p>Note that this modifies the files, but doesnât commit them â youâll likely want
+to run</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> git commit --amend -a
+</pre></div>
+</div>
+<p>in order to update the last commit with all pending changes.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you donât already have <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clang-format</span></code> installed
+on your system, the <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> binary will be built alongside clang, and
+the git integration can be run from
+<code class="docutils literal notranslate"><span class="pre">clang/tools/clang-format/git-clang-format</span></code>.</p>
+</div>
+</div>
+<div class="section" id="for-developers-to-commit-changes-from-git">
+<span id="commit-from-git"></span><h4><a class="toc-backref" href="#id15">For developers to commit changes from Git</a><a class="headerlink" href="#for-developers-to-commit-changes-from-git" title="Permalink to this headline">¶</a></h4>
+<p>A helper script is provided in <code class="docutils literal notranslate"><span class="pre">llvm/utils/git-svn/git-llvm</span></code>. After you add it
+to your path, you can push committed changes upstream with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">llvm</span>
+<span class="pre">push</span></code>. While this creates a Subversion checkout and patches it under the hood,
+it does not require you to have interaction with it.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nb">export</span> <span class="nv">PATH</span><span class="o">=</span><span class="nv">$PATH</span>:<span class="nv">$TOP_LEVEL_DIR</span>/llvm-project/llvm/utils/git-svn/
+<span class="gp">%</span> git llvm push
+</pre></div>
+</div>
+<p>Within a couple minutes after pushing to subversion, the svn commit will have
+been converted back to a Git commit, and made its way into the official Git
+repository. At that point, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> should get back the changes as they were
+committed.</p>
+<p>Youâll likely want to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span> <span class="pre">--rebase</span></code> to get the official git commit
+downloaded back to your repository. The SVN revision numbers of each commit can
+be found at the end of the commit message, e.g. <code class="docutils literal notranslate"><span class="pre">llvm-svn:</span> <span class="pre">350914</span></code>.</p>
+<p>You may also find the <code class="docutils literal notranslate"><span class="pre">-n</span></code> flag useful, like <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">llvm</span> <span class="pre">push</span> <span class="pre">-n</span></code>. This runs
+through all the steps of committing _without_ actually doing the commit, and
+tell you what it would have done. That can be useful if youâre unsure whether
+the right thing will happen.</p>
+</div>
+<div class="section" id="checkout-via-svn-deprecated">
+<h4><a class="toc-backref" href="#id16">Checkout via SVN (deprecated)</a><a class="headerlink" href="#checkout-via-svn-deprecated" title="Permalink to this headline">¶</a></h4>
+<p>Until we have fully migrated to Git, you may also get a fresh copy of
+the code from the official Subversion repository.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></code></li>
+<li>Read-Only: <code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/llvm/trunk</span> <span class="pre">llvm</span></code></li>
+<li>Read-Write: <code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">https://user@llvm.org/svn/llvm-project/llvm/trunk</span> <span class="pre">llvm</span></code></li>
+</ul>
+<p>This will create an â<code class="docutils literal notranslate"><span class="pre">llvm</span></code>â directory in the current directory and fully
+populate it with the LLVM source code, Makefiles, test directories, and local
+copies of documentation files.</p>
+<p>If you want to get a specific release (as opposed to the most recent revision),
+you can check it out from the â<code class="docutils literal notranslate"><span class="pre">tags</span></code>â directory (instead of â<code class="docutils literal notranslate"><span class="pre">trunk</span></code>â). The
+following releases are located in the following subdirectories of the â<code class="docutils literal notranslate"><span class="pre">tags</span></code>â
+directory:</p>
+<ul class="simple">
+<li>Release 3.5.0 and later: <strong>RELEASE_350/final</strong> and so on</li>
+<li>Release 2.9 through 3.4: <strong>RELEASE_29/final</strong> and so on</li>
+<li>Release 1.1 through 2.8: <strong>RELEASE_11</strong> and so on</li>
+<li>Release 1.0: <strong>RELEASE_1</strong></li>
+</ul>
+</div>
+</div>
+<div class="section" id="local-llvm-configuration">
+<h3><a class="toc-backref" href="#id17">Local LLVM Configuration</a><a class="headerlink" href="#local-llvm-configuration" title="Permalink to this headline">¶</a></h3>
+<p>Once checked out repository, the LLVM suite source code must be configured
+before being built. This process uses CMake. Unlinke the normal <code class="docutils literal notranslate"><span class="pre">configure</span></code>
+script, CMake generates the build files in whatever format you request as well
+as various <code class="docutils literal notranslate"><span class="pre">*.inc</span></code> files, and <code class="docutils literal notranslate"><span class="pre">llvm/include/Config/config.h</span></code>.</p>
+<p>Variables are passed to <code class="docutils literal notranslate"><span class="pre">cmake</span></code> on the command line using the format
+<code class="docutils literal notranslate"><span class="pre">-D<variable</span> <span class="pre">name>=<value></span></code>. The following variables are some common options
+used by people developing LLVM.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="32%" />
+<col width="68%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Variable</th>
+<th class="head">Purpose</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>CMAKE_C_COMPILER</td>
+<td>Tells <code class="docutils literal notranslate"><span class="pre">cmake</span></code> which C compiler to use. By
+default, this will be /usr/bin/cc.</td>
+</tr>
+<tr class="row-odd"><td>CMAKE_CXX_COMPILER</td>
+<td>Tells <code class="docutils literal notranslate"><span class="pre">cmake</span></code> which C++ compiler to use. By
+default, this will be /usr/bin/c++.</td>
+</tr>
+<tr class="row-even"><td>CMAKE_BUILD_TYPE</td>
+<td>Tells <code class="docutils literal notranslate"><span class="pre">cmake</span></code> what type of build you are trying
+to generate files for. Valid options are Debug,
+Release, RelWithDebInfo, and MinSizeRel. Default
+is Debug.</td>
+</tr>
+<tr class="row-odd"><td>CMAKE_INSTALL_PREFIX</td>
+<td>Specifies the install directory to target when
+running the install action of the build files.</td>
+</tr>
+<tr class="row-even"><td>LLVM_TARGETS_TO_BUILD</td>
+<td>A semicolon delimited list controlling which
+targets will be built and linked into llvm.
+The default list is defined as
+<code class="docutils literal notranslate"><span class="pre">LLVM_ALL_TARGETS</span></code>, and can be set to include
+out-of-tree targets. The default value includes:
+<code class="docutils literal notranslate"><span class="pre">AArch64,</span> <span class="pre">AMDGPU,</span> <span class="pre">ARM,</span> <span class="pre">BPF,</span> <span class="pre">Hexagon,</span> <span class="pre">Mips,</span>
+<span class="pre">MSP430,</span> <span class="pre">NVPTX,</span> <span class="pre">PowerPC,</span> <span class="pre">Sparc,</span> <span class="pre">SystemZ,</span> <span class="pre">X86,</span>
+<span class="pre">XCore</span></code>.</td>
+</tr>
+<tr class="row-odd"><td>LLVM_ENABLE_DOXYGEN</td>
+<td>Build doxygen-based documentation from the source
+code This is disabled by default because it is
+slow and generates a lot of output.</td>
+</tr>
+<tr class="row-even"><td>LLVM_ENABLE_PROJECTS</td>
+<td>A semicolon-delimited list selecting which of the
+other LLVM subprojects to additionally build. (Only
+effective when using a side-by-side project layout
+e.g. via git). The default list is empty. Can
+include: clang, libcxx, libcxxabi, libunwind, lldb,
+compiler-rt, lld, polly, or debuginfo-tests.</td>
+</tr>
+<tr class="row-odd"><td>LLVM_ENABLE_SPHINX</td>
+<td>Build sphinx-based documentation from the source
+code. This is disabled by default because it is
+slow and generates a lot of output. Sphinx version
+1.5 or later recommended.</td>
+</tr>
+<tr class="row-even"><td>LLVM_BUILD_LLVM_DYLIB</td>
+<td>Generate libLLVM.so. This library contains a
+default set of LLVM components that can be
+overridden with <code class="docutils literal notranslate"><span class="pre">LLVM_DYLIB_COMPONENTS</span></code>. The
+default contains most of LLVM and is defined in
+<code class="docutils literal notranslate"><span class="pre">tools/llvm-shlib/CMakelists.txt</span></code>.</td>
+</tr>
+<tr class="row-odd"><td>LLVM_OPTIMIZED_TABLEGEN</td>
+<td>Builds a release tablegen that gets used during
+the LLVM build. This can dramatically speed up
+debug builds.</td>
+</tr>
+</tbody>
+</table>
+<p>To configure LLVM, follow these steps:</p>
+<ol class="arabic">
+<li><p class="first">Change directory into the object root directory:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nb">cd</span> OBJ_ROOT
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the <code class="docutils literal notranslate"><span class="pre">cmake</span></code>:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cmake -G <span class="s2">"Unix Makefiles"</span> -DCMAKE_INSTALL_PREFIX<span class="o">=</span>/install/path
+<span class="go"> [other options] SRC_ROOT</span>
+</pre></div>
+</div>
+</li>
+</ol>
+</div>
+<div class="section" id="compiling-the-llvm-suite-source-code">
+<h3><a class="toc-backref" href="#id18">Compiling the LLVM Suite Source Code</a><a class="headerlink" href="#compiling-the-llvm-suite-source-code" title="Permalink to this headline">¶</a></h3>
+<p>Unlike with autotools, with CMake your build type is defined at configuration.
+If you want to change your build type, you can re-run cmake with the following
+invocation:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cmake -G <span class="s2">"Unix Makefiles"</span> -DCMAKE_BUILD_TYPE<span class="o">=</span><span class="nb">type</span> SRC_ROOT
+</pre></div>
+</div>
+</div></blockquote>
+<p>Between runs, CMake preserves the values set for all options. CMake has the
+following build types defined:</p>
+<p>Debug</p>
+<blockquote>
+<div>These builds are the default. The build system will compile the tools and
+libraries unoptimized, with debugging information, and asserts enabled.</div></blockquote>
+<p>Release</p>
+<blockquote>
+<div>For these builds, the build system will compile the tools and libraries
+with optimizations enabled and not generate debug info. CMakes default
+optimization level is -O3. This can be configured by setting the
+<code class="docutils literal notranslate"><span class="pre">CMAKE_CXX_FLAGS_RELEASE</span></code> variable on the CMake command line.</div></blockquote>
+<p>RelWithDebInfo</p>
+<blockquote>
+<div>These builds are useful when debugging. They generate optimized binaries with
+debug information. CMakes default optimization level is -O2. This can be
+configured by setting the <code class="docutils literal notranslate"><span class="pre">CMAKE_CXX_FLAGS_RELWITHDEBINFO</span></code> variable on the
+CMake command line.</div></blockquote>
+<p>Once you have LLVM configured, you can build it by entering the <em>OBJ_ROOT</em>
+directory and issuing the following command:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> make
+</pre></div>
+</div>
+<p>If the build fails, please <a class="reference internal" href="#check-here">check here</a> to see if you are using a version of
+GCC that is known not to compile LLVM.</p>
+<p>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:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> make -j2
+</pre></div>
+</div>
+<p>There are several special targets which are useful when working with the LLVM
+source code:</p>
+<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clean</span></code></p>
+<blockquote>
+<div>Removes all files generated by the build. This includes object files,
+generated C/C++ files, libraries, and executables.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code></p>
+<blockquote>
+<div>Installs LLVM header files, libraries, tools, and documentation in a hierarchy
+under <code class="docutils literal notranslate"><span class="pre">$PREFIX</span></code>, specified with <code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code>, which
+defaults to <code class="docutils literal notranslate"><span class="pre">/usr/local</span></code>.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">docs-llvm-html</span></code></p>
+<blockquote>
+<div>If configured with <code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_SPHINX=On</span></code>, this will generate a directory
+at <code class="docutils literal notranslate"><span class="pre">OBJ_ROOT/docs/html</span></code> which contains the HTML formatted documentation.</div></blockquote>
+</div>
+<div class="section" id="cross-compiling-llvm">
+<h3><a class="toc-backref" href="#id19">Cross-Compiling LLVM</a><a class="headerlink" href="#cross-compiling-llvm" title="Permalink to this headline">¶</a></h3>
+<p>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 generate build files for
+cross-compiling CMake provides a variable <code class="docutils literal notranslate"><span class="pre">CMAKE_TOOLCHAIN_FILE</span></code> which can
+define compiler flags and variables used during the CMake test operations.</p>
+<p>The result of such a build is executables that are not runnable on the build
+host but can be executed on the target. As an example the following CMake
+invocation can generate build files targeting iOS. This will work on Mac OS X
+with the latest Xcode:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cmake -G <span class="s2">"Ninja"</span> -DCMAKE_OSX_ARCHITECTURES<span class="o">=</span><span class="s2">"armv7;armv7s;arm64"</span>
+<span class="go"> -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake</span>
+<span class="go"> -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off</span>
+<span class="go"> -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options]</span>
+<span class="go"> <PATH_TO_LLVM></span>
+</pre></div>
+</div>
+<p>Note: There are some additional flags that need to be passed when building for
+iOS due to limitations in the iOS SDK.</p>
+<p>Check <a class="reference internal" href="HowToCrossCompileLLVM.html"><span class="doc">How To Cross-Compile Clang/LLVM using Clang/LLVM</span></a> and <a class="reference external" href="http://clang.llvm.org/docs/CrossCompilation.html">Clang docs on how to cross-compile in general</a> for more information
+about cross-compiling.</p>
+</div>
+<div class="section" id="the-location-of-llvm-object-files">
+<h3><a class="toc-backref" href="#id20">The Location of LLVM Object Files</a><a class="headerlink" href="#the-location-of-llvm-object-files" title="Permalink to this headline">¶</a></h3>
+<p>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.</p>
+<ul>
+<li><p class="first">Change directory to where the LLVM object files should live:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nb">cd</span> OBJ_ROOT
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run <code class="docutils literal notranslate"><span class="pre">cmake</span></code>:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cmake -G <span class="s2">"Unix Makefiles"</span> SRC_ROOT
+</pre></div>
+</div>
+</li>
+</ul>
+<p>The LLVM build will create a structure underneath <em>OBJ_ROOT</em> that matches the
+LLVM source tree. At each level where source files are present in the source
+tree there will be a corresponding <code class="docutils literal notranslate"><span class="pre">CMakeFiles</span></code> directory in the <em>OBJ_ROOT</em>.
+Underneath that directory there is another directory with a name ending in
+<code class="docutils literal notranslate"><span class="pre">.dir</span></code> under which youâll find object files for each source.</p>
+<p>For example:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nb">cd</span> llvm_build_dir
+<span class="gp">%</span> find lib/Support/ -name APFloat*
+<span class="go">lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="optional-configuration-items">
+<h3><a class="toc-backref" href="#id21">Optional Configuration Items</a><a class="headerlink" href="#optional-configuration-items" title="Permalink to this headline">¶</a></h3>
+<p>If youâre running on a Linux system that supports the <a class="reference external" href="http://en.wikipedia.org/wiki/binfmt_misc">binfmt_misc</a>
+module, and you have root access on the system, you can set your system up to
+execute LLVM bitcode files directly. To do this, use commands like this (the
+first command may not be required if you are already using the module):</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
+<span class="gp">%</span> <span class="nb">echo</span> <span class="s1">':llvm:M::BC::/path/to/lli:'</span> > /proc/sys/fs/binfmt_misc/register
+<span class="gp">%</span> chmod u+x hello.bc <span class="o">(</span><span class="k">if</span> needed<span class="o">)</span>
+<span class="gp">%</span> ./hello.bc
+</pre></div>
+</div>
+<p>This allows you to execute LLVM bitcode files directly. On Debian, you can also
+use this command instead of the âechoâ command above:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> sudo update-binfmts --install llvm /path/to/lli --magic <span class="s1">'BC'</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="directory-layout">
+<span id="general-layout"></span><span id="program-layout"></span><h2><a class="toc-backref" href="#id22">Directory Layout</a><a class="headerlink" href="#directory-layout" title="Permalink to this headline">¶</a></h2>
+<p>One useful source of information about the LLVM source base is the LLVM <a class="reference external" href="http://www.doxygen.org/">doxygen</a> documentation available at
+<a class="reference external" href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a>. The following is a brief introduction to code
+layout:</p>
+<div class="section" id="llvm-examples">
+<h3><a class="toc-backref" href="#id23"><code class="docutils literal notranslate"><span class="pre">llvm/examples</span></code></a><a class="headerlink" href="#llvm-examples" title="Permalink to this headline">¶</a></h3>
+<p>Simple examples using the LLVM IR and JIT.</p>
+</div>
+<div class="section" id="llvm-include">
+<h3><a class="toc-backref" href="#id24"><code class="docutils literal notranslate"><span class="pre">llvm/include</span></code></a><a class="headerlink" href="#llvm-include" title="Permalink to this headline">¶</a></h3>
+<p>Public header files exported from the LLVM library. The three main subdirectories:</p>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm</span></code></p>
+<blockquote>
+<div>All LLVM-specific header files, and subdirectories for different portions of
+LLVM: <code class="docutils literal notranslate"><span class="pre">Analysis</span></code>, <code class="docutils literal notranslate"><span class="pre">CodeGen</span></code>, <code class="docutils literal notranslate"><span class="pre">Target</span></code>, <code class="docutils literal notranslate"><span class="pre">Transforms</span></code>, etcâ¦</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/Support</span></code></p>
+<blockquote>
+<div>Generic support libraries provided with LLVM but not necessarily specific to
+LLVM. For example, some C++ STL utilities and a Command Line option processing
+library store header files here.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/Config</span></code></p>
+<blockquote>
+<div>Header files configured by <code class="docutils literal notranslate"><span class="pre">cmake</span></code>. They wrap âstandardâ UNIX and
+C header files. Source code can include these header files which
+automatically take care of the conditional #includes that <code class="docutils literal notranslate"><span class="pre">cmake</span></code>
+generates.</div></blockquote>
+</div>
+<div class="section" id="llvm-lib">
+<h3><a class="toc-backref" href="#id25"><code class="docutils literal notranslate"><span class="pre">llvm/lib</span></code></a><a class="headerlink" href="#llvm-lib" title="Permalink to this headline">¶</a></h3>
+<p>Most source files are here. By putting code in libraries, LLVM makes it easy to
+share code among the <a class="reference internal" href="#tools">tools</a>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/</span></code></p>
+<blockquote>
+<div>Core LLVM source files that implement core classes like Instruction and
+BasicBlock.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/</span></code></p>
+<blockquote>
+<div>Source code for the LLVM assembly language parser library.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/</span></code></p>
+<blockquote>
+<div>Code for reading and writing bitcode.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Analysis/</span></code></p>
+<blockquote>
+<div>A variety of program analyses, such as Call Graphs, Induction Variables,
+Natural Loop Identification, etc.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Transforms/</span></code></p>
+<blockquote>
+<div>IR-to-IR program transformations, such as Aggressive Dead Code Elimination,
+Sparse Conditional Constant Propagation, Inlining, Loop Invariant Code Motion,
+Dead Global Elimination, and many others.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Target/</span></code></p>
+<blockquote>
+<div>Files describing target architectures for code generation. For example,
+<code class="docutils literal notranslate"><span class="pre">llvm/lib/Target/X86</span></code> holds the X86 machine description.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/CodeGen/</span></code></p>
+<blockquote>
+<div>The major parts of the code generator: Instruction Selector, Instruction
+Scheduling, and Register Allocation.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/MC/</span></code></p>
+<blockquote>
+<div>(FIXME: T.B.D.) â¦.?</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/ExecutionEngine/</span></code></p>
+<blockquote>
+<div>Libraries for directly executing bitcode at runtime in interpreted and
+JIT-compiled scenarios.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Support/</span></code></p>
+<blockquote>
+<div>Source code that corresponding to the header files in <code class="docutils literal notranslate"><span class="pre">llvm/include/ADT/</span></code>
+and <code class="docutils literal notranslate"><span class="pre">llvm/include/Support/</span></code>.</div></blockquote>
+</div>
+<div class="section" id="llvm-projects">
+<h3><a class="toc-backref" href="#id26"><code class="docutils literal notranslate"><span class="pre">llvm/projects</span></code></a><a class="headerlink" href="#llvm-projects" title="Permalink to this headline">¶</a></h3>
+<p>Projects not strictly part of LLVM but shipped with LLVM. This is also the
+directory for creating your own LLVM-based projects which leverage the LLVM
+build system.</p>
+</div>
+<div class="section" id="llvm-test">
+<h3><a class="toc-backref" href="#id27"><code class="docutils literal notranslate"><span class="pre">llvm/test</span></code></a><a class="headerlink" href="#llvm-test" title="Permalink to this headline">¶</a></h3>
+<p>Feature and regression tests and other sanity checks on LLVM infrastructure. These
+are intended to run quickly and cover a lot of territory without being exhaustive.</p>
+</div>
+<div class="section" id="test-suite">
+<h3><a class="toc-backref" href="#id28"><code class="docutils literal notranslate"><span class="pre">test-suite</span></code></a><a class="headerlink" href="#test-suite" title="Permalink to this headline">¶</a></h3>
+<p>A comprehensive correctness, performance, and benchmarking test suite
+for LLVM. This comes in a <code class="docutils literal notranslate"><span class="pre">separate</span> <span class="pre">git</span> <span class="pre">repository</span>
+<span class="pre"><https://github.com/llvm/llvm-test-suite></span></code>, because it contains a
+large amount of third-party code under a variety of licenses. For
+details see the <a class="reference internal" href="TestingGuide.html"><span class="doc">Testing Guide</span></a> document.</p>
+</div>
+<div class="section" id="llvm-tools">
+<span id="tools"></span><h3><a class="toc-backref" href="#id29"><code class="docutils literal notranslate"><span class="pre">llvm/tools</span></code></a><a class="headerlink" href="#llvm-tools" title="Permalink to this headline">¶</a></h3>
+<p>Executables built out of the libraries
+above, which form the main part of the user interface. You can always get help
+for a tool by typing <code class="docutils literal notranslate"><span class="pre">tool_name</span> <span class="pre">-help</span></code>. The following is a brief introduction
+to the most important tools. More detailed information is in
+the <a class="reference external" href="CommandGuide/index.html">Command Guide</a>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">bugpoint</span></code></p>
+<blockquote>
+<div><code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> is used to debug optimization passes or code generation backends
+by narrowing down the given test case to the minimum number of passes and/or
+instructions that still cause a problem, whether it is a crash or
+miscompilation. See <a class="reference external" href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information on using
+<code class="docutils literal notranslate"><span class="pre">bugpoint</span></code>.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm-ar</span></code></p>
+<blockquote>
+<div>The archiver produces an archive containing the given LLVM bitcode files,
+optionally with an index for faster lookup.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm-as</span></code></p>
+<blockquote>
+<div>The assembler transforms the human readable LLVM assembly to LLVM bitcode.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm-dis</span></code></p>
+<blockquote>
+<div>The disassembler transforms the LLVM bitcode to human readable LLVM assembly.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvm-link</span></code></p>
+<blockquote>
+<div><code class="docutils literal notranslate"><span class="pre">llvm-link</span></code>, not surprisingly, links multiple LLVM modules into a single
+program.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">lli</span></code></p>
+<blockquote>
+<div><code class="docutils literal notranslate"><span class="pre">lli</span></code> is the LLVM interpreter, which can directly execute LLVM bitcode
+(although very slowlyâ¦). For architectures that support it (currently x86,
+Sparc, and PowerPC), by default, <code class="docutils literal notranslate"><span class="pre">lli</span></code> will function as a Just-In-Time
+compiler (if the functionality was compiled in), and will execute the code
+<em>much</em> faster than the interpreter.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llc</span></code></p>
+<blockquote>
+<div><code class="docutils literal notranslate"><span class="pre">llc</span></code> is the LLVM backend compiler, which translates LLVM bitcode to a
+native code assembly file.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">opt</span></code></p>
+<blockquote>
+<div><p><code class="docutils literal notranslate"><span class="pre">opt</span></code> reads LLVM bitcode, applies a series of LLVM to LLVM transformations
+(which are specified on the command line), and outputs the resultant
+bitcode. â<code class="docutils literal notranslate"><span class="pre">opt</span> <span class="pre">-help</span></code>â is a good way to get a list of the
+program transformations available in LLVM.</p>
+<p><code class="docutils literal notranslate"><span class="pre">opt</span></code> can also run a specific analysis on an input LLVM bitcode
+file and print the results. Primarily useful for debugging
+analyses, or familiarizing yourself with what an analysis does.</p>
+</div></blockquote>
+</div>
+<div class="section" id="llvm-utils">
+<h3><a class="toc-backref" href="#id30"><code class="docutils literal notranslate"><span class="pre">llvm/utils</span></code></a><a class="headerlink" href="#llvm-utils" title="Permalink to this headline">¶</a></h3>
+<p>Utilities for working with LLVM source code; some are part of the build process
+because they are code generators for parts of the infrastructure.</p>
+<p><code class="docutils literal notranslate"><span class="pre">codegen-diff</span></code></p>
+<blockquote>
+<div><code class="docutils literal notranslate"><span class="pre">codegen-diff</span></code> finds differences between code that LLC
+generates and code that LLI generates. This is useful if you are
+debugging one of them, assuming that the other generates correct output. For
+the full user manual, run <code class="docutils literal notranslate"><span class="pre">`perldoc</span> <span class="pre">codegen-diff'</span></code>.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">emacs/</span></code></p>
+<blockquote>
+<div>Emacs and XEmacs syntax highlighting for LLVM assembly files and TableGen
+description files. See the <code class="docutils literal notranslate"><span class="pre">README</span></code> for information on using them.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">getsrcs.sh</span></code></p>
+<blockquote>
+<div>Finds and outputs all non-generated source files,
+useful if one wishes to do a lot of development across directories
+and does not want to find each file. One way to use it is to run,
+for example: <code class="docutils literal notranslate"><span class="pre">xemacs</span> <span class="pre">`utils/getsources.sh`</span></code> from the top of the LLVM source
+tree.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">llvmgrep</span></code></p>
+<blockquote>
+<div>Performs an <code class="docutils literal notranslate"><span class="pre">egrep</span> <span class="pre">-H</span> <span class="pre">-n</span></code> on each source file in LLVM and
+passes to it a regular expression provided on <code class="docutils literal notranslate"><span class="pre">llvmgrep</span></code>âs command
+line. This is an efficient way of searching the source base for a
+particular regular expression.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">TableGen/</span></code></p>
+<blockquote>
+<div>Contains the tool used to generate register
+descriptions, instruction set descriptions, and even assemblers from common
+TableGen description files.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">vim/</span></code></p>
+<blockquote>
+<div>vim syntax-highlighting for LLVM assembly files
+and TableGen description files. See the <code class="docutils literal notranslate"><span class="pre">README</span></code> for how to use them.</div></blockquote>
+</div>
+</div>
+<div class="section" id="an-example-using-the-llvm-tool-chain">
+<span id="simple-example"></span><h2><a class="toc-backref" href="#id31">An Example Using the LLVM Tool Chain</a><a class="headerlink" href="#an-example-using-the-llvm-tool-chain" title="Permalink to this headline">¶</a></h2>
+<p>This section gives an example of using LLVM with the Clang front end.</p>
+<div class="section" id="example-with-clang">
+<h3><a class="toc-backref" href="#id32">Example with clang</a><a class="headerlink" href="#example-with-clang" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first">First, create a simple C file, name it âhello.câ:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Next, compile the C file into a native executable:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> clang hello.c -o hello
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang works just like GCC by default. The standard -S and -c arguments
+work as usual (producing a native .s or .o file, respectively).</p>
+</div>
+</li>
+<li><p class="first">Next, compile the C file into an LLVM bitcode file:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> clang -O3 -emit-llvm hello.c -c -o hello.bc
+</pre></div>
+</div>
+<p>The -emit-llvm option can be used with the -S or -c options to emit an LLVM
+<code class="docutils literal notranslate"><span class="pre">.ll</span></code> or <code class="docutils literal notranslate"><span class="pre">.bc</span></code> file (respectively) for the code. This allows you to use
+the <a class="reference external" href="CommandGuide/index.html">standard LLVM tools</a> on the bitcode file.</p>
+</li>
+<li><p class="first">Run the program in both forms. To run the program, use:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> ./hello
+</pre></div>
+</div>
+<p>and</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> lli hello.bc
+</pre></div>
+</div>
+<p>The second examples shows how to invoke the LLVM JIT, <a class="reference internal" href="CommandGuide/lli.html"><span class="doc">lli</span></a>.</p>
+</li>
+<li><p class="first">Use the <code class="docutils literal notranslate"><span class="pre">llvm-dis</span></code> utility to take a look at the LLVM assembly code:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> llvm-dis < hello.bc <span class="p">|</span> less
+</pre></div>
+</div>
+</li>
+<li><p class="first">Compile the program to native assembly using the LLC code generator:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> llc hello.bc -o hello.s
+</pre></div>
+</div>
+</li>
+<li><p class="first">Assemble the native assembly language file into a program:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> /opt/SUNWspro/bin/cc -xarch<span class="o">=</span>v9 hello.s -o hello.native <span class="c1"># On Solaris</span>
+
+<span class="gp">%</span> gcc hello.s -o hello.native <span class="c1"># On others</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Execute the native code program:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> ./hello.native
+</pre></div>
+</div>
+<p>Note that using clang to compile directly to native code (i.e. when the
+<code class="docutils literal notranslate"><span class="pre">-emit-llvm</span></code> option is not present) does steps 6/7/8 for you.</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="section" id="common-problems">
+<h2><a class="toc-backref" href="#id33">Common Problems</a><a class="headerlink" href="#common-problems" title="Permalink to this headline">¶</a></h2>
+<p>If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the <a class="reference external" href="FAQ.html">Frequently Asked
+Questions</a> page.</p>
+</div>
+<div class="section" id="links">
+<span id="id2"></span><h2><a class="toc-backref" href="#id34">Links</a><a class="headerlink" href="#links" title="Permalink to this headline">¶</a></h2>
+<p>This document is just an <strong>introduction</strong> on how to use LLVM to do some simple
+things⦠there are many more interesting and complicated things that you can do
+that arenât documented here (but weâll gladly accept a patch if you want to
+write something up!). For more information about LLVM, check out:</p>
+<ul class="simple">
+<li><a class="reference external" href="http://llvm.org/">LLVM Homepage</a></li>
+<li><a class="reference external" href="http://llvm.org/doxygen/">LLVM Doxygen Tree</a></li>
+<li><a class="reference external" href="http://llvm.org/docs/Projects.html">Starting a Project that Uses LLVM</a></li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CommandGuide/llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/GettingStartedVS.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/GettingStartedVS.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/GettingStartedVS.html (added)
+++ www-releases/trunk/8.0.0/docs/GettingStartedVS.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,327 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Getting Started with the LLVM System using Microsoft Visual Studio — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Frequently Asked Questions (FAQ)" href="FAQ.html" />
+ <link rel="prev" title="Getting Started with the LLVM System" href="GettingStarted.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="FAQ.html" title="Frequently Asked Questions (FAQ)"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GettingStarted.html" title="Getting Started with the LLVM System"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="getting-started-with-the-llvm-system-using-microsoft-visual-studio">
+<h1>Getting Started with the LLVM System using Microsoft Visual Studio<a class="headerlink" href="#getting-started-with-the-llvm-system-using-microsoft-visual-studio" 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="id2">Overview</a></li>
+<li><a class="reference internal" href="#requirements" id="id3">Requirements</a><ul>
+<li><a class="reference internal" href="#hardware" id="id4">Hardware</a></li>
+<li><a class="reference internal" href="#software" id="id5">Software</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#getting-started" id="id6">Getting Started</a></li>
+<li><a class="reference internal" href="#an-example-using-the-llvm-tool-chain" id="id7">An Example Using the LLVM Tool Chain</a></li>
+<li><a class="reference internal" href="#common-problems" id="id8">Common Problems</a></li>
+<li><a class="reference internal" href="#links" id="id9">Links</a></li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id2">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to LLVM on Windows! This document only covers LLVM on Windows using
+Visual Studio, not mingw or cygwin. In order to get started, you first need to
+know some basic information.</p>
+<p>There are many different projects that compose LLVM. The first piece is the
+LLVM suite. This contains all of the tools, libraries, and header files needed
+to use LLVM. It contains an assembler, disassembler, bitcode analyzer and
+bitcode optimizer. It also contains basic regression tests that can be used to
+test the LLVM tools and the Clang front end.</p>
+<p>The second piece is the <a class="reference external" href="http://clang.llvm.org/">Clang</a> front end. This
+component compiles C, C++, Objective C, and Objective C++ code into LLVM
+bitcode. Clang typically uses LLVM libraries to optimize the bitcode and emit
+machine code. LLVM fully supports the COFF object file format, which is
+compatible with all other existing Windows toolchains.</p>
+<p>The last major part of LLVM, the execution Test Suite, does not run on Windows,
+and this document does not discuss it.</p>
+<p>Additional information about the LLVM directory structure and tool chain
+can be found on the main <a class="reference internal" href="GettingStarted.html"><span class="doc">Getting Started with the LLVM System</span></a> page.</p>
+</div>
+<div class="section" id="requirements">
+<h2><a class="toc-backref" href="#id3">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
+<p>Before you begin to use the LLVM system, review the requirements given
+below. This may save you some trouble by knowing ahead of time what hardware
+and software you will need.</p>
+<div class="section" id="hardware">
+<h3><a class="toc-backref" href="#id4">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h3>
+<p>Any system that can adequately run Visual Studio 2015 is fine. The LLVM
+source tree and object files, libraries and executables will consume
+approximately 3GB.</p>
+</div>
+<div class="section" id="software">
+<h3><a class="toc-backref" href="#id5">Software</a><a class="headerlink" href="#software" title="Permalink to this headline">¶</a></h3>
+<p>You will need Visual Studio 2015 or higher, with the latest Update installed.</p>
+<p>You will also need the <a class="reference external" href="http://www.cmake.org/">CMake</a> build system since it
+generates the project files you will use to build with.</p>
+<p>If you would like to run the LLVM tests you will need <a class="reference external" href="http://www.python.org/">Python</a>. Version 2.7 and newer are known to work. You will
+need <a class="reference external" href="http://gnuwin32.sourceforge.net/">GnuWin32</a> tools, too.</p>
+<p>Do not install the LLVM directory tree into a path containing spaces (e.g.
+<code class="docutils literal notranslate"><span class="pre">C:\Documents</span> <span class="pre">and</span> <span class="pre">Settings\...</span></code>) as the configure step will fail.</p>
+</div>
+</div>
+<div class="section" id="getting-started">
+<h2><a class="toc-backref" href="#id6">Getting Started</a><a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
+<p>Hereâs the short story for getting up and running quickly with LLVM:</p>
+<ol class="arabic">
+<li><p class="first">Read the documentation.</p>
+</li>
+<li><p class="first">Seriously, read the documentation.</p>
+</li>
+<li><p class="first">Remember that you were warned twice about reading the documentation.</p>
+</li>
+<li><p class="first">Get the Source Code</p>
+<ul>
+<li><p class="first">With the distributed files:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre"><where-you-want-llvm-to-live></span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">gunzip</span> <span class="pre">--stdout</span> <span class="pre">llvm-VERSION.tar.gz</span> <span class="pre">|</span> <span class="pre">tar</span> <span class="pre">-xvf</span> <span class="pre">-</span></code>
+(<em>or use WinZip</em>)</li>
+<li><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">llvm</span></code></li>
+</ol>
+</div></blockquote>
+</li>
+<li><p class="first">With anonymous Subversion access:</p>
+<p><em>Note:</em> some regression tests require Unix-style line ending (<code class="docutils literal notranslate"><span class="pre">\n</span></code>). To
+pass all regression tests, please add two lines <em>enable-auto-props = yes</em>
+and <em>* = svn:mime-type=application/octet-stream</em> to
+<code class="docutils literal notranslate"><span class="pre">C:\Users\<username>\AppData\Roaming\Subversion\config</span></code>.</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre"><where-you-want-llvm-to-live></span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/llvm/trunk</span> <span class="pre">llvm</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">llvm</span></code></li>
+</ol>
+</div></blockquote>
+</li>
+</ul>
+</li>
+<li><p class="first">Use <a class="reference external" href="http://www.cmake.org/">CMake</a> to generate up-to-date project files:</p>
+<ul class="simple">
+<li>Once CMake is installed then the simplest way is to just start the
+CMake GUI, select the directory where you have LLVM extracted to, and
+the default options should all be fine. One option you may really
+want to change, regardless of anything else, might be the
+<code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code> setting to select a directory to INSTALL to
+once compiling is complete, although installation is not mandatory for
+using LLVM. Another important option is <code class="docutils literal notranslate"><span class="pre">LLVM_TARGETS_TO_BUILD</span></code>,
+which controls the LLVM target architectures that are included on the
+build.</li>
+<li>If CMake complains that it cannot find the compiler, make sure that
+you have the Visual Studio C++ Tools installed, not just Visual Studio
+itself (trying to create a C++ project in Visual Studio will generally
+download the C++ tools if they havenât already been).</li>
+<li>See the <a class="reference internal" href="CMake.html"><span class="doc">LLVM CMake guide</span></a> for detailed information about
+how to configure the LLVM build.</li>
+<li>CMake generates project files for all build types. To select a specific
+build type, use the Configuration manager from the VS IDE or the
+<code class="docutils literal notranslate"><span class="pre">/property:Configuration</span></code> command line option when using MSBuild.</li>
+<li>By default, the Visual Studio project files generated by CMake use the
+32-bit toolset. If you are developing on a 64-bit version of Windows and
+want to use the 64-bit toolset, pass the <code class="docutils literal notranslate"><span class="pre">-Thost=x64</span></code> flag when
+generating the Visual Studio solution. This requires CMake 3.8.0 or later.</li>
+</ul>
+</li>
+<li><p class="first">Start Visual Studio</p>
+<ul class="simple">
+<li>In the directory you created the project files will have an <code class="docutils literal notranslate"><span class="pre">llvm.sln</span></code>
+file, just double-click on that to open Visual Studio.</li>
+</ul>
+</li>
+<li><p class="first">Build the LLVM Suite:</p>
+<ul class="simple">
+<li>The projects may still be built individually, but to build them all do
+not just select all of them in batch build (as some are meant as
+configuration projects), but rather select and build just the
+<code class="docutils literal notranslate"><span class="pre">ALL_BUILD</span></code> project to build everything, or the <code class="docutils literal notranslate"><span class="pre">INSTALL</span></code> project,
+which first builds the <code class="docutils literal notranslate"><span class="pre">ALL_BUILD</span></code> project, then installs the LLVM
+headers, libs, and other useful things to the directory set by the
+<code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code> setting when you first configured CMake.</li>
+<li>The Fibonacci project is a sample program that uses the JIT. Modify the
+projectâs debugging properties to provide a numeric command line argument
+or run it from the command line. The program will print the
+corresponding fibonacci value.</li>
+</ul>
+</li>
+<li><p class="first">Test LLVM in Visual Studio:</p>
+<ul class="simple">
+<li>If <code class="docutils literal notranslate"><span class="pre">%PATH%</span></code> does not contain GnuWin32, you may specify
+<code class="docutils literal notranslate"><span class="pre">LLVM_LIT_TOOLS_DIR</span></code> on CMake for the path to GnuWin32.</li>
+<li>You can run LLVM tests by merely building the project âcheckâ. The test
+results will be shown in the VS output window.</li>
+</ul>
+</li>
+<li><p class="first">Test LLVM on the command line:</p>
+<ul>
+<li><p class="first">The LLVM tests can be run by changing directory to the llvm source
+directory and running:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..\llvm</span><span class="c1">> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test</span>
+</pre></div>
+</div>
+<p>This example assumes that Python is in your PATH variable, you
+have built a Win32 Debug version of llvm with a standard out of
+line build. You should not see any unexpected failures, but will
+see many unsupported tests and expected failures.</p>
+<p>A specific test or test directory can be run with:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..\llvm</span><span class="c1">> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test/path/to/test</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</li>
+</ol>
+</div>
+<div class="section" id="an-example-using-the-llvm-tool-chain">
+<h2><a class="toc-backref" href="#id7">An Example Using the LLVM Tool Chain</a><a class="headerlink" href="#an-example-using-the-llvm-tool-chain" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic">
+<li><p class="first">First, create a simple C file, name it â<code class="docutils literal notranslate"><span class="pre">hello.c</span></code>â:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Next, compile the C file into an LLVM bitcode file:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..</span><span class="c1">> clang -c hello.c -emit-llvm -o hello.bc</span>
+</pre></div>
+</div>
+<p>This will create the result file <code class="docutils literal notranslate"><span class="pre">hello.bc</span></code> which is the LLVM bitcode
+that corresponds the compiled program and the library facilities that
+it required. You can execute this file directly using <code class="docutils literal notranslate"><span class="pre">lli</span></code> tool,
+compile it to native assembly with the <code class="docutils literal notranslate"><span class="pre">llc</span></code>, optimize or analyze it
+further with the <code class="docutils literal notranslate"><span class="pre">opt</span></code> tool, etc.</p>
+<p>Alternatively you can directly output an executable with clang with:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..</span><span class="c1">> clang hello.c -o hello.exe</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">hello.exe</span></code> is required because clang currently outputs <code class="docutils literal notranslate"><span class="pre">a.out</span></code>
+when neither <code class="docutils literal notranslate"><span class="pre">-o</span></code> nor <code class="docutils literal notranslate"><span class="pre">-c</span></code> are given.</p>
+</li>
+<li><p class="first">Run the program using the just-in-time compiler:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..</span><span class="c1">> lli hello.bc</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Use the <code class="docutils literal notranslate"><span class="pre">llvm-dis</span></code> utility to take a look at the LLVM assembly code:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..</span><span class="c1">> llvm-dis < hello.bc | more</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Compile the program to object code using the LLC code generator:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..</span><span class="c1">> llc -filetype=obj hello.bc</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Link to binary using Microsoft link:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..</span><span class="c1">> link hello.obj -defaultlib:libcmt</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Execute the native code program:</p>
+<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>C<span class="p">:</span><span class="nl">\..</span><span class="c1">> hello.exe</span>
+</pre></div>
+</div>
+</li>
+</ol>
+</div>
+<div class="section" id="common-problems">
+<h2><a class="toc-backref" href="#id8">Common Problems</a><a class="headerlink" href="#common-problems" title="Permalink to this headline">¶</a></h2>
+<p>If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the <a class="reference internal" href="FAQ.html"><span class="doc">Frequently Asked Questions</span></a> page.</p>
+</div>
+<div class="section" id="links">
+<h2><a class="toc-backref" href="#id9">Links</a><a class="headerlink" href="#links" title="Permalink to this headline">¶</a></h2>
+<p>This document is just an <strong>introduction</strong> to how to use LLVM to do some simple
+things⦠there are many more interesting and complicated things that you can
+do that arenât documented here (but weâll gladly accept a patch if you want to
+write something up!). For more information about LLVM, check out:</p>
+<ul class="simple">
+<li><a class="reference external" href="http://llvm.org/">LLVM homepage</a></li>
+<li><a class="reference external" href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="FAQ.html" title="Frequently Asked Questions (FAQ)"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GettingStarted.html" title="Getting Started with the LLVM System"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/GlobalISel.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/GlobalISel.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/GlobalISel.html (added)
+++ www-releases/trunk/8.0.0/docs/GlobalISel.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,726 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Global Instruction Selection — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="XRay Instrumentation" href="XRay.html" />
+ <link rel="prev" title="Coroutines in LLVM" href="Coroutines.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="XRay.html" title="XRay Instrumentation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Coroutines.html" title="Coroutines in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="global-instruction-selection">
+<h1>Global Instruction Selection<a class="headerlink" href="#global-instruction-selection" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id12">Introduction</a></li>
+<li><a class="reference internal" href="#generic-machine-ir" id="id13">Generic Machine IR</a></li>
+<li><a class="reference internal" href="#core-pipeline" id="id14">Core Pipeline</a></li>
+<li><a class="reference internal" href="#maintainability" id="id15">Maintainability</a></li>
+<li><a class="reference internal" href="#progress-and-future-work" id="id16">Progress and Future Work</a></li>
+<li><a class="reference internal" href="#porting-globalisel-to-a-new-target" id="id17">Porting GlobalISel to A New Target</a></li>
+<li><a class="reference internal" href="#resources" id="id18">Resources</a></li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is a work in progress. It reflects the current state of the
+implementation, as well as open design and implementation issues.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id12">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>GlobalISel is a framework that provides a set of reusable passes and utilities
+for instruction selection â translation from LLVM IR to target-specific
+Machine IR (MIR).</p>
+<p>GlobalISel is intended to be a replacement for SelectionDAG and FastISel, to
+solve three major problems:</p>
+<ul>
+<li><p class="first"><strong>Performance</strong> â SelectionDAG introduces a dedicated intermediate
+representation, which has a compile-time cost.</p>
+<p>GlobalISel directly operates on the post-isel representation used by the
+rest of the code generator, MIR.
+It does require extensions to that representation to support arbitrary
+incoming IR: <a class="reference internal" href="#gmir"><span class="std std-ref">Generic Machine IR</span></a>.</p>
+</li>
+<li><p class="first"><strong>Granularity</strong> â SelectionDAG and FastISel operate on individual basic
+blocks, losing some global optimization opportunities.</p>
+<p>GlobalISel operates on the whole function.</p>
+</li>
+<li><p class="first"><strong>Modularity</strong> â SelectionDAG and FastISel are radically different and share
+very little code.</p>
+<p>GlobalISel is built in a way that enables code reuse. For instance, both the
+optimized and fast selectors share the <a class="reference internal" href="#pipeline"><span class="std std-ref">Core Pipeline</span></a>, and targets can
+configure that pipeline to better suit their needs.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="generic-machine-ir">
+<span id="gmir"></span><h2><a class="toc-backref" href="#id13">Generic Machine IR</a><a class="headerlink" href="#generic-machine-ir" title="Permalink to this headline">¶</a></h2>
+<p>Machine IR operates on physical registers, register classes, and (mostly)
+target-specific instructions.</p>
+<p>To bridge the gap with LLVM IR, GlobalISel introduces âgenericâ extensions to
+Machine IR:</p>
+<div class="contents local topic" id="id1">
+<ul class="simple">
+<li><a class="reference internal" href="#generic-instructions" id="id19">Generic Instructions</a></li>
+<li><a class="reference internal" href="#generic-virtual-registers" id="id20">Generic Virtual Registers</a></li>
+<li><a class="reference internal" href="#register-bank" id="id21">Register Bank</a></li>
+<li><a class="reference internal" href="#low-level-type" id="id22">Low Level Type</a></li>
+</ul>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>:
+The generic MIR (GMIR) representation still contains references to IR
+constructs (such as <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code>). Removing those should let us write more
+accurate tests, or delete IR after building the initial MIR. However, it is
+not part of the GlobalISel effort.</p>
+<div class="section" id="generic-instructions">
+<span id="gmir-instructions"></span><h3><a class="toc-backref" href="#id19">Generic Instructions</a><a class="headerlink" href="#generic-instructions" title="Permalink to this headline">¶</a></h3>
+<p>The main addition is support for pre-isel generic machine instructions (e.g.,
+<code class="docutils literal notranslate"><span class="pre">G_ADD</span></code>). Like other target-independent instructions (e.g., <code class="docutils literal notranslate"><span class="pre">COPY</span></code> or
+<code class="docutils literal notranslate"><span class="pre">PHI</span></code>), these are available on all targets.</p>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+While weâre progressively adding instructions, one kind in particular exposes
+interesting problems: compares and how to represent condition codes.
+Some targets (x86, ARM) have generic comparisons setting multiple flags,
+which are then used by predicated variants.
+Others (IR) specify the predicate in the comparison and users just get a single
+bit. SelectionDAG uses SETCC/CONDBR vs BR_CC (and similar for select) to
+represent this.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">MachineIRBuilder</span></code> class wraps the <code class="docutils literal notranslate"><span class="pre">MachineInstrBuilder</span></code> and provides
+a convenient way to create these generic instructions.</p>
+</div>
+<div class="section" id="generic-virtual-registers">
+<span id="gmir-gvregs"></span><h3><a class="toc-backref" href="#id20">Generic Virtual Registers</a><a class="headerlink" href="#generic-virtual-registers" title="Permalink to this headline">¶</a></h3>
+<p>Generic instructions operate on a new kind of register: âgenericâ virtual
+registers. As opposed to non-generic vregs, they are not assigned a Register
+Class. Instead, generic vregs have a <a class="reference internal" href="#gmir-llt"><span class="std std-ref">Low Level Type</span></a>, and can be assigned
+a <a class="reference internal" href="#gmir-regbank"><span class="std std-ref">Register Bank</span></a>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">MachineRegisterInfo</span></code> tracks the same information that it does for
+non-generic vregs (e.g., use-def chains). Additionally, it also tracks the
+<a class="reference internal" href="#gmir-llt"><span class="std std-ref">Low Level Type</span></a> of the register, and, instead of the <code class="docutils literal notranslate"><span class="pre">TargetRegisterClass</span></code>,
+its <a class="reference internal" href="#gmir-regbank"><span class="std std-ref">Register Bank</span></a>, if any.</p>
+<p>For simplicity, most generic instructions only accept generic vregs:</p>
+<ul class="simple">
+<li>instead of immediates, they use a gvreg defined by an instruction
+materializing the immediate value (see <a class="reference internal" href="#irtranslator-constants"><span class="std std-ref">Constant Lowering</span></a>).</li>
+<li>instead of physical register, they use a gvreg defined by a <code class="docutils literal notranslate"><span class="pre">COPY</span></code>.</li>
+</ul>
+<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>:
+We started with an alternative representation, where MRI tracks a size for
+each gvreg, and instructions have lists of types.
+That had two flaws: the type and size are redundant, and there was no generic
+way of getting a given operandâs type (as there was no 1:1 mapping between
+instruction types and operands).
+We considered putting the type in some variant of MCInstrDesc instead:
+See <a class="reference external" href="http://llvm.org/PR26576">PR26576</a>: [GlobalISel] Generic MachineInstrs
+need a type but this increases the memory footprint of the related objects</p>
+</div>
+<div class="section" id="register-bank">
+<span id="gmir-regbank"></span><h3><a class="toc-backref" href="#id21">Register Bank</a><a class="headerlink" href="#register-bank" title="Permalink to this headline">¶</a></h3>
+<p>A Register Bank is a set of register classes defined by the target.
+A bank has a size, which is the maximum store size of all covered classes.</p>
+<p>In general, cross-class copies inside a bank are expected to be cheaper than
+copies across banks. They are also coalesceable by the register coalescer,
+whereas cross-bank copies are not.</p>
+<p>Also, equivalent operations can be performed on different banks using different
+instructions.</p>
+<p>For example, X86 can be seen as having 3 main banks: general-purpose, x87, and
+vector (which could be further split into a bank per domain for single vs
+double precision instructions).</p>
+<p>Register banks are described by a target-provided API,
+<a class="reference internal" href="#api-registerbankinfo"><span class="std std-ref">RegisterBankInfo</span></a>.</p>
+</div>
+<div class="section" id="low-level-type">
+<span id="gmir-llt"></span><h3><a class="toc-backref" href="#id22">Low Level Type</a><a class="headerlink" href="#low-level-type" title="Permalink to this headline">¶</a></h3>
+<p>Additionally, every generic virtual register has a type, represented by an
+instance of the <code class="docutils literal notranslate"><span class="pre">LLT</span></code> class.</p>
+<p>Like <code class="docutils literal notranslate"><span class="pre">EVT</span></code>/<code class="docutils literal notranslate"><span class="pre">MVT</span></code>/<code class="docutils literal notranslate"><span class="pre">Type</span></code>, it has no distinction between unsigned and signed
+integer types. Furthermore, it also has no distinction between integer and
+floating-point types: it mainly conveys absolutely necessary information, such
+as size and number of vector lanes:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">sN</span></code> for scalars</li>
+<li><code class="docutils literal notranslate"><span class="pre">pN</span></code> for pointers</li>
+<li><code class="docutils literal notranslate"><span class="pre"><N</span> <span class="pre">x</span> <span class="pre">sM></span></code> for vectors</li>
+<li><code class="docutils literal notranslate"><span class="pre">unsized</span></code> for labels, etc..</li>
+</ul>
+<p><code class="docutils literal notranslate"><span class="pre">LLT</span></code> is intended to replace the usage of <code class="docutils literal notranslate"><span class="pre">EVT</span></code> in SelectionDAG.</p>
+<p>Here are some LLT examples and their <code class="docutils literal notranslate"><span class="pre">EVT</span></code> and <code class="docutils literal notranslate"><span class="pre">Type</span></code> equivalents:</p>
+<blockquote>
+<div><table border="1" class="docutils">
+<colgroup>
+<col width="22%" />
+<col width="15%" />
+<col width="63%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">LLT</th>
+<th class="head">EVT</th>
+<th class="head">IR Type</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">s1</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i1</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i1</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">s8</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i8</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i8</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">s32</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i32</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i32</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">s32</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">f32</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">float</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">s17</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i17</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i17</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">s16</span></code></td>
+<td>N/A</td>
+<td><code class="docutils literal notranslate"><span class="pre">{i8,</span> <span class="pre">i8}</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">s32</span></code></td>
+<td>N/A</td>
+<td><code class="docutils literal notranslate"><span class="pre">[4</span> <span class="pre">x</span> <span class="pre">i8]</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">p0</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">iPTR</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i8*</span></code>, <code class="docutils literal notranslate"><span class="pre">i32*</span></code>, <code class="docutils literal notranslate"><span class="pre">%opaque*</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">p2</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">iPTR</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">i8</span> <span class="pre">addrspace(2)*</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre"><4</span> <span class="pre">x</span> <span class="pre">s32></span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">v4f32</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre"><4</span> <span class="pre">x</span> <span class="pre">float></span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">s64</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">v1f64</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre"><1</span> <span class="pre">x</span> <span class="pre">double></span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre"><3</span> <span class="pre">x</span> <span class="pre">s32></span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">v3i32</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre"><3</span> <span class="pre">x</span> <span class="pre">i32></span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">unsized</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">Other</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">label</span></code></td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+<p>Rationale: instructions already encode a specific interpretation of types
+(e.g., <code class="docutils literal notranslate"><span class="pre">add</span></code> vs. <code class="docutils literal notranslate"><span class="pre">fadd</span></code>, or <code class="docutils literal notranslate"><span class="pre">sdiv</span></code> vs. <code class="docutils literal notranslate"><span class="pre">udiv</span></code>). Also encoding that
+information in the type system requires introducing bitcast with no real
+advantage for the selector.</p>
+<p>Pointer types are distinguished by address space. This matches IR, as opposed
+to SelectionDAG where address space is an attribute on operations.
+This representation better supports pointers having different sizes depending
+on their addressspace.</p>
+<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>:
+Currently, LLT requires at least 2 elements in vectors, but some targets have
+the concept of a â1-element vectorâ. Representing them as their underlying
+scalar type is a nice simplification.</p>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+Currently, non-generic virtual registers, defined by non-pre-isel-generic
+instructions, cannot have a type, and thus cannot be used by a pre-isel generic
+instruction. Instead, they are given a type using a COPY. We could relax that
+and allow types on all vregs: this would reduce the number of MI required when
+emitting target-specific MIR early in the pipeline. This should purely be
+a compile-time optimization.</p>
+</div>
+</div>
+<div class="section" id="core-pipeline">
+<span id="pipeline"></span><h2><a class="toc-backref" href="#id14">Core Pipeline</a><a class="headerlink" href="#core-pipeline" title="Permalink to this headline">¶</a></h2>
+<p>There are four required passes, regardless of the optimization mode:</p>
+<div class="contents local topic" id="id2">
+<ul class="simple">
+<li><a class="reference internal" href="#irtranslator" id="id23">IRTranslator</a><ul>
+<li><a class="reference internal" href="#api-calllowering" id="id24">API: CallLowering</a></li>
+<li><a class="reference internal" href="#aggregates" id="id25">Aggregates</a></li>
+<li><a class="reference internal" href="#constant-lowering" id="id26">Constant Lowering</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#legalizer" id="id27">Legalizer</a><ul>
+<li><a class="reference internal" href="#api-legalizerinfo" id="id28">API: LegalizerInfo</a></li>
+<li><a class="reference internal" href="#non-power-of-2-types" id="id29">Non-power of 2 types</a></li>
+<li><a class="reference internal" href="#vector-types" id="id30">Vector types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#regbankselect" id="id31">RegBankSelect</a><ul>
+<li><a class="reference internal" href="#api-registerbankinfo" id="id32">API: RegisterBankInfo</a></li>
+<li><a class="reference internal" href="#regbankselect-modes" id="id33">RegBankSelect Modes</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instructionselect" id="id34">InstructionSelect</a><ul>
+<li><a class="reference internal" href="#api-instructionselector" id="id35">API: InstructionSelector</a></li>
+<li><a class="reference internal" href="#selectiondag-rule-imports" id="id36">SelectionDAG Rule Imports</a></li>
+<li><a class="reference internal" href="#patleaf-predicates" id="id37">PatLeaf Predicates</a></li>
+<li><a class="reference internal" href="#custom-sdnodes" id="id38">Custom SDNodes</a></li>
+<li><a class="reference internal" href="#complexpatterns" id="id39">ComplexPatterns</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<p>Additional passes can then be inserted at higher optimization levels or for
+specific targets. For example, to match the current SelectionDAG set of
+transformations: MachineCSE and a better MachineCombiner between every pass.</p>
+<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>:
+In theory, not all passes are always necessary.
+As an additional compile-time optimization, we could skip some of the passes by
+setting the relevant MachineFunction properties. For instance, if the
+IRTranslator did not encounter any illegal instruction, it would set the
+<code class="docutils literal notranslate"><span class="pre">legalized</span></code> property to avoid running the <a class="reference internal" href="#milegalizer"><span class="std std-ref">Legalizer</span></a>.
+Similarly, we considered specializing the IRTranslator per-target to directly
+emit target-specific MI.
+However, we instead decided to keep the core pipeline simple, and focus on
+minimizing the overhead of the passes in the no-op cases.</p>
+<div class="section" id="irtranslator">
+<span id="id3"></span><h3><a class="toc-backref" href="#id23">IRTranslator</a><a class="headerlink" href="#irtranslator" title="Permalink to this headline">¶</a></h3>
+<p>This pass translates the input LLVM IR <code class="docutils literal notranslate"><span class="pre">Function</span></code> to a GMIR
+<code class="docutils literal notranslate"><span class="pre">MachineFunction</span></code>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+This currently doesnât support the more complex instructions, in particular
+those involving control flow (<code class="docutils literal notranslate"><span class="pre">switch</span></code>, <code class="docutils literal notranslate"><span class="pre">invoke</span></code>, â¦).
+For <code class="docutils literal notranslate"><span class="pre">switch</span></code> in particular, we can initially use the <code class="docutils literal notranslate"><span class="pre">LowerSwitch</span></code> pass.</p>
+<div class="section" id="api-calllowering">
+<span id="id4"></span><h4><a class="toc-backref" href="#id24">API: CallLowering</a><a class="headerlink" href="#api-calllowering" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">IRTranslator</span></code> (using the <code class="docutils literal notranslate"><span class="pre">CallLowering</span></code> target-provided utility) also
+implements the ABIâs calling convention by lowering calls, returns, and
+arguments to the appropriate physical register usage and instruction sequences.</p>
+</div>
+<div class="section" id="aggregates">
+<span id="irtranslator-aggregates"></span><h4><a class="toc-backref" href="#id25">Aggregates</a><a class="headerlink" href="#aggregates" title="Permalink to this headline">¶</a></h4>
+<p>Aggregates are lowered to a single scalar vreg.
+This differs from SelectionDAGâs multiple vregs via <code class="docutils literal notranslate"><span class="pre">GetValueVTs</span></code>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+As some of the bits are undef (padding), we should consider augmenting the
+representation with additional metadata (in effect, caching computeKnownBits
+information on vregs).
+See <a class="reference external" href="http://llvm.org/PR26161">PR26161</a>: [GlobalISel] Value to vreg during
+IR to MachineInstr translation for aggregate type</p>
+</div>
+<div class="section" id="constant-lowering">
+<span id="irtranslator-constants"></span><h4><a class="toc-backref" href="#id26">Constant Lowering</a><a class="headerlink" href="#constant-lowering" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">IRTranslator</span></code> lowers <code class="docutils literal notranslate"><span class="pre">Constant</span></code> operands into uses of gvregs defined
+by <code class="docutils literal notranslate"><span class="pre">G_CONSTANT</span></code> or <code class="docutils literal notranslate"><span class="pre">G_FCONSTANT</span></code> instructions.
+Currently, these instructions are always emitted in the entry basic block.
+In a <code class="docutils literal notranslate"><span class="pre">MachineFunction</span></code>, each <code class="docutils literal notranslate"><span class="pre">Constant</span></code> is materialized by a single gvreg.</p>
+<p>This is beneficial as it allows us to fold constants into immediate operands
+during <a class="reference internal" href="#instructionselect"><span class="std std-ref">InstructionSelect</span></a>, while still avoiding redundant materializations
+for expensive non-foldable constants.
+However, this can lead to unnecessary spills and reloads in an -O0 pipeline, as
+these vregs can have long live ranges.</p>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+Weâre investigating better placement of these instructions, in fast and
+optimized modes.</p>
+</div>
+</div>
+<div class="section" id="legalizer">
+<span id="milegalizer"></span><h3><a class="toc-backref" href="#id27">Legalizer</a><a class="headerlink" href="#legalizer" title="Permalink to this headline">¶</a></h3>
+<p>This pass transforms the generic machine instructions such that they are legal.</p>
+<p>A legal instruction is defined as:</p>
+<ul class="simple">
+<li><strong>selectable</strong> â the target will later be able to select it to a
+target-specific (non-generic) instruction.</li>
+<li>operating on <strong>vregs that can be loaded and stored</strong> â if necessary, the
+target can select a <code class="docutils literal notranslate"><span class="pre">G_LOAD</span></code>/<code class="docutils literal notranslate"><span class="pre">G_STORE</span></code> of each gvreg operand.</li>
+</ul>
+<p>As opposed to SelectionDAG, there are no legalization phases. In particular,
+âtypeâ and âoperationâ legalization are not separate.</p>
+<p>Legalization is iterative, and all state is contained in GMIR. To maintain the
+validity of the intermediate code, instructions are introduced:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">G_MERGE_VALUES</span></code> â concatenate multiple registers of the same
+size into a single wider register.</li>
+<li><code class="docutils literal notranslate"><span class="pre">G_UNMERGE_VALUES</span></code> â extract multiple registers of the same size
+from a single wider register.</li>
+<li><code class="docutils literal notranslate"><span class="pre">G_EXTRACT</span></code> â extract a simple register (as contiguous sequences of bits)
+from a single wider register.</li>
+</ul>
+<p>As they are expected to be temporary byproducts of the legalization process,
+they are combined at the end of the <a class="reference internal" href="#milegalizer"><span class="std std-ref">Legalizer</span></a> pass.
+If any remain, they are expected to always be selectable, using loads and stores
+if necessary.</p>
+<div class="section" id="api-legalizerinfo">
+<span id="id5"></span><h4><a class="toc-backref" href="#id28">API: LegalizerInfo</a><a class="headerlink" href="#api-legalizerinfo" title="Permalink to this headline">¶</a></h4>
+<p>Currently the API is broadly similar to SelectionDAG/TargetLowering, but
+extended in two ways:</p>
+<ul class="simple">
+<li>The set of available actions is wider, avoiding the currently very
+overloaded <code class="docutils literal notranslate"><span class="pre">Expand</span></code> (which can cover everything from libcalls to
+scalarization depending on the nodeâs opcode).</li>
+<li>Since thereâs no separate type legalization, independently varying
+types on an instruction can have independent actions. For example a
+<code class="docutils literal notranslate"><span class="pre">G_ICMP</span></code> has 2 independent types: the result and the inputs; we need
+to be able to say that comparing 2 s32s is OK, but the s1 result
+must be dealt with in another way.</li>
+</ul>
+<p>As such, the primary key when deciding what to do is the <code class="docutils literal notranslate"><span class="pre">InstrAspect</span></code>,
+essentially a tuple consisting of <code class="docutils literal notranslate"><span class="pre">(Opcode,</span> <span class="pre">TypeIdx,</span> <span class="pre">Type)</span></code> and mapping to a
+suggested course of action.</p>
+<p>An example use might be:</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// The CPU can't deal with an s1 result, do something about it.</span>
+<span class="n">setAction</span><span class="p">({</span><span class="n">G_ICMP</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">s1</span><span class="p">},</span> <span class="n">WidenScalar</span><span class="p">);</span>
+<span class="c1">// An s32 input (the second type) is fine though.</span>
+<span class="n">setAction</span><span class="p">({</span><span class="n">G_ICMP</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">s32</span><span class="p">},</span> <span class="n">Legal</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+An alternative worth investigating is to generalize the API to represent
+actions using <code class="docutils literal notranslate"><span class="pre">std::function</span></code> that implements the action, instead of explicit
+enum tokens (<code class="docutils literal notranslate"><span class="pre">Legal</span></code>, <code class="docutils literal notranslate"><span class="pre">WidenScalar</span></code>, â¦).</p>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+Moreover, we could use TableGen to initially infer legality of operation from
+existing patterns (as any pattern we can select is by definition legal).
+Expanding that to describe legalization actions is a much larger but
+potentially useful project.</p>
+</div>
+<div class="section" id="non-power-of-2-types">
+<span id="milegalizer-non-power-of-2"></span><h4><a class="toc-backref" href="#id29">Non-power of 2 types</a><a class="headerlink" href="#non-power-of-2-types" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+Types which have a size that isnât a power of 2 arenât currently supported.
+The setAction API will probably require changes to support them.
+Even notionally explicitly specified operations only make suggestions
+like âWidenâ or âNarrowâ. The eventual type is still unspecified and a
+search is performed by repeated doubling/halving of the typeâs
+size.
+This is incorrect for types that arenât a power of 2. Itâs reasonable to
+expect we could construct an efficient set of side-tables for more general
+lookups though, encoding a map from the integers (i.e. the size of the current
+type) to types (the legal size).</p>
+</div>
+<div class="section" id="vector-types">
+<span id="milegalizer-vector"></span><h4><a class="toc-backref" href="#id30">Vector types</a><a class="headerlink" href="#vector-types" title="Permalink to this headline">¶</a></h4>
+<p>Vectors first get their element type legalized: <code class="docutils literal notranslate"><span class="pre"><A</span> <span class="pre">x</span> <span class="pre">sB></span></code> becomes
+<code class="docutils literal notranslate"><span class="pre"><A</span> <span class="pre">x</span> <span class="pre">sC></span></code> such that at least one operation is legal with <code class="docutils literal notranslate"><span class="pre">sC</span></code>.</p>
+<p>This is currently specified by the function <code class="docutils literal notranslate"><span class="pre">setScalarInVectorAction</span></code>, called
+for example as:</p>
+<blockquote>
+<div>setScalarInVectorAction(G_ICMP, s1, WidenScalar);</div></blockquote>
+<p>Next the number of elements is chosen so that the entire operation is
+legal. This aspect is not controllable at the moment, but probably
+should be (you could imagine disagreements on whether a <code class="docutils literal notranslate"><span class="pre"><2</span> <span class="pre">x</span> <span class="pre">s8></span></code>
+operation should be scalarized or extended to <code class="docutils literal notranslate"><span class="pre"><8</span> <span class="pre">x</span> <span class="pre">s8></span></code>).</p>
+</div>
+</div>
+<div class="section" id="regbankselect">
+<span id="id6"></span><h3><a class="toc-backref" href="#id31">RegBankSelect</a><a class="headerlink" href="#regbankselect" title="Permalink to this headline">¶</a></h3>
+<p>This pass constrains the <a class="reference internal" href="#gmir-gvregs"><span class="std std-ref">Generic Virtual Registers</span></a> operands of generic
+instructions to some <a class="reference internal" href="#gmir-regbank"><span class="std std-ref">Register Bank</span></a>.</p>
+<p>It iteratively maps instructions to a set of per-operand bank assignment.
+The possible mappings are determined by the target-provided
+<a class="reference internal" href="#api-registerbankinfo"><span class="std std-ref">RegisterBankInfo</span></a>.
+The mapping is then applied, possibly introducing <code class="docutils literal notranslate"><span class="pre">COPY</span></code> instructions if
+necessary.</p>
+<p>It traverses the <code class="docutils literal notranslate"><span class="pre">MachineFunction</span></code> top down so that all operands are already
+mapped when analyzing an instruction.</p>
+<p>This pass could also remap target-specific instructions when beneficial.
+In the future, this could replace the ExeDepsFix pass, as we can directly
+select the best variant for an instruction thatâs available on multiple banks.</p>
+<div class="section" id="api-registerbankinfo">
+<span id="id7"></span><h4><a class="toc-backref" href="#id32">API: RegisterBankInfo</a><a class="headerlink" href="#api-registerbankinfo" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">RegisterBankInfo</span></code> class describes multiple aspects of register banks.</p>
+<ul class="simple">
+<li><strong>Banks</strong>: <code class="docutils literal notranslate"><span class="pre">addRegBankCoverage</span></code> â which register bank covers each
+register class.</li>
+<li><strong>Cross-Bank Copies</strong>: <code class="docutils literal notranslate"><span class="pre">copyCost</span></code> â the cost of a <code class="docutils literal notranslate"><span class="pre">COPY</span></code> from one bank
+to another.</li>
+<li><strong>Default Mapping</strong>: <code class="docutils literal notranslate"><span class="pre">getInstrMapping</span></code> â the default bank assignments for
+a given instruction.</li>
+<li><strong>Alternative Mapping</strong>: <code class="docutils literal notranslate"><span class="pre">getInstrAlternativeMapping</span></code> â the other
+possible bank assignments for a given instruction.</li>
+</ul>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+All this information should eventually be static and generated by TableGen,
+mostly using existing information augmented by bank descriptions.</p>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+<code class="docutils literal notranslate"><span class="pre">getInstrMapping</span></code> is currently separate from <code class="docutils literal notranslate"><span class="pre">getInstrAlternativeMapping</span></code>
+because the latter is more expensive: as we move to static mapping info,
+both methods should be free, and we should merge them.</p>
+</div>
+<div class="section" id="regbankselect-modes">
+<span id="id8"></span><h4><a class="toc-backref" href="#id33">RegBankSelect Modes</a><a class="headerlink" href="#regbankselect-modes" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">RegBankSelect</span></code> currently has two modes:</p>
+<ul class="simple">
+<li><strong>Fast</strong> â For each instruction, pick a target-provided âdefaultâ bank
+assignment. This is the default at -O0.</li>
+<li><strong>Greedy</strong> â For each instruction, pick the cheapest of several
+target-provided bank assignment alternatives.</li>
+</ul>
+<p>We intend to eventually introduce an additional optimizing mode:</p>
+<ul class="simple">
+<li><strong>Global</strong> â Across multiple instructions, pick the cheapest combination of
+bank assignments.</li>
+</ul>
+<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>:
+On AArch64, we are considering using the Greedy mode even at -O0 (or perhaps at
+backend -O1): because <a class="reference internal" href="#gmir-llt"><span class="std std-ref">Low Level Type</span></a> doesnât distinguish floating point from
+integer scalars, the default assignment for loads and stores is the integer
+bank, introducing cross-bank copies on most floating point operations.</p>
+</div>
+</div>
+<div class="section" id="instructionselect">
+<span id="id9"></span><h3><a class="toc-backref" href="#id34">InstructionSelect</a><a class="headerlink" href="#instructionselect" title="Permalink to this headline">¶</a></h3>
+<p>This pass transforms generic machine instructions into equivalent
+target-specific instructions. It traverses the <code class="docutils literal notranslate"><span class="pre">MachineFunction</span></code> bottom-up,
+selecting uses before definitions, enabling trivial dead code elimination.</p>
+<div class="section" id="api-instructionselector">
+<span id="id10"></span><h4><a class="toc-backref" href="#id35">API: InstructionSelector</a><a class="headerlink" href="#api-instructionselector" title="Permalink to this headline">¶</a></h4>
+<p>The target implements the <code class="docutils literal notranslate"><span class="pre">InstructionSelector</span></code> class, containing the
+target-specific selection logic proper.</p>
+<p>The instance is provided by the subtarget, so that it can specialize the
+selector by subtarget feature (with, e.g., a vector selector overriding parts
+of a general-purpose common selector).
+We might also want to parameterize it by MachineFunction, to enable selector
+variants based on function attributes like optsize.</p>
+<p>The simple API consists of:</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">select</span><span class="p">(</span><span class="n">MachineInstr</span> <span class="o">&</span><span class="n">MI</span><span class="p">)</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>This target-provided method is responsible for mutating (or replacing) a
+possibly-generic MI into a fully target-specific equivalent.
+It is also responsible for doing the necessary constraining of gvregs into the
+appropriate register classes as well as passing through COPY instructions to
+the register allocator.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">InstructionSelector</span></code> can fold other instructions into the selected MI,
+by walking the use-def chain of the vreg operands.
+As GlobalISel is Global, this folding can occur across basic blocks.</p>
+</div>
+<div class="section" id="selectiondag-rule-imports">
+<h4><a class="toc-backref" href="#id36">SelectionDAG Rule Imports</a><a class="headerlink" href="#selectiondag-rule-imports" title="Permalink to this headline">¶</a></h4>
+<p>TableGen will import SelectionDAG rules and provide the following function to
+execute them:</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">bool</span> <span class="n">selectImpl</span><span class="p">(</span><span class="n">MachineInstr</span> <span class="o">&</span><span class="n">MI</span><span class="p">)</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>The <code class="docutils literal notranslate"><span class="pre">--stats</span></code> option can be used to determine what proportion of rules were
+successfully imported. The easiest way to use this is to copy the
+<code class="docutils literal notranslate"><span class="pre">-gen-globalisel</span></code> tablegen command from <code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">-v</span></code> and modify it.</p>
+<p>Similarly, the <code class="docutils literal notranslate"><span class="pre">--warn-on-skipped-patterns</span></code> option can be used to obtain the
+reasons that rules werenât imported. This can be used to focus on the most
+important rejection reasons.</p>
+</div>
+<div class="section" id="patleaf-predicates">
+<h4><a class="toc-backref" href="#id37">PatLeaf Predicates</a><a class="headerlink" href="#patleaf-predicates" title="Permalink to this headline">¶</a></h4>
+<p>PatLeafs cannot be imported because their C++ is implemented in terms of
+<code class="docutils literal notranslate"><span class="pre">SDNode</span></code> objects. PatLeafs that handle immediate predicates should be
+replaced by <code class="docutils literal notranslate"><span class="pre">ImmLeaf</span></code>, <code class="docutils literal notranslate"><span class="pre">IntImmLeaf</span></code>, or <code class="docutils literal notranslate"><span class="pre">FPImmLeaf</span></code> as appropriate.</p>
+<p>Thereâs no standard answer for other PatLeafs. Some standard predicates have
+been baked into TableGen but this should not generally be done.</p>
+</div>
+<div class="section" id="custom-sdnodes">
+<h4><a class="toc-backref" href="#id38">Custom SDNodes</a><a class="headerlink" href="#custom-sdnodes" title="Permalink to this headline">¶</a></h4>
+<p>Custom SDNodes should be mapped to Target Pseudos using <code class="docutils literal notranslate"><span class="pre">GINodeEquiv</span></code>. This
+will cause the instruction selector to import them but you will also need to
+ensure the target pseudo is introduced to the MIR before the instruction
+selector. Any preceeding pass is suitable but the legalizer will be a
+particularly common choice.</p>
+</div>
+<div class="section" id="complexpatterns">
+<h4><a class="toc-backref" href="#id39">ComplexPatterns</a><a class="headerlink" href="#complexpatterns" title="Permalink to this headline">¶</a></h4>
+<p>ComplexPatterns cannot be imported because their C++ is implemented in terms of
+<code class="docutils literal notranslate"><span class="pre">SDNode</span></code> objects. GlobalISel versions should be defined with
+<code class="docutils literal notranslate"><span class="pre">GIComplexOperandMatcher</span></code> and mapped to ComplexPattern with
+<code class="docutils literal notranslate"><span class="pre">GIComplexPatternEquiv</span></code>.</p>
+<p>The following predicates are useful for porting ComplexPattern:</p>
+<ul class="simple">
+<li>isBaseWithConstantOffset() - Check for base+offset structures</li>
+<li>isOperandImmEqual() - Check for a particular constant</li>
+<li>isObviouslySafeToFold() - Check for reasons an instruction canât be sunk and folded into another.</li>
+</ul>
+<p>There are some important points for the C++ implementation:</p>
+<ul class="simple">
+<li>Donât modify MIR in the predicate</li>
+<li>Renderer lambdas should capture by value to avoid use-after-free. They will be used after the predicate returns.</li>
+<li>Only create instructions in a renderer lambda. GlobalISel wonât clean up things you create but donât use.</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="section" id="maintainability">
+<span id="id11"></span><h2><a class="toc-backref" href="#id15">Maintainability</a><a class="headerlink" href="#maintainability" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="iterative-transformations">
+<span id="maintainability-iterative"></span><h3>Iterative Transformations<a class="headerlink" href="#iterative-transformations" title="Permalink to this headline">¶</a></h3>
+<p>Passes are split into small, iterative transformations, with all state
+represented in the MIR.</p>
+<p>This differs from SelectionDAG (in particular, the legalizer) using various
+in-memory side-tables.</p>
+</div>
+<div class="section" id="mir-serialization">
+<span id="maintainability-mir"></span><h3>MIR Serialization<a class="headerlink" href="#mir-serialization" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference internal" href="#gmir"><span class="std std-ref">Generic Machine IR</span></a> is serializable (see <a class="reference internal" href="MIRLangRef.html"><span class="doc">Machine IR (MIR) Format Reference Manual</span></a>).
+Combined with <a class="reference internal" href="#maintainability-iterative"><span class="std std-ref">Iterative Transformations</span></a>, this enables much finer-grained
+testing, rather than requiring large and fragile IR-to-assembly tests.</p>
+<p>The current âstageâ in the <a class="reference internal" href="#pipeline"><span class="std std-ref">Core Pipeline</span></a> is represented by a set of
+<code class="docutils literal notranslate"><span class="pre">MachineFunctionProperties</span></code>:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">legalized</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">regBankSelected</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">selected</span></code></li>
+</ul>
+</div>
+<div class="section" id="machineverifier">
+<span id="maintainability-verifier"></span><h3>MachineVerifier<a class="headerlink" href="#machineverifier" title="Permalink to this headline">¶</a></h3>
+<p>The pass approach lets us use the <code class="docutils literal notranslate"><span class="pre">MachineVerifier</span></code> to enforce invariants.
+For instance, a <code class="docutils literal notranslate"><span class="pre">regBankSelected</span></code> function may not have gvregs without
+a bank.</p>
+<p><code class="docutils literal notranslate"><span class="pre">TODO</span></code>:
+The <code class="docutils literal notranslate"><span class="pre">MachineVerifier</span></code> being monolithic, some of the checks we want to do
+canât be integrated to it: GlobalISel is a separate library, so we canât
+directly reference it from CodeGen. For instance, legality checks are
+currently done in RegBankSelect/InstructionSelect proper. We could #ifdef out
+the checks, or we could add some sort of verifier API.</p>
+</div>
+</div>
+<div class="section" id="progress-and-future-work">
+<span id="progress"></span><h2><a class="toc-backref" href="#id16">Progress and Future Work</a><a class="headerlink" href="#progress-and-future-work" title="Permalink to this headline">¶</a></h2>
+<p>The initial goal is to replace FastISel on AArch64. The next step will be to
+replace SelectionDAG as the optimized ISel.</p>
+<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>:
+While we iterate on GlobalISel, we strive to avoid affecting the performance of
+SelectionDAG, FastISel, or the other MIR passes. For instance, the types of
+<a class="reference internal" href="#gmir-gvregs"><span class="std std-ref">Generic Virtual Registers</span></a> are stored in a separate table in <code class="docutils literal notranslate"><span class="pre">MachineRegisterInfo</span></code>,
+that is destroyed after <a class="reference internal" href="#instructionselect"><span class="std std-ref">InstructionSelect</span></a>.</p>
+<div class="section" id="fastisel-replacement">
+<span id="progress-fastisel"></span><h3>FastISel Replacement<a class="headerlink" href="#fastisel-replacement" title="Permalink to this headline">¶</a></h3>
+<p>For the initial FastISel replacement, we intend to fallback to SelectionDAG on
+selection failures.</p>
+<p>Currently, compile-time of the fast pipeline is within 1.5x of FastISel.
+Weâre optimistic we can get to within 1.1/1.2x, but beating FastISel will be
+challenging given the multi-pass approach.
+Still, supporting all IR (via a complete legalizer) and avoiding the fallback
+to SelectionDAG in the worst case should enable better amortized performance
+than SelectionDAG+FastISel.</p>
+<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>:
+We considered never having a fallback to SelectionDAG, instead deciding early
+whether a given function is supported by GlobalISel or not. The decision would
+be based on <a class="reference internal" href="#milegalizer"><span class="std std-ref">Legalizer</span></a> queries.
+We abandoned that for two reasons:
+a) on IR inputs, weâd need to basically simulate the <a class="reference internal" href="#irtranslator"><span class="std std-ref">IRTranslator</span></a>;
+b) to be robust against unforeseen failures and to enable iterative
+improvements.</p>
+</div>
+<div class="section" id="support-for-other-targets">
+<span id="progress-targets"></span><h3>Support For Other Targets<a class="headerlink" href="#support-for-other-targets" title="Permalink to this headline">¶</a></h3>
+<p>In parallel, weâre investigating adding support for other - ideally quite
+different - targets. For instance, there is some initial AMDGPU support.</p>
+</div>
+</div>
+<div class="section" id="porting-globalisel-to-a-new-target">
+<span id="porting"></span><h2><a class="toc-backref" href="#id17">Porting GlobalISel to A New Target</a><a class="headerlink" href="#porting-globalisel-to-a-new-target" title="Permalink to this headline">¶</a></h2>
+<p>There are four major classes to implement by the target:</p>
+<ul class="simple">
+<li><a class="reference internal" href="#api-calllowering"><span class="std std-ref">CallLowering</span></a> â lower calls, returns, and arguments
+according to the ABI.</li>
+<li><a class="reference internal" href="#api-registerbankinfo"><span class="std std-ref">RegisterBankInfo</span></a> â describe
+<a class="reference internal" href="#gmir-regbank"><span class="std std-ref">Register Bank</span></a> coverage, cross-bank copy cost, and the mapping of
+operands onto banks for each instruction.</li>
+<li><a class="reference internal" href="#api-legalizerinfo"><span class="std std-ref">LegalizerInfo</span></a> â describe what is legal, and how
+to legalize what isnât.</li>
+<li><a class="reference internal" href="#api-instructionselector"><span class="std std-ref">InstructionSelector</span></a> â select generic MIR
+to target-specific MIR.</li>
+</ul>
+<p>Additionally:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">TargetPassConfig</span></code> â create the passes constituting the pipeline,
+including additional passes not included in the <a class="reference internal" href="#pipeline"><span class="std std-ref">Core Pipeline</span></a>.</li>
+</ul>
+</div>
+<div class="section" id="resources">
+<span id="other-resources"></span><h2><a class="toc-backref" href="#id18">Resources</a><a class="headerlink" href="#resources" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="https://www.youtube.com/watch?v=F6GGbYtae3g">Global Instruction Selection - A Proposal by Quentin Colombet @LLVMDevMeeting 2015</a></li>
+<li><a class="reference external" href="https://www.youtube.com/watch?v=6tfb344A7w8">Global Instruction Selection - Status by Quentin Colombet, Ahmed Bougacha, and Tim Northover @LLVMDevMeeting 2016</a></li>
+<li><a class="reference external" href="https://www.youtube.com/watch?v=d6dF6E4BPeU">GlobalISel - LLVMâs Latest Instruction Selection Framework by Diana Picus @FOSDEM17</a></li>
+<li>GlobalISel: Past, Present, and Future by Quentin Colombet and Ahmed Bougacha @LLVMDevMeeting 2017</li>
+<li>Head First into GlobalISel by Daniel Sanders, Aditya Nandakumar, and Justin Bogner @LLVMDevMeeting 2017</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="XRay.html" title="XRay Instrumentation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Coroutines.html" title="Coroutines in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/GoldPlugin.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/GoldPlugin.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/GoldPlugin.html (added)
+++ www-releases/trunk/8.0.0/docs/GoldPlugin.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,247 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>The LLVM gold plugin — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVMâs Optional Rich Disassembly Output" href="MarkedUpDisassembly.html" />
+ <link rel="prev" title="Debugging JIT-ed Code With GDB" href="DebuggingJITedCode.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-llvm-gold-plugin">
+<h1>The LLVM gold plugin<a class="headerlink" href="#the-llvm-gold-plugin" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Building with link time optimization requires cooperation from
+the system linker. LTO support on Linux systems is available via the
+<a class="reference external" href="http://sourceware.org/binutils">gold linker</a> which supports LTO via plugins. This is the same mechanism
+used by the <a class="reference external" href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a> project.</p>
+<p>The LLVM gold plugin implements the gold plugin interface on top of
+<a class="reference internal" href="LinkTimeOptimization.html#liblto"><span class="std std-ref">libLTO</span></a>. The same plugin can also be used by other tools such as
+<code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm</span></code>. Note that ld.bfd from binutils version 2.21.51.0.2
+and above also supports LTO via plugins. However, usage of the LLVM
+gold plugin with ld.bfd is not tested and therefore not officially
+supported or recommended.</p>
+</div>
+<div class="section" id="how-to-build-it">
+<span id="lto-how-to-build"></span><h2>How to build it<a class="headerlink" href="#how-to-build-it" title="Permalink to this headline">¶</a></h2>
+<p>You need to have gold with plugin support and build the LLVMgold plugin.
+The gold linker is installed as ld.gold. To see whether gold is the default
+on your system, run <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span> <span class="pre">-v</span></code>. It will report âGNU
+goldâ or else âGNU ldâ if not. If gold is already installed at
+<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code>, one option is to simply make that the default by
+backing up your existing <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span></code> and creating a symbolic link
+with <code class="docutils literal notranslate"><span class="pre">ln</span> <span class="pre">-s</span> <span class="pre">/usr/bin/ld.gold</span> <span class="pre">/usr/bin/ld</span></code>. Alternatively, you can build
+with clangâs <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> or add <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> to LDFLAGS, which will
+cause the clang driver to invoke <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code> directly.</p>
+<p>If you have gold installed, check for plugin support by running
+<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span> <span class="pre">-plugin</span></code>. If it complains âmissing argumentâ then
+you have plugin support. If not, and you get an error such as âunknown optionâ,
+then you will either need to build gold or install a version with plugin
+support.</p>
+<ul>
+<li><p class="first">Download, configure and build gold with plugin support:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git clone --depth <span class="m">1</span> git://sourceware.org/git/binutils-gdb.git binutils
+$ mkdir build
+$ <span class="nb">cd</span> build
+$ ../binutils/configure --enable-gold --enable-plugins --disable-werror
+$ make all-gold
+</pre></div>
+</div>
+<p>That should leave you with <code class="docutils literal notranslate"><span class="pre">build/gold/ld-new</span></code> which supports
+the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option. Running <code class="docutils literal notranslate"><span class="pre">make</span></code> will additionally build
+<code class="docutils literal notranslate"><span class="pre">build/binutils/ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm-new</span></code> binaries supporting plugins.</p>
+<p>Once youâre ready to switch to using gold, backup your existing
+<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span></code> then replace it with <code class="docutils literal notranslate"><span class="pre">ld-new</span></code>. Alternatively, install
+in <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code> and use <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> as described earlier.</p>
+<p>Optionally, add <code class="docutils literal notranslate"><span class="pre">--enable-gold=default</span></code> to the above configure invocation
+to automatically install the newly built gold as the default linker with
+<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code>.</p>
+</li>
+<li><p class="first">Build the LLVMgold plugin. Run CMake with
+<code class="docutils literal notranslate"><span class="pre">-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include</span></code>. The correct include
+path will contain the file <code class="docutils literal notranslate"><span class="pre">plugin-api.h</span></code>.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="usage">
+<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>You should produce bitcode files from <code class="docutils literal notranslate"><span class="pre">clang</span></code> with the option
+<code class="docutils literal notranslate"><span class="pre">-flto</span></code>. This flag will also cause <code class="docutils literal notranslate"><span class="pre">clang</span></code> to look for the gold plugin in
+the <code class="docutils literal notranslate"><span class="pre">lib</span></code> directory under its prefix and pass the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option to
+<code class="docutils literal notranslate"><span class="pre">ld</span></code>. It will not look for an alternate linker without <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code>,
+which is why you otherwise need gold to be the installed system linker in
+your path.</p>
+<p><code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm</span></code> also accept the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option and itâs possible to
+to install <code class="docutils literal notranslate"><span class="pre">LLVMgold.so</span></code> to <code class="docutils literal notranslate"><span class="pre">/usr/lib/bfd-plugins</span></code> for a seamless setup.
+If you built your own gold, be sure to install the <code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm-new</span></code> you
+built to <code class="docutils literal notranslate"><span class="pre">/usr/bin</span></code>.</p>
+<div class="section" id="example-of-link-time-optimization">
+<h3>Example of link time optimization<a class="headerlink" href="#example-of-link-time-optimization" title="Permalink to this headline">¶</a></h3>
+<p>The following example shows a worked example of the gold plugin mixing LLVM
+bitcode and native code.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">---</span> <span class="n">a</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
+<span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
+
+<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+<span class="k">extern</span> <span class="kt">void</span> <span class="nf">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"Foo2</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">foo3</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">foo4</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">foo1</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="o">---</span> <span class="n">b</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
+<span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
+
+<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">foo2</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"Foo4"</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>--- <span class="nb">command</span> lines ---
+$ clang -flto a.c -c -o a.o <span class="c1"># <-- a.o is LLVM bitcode file</span>
+$ ar q a.a a.o <span class="c1"># <-- a.a is an archive with LLVM bitcode</span>
+$ clang b.c -c -o b.o <span class="c1"># <-- b.o is native object file</span>
+$ clang -flto a.a b.o -o main <span class="c1"># <-- link with LLVMgold plugin</span>
+</pre></div>
+</div>
+<p>Gold informs the plugin that foo3 is never referenced outside the IR,
+leading LLVM to delete that function. However, unlike in the <a class="reference internal" href="LinkTimeOptimization.html#liblto-example"><span class="std std-ref">libLTO
+example</span></a> gold does not currently eliminate foo4.</p>
+</div>
+</div>
+<div class="section" id="quickstart-for-using-lto-with-autotooled-projects">
+<h2>Quickstart for using LTO with autotooled projects<a class="headerlink" href="#quickstart-for-using-lto-with-autotooled-projects" title="Permalink to this headline">¶</a></h2>
+<p>Once your system <code class="docutils literal notranslate"><span class="pre">ld</span></code>, <code class="docutils literal notranslate"><span class="pre">ar</span></code>, and <code class="docutils literal notranslate"><span class="pre">nm</span></code> all support LLVM bitcode,
+everything is in place for an easy to use LTO build of autotooled projects:</p>
+<ul>
+<li><p class="first">Follow the instructions <a class="reference internal" href="#lto-how-to-build"><span class="std std-ref">on how to build LLVMgold.so</span></a>.</p>
+</li>
+<li><p class="first">Install the newly built binutils to <code class="docutils literal notranslate"><span class="pre">$PREFIX</span></code></p>
+</li>
+<li><p class="first">Copy <code class="docutils literal notranslate"><span class="pre">Release/lib/LLVMgold.so</span></code> to <code class="docutils literal notranslate"><span class="pre">$PREFIX/lib/bfd-plugins/</span></code></p>
+</li>
+<li><p class="first">Set environment variables (<code class="docutils literal notranslate"><span class="pre">$PREFIX</span></code> is where you installed clang and
+binutils):</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">CC</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin/clang -flto"</span>
+<span class="nb">export</span> <span class="nv">CXX</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin/clang++ -flto"</span>
+<span class="nb">export</span> <span class="nv">AR</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin/ar"</span>
+<span class="nb">export</span> <span class="nv">NM</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin/nm"</span>
+<span class="nb">export</span> <span class="nv">RANLIB</span><span class="o">=</span>/bin/true <span class="c1">#ranlib is not needed, and doesn't support .bc files in .a</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Or you can just set your path:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">PATH</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin:</span><span class="nv">$PATH</span><span class="s2">"</span>
+<span class="nb">export</span> <span class="nv">CC</span><span class="o">=</span><span class="s2">"clang -flto"</span>
+<span class="nb">export</span> <span class="nv">CXX</span><span class="o">=</span><span class="s2">"clang++ -flto"</span>
+<span class="nb">export</span> <span class="nv">RANLIB</span><span class="o">=</span>/bin/true
+</pre></div>
+</div>
+</li>
+<li><p class="first">Configure and build the project as usual:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>% ./configure <span class="o">&&</span> make <span class="o">&&</span> make check
+</pre></div>
+</div>
+</li>
+</ul>
+<p>The environment variable settings may work for non-autotooled projects too,
+but you may need to set the <code class="docutils literal notranslate"><span class="pre">LD</span></code> environment variable as well.</p>
+</div>
+<div class="section" id="licensing">
+<h2>Licensing<a class="headerlink" href="#licensing" title="Permalink to this headline">¶</a></h2>
+<p>Gold is licensed under the GPLv3. LLVMgold uses the interface file
+<code class="docutils literal notranslate"><span class="pre">plugin-api.h</span></code> from gold which means that the resulting <code class="docutils literal notranslate"><span class="pre">LLVMgold.so</span></code>
+binary is also GPLv3. This can still be used to link non-GPLv3 programs
+just as much as gold could without the plugin.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToAddABuilder.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToAddABuilder.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToAddABuilder.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToAddABuilder.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,189 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Add Your Build Configuration To LLVM Buildbot Infrastructure — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="yaml2obj" href="yaml2obj.html" />
+ <link rel="prev" title="The LLVM Lexicon" href="Lexicon.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="yaml2obj.html" title="yaml2obj"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-add-your-build-configuration-to-llvm-buildbot-infrastructure">
+<h1>How To Add Your Build Configuration To LLVM Buildbot Infrastructure<a class="headerlink" href="#how-to-add-your-build-configuration-to-llvm-buildbot-infrastructure" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about adding a build configuration and
+buildslave to private slave builder to LLVM Buildbot Infrastructure.</p>
+</div>
+<div class="section" id="buildmasters">
+<h2>Buildmasters<a class="headerlink" href="#buildmasters" title="Permalink to this headline">¶</a></h2>
+<p>There are two buildmasters running.</p>
+<ul class="simple">
+<li>The main buildmaster at <a class="reference external" href="http://lab.llvm.org:8011">http://lab.llvm.org:8011</a>. All builders attached
+to this machine will notify commit authors every time they break the build.</li>
+<li>The staging buildbot at <a class="reference external" href="http://lab.llvm.org:8014">http://lab.llvm.org:8014</a>. All builders attached
+to this machine will be completely silent by default when the build is broken.
+Builders for experimental backends should generally be attached to this
+buildmaster.</li>
+</ul>
+</div>
+<div class="section" id="steps-to-add-builder-to-llvm-buildbot">
+<h2>Steps To Add Builder To LLVM Buildbot<a class="headerlink" href="#steps-to-add-builder-to-llvm-buildbot" title="Permalink to this headline">¶</a></h2>
+<p>Volunteers can provide their build machines to work as build slaves to
+public LLVM Buildbot.</p>
+<p>Here are the steps you can follow to do so:</p>
+<ol class="arabic">
+<li><p class="first">Check the existing build configurations to make sure the one you are
+interested in is not covered yet or gets built on your computer much
+faster than on the existing one. We prefer faster builds so developers
+will get feedback sooner after changes get committed.</p>
+</li>
+<li><p class="first">The computer you will be registering with the LLVM buildbot
+infrastructure should have all dependencies installed and you can
+actually build your configuration successfully. Please check what degree
+of parallelism (-j param) would give the fastest build. You can build
+multiple configurations on one computer.</p>
+</li>
+<li><p class="first">Install buildslave (currently we are using buildbot version 0.8.5).
+Depending on the platform, buildslave could be available to download and
+install with your package manager, or you can download it directly from
+<a class="reference external" href="http://trac.buildbot.net">http://trac.buildbot.net</a> and install it manually.</p>
+</li>
+<li><p class="first">Create a designated user account, your buildslave will be running under,
+and set appropriate permissions.</p>
+</li>
+<li><p class="first">Choose the buildslave root directory (all builds will be placed under
+it), buildslave access name and password the build master will be using
+to authenticate your buildslave.</p>
+</li>
+<li><p class="first">Create a buildslave in context of that buildslave account. Point it to
+the <strong>lab.llvm.org</strong> port <strong>9990</strong> (see <a class="reference external" href="http://docs.buildbot.net/current/tutorial/firstrun.html#creating-a-slave">Buildbot documentation,
+Creating a slave</a>
+for more details) by running the following command:</p>
+<blockquote>
+<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ buildslave create-slave <buildslave-root-directory> <span class="se">\</span>
+ lab.llvm.org:9990 <span class="se">\</span>
+ <buildslave-access-name> <buildslave-access-password>
+</pre></div>
+</div>
+</div></blockquote>
+<p>To point a slave to silent master please use lab.llvm.org:9994 instead
+of lab.llvm.org:9990.</p>
+</li>
+<li><p class="first">Fill the buildslave description and admin name/e-mail. Here is an
+example of the buildslave description:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Windows</span> <span class="mi">7</span> <span class="n">x64</span>
+<span class="n">Core</span> <span class="n">i7</span> <span class="p">(</span><span class="mf">2.66</span><span class="n">GHz</span><span class="p">),</span> <span class="mi">16</span><span class="n">GB</span> <span class="n">of</span> <span class="n">RAM</span>
+
+<span class="n">g</span><span class="o">++.</span><span class="n">exe</span> <span class="p">(</span><span class="n">TDM</span><span class="o">-</span><span class="mi">1</span> <span class="n">mingw32</span><span class="p">)</span> <span class="mf">4.4</span><span class="o">.</span><span class="mi">0</span>
+<span class="n">GNU</span> <span class="n">Binutils</span> <span class="mf">2.19</span><span class="o">.</span><span class="mi">1</span>
+<span class="n">cmake</span> <span class="n">version</span> <span class="mf">2.8</span><span class="o">.</span><span class="mi">4</span>
+<span class="n">Microsoft</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="mi">32</span><span class="o">-</span><span class="n">bit</span> <span class="n">C</span><span class="o">/</span><span class="n">C</span><span class="o">++</span> <span class="n">Optimizing</span> <span class="n">Compiler</span> <span class="n">Version</span> <span class="mf">16.00</span><span class="o">.</span><span class="mf">40219.01</span> <span class="k">for</span> <span class="mi">80</span><span class="n">x86</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Make sure you can actually start the buildslave successfully. Then set
+up your buildslave to start automatically at the start up time. See the
+buildbot documentation for help. You may want to restart your computer
+to see if it works.</p>
+</li>
+<li><p class="first">Send a patch which adds your build slave and your builder to zorg.</p>
+<ul class="simple">
+<li>slaves are added to <code class="docutils literal notranslate"><span class="pre">buildbot/osuosl/master/config/slaves.py</span></code></li>
+<li>builders are added to <code class="docutils literal notranslate"><span class="pre">buildbot/osuosl/master/config/builders.py</span></code></li>
+</ul>
+<p>Please make sure your builder name and its builddir are unique through the file.</p>
+<p>It is possible to whitelist email addresses to unconditionally receive notifications
+on build failure; for this youâll need to add an <code class="docutils literal notranslate"><span class="pre">InformativeMailNotifier</span></code> to
+<code class="docutils literal notranslate"><span class="pre">buildbot/osuosl/master/config/status.py</span></code>. This is particularly useful for the
+staging buildmaster which is silent otherwise.</p>
+</li>
+<li><p class="first">Send the buildslave access name and the access password directly to
+<a class="reference external" href="mailto:gkistanova%40gmail.com">Galina Kistanova</a>, and wait till she
+will let you know that your changes are applied and buildmaster is
+reconfigured.</p>
+</li>
+<li><p class="first">Check the status of your buildslave on the <a class="reference external" href="http://lab.llvm.org:8011/waterfall">Waterfall Display</a> to make sure it is connected, and
+<code class="docutils literal notranslate"><span class="pre">http://lab.llvm.org:8011/buildslaves/<your-buildslave-name></span></code> to see
+if administrator contact and slave information are correct.</p>
+</li>
+<li><p class="first">Wait for the first build to succeed and enjoy.</p>
+</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="yaml2obj.html" title="yaml2obj"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToBuildOnARM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToBuildOnARM.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToBuildOnARM.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToBuildOnARM.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,162 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Build On ARM — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="How To Build Clang and LLVM with Profile-Guided Optimizations" href="HowToBuildWithPGO.html" />
+ <link rel="prev" title="Advanced Build Configurations" href="AdvancedBuilds.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToBuildWithPGO.html" title="How To Build Clang and LLVM with Profile-Guided Optimizations"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="AdvancedBuilds.html" title="Advanced Build Configurations"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-build-on-arm">
+<h1>How To Build On ARM<a class="headerlink" href="#how-to-build-on-arm" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about building/testing LLVM and
+Clang on an ARM machine.</p>
+<p>This document is <em>NOT</em> tailored to help you cross-compile LLVM/Clang
+to ARM on another architecture, for example an x86_64 machine. To find
+out more about cross-compiling, please check <a class="reference internal" href="HowToCrossCompileLLVM.html"><span class="doc">How To Cross-Compile Clang/LLVM using Clang/LLVM</span></a>.</p>
+</div>
+<div class="section" id="notes-on-building-llvm-clang-on-arm">
+<h2>Notes On Building LLVM/Clang on ARM<a class="headerlink" href="#notes-on-building-llvm-clang-on-arm" title="Permalink to this headline">¶</a></h2>
+<p>Here are some notes on building/testing LLVM/Clang on ARM. Note that
+ARM encompasses a wide variety of CPUs; this advice is primarily based
+on the ARMv6 and ARMv7 architectures and may be inapplicable to older chips.</p>
+<ol class="arabic">
+<li><p class="first">The most popular Linaro/Ubuntu OSâs for ARM boards, e.g., the
+Pandaboard, have become hard-float platforms. There are a number of
+choices when using CMake. Autoconf usage is deprecated as of 3.8.</p>
+<p>Building LLVM/Clang in <code class="docutils literal notranslate"><span class="pre">Relese</span></code> mode is preferred since it consumes
+a lot less memory. Otherwise, the building process will very likely
+fail due to insufficient memory. Itâs also a lot quicker to only build
+the relevant back-ends (ARM and AArch64), since itâs very unlikely that
+youâll use an ARM board to cross-compile to other arches. If youâre
+running Compiler-RT tests, also include the x86 back-end, or some tests
+will fail.</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cmake <span class="nv">$LLVM_SRC_DIR</span> -DCMAKE_BUILD_TYPE<span class="o">=</span>Release <span class="se">\</span>
+ -DLLVM_TARGETS_TO_BUILD<span class="o">=</span><span class="s2">"ARM;X86;AArch64"</span>
+</pre></div>
+</div>
+<p>Other options you can use are:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>Use Ninja instead of Make: <span class="s2">"-G Ninja"</span>
+Build with assertions on: <span class="s2">"-DLLVM_ENABLE_ASSERTIONS=True"</span>
+Force Python2: <span class="s2">"-DPYTHON_EXECUTABLE=/usr/bin/python2"</span>
+Local <span class="o">(</span>non-sudo<span class="o">)</span> install path: <span class="s2">"-DCMAKE_INSTALL_PREFIX=</span><span class="nv">$HOME</span><span class="s2">/llvm/instal"</span>
+CPU flags: <span class="s2">"DCMAKE_C_FLAGS=-mcpu=cortex-a15"</span> <span class="o">(</span>same <span class="k">for</span> CXX_FLAGS<span class="o">)</span>
+</pre></div>
+</div>
+<p>After that, just typing <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-jN</span></code> or <code class="docutils literal notranslate"><span class="pre">ninja</span></code> will build everything.
+<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-jN</span> <span class="pre">check-all</span></code> or <code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">check-all</span></code> will run all compiler tests. For
+running the test suite, please refer to <a class="reference internal" href="TestingGuide.html"><span class="doc">LLVM Testing Infrastructure Guide</span></a>.</p>
+</li>
+<li><p class="first">If you are building LLVM/Clang on an ARM board with 1G of memory or less,
+please use <code class="docutils literal notranslate"><span class="pre">gold</span></code> rather then GNU <code class="docutils literal notranslate"><span class="pre">ld</span></code>. In any case it is probably a good
+idea to set up a swap partition, too.</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ sudo ln -sf /usr/bin/ld /usr/bin/ld.gold
+</pre></div>
+</div>
+</li>
+<li><p class="first">ARM development boards can be unstable and you may experience that cores
+are disappearing, caches being flushed on every big.LITTLE switch, and
+other similar issues. To help ease the effect of this, set the Linux
+scheduler to âperformanceâ on <strong>all</strong> cores using this little script:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># The code below requires the package 'cpufrequtils' to be installed.</span>
+<span class="k">for</span> <span class="o">((</span><span class="nv">cpu</span><span class="o">=</span><span class="m">0</span><span class="p">;</span> cpu<<span class="sb">`</span>grep -c proc /proc/cpuinfo<span class="sb">`</span><span class="p">;</span> cpu++<span class="o">))</span><span class="p">;</span> <span class="k">do</span>
+ sudo cpufreq-set -c <span class="nv">$cpu</span> -g performance
+<span class="k">done</span>
+</pre></div>
+</div>
+<p>Remember to turn that off after the build, or you may risk burning your
+CPU. Most modern kernels donât need that, so only use it if you have
+problems.</p>
+</li>
+<li><p class="first">Running the build on SD cards is ok, but they are more prone to failures
+than good quality USB sticks, and those are more prone to failures than
+external hard-drives (those are also a lot faster). So, at least, you
+should consider to buy a fast USB stick. On systems with a fast eMMC,
+thatâs a good option too.</p>
+</li>
+<li><p class="first">Make sure you have a decent power supply (dozens of dollars worth) that can
+provide <em>at least</em> 4 amperes, this is especially important if you use USB
+devices with your board. Externally powered USB/SATA harddrives are even
+better than having a good power supply.</p>
+</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToBuildWithPGO.html" title="How To Build Clang and LLVM with Profile-Guided Optimizations"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="AdvancedBuilds.html" title="Advanced Build Configurations"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToBuildWithPGO.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToBuildWithPGO.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToBuildWithPGO.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToBuildWithPGO.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,246 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Build Clang and LLVM with Profile-Guided Optimizations — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="How to Cross Compile Compiler-rt Builtins For Arm" href="HowToCrossCompileBuiltinsOnArm.html" />
+ <link rel="prev" title="How To Build On ARM" href="HowToBuildOnARM.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToCrossCompileBuiltinsOnArm.html" title="How to Cross Compile Compiler-rt Builtins For Arm"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToBuildOnARM.html" title="How To Build On ARM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-build-clang-and-llvm-with-profile-guided-optimizations">
+<h1>How To Build Clang and LLVM with Profile-Guided Optimizations<a class="headerlink" href="#how-to-build-clang-and-llvm-with-profile-guided-optimizations" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>PGO (Profile-Guided Optimization) allows your compiler to better optimize code
+for how it actually runs. Users report that applying this to Clang and LLVM can
+decrease overall compile time by 20%.</p>
+<p>This guide walks you through how to build Clang with PGO, though it also applies
+to other subprojects, such as LLD.</p>
+</div>
+<div class="section" id="using-the-script">
+<h2>Using the script<a class="headerlink" href="#using-the-script" title="Permalink to this headline">¶</a></h2>
+<p>We have a script at <code class="docutils literal notranslate"><span class="pre">utils/collect_and_build_with_pgo.py</span></code>. This script is
+tested on a few Linux flavors, and requires a checkout of LLVM, Clang, and
+compiler-rt. Despite the the name, it performs four clean builds of Clang, so it
+can take a while to run to completion. Please see the scriptâs <code class="docutils literal notranslate"><span class="pre">--help</span></code> for
+more information on how to run it, and the different options available to you.
+If you want to get the most out of PGO for a particular use-case (e.g. compiling
+a specific large piece of software), please do read the section below on
+âbenchmarkâ selection.</p>
+<p>Please note that this script is only tested on a few Linux distros. Patches to
+add support for other platforms, as always, are highly appreciated. :)</p>
+<p>This script also supports a <code class="docutils literal notranslate"><span class="pre">--dry-run</span></code> option, which causes it to print
+important commands instead of running them.</p>
+</div>
+<div class="section" id="selecting-benchmarks">
+<h2>Selecting âbenchmarksâ<a class="headerlink" href="#selecting-benchmarks" title="Permalink to this headline">¶</a></h2>
+<p>PGO does best when the profiles gathered represent how the user plans to use the
+compiler. Notably, highly accurate profiles of llc building x86_64 code arenât
+incredibly helpful if youâre going to be targeting ARM.</p>
+<p>By default, the script above does two things to get solid coverage. It:</p>
+<ul class="simple">
+<li>runs all of Clang and LLVMâs lit tests, and</li>
+<li>uses the instrumented Clang to build Clang, LLVM, and all of the other
+LLVM subprojects available to it.</li>
+</ul>
+<p>Together, these should give you:</p>
+<ul class="simple">
+<li>solid coverage of building C++,</li>
+<li>good coverage of building C,</li>
+<li>great coverage of running optimizations,</li>
+<li>great coverage of the backend for your hostâs architecture, and</li>
+<li>some coverage of other architectures (if other arches are supported backends).</li>
+</ul>
+<p>Altogether, this should cover a diverse set of uses for Clang and LLVM. If you
+have very specific needs (e.g. your compiler is meant to compile a large browser
+for four different platforms, or similar), you may want to do something else.
+This is configurable in the script itself.</p>
+</div>
+<div class="section" id="building-clang-with-pgo">
+<h2>Building Clang with PGO<a class="headerlink" href="#building-clang-with-pgo" title="Permalink to this headline">¶</a></h2>
+<p>If you prefer to not use the script, this briefly goes over how to build
+Clang/LLVM with PGO.</p>
+<p>First, you should have at least LLVM, Clang, and compiler-rt checked out
+locally.</p>
+<p>Next, at a high level, youâre going to need to do the following:</p>
+<ol class="arabic simple">
+<li>Build a standard Release Clang and the relevant libclang_rt.profile library</li>
+<li>Build Clang using the Clang you built above, but with instrumentation</li>
+<li>Use the instrumented Clang to generate profiles, which consists of two steps:</li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li>Running the instrumented Clang/LLVM/lld/etc. on tasks that represent how
+users will use said tools.</li>
+<li>Using a tool to convert the ârawâ profiles generated above into a single,
+final PGO profile.</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="4">
+<li>Build a final release Clang (along with whatever other binaries you need)
+using the profile collected from your benchmark</li>
+</ol>
+<p>In more detailed steps:</p>
+<ol class="arabic simple">
+<li>Configure a Clang build as you normally would. Itâs highly recommended that
+you use the Release configuration for this, since it will be used to build
+another Clang. Because you need Clang and supporting libraries, youâll want
+to build the <code class="docutils literal notranslate"><span class="pre">all</span></code> target (e.g. <code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">all</span></code> or <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-j4</span> <span class="pre">all</span></code>).</li>
+<li>Configure a Clang build as above, but add the following CMake args:<ul>
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_BUILD_INSTRUMENTED=IR</span></code> â This causes us to build everything
+with instrumentation.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_BUILD_RUNTIME=No</span></code> â A few projects have bad interactions when
+built with profiling, and arenât necessary to build. This flag turns them
+off.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER=/path/to/stage1/clang</span></code> - Use the Clang we built in
+step 1.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_CXX_COMPILER=/path/to/stage1/clang++</span></code> - Same as above.</li>
+</ul>
+</li>
+</ol>
+<blockquote>
+<div>In this build directory, you simply need to build the <code class="docutils literal notranslate"><span class="pre">clang</span></code> target (and
+whatever supporting tooling your benchmark requires).</div></blockquote>
+<ol class="arabic" start="3">
+<li><p class="first">As mentioned above, this has two steps: gathering profile data, and then
+massaging it into a useful form:</p>
+<ol class="loweralpha">
+<li><p class="first">Build your benchmark using the Clang generated in step 2. The âstandardâ
+benchmark recommended is to run <code class="docutils literal notranslate"><span class="pre">check-clang</span></code> and <code class="docutils literal notranslate"><span class="pre">check-llvm</span></code> in your
+instrumented Clangâs build directory, and to do a full build of Clang/LLVM
+using your instrumented Clang. So, create yet another build directory,
+with the following CMake arguments:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER=/path/to/stage2/clang</span></code> - Use the Clang we built in
+step 2.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_CXX_COMPILER=/path/to/stage2/clang++</span></code> - Same as above.</li>
+</ul>
+<p>If your users are fans of debug info, you may want to consider using
+<code class="docutils literal notranslate"><span class="pre">-DCMAKE_BUILD_TYPE=RelWithDebInfo</span></code> instead of
+<code class="docutils literal notranslate"><span class="pre">-DCMAKE_BUILD_TYPE=Release</span></code>. This will grant better coverage of
+debug info pieces of clang, but will take longer to complete and will
+result in a much larger build directory.</p>
+<p>Itâs recommended to build the <code class="docutils literal notranslate"><span class="pre">all</span></code> target with your instrumented Clang,
+since more coverage is often better.</p>
+</li>
+</ol>
+</li>
+</ol>
+<blockquote>
+<div><ol class="loweralpha simple" start="2">
+<li>You should now have a few <code class="docutils literal notranslate"><span class="pre">*.profraw</span></code> files in
+<code class="docutils literal notranslate"><span class="pre">path/to/stage2/profiles/</span></code>. You need to merge these using
+<code class="docutils literal notranslate"><span class="pre">llvm-profdata</span></code> (even if you only have one! The profile merge transforms
+profraw into actual profile data, as well). This can be done with
+<code class="docutils literal notranslate"><span class="pre">/path/to/stage1/llvm-profdata</span> <span class="pre">merge</span>
+<span class="pre">-output=/path/to/output/profdata.prof</span> <span class="pre">path/to/stage2/profiles/*.profraw</span></code>.</li>
+</ol>
+</div></blockquote>
+<ol class="arabic" start="4">
+<li><p class="first">Now, build your final, PGO-optimized Clang. To do this, youâll want to pass
+the following additional arguments to CMake.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_PROFDATA_FILE=/path/to/output/profdata.prof</span></code> - Use the PGO
+profile from the previous step.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER=/path/to/stage1/clang</span></code> - Use the Clang we built in
+step 1.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_CXX_COMPILER=/path/to/stage1/clang++</span></code> - Same as above.</li>
+</ul>
+<p>From here, you can build whatever targets you need.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">You may see warnings about a mismatched profile in the build output. These
+are generally harmless. To silence them, you can add
+<code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_FLAGS='-Wno-backend-plugin'</span>
+<span class="pre">-DCMAKE_CXX_FLAGS='-Wno-backend-plugin'</span></code> to your CMake invocation.</p>
+</div>
+</li>
+</ol>
+<p>Congrats! You now have a Clang built with profile-guided optimizations, and you
+can delete all but the final build directory if youâd like.</p>
+<p>If this worked well for you and you plan on doing it often, thereâs a slight
+optimization that can be made: LLVM and Clang have a tool called tblgen thatâs
+built and run during the build process. While itâs potentially nice to build
+this for coverage as part of step 3, none of your other builds should benefit
+from building it. You can pass the CMake options
+<code class="docutils literal notranslate"><span class="pre">-DCLANG_TABLEGEN=/path/to/stage1/bin/clang-tblgen</span>
+<span class="pre">-DLLVM_TABLEGEN=/path/to/stage1/bin/llvm-tblgen</span></code> to steps 2 and onward to avoid
+these useless rebuilds.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToCrossCompileBuiltinsOnArm.html" title="How to Cross Compile Compiler-rt Builtins For Arm"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToBuildOnARM.html" title="How To Build On ARM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToCrossCompileBuiltinsOnArm.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToCrossCompileBuiltinsOnArm.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToCrossCompileBuiltinsOnArm.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToCrossCompileBuiltinsOnArm.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,354 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How to Cross Compile Compiler-rt Builtins For Arm — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="How To Cross-Compile Clang/LLVM using Clang/LLVM" href="HowToCrossCompileLLVM.html" />
+ <link rel="prev" title="How To Build Clang and LLVM with Profile-Guided Optimizations" href="HowToBuildWithPGO.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToCrossCompileLLVM.html" title="How To Cross-Compile Clang/LLVM using Clang/LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToBuildWithPGO.html" title="How To Build Clang and LLVM with Profile-Guided Optimizations"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-cross-compile-compiler-rt-builtins-for-arm">
+<h1>How to Cross Compile Compiler-rt Builtins For Arm<a class="headerlink" href="#how-to-cross-compile-compiler-rt-builtins-for-arm" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about building and testing the builtins part
+of compiler-rt for an Arm target, from an x86_64 Linux machine.</p>
+<p>While this document concentrates on Arm and Linux the general principles should
+apply to other targets supported by compiler-rt. Further contributions for other
+targets are welcome.</p>
+<p>The instructions in this document depend on libraries and programs external to
+LLVM, there are many ways to install and configure these dependencies so you
+may need to adapt the instructions here to fit your own local situation.</p>
+</div>
+<div class="section" id="prerequisites">
+<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
+<p>In this use case weâll be using cmake on a Debian-based Linux system,
+cross-compiling from an x86_64 host to a hard-float Armv7-A target. Weâll be
+using as many of the LLVM tools as we can, but it is possible to use GNU
+equivalents.</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">A</span> <span class="pre">build</span> <span class="pre">of</span> <span class="pre">LLVM/clang</span> <span class="pre">for</span> <span class="pre">the</span> <span class="pre">llvm-tools</span> <span class="pre">and</span> <span class="pre">llvm-config</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">A</span> <span class="pre">clang</span> <span class="pre">executable</span> <span class="pre">with</span> <span class="pre">support</span> <span class="pre">for</span> <span class="pre">the</span> <span class="pre">ARM</span> <span class="pre">target</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">compiler-rt</span> <span class="pre">sources</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">The</span> <span class="pre">qemu-arm</span> <span class="pre">user</span> <span class="pre">mode</span> <span class="pre">emulator</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">An</span> <span class="pre">arm-linux-gnueabihf</span> <span class="pre">sysroot</span></code></li>
+</ul>
+</div></blockquote>
+<p>In this example we will be using ninja.</p>
+<p>See <a class="reference external" href="https://compiler-rt.llvm.org/">https://compiler-rt.llvm.org/</a> for more information about the dependencies
+on clang and LLVM.</p>
+<p>See <a class="reference external" href="https://llvm.org/docs/GettingStarted.html">https://llvm.org/docs/GettingStarted.html</a> for information about obtaining
+the source for LLVM and compiler-rt. Note that the getting started guide
+places compiler-rt in the projects subdirectory, but this is not essential and
+if you are using the BaremetalARM.cmake cache for v6-M, v7-M and v7-EM then
+compiler-rt must be placed in the runtimes directory.</p>
+<p><code class="docutils literal notranslate"><span class="pre">qemu-arm</span></code> should be available as a package for your Linux distribution.</p>
+<p>The most complicated of the prequisites to satisfy is the arm-linux-gnueabihf
+sysroot. In theory it is possible to use the Linux distributions multiarch
+support to fulfill the dependencies for building but unfortunately due to
+/usr/local/include being added some host includes are selected. The easiest way
+to supply a sysroot is to download the arm-linux-gnueabihf toolchain. This can
+be found at:
+* <a class="reference external" href="https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads">https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads</a> for gcc 8 and above
+* <a class="reference external" href="https://releases.linaro.org/components/toolchain/binaries/">https://releases.linaro.org/components/toolchain/binaries/</a> for gcc 4.9 to 7.3</p>
+</div>
+<div class="section" id="building-compiler-rt-builtins-for-arm">
+<h2>Building compiler-rt builtins for Arm<a class="headerlink" href="#building-compiler-rt-builtins-for-arm" title="Permalink to this headline">¶</a></h2>
+<p>We will be doing a standalone build of compiler-rt using the following cmake
+options.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">path/to/compiler-rt</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-G</span> <span class="pre">Ninja</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_BUILTINS=ON</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_SANITIZERS=OFF</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_XRAY=OFF</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_LIBFUZZER=OFF</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_PROFILE=OFF</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER=/path/to/clang</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_AR=/path/to/llvm-ar</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_NM=/path/to/llvm-nm</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_RANLIB=/path/to/llvm-ranlib</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER_TARGET="arm-linux-gnueabihf"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_ASM_COMPILER_TARGET="arm-linux-gnueabihf"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_CONFIG_PATH=/path/to/llvm-config</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_FLAGS="build-c-flags"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_ASM_FLAGS="build-c-flags"</span></code></li>
+</ul>
+<p>The <code class="docutils literal notranslate"><span class="pre">build-c-flags</span></code> need to be sufficient to pass the C-make compiler check,
+compile compiler-rt, and if you are running the tests, compile and link the
+tests. When cross-compiling with clang we will need to pass sufficient
+information to generate code for the Arm architecture we are targeting. We will
+need to select the Arm target, select the Armv7-A architecture and choose
+between using Arm or Thumb.
+instructions. For example:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">--target=arm-linux-gnueabihf</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-march=armv7a</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-mthumb</span></code></li>
+</ul>
+<p>When using a GCC arm-linux-gnueabihf toolchain the following flags are
+needed to pick up the includes and libraries:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">--gcc-toolchain=/path/to/dir/toolchain</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">--sysroot=/path/to/toolchain/arm-linux-gnueabihf/libc</span></code></li>
+</ul>
+<p>In this example we will be adding all of the command line options to both
+<code class="docutils literal notranslate"><span class="pre">CMAKE_C_FLAGS</span></code> and <code class="docutils literal notranslate"><span class="pre">CMAKE_ASM_FLAGS</span></code>. There are cmake flags to pass some of
+these options individually which can be used to simplify the <code class="docutils literal notranslate"><span class="pre">build-c-flags</span></code>:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER_TARGET="arm-linux-gnueabihf"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_ASM_COMPILER_TARGET="arm-linux-gnueabihf"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN=/path/to/dir/toolchain</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_SYSROOT=/path/to/dir/toolchain/arm-linux-gnueabihf/libc</span></code></li>
+</ul>
+<p>Once cmake has completed the builtins can be built with <code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">builtins</span></code></p>
+</div>
+<div class="section" id="testing-compiler-rt-builtins-using-qemu-arm">
+<h2>Testing compiler-rt builtins using qemu-arm<a class="headerlink" href="#testing-compiler-rt-builtins-using-qemu-arm" title="Permalink to this headline">¶</a></h2>
+<p>To test the builtins library we need to add a few more cmake flags to enable
+testing and set up the compiler and flags for test case. We must also tell
+cmake that we wish to run the tests on <code class="docutils literal notranslate"><span class="pre">qemu-arm</span></code>.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_EMULATOR="qemu-arm</span> <span class="pre">-L</span> <span class="pre">/path/to/armhf/sysroot</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_INCLUDE_TESTS=ON</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_TEST_COMPILER="/path/to/clang"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_TEST_COMPILER_CFLAGS="test-c-flags"</span></code></li>
+</ul>
+<p>The <code class="docutils literal notranslate"><span class="pre">/path/to/armhf/sysroot</span></code> should be the same as the one passed to
+<code class="docutils literal notranslate"><span class="pre">--sysroot</span></code> in the âbuild-c-flagsâ.</p>
+<p>The âtest-c-flagsâ need to include the target, architecture, gcc-toolchain,
+sysroot and arm/thumb state. The additional cmake defines such as
+<code class="docutils literal notranslate"><span class="pre">CMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN</span></code> do not apply when building the tests. If
+you have put all of these in âbuild-c-flagsâ then these can be repeated. If you
+wish to use lld to link the tests then add <code class="docutils literal notranslate"><span class="pre">"-fuse-ld=lld</span></code>.</p>
+<p>Once cmake has completed the tests can be built and run using
+<code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">check-builtins</span></code></p>
+</div>
+<div class="section" id="troubleshooting">
+<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="the-cmake-try-compile-stage-fails">
+<h3>The cmake try compile stage fails<a class="headerlink" href="#the-cmake-try-compile-stage-fails" title="Permalink to this headline">¶</a></h3>
+<p>At an early stage cmake will attempt to compile and link a simple C program to
+test if the toolchain is working.</p>
+<p>This stage can often fail at link time if the <code class="docutils literal notranslate"><span class="pre">--sysroot</span></code> and
+<code class="docutils literal notranslate"><span class="pre">--gcc-toolchain</span></code> options are not passed to the compiler. Check the
+<code class="docutils literal notranslate"><span class="pre">CMAKE_C_FLAGS</span></code> and <code class="docutils literal notranslate"><span class="pre">CMAKE_C_COMPILER_TARGET</span></code> flags.</p>
+<p>It can be useful to build a simple example outside of cmake with your toolchain
+to make sure it is working. For example: <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">--target=arm-linux-gnueabi</span> <span class="pre">-march=armv7a</span> <span class="pre">--gcc-toolchain=/path/to/gcc-toolchain</span> <span class="pre">--sysroot=/path/to/gcc-toolchain/arm-linux-gnueabihf/libc</span> <span class="pre">helloworld.c</span></code></p>
+</div>
+<div class="section" id="clang-uses-the-host-header-files">
+<h3>Clang uses the host header files<a class="headerlink" href="#clang-uses-the-host-header-files" title="Permalink to this headline">¶</a></h3>
+<p>On debian based systems it is possible to install multiarch support for
+arm-linux-gnueabi and arm-linux-gnueabihf. In many cases clang can successfully
+use this multiarch support when -gcc-toolchain and âsysroot are not supplied.
+Unfortunately clang adds <code class="docutils literal notranslate"><span class="pre">/usr/local/include</span></code> before
+<code class="docutils literal notranslate"><span class="pre">/usr/include/arm-linux-gnueabihf</span></code> leading to errors when compiling the hosts
+header files.</p>
+<p>The multiarch support is not sufficient to build the builtins you will need to
+use a separate arm-linux-gnueabihf toolchain.</p>
+</div>
+<div class="section" id="no-target-passed-to-clang">
+<h3>No target passed to clang<a class="headerlink" href="#no-target-passed-to-clang" title="Permalink to this headline">¶</a></h3>
+<p>If clang is not given a target it will typically use the host target, this will
+not understand the Arm assembly language files resulting in error messages such
+as <code class="docutils literal notranslate"><span class="pre">error:</span> <span class="pre">unknown</span> <span class="pre">directive</span> <span class="pre">.syntax</span> <span class="pre">unified</span></code>.</p>
+<p>You can check the clang invocation in the error message to see if there is no
+<code class="docutils literal notranslate"><span class="pre">--target</span></code> or if it is set incorrectly. The cause is usually
+<code class="docutils literal notranslate"><span class="pre">CMAKE_ASM_FLAGS</span></code> not containing <code class="docutils literal notranslate"><span class="pre">--target</span></code> or <code class="docutils literal notranslate"><span class="pre">CMAKE_ASM_COMPILER_TARGET</span></code> not being present.</p>
+</div>
+<div class="section" id="arm-architecture-not-given">
+<h3>Arm architecture not given<a class="headerlink" href="#arm-architecture-not-given" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">--target=arm-linux-gnueabihf</span></code> will default to arm architecture v4t which
+cannot assemble the barrier instructions used in the synch_and_fetch source
+files.</p>
+<p>The cause is usually a missing <code class="docutils literal notranslate"><span class="pre">-march=armv7a</span></code> from the <code class="docutils literal notranslate"><span class="pre">CMAKE_ASM_FLAGS</span></code>.</p>
+</div>
+<div class="section" id="compiler-rt-builds-but-the-tests-fail-to-build">
+<h3>Compiler-rt builds but the tests fail to build<a class="headerlink" href="#compiler-rt-builds-but-the-tests-fail-to-build" title="Permalink to this headline">¶</a></h3>
+<p>The flags used to build the tests are not the same as those used to build the
+builtins. The c flags are provided by <code class="docutils literal notranslate"><span class="pre">COMPILER_RT_TEST_COMPILE_CFLAGS</span></code> and
+the <code class="docutils literal notranslate"><span class="pre">CMAKE_C_COMPILER_TARGET</span></code>, <code class="docutils literal notranslate"><span class="pre">CMAKE_ASM_COMPILER_TARGET</span></code>,
+<code class="docutils literal notranslate"><span class="pre">CMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN</span></code> and <code class="docutils literal notranslate"><span class="pre">CMAKE_SYSROOT</span></code> flags are not
+applied.</p>
+<p>Make sure that <code class="docutils literal notranslate"><span class="pre">COMPILER_RT_TEST_COMPILE_CFLAGS</span></code> contains all the necessary
+information.</p>
+</div>
+</div>
+<div class="section" id="modifications-for-other-targets">
+<h2>Modifications for other Targets<a class="headerlink" href="#modifications-for-other-targets" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="arm-soft-float-target">
+<h3>Arm Soft-Float Target<a class="headerlink" href="#arm-soft-float-target" title="Permalink to this headline">¶</a></h3>
+<p>The instructions for the Arm hard-float target can be used for the soft-float
+target by substituting soft-float equivalents for the sysroot and target. The
+target to use is:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER_TARGET=arm-linux-gnueabi</span></code></li>
+</ul>
+<p>Depending on whether you want to use floating point instructions or not you
+may need extra c-flags such as <code class="docutils literal notranslate"><span class="pre">-mfloat-abi=softfp</span></code> for use of floating-point
+instructions, and <code class="docutils literal notranslate"><span class="pre">-mfloat-abi=soft</span> <span class="pre">-mfpu=none</span></code> for software floating-point
+emulation.</p>
+<p>You will need to use an arm-linux-gnueabi GNU toolchain for soft-float.</p>
+</div>
+<div class="section" id="aarch64-target">
+<h3>AArch64 Target<a class="headerlink" href="#aarch64-target" title="Permalink to this headline">¶</a></h3>
+<p>The instructions for Arm can be used for AArch64 by substituting AArch64
+equivalents for the sysroot, emulator and target.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER_TARGET=aarch64-linux-gnu</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_EMULATOR="qemu-aarch64</span> <span class="pre">-L</span> <span class="pre">/path/to/aarch64/sysroot</span></code></li>
+</ul>
+<p>The CMAKE_C_FLAGS and COMPILER_RT_TEST_COMPILER_CFLAGS may also need:
+<code class="docutils literal notranslate"><span class="pre">"--sysroot=/path/to/aarch64/sysroot</span> <span class="pre">--gcc-toolchain=/path/to/gcc-toolchain"</span></code></p>
+</div>
+<div class="section" id="armv6-m-armv7-m-and-armv7e-m-targets">
+<h3>Armv6-m, Armv7-m and Armv7E-M targets<a class="headerlink" href="#armv6-m-armv7-m-and-armv7e-m-targets" title="Permalink to this headline">¶</a></h3>
+<p>To build and test the libraries using a similar method to Armv7-A is possible
+but more difficult. The main problems are:</p>
+<ul class="simple">
+<li>There isnât a <code class="docutils literal notranslate"><span class="pre">qemu-arm</span></code> user-mode emulator for bare-metal systems. The <code class="docutils literal notranslate"><span class="pre">qemu-system-arm</span></code> can be used but this is significantly more difficult to setup.</li>
+<li>The targets to compile compiler-rt have the suffix -none-eabi. This uses the BareMetal driver in clang and by default wonât find the libraries needed to pass the cmake compiler check.</li>
+</ul>
+<p>As the Armv6-M, Armv7-M and Armv7E-M builds of compiler-rt only use instructions
+that are supported on Armv7-A we can still get most of the value of running the
+tests using the same <code class="docutils literal notranslate"><span class="pre">qemu-arm</span></code> that we used for Armv7-A by building and
+running the test cases for Armv7-A but using the builtins compiled for
+Armv6-M, Armv7-M or Armv7E-M. This will test that the builtins can be linked
+into a binary and execute the tests correctly but it will not catch if the
+builtins use instructions that are supported on Armv7-A but not Armv6-M,
+Armv7-M and Armv7E-M.</p>
+<p>To get the cmake compile test to pass you will need to pass the libraries
+needed to successfully link the cmake test via <code class="docutils literal notranslate"><span class="pre">CMAKE_CFLAGS</span></code>. It is
+strongly recommended that you use version 3.6 or above of cmake so you can use
+<code class="docutils literal notranslate"><span class="pre">CMAKE_TRY_COMPILE_TARGET=STATIC_LIBRARY</span></code> to skip the link step.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_OS_DIR="baremetal"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_BUILTINS=ON</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_SANITIZERS=OFF</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_XRAY=OFF</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_LIBFUZZER=OFF</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BUILD_PROFILE=OFF</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER=${host_install_dir}/bin/clang</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER_TARGET="your</span> <span class="pre">*-none-eabi</span> <span class="pre">target"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_ASM_COMPILER_TARGET="your</span> <span class="pre">*-none-eabi</span> <span class="pre">target"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_AR=/path/to/llvm-ar</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_NM=/path/to/llvm-nm</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_RANLIB=/path/to/llvm-ranlib</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_BAREMETAL_BUILD=ON</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_CONFIG_PATH=/path/to/llvm-config</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_FLAGS="build-c-flags"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_ASM_FLAGS="build-c-flags"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_EMULATOR="qemu-arm</span> <span class="pre">-L</span> <span class="pre">/path/to/armv7-A/sysroot"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_INCLUDE_TESTS=ON</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_TEST_COMPILER="/path/to/clang"</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCOMPILER_RT_TEST_COMPILER_CFLAGS="test-c-flags"</span></code></li>
+</ul>
+<p>The Armv6-M builtins will use the soft-float ABI. When compiling the tests for
+Armv7-A we must include <code class="docutils literal notranslate"><span class="pre">"-mthumb</span> <span class="pre">-mfloat-abi=soft</span> <span class="pre">-mfpu=none"</span></code> in the
+test-c-flags. We must use an Armv7-A soft-float abi sysroot for <code class="docutils literal notranslate"><span class="pre">qemu-arm</span></code>.</p>
+<p>Depending on the linker used for the test cases you may encounter BuildAttribute
+mismatches between the M-profile objects from compiler-rt and the A-profile
+objects from the test. The lld linker does not check the profile
+BuildAttribute so it can be used to link the tests by adding -fuse-ld=lld to the
+<code class="docutils literal notranslate"><span class="pre">COMPILER_RT_TEST_COMPILER_CFLAGS</span></code>.</p>
+</div>
+<div class="section" id="alternative-using-a-cmake-cache">
+<h3>Alternative using a cmake cache<a class="headerlink" href="#alternative-using-a-cmake-cache" title="Permalink to this headline">¶</a></h3>
+<p>If you wish to build, but not test compiler-rt for Armv6-M, Armv7-M or Armv7E-M
+the easiest way is to use the BaremetalARM.cmake recipe in clang/cmake/caches.</p>
+<p>You will need a bare metal sysroot such as that provided by the GNU ARM
+Embedded toolchain.</p>
+<p>The libraries can be built with the cmake options:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DBAREMETAL_ARMV6M_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DBAREMETAL_ARMV7M_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DBAREMETAL_ARMV7EM_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-C</span> <span class="pre">/path/to/llvm/source/tools/clang/cmake/caches/BaremetalARM.cmake</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">/path/to/llvm</span></code></li>
+</ul>
+<p><strong>Note</strong> that for the recipe to work the compiler-rt source must be checked out
+into the directory llvm/runtimes. You will also need clang and lld checked out.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToCrossCompileLLVM.html" title="How To Cross-Compile Clang/LLVM using Clang/LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToBuildWithPGO.html" title="How To Build Clang and LLVM with Profile-Guided Optimizations"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToCrossCompileLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToCrossCompileLLVM.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToCrossCompileLLVM.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToCrossCompileLLVM.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,277 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Cross-Compile Clang/LLVM using Clang/LLVM — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVM Command Guide" href="CommandGuide/index.html" />
+ <link rel="prev" title="How to Cross Compile Compiler-rt Builtins For Arm" href="HowToCrossCompileBuiltinsOnArm.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="CommandGuide/index.html" title="LLVM Command Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToCrossCompileBuiltinsOnArm.html" title="How to Cross Compile Compiler-rt Builtins For Arm"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-cross-compile-clang-llvm-using-clang-llvm">
+<h1>How To Cross-Compile Clang/LLVM using Clang/LLVM<a class="headerlink" href="#how-to-cross-compile-clang-llvm-using-clang-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about building LLVM and
+Clang on host machine, targeting another platform.</p>
+<p>For more information on how to use Clang as a cross-compiler,
+please check <a class="reference external" href="http://clang.llvm.org/docs/CrossCompilation.html">http://clang.llvm.org/docs/CrossCompilation.html</a>.</p>
+<p>TODO: Add MIPS and other platforms to this document.</p>
+</div>
+<div class="section" id="cross-compiling-from-x86-64-to-arm">
+<h2>Cross-Compiling from x86_64 to ARM<a class="headerlink" href="#cross-compiling-from-x86-64-to-arm" title="Permalink to this headline">¶</a></h2>
+<p>In this use case, weâll be using CMake and Ninja, on a Debian-based Linux
+system, cross-compiling from an x86_64 host (most Intel and AMD chips
+nowadays) to a hard-float ARM target (most ARM targets nowadays).</p>
+<p>The packages youâll need are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">cmake</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">ninja-build</span></code> (from backports in Ubuntu)</li>
+<li><code class="docutils literal notranslate"><span class="pre">gcc-4.7-arm-linux-gnueabihf</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">gcc-4.7-multilib-arm-linux-gnueabihf</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">binutils-arm-linux-gnueabihf</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">libgcc1-armhf-cross</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">libsfgcc1-armhf-cross</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">libstdc++6-armhf-cross</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">libstdc++6-4.7-dev-armhf-cross</span></code></li>
+</ul>
+</div></blockquote>
+<div class="section" id="configuring-cmake">
+<h3>Configuring CMake<a class="headerlink" href="#configuring-cmake" title="Permalink to this headline">¶</a></h3>
+<p>For more information on how to configure CMake for LLVM/Clang,
+see <a class="reference internal" href="CMake.html"><span class="doc">Building LLVM with CMake</span></a>.</p>
+<p>The CMake options you need to add are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_CROSSCOMPILING=True</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_INSTALL_PREFIX=<install-dir></span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_TARGET_ARCH=ARM</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-DLLVM_TARGETS_TO_BUILD=ARM</span></code></li>
+</ul>
+</div></blockquote>
+<p>If youâre compiling with GCC, you can use architecture options for your target,
+and the compiler driver will detect everything that it needs:</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-DCMAKE_CXX_FLAGS='-march=armv7-a</span> <span class="pre">-mcpu=cortex-a9</span> <span class="pre">-mfloat-abi=hard'</span></code></li>
+</ul>
+</div></blockquote>
+<p>However, if youâre using Clang, the driver might not be up-to-date with your
+specific Linux distribution, version or GCC layout, so youâll need to fudge.</p>
+<p>In addition to the ones above, youâll also need:</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">'-target</span> <span class="pre">arm-linux-gnueabihf'</span></code> or whatever is the triple of your cross GCC.</li>
+<li><code class="docutils literal notranslate"><span class="pre">'--sysroot=/usr/arm-linux-gnueabihf'</span></code>, <code class="docutils literal notranslate"><span class="pre">'--sysroot=/opt/gcc/arm-linux-gnueabihf'</span></code>
+or whatever is the location of your GCCâs sysroot (where /lib, /bin etc are).</li>
+<li>Appropriate use of <code class="docutils literal notranslate"><span class="pre">-I</span></code> and <code class="docutils literal notranslate"><span class="pre">-L</span></code>, depending on how the cross GCC is installed,
+and where are the libraries and headers.</li>
+</ul>
+</div></blockquote>
+<p>The TableGen options are required to compile it with the host compiler,
+so youâll need to compile LLVM (or at least <code class="docutils literal notranslate"><span class="pre">llvm-tblgen</span></code>) to your host
+platform before you start. The CXX flags define the target, cpu (which in this case
+defaults to <code class="docutils literal notranslate"><span class="pre">fpu=VFP3</span></code> with NEON), and forcing the hard-float ABI. If youâre
+using Clang as a cross-compiler, you will <em>also</em> have to set <code class="docutils literal notranslate"><span class="pre">--sysroot</span></code>
+to make sure it picks the correct linker.</p>
+<p>When using Clang, itâs important that you choose the triple to be <em>identical</em>
+to the GCC triple and the sysroot. This will make it easier for Clang to
+find the correct tools and include headers. But that wonât mean all headers and
+libraries will be found. Youâll still need to use <code class="docutils literal notranslate"><span class="pre">-I</span></code> and <code class="docutils literal notranslate"><span class="pre">-L</span></code> to locate
+those extra ones, depending on your distribution.</p>
+<p>Most of the time, what you want is to have a native compiler to the
+platform itself, but not others. So thereâs rarely a point in compiling
+all back-ends. For that reason, you should also set the
+<code class="docutils literal notranslate"><span class="pre">TARGETS_TO_BUILD</span></code> to only build the back-end youâre targeting to.</p>
+<p>You must set the <code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code>, otherwise a <code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">install</span></code>
+will copy ARM binaries to your root filesystem, which is not what you
+want.</p>
+</div>
+<div class="section" id="hacks">
+<h3>Hacks<a class="headerlink" href="#hacks" title="Permalink to this headline">¶</a></h3>
+<p>There are some bugs in current LLVM, which require some fiddling before
+running CMake:</p>
+<ol class="arabic">
+<li><p class="first">If youâre using Clang as the cross-compiler, there is a problem in
+the LLVM ARM back-end that is producing absolute relocations on
+position-independent code (<code class="docutils literal notranslate"><span class="pre">R_ARM_THM_MOVW_ABS_NC</span></code>), so for now, you
+should disable PIC:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DLLVM_ENABLE_PIC<span class="o">=</span>False
+</pre></div>
+</div>
+<p>This is not a problem, since Clang/LLVM libraries are statically
+linked anyway, it shouldnât affect much.</p>
+</li>
+<li><p class="first">The ARM libraries wonât be installed in your system.
+But the CMake prepare step, which checks for
+dependencies, will check the <em>host</em> libraries, not the <em>target</em>
+ones. Below thereâs a list of some dependencies, but your project could
+have more, or this document could be outdated. Youâll see the errors
+while linking as an indication of that.</p>
+<p>Debian based distros have a way to add <code class="docutils literal notranslate"><span class="pre">multiarch</span></code>, which adds
+a new architecture and allows you to install packages for those
+systems. See <a class="reference external" href="https://wiki.debian.org/Multiarch/HOWTO">https://wiki.debian.org/Multiarch/HOWTO</a> for more info.</p>
+<p>But not all distros will have that, and possibly not an easy way to
+install them in any anyway, so youâll have to build/download
+them separately.</p>
+<p>A quick way of getting the libraries is to download them from
+a distribution repository, like Debian (<a class="reference external" href="http://packages.debian.org/jessie/">http://packages.debian.org/jessie/</a>),
+and download the missing libraries. Note that the <code class="docutils literal notranslate"><span class="pre">libXXX</span></code>
+will have the shared objects (<code class="docutils literal notranslate"><span class="pre">.so</span></code>) and the <code class="docutils literal notranslate"><span class="pre">libXXX-dev</span></code> will
+give you the headers and the static (<code class="docutils literal notranslate"><span class="pre">.a</span></code>) library. Just in
+case, download both.</p>
+<p>The ones you need for ARM are: <code class="docutils literal notranslate"><span class="pre">libtinfo</span></code>, <code class="docutils literal notranslate"><span class="pre">zlib1g</span></code>,
+<code class="docutils literal notranslate"><span class="pre">libxml2</span></code> and <code class="docutils literal notranslate"><span class="pre">liblzma</span></code>. In the Debian repository youâll
+find downloads for all architectures.</p>
+<p>After you download and unpack all <code class="docutils literal notranslate"><span class="pre">.deb</span></code> packages, copy all
+<code class="docutils literal notranslate"><span class="pre">.so</span></code> and <code class="docutils literal notranslate"><span class="pre">.a</span></code> to a directory, make the appropriate
+symbolic links (if necessary), and add the relevant <code class="docutils literal notranslate"><span class="pre">-L</span></code>
+and <code class="docutils literal notranslate"><span class="pre">-I</span></code> paths to <code class="docutils literal notranslate"><span class="pre">-DCMAKE_CXX_FLAGS</span></code> above.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="running-cmake-and-building">
+<h3>Running CMake and Building<a class="headerlink" href="#running-cmake-and-building" title="Permalink to this headline">¶</a></h3>
+<p>Finally, if youâre using your platform compiler, run:</p>
+<blockquote>
+<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ cmake -G Ninja <source-dir> <options above>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If youâre using Clang as the cross-compiler, run:</p>
+<blockquote>
+<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nv">CC</span><span class="o">=</span><span class="s1">'clang'</span> <span class="nv">CXX</span><span class="o">=</span><span class="s1">'clang++'</span> cmake -G Ninja <source-dir> <options above>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If you have <code class="docutils literal notranslate"><span class="pre">clang</span></code>/<code class="docutils literal notranslate"><span class="pre">clang++</span></code> on the path, it should just work, and special
+Ninja files will be created in the build directory. I strongly suggest
+you to run <code class="docutils literal notranslate"><span class="pre">cmake</span></code> on a separate build directory, <em>not</em> inside the
+source tree.</p>
+<p>To build, simply type:</p>
+<blockquote>
+<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ ninja
+</pre></div>
+</div>
+</div></blockquote>
+<p>It should automatically find out how many cores you have, what are
+the rules that needs building and will build the whole thing.</p>
+<p>You canât run <code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">check-all</span></code> on this tree because the created
+binaries are targeted to ARM, not x86_64.</p>
+</div>
+<div class="section" id="installing-and-using">
+<h3>Installing and Using<a class="headerlink" href="#installing-and-using" title="Permalink to this headline">¶</a></h3>
+<p>After the LLVM/Clang has built successfully, you should install it
+via:</p>
+<blockquote>
+<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ ninja install
+</pre></div>
+</div>
+</div></blockquote>
+<p>which will create a sysroot on the install-dir. You can then tar
+that directory into a binary with the full triple name (for easy
+identification), like:</p>
+<blockquote>
+<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ ln -sf <install-dir> arm-linux-gnueabihf-clang
+$ tar zchf arm-linux-gnueabihf-clang.tar.gz arm-linux-gnueabihf-clang
+</pre></div>
+</div>
+</div></blockquote>
+<p>If you copy that tarball to your target board, youâll be able to use
+it for running the test-suite, for example. Follow the guidelines at
+<a class="reference external" href="http://llvm.org/docs/lnt/quickstart.html">http://llvm.org/docs/lnt/quickstart.html</a>, unpack the tarball in the
+test directory, and use options:</p>
+<blockquote>
+<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ ./sandbox/bin/python sandbox/bin/lnt runtest nt <span class="se">\</span>
+ --sandbox sandbox <span class="se">\</span>
+ --test-suite <span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span>/test-suite <span class="se">\</span>
+ --cc <span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span>/arm-linux-gnueabihf-clang/bin/clang <span class="se">\</span>
+ --cxx <span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span>/arm-linux-gnueabihf-clang/bin/clang++
+</pre></div>
+</div>
+</div></blockquote>
+<p>Remember to add the <code class="docutils literal notranslate"><span class="pre">-jN</span></code> options to <code class="docutils literal notranslate"><span class="pre">lnt</span></code> to the number of CPUs
+on your board. Also, the path to your clang has to be absolute, so
+youâll need the <cite>pwd</cite> trick above.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="CommandGuide/index.html" title="LLVM Command Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToCrossCompileBuiltinsOnArm.html" title="How to Cross Compile Compiler-rt Builtins For Arm"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToReleaseLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToReleaseLLVM.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToReleaseLLVM.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToReleaseLLVM.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,429 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Release LLVM To The Public — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Advice on Packaging LLVM" href="Packaging.html" />
+ <link rel="prev" title="LLVMBuild Guide" href="LLVMBuild.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Packaging.html" title="Advice on Packaging LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LLVMBuild.html" title="LLVMBuild Guide"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-release-llvm-to-the-public">
+<h1>How To Release LLVM To The Public<a class="headerlink" href="#how-to-release-llvm-to-the-public" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about successfully releasing LLVM â
+including sub-projects: e.g., <code class="docutils literal notranslate"><span class="pre">clang</span></code> and <code class="docutils literal notranslate"><span class="pre">compiler-rt</span></code> â to the public.
+It is the Release Managerâs responsibility to ensure that a high quality build
+of LLVM is released.</p>
+<p>If youâre looking for the document on how to test the release candidates and
+create the binary packages, please refer to the <a class="reference internal" href="ReleaseProcess.html"><span class="doc">How To Validate a New Release</span></a> instead.</p>
+</div>
+<div class="section" id="release-timeline">
+<span id="timeline"></span><h2>Release Timeline<a class="headerlink" href="#release-timeline" title="Permalink to this headline">¶</a></h2>
+<p>LLVM is released on a time based schedule â with major releases roughly
+every 6 months. In between major releases there may be dot releases.
+The release manager will determine if and when to make a dot release based
+on feedback from the community. Typically, dot releases should be made if
+there are large number of bug-fixes in the stable branch or a critical bug
+has been discovered that affects a large number of users.</p>
+<p>Unless otherwise stated, dot releases will follow the same procedure as
+major releases.</p>
+<p>The release process is roughly as follows:</p>
+<ul class="simple">
+<li>Set code freeze and branch creation date for 6 months after last code freeze
+date. Announce release schedule to the LLVM community and update the website.</li>
+<li>Create release branch and begin release process.</li>
+<li>Send out release candidate sources for first round of testing. Testing lasts
+7-10 days. During the first round of testing, any regressions found should be
+fixed. Patches are merged from mainline into the release branch. Also, all
+features need to be completed during this time. Any features not completed at
+the end of the first round of testing will be removed or disabled for the
+release.</li>
+<li>Generate and send out the second release candidate sources. Only <em>critical</em>
+bugs found during this testing phase will be fixed. Any bugs introduced by
+merged patches will be fixed. If so a third round of testing is needed.</li>
+<li>The release notes are updated.</li>
+<li>Finally, release!</li>
+</ul>
+<p>The release process will be accelerated for dot releases. If the first round
+of testing finds no critical bugs and no regressions since the last major release,
+then additional rounds of testing will not be required.</p>
+</div>
+<div class="section" id="release-process">
+<h2>Release Process<a class="headerlink" href="#release-process" title="Permalink to this headline">¶</a></h2>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#release-administrative-tasks" id="id1">Release Administrative Tasks</a><ul>
+<li><a class="reference internal" href="#create-release-branch" id="id2">Create Release Branch</a></li>
+<li><a class="reference internal" href="#update-llvm-version" id="id3">Update LLVM Version</a></li>
+<li><a class="reference internal" href="#tagging-the-llvm-release-candidates" id="id4">Tagging the LLVM Release Candidates</a></li>
+<li><a class="reference internal" href="#build-clang-binary-distribution" id="id5">Build Clang Binary Distribution</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#release-qualification-criteria" id="id6">Release Qualification Criteria</a></li>
+<li><a class="reference internal" href="#official-testing" id="id7">Official Testing</a></li>
+<li><a class="reference internal" href="#community-testing" id="id8">Community Testing</a></li>
+<li><a class="reference internal" href="#reporting-regressions" id="id9">Reporting Regressions</a></li>
+<li><a class="reference internal" href="#merge-requests" id="id10">Merge Requests</a></li>
+<li><a class="reference internal" href="#release-patch-rules" id="id11">Release Patch Rules</a><ul>
+<li><a class="reference internal" href="#merging-patches" id="id12">Merging Patches</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#release-final-tasks" id="id13">Release Final Tasks</a><ul>
+<li><a class="reference internal" href="#update-documentation" id="id14">Update Documentation</a></li>
+<li><a class="reference internal" href="#tag-the-llvm-final-release" id="id15">Tag the LLVM Final Release</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#update-the-llvm-demo-page" id="id16">Update the LLVM Demo Page</a><ul>
+<li><a class="reference internal" href="#update-the-llvm-website" id="id17">Update the LLVM Website</a></li>
+<li><a class="reference internal" href="#announce-the-release" id="id18">Announce the Release</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="release-administrative-tasks">
+<h3><a class="toc-backref" href="#id1">Release Administrative Tasks</a><a class="headerlink" href="#release-administrative-tasks" title="Permalink to this headline">¶</a></h3>
+<p>This section describes a few administrative tasks that need to be done for the
+release process to begin. Specifically, it involves:</p>
+<ul class="simple">
+<li>Creating the release branch,</li>
+<li>Setting version numbers, and</li>
+<li>Tagging release candidates for the release team to begin testing.</li>
+</ul>
+<div class="section" id="create-release-branch">
+<h4><a class="toc-backref" href="#id2">Create Release Branch</a><a class="headerlink" href="#create-release-branch" title="Permalink to this headline">¶</a></h4>
+<p>Branch the Subversion trunk using the following procedure:</p>
+<ol class="arabic">
+<li><p class="first">Remind developers that the release branching is imminent and to refrain from
+committing patches that might break the build. E.g., new features, large
+patches for works in progress, an overhaul of the type system, an exciting
+new TableGen feature, etc.</p>
+</li>
+<li><p class="first">Verify that the current Subversion trunk is in decent shape by
+examining nightly tester and buildbot results.</p>
+</li>
+<li><p class="first">Create the release branch for <code class="docutils literal notranslate"><span class="pre">llvm</span></code>, <code class="docutils literal notranslate"><span class="pre">clang</span></code>, and other sub-projects,
+from the last known good revision. The branchâs name is
+<code class="docutils literal notranslate"><span class="pre">release_XY</span></code>, where <code class="docutils literal notranslate"><span class="pre">X</span></code> is the major and <code class="docutils literal notranslate"><span class="pre">Y</span></code> the minor release
+numbers. Use <code class="docutils literal notranslate"><span class="pre">utils/release/tag.sh</span></code> to tag the release.</p>
+</li>
+<li><p class="first">Advise developers that they may now check their patches into the Subversion
+tree again.</p>
+</li>
+<li><p class="first">The Release Manager should switch to the release branch, because all changes
+to the release will now be done in the branch. The easiest way to do this is
+to grab a working copy using the following commands:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XY llvm-X.Y
+
+$ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XY clang-X.Y
+
+$ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XY test-suite-X.Y
+</pre></div>
+</div>
+</li>
+</ol>
+</div>
+<div class="section" id="update-llvm-version">
+<h4><a class="toc-backref" href="#id3">Update LLVM Version</a><a class="headerlink" href="#update-llvm-version" title="Permalink to this headline">¶</a></h4>
+<p>After creating the LLVM release branch, update the release branchesâ
+<code class="docutils literal notranslate"><span class="pre">autoconf</span></code> and <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code> versions from â<code class="docutils literal notranslate"><span class="pre">X.Ysvn</span></code>â to â<code class="docutils literal notranslate"><span class="pre">X.Y</span></code>â.
+Update it on mainline as well to be the next version (â<code class="docutils literal notranslate"><span class="pre">X.Y+1svn</span></code>â).
+Regenerate the configure scripts for both <code class="docutils literal notranslate"><span class="pre">llvm</span></code> and the <code class="docutils literal notranslate"><span class="pre">test-suite</span></code>.</p>
+<p>In addition, the version numbers of all the Bugzilla components must be updated
+for the next release.</p>
+</div>
+<div class="section" id="tagging-the-llvm-release-candidates">
+<h4><a class="toc-backref" href="#id4">Tagging the LLVM Release Candidates</a><a class="headerlink" href="#tagging-the-llvm-release-candidates" title="Permalink to this headline">¶</a></h4>
+<p>Tag release candidates using the tag.sh script in utils/release.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./tag.sh -release X.Y.Z -rc $RC
+</pre></div>
+</div>
+<p>The Release Manager may supply pre-packaged source tarballs for users. This can
+be done with the export.sh script in utils/release.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./export.sh -release X.Y.Z -rc $RC
+</pre></div>
+</div>
+<p>This will generate source tarballs for each LLVM project being validated, which
+can be uploaded to the website for further testing.</p>
+</div>
+<div class="section" id="build-clang-binary-distribution">
+<h4><a class="toc-backref" href="#id5">Build Clang Binary Distribution</a><a class="headerlink" href="#build-clang-binary-distribution" title="Permalink to this headline">¶</a></h4>
+<p>Creating the <code class="docutils literal notranslate"><span class="pre">clang</span></code> binary distribution requires following the instructions
+<a class="reference internal" href="ReleaseProcess.html"><span class="doc">here</span></a>.</p>
+<p>That process will perform both Release+Asserts and Release builds but only
+pack the Release build for upload. You should use the Release+Asserts sysroot,
+normally under <code class="docutils literal notranslate"><span class="pre">final/Phase3/Release+Asserts/llvmCore-3.8.1-RCn.install/</span></code>,
+for test-suite and run-time benchmarks, to make sure nothing serious has
+passed through the net. For compile-time benchmarks, use the Release version.</p>
+<p>The minimum required version of the tools youâll need are <a class="reference internal" href="GettingStarted.html"><span class="doc">here</span></a></p>
+</div>
+</div>
+<div class="section" id="release-qualification-criteria">
+<h3><a class="toc-backref" href="#id6">Release Qualification Criteria</a><a class="headerlink" href="#release-qualification-criteria" title="Permalink to this headline">¶</a></h3>
+<p>A release is qualified when it has no regressions from the previous release (or
+baseline). Regressions are related to correctness first and performance second.
+(We may tolerate some minor performance regressions if they are deemed
+necessary for the general quality of the compiler.)</p>
+<p>More specifically, Clang/LLVM is qualified when it has a clean test with all
+supported sub-projects included (<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">check-all</span></code>), per target, and it has no
+regressions with the <code class="docutils literal notranslate"><span class="pre">test-suite</span></code> in relation to the previous release.</p>
+<p>Regressions are new failures in the set of tests that are used to qualify
+each product and only include things on the list. Every release will have
+some bugs in it. It is the reality of developing a complex piece of
+software. We need a very concrete and definitive release criteria that
+ensures we have monotonically improving quality on some metric. The metric we
+use is described below. This doesnât mean that we donât care about other
+criteria, but these are the criteria which we found to be most important and
+which must be satisfied before a release can go out.</p>
+</div>
+<div class="section" id="official-testing">
+<h3><a class="toc-backref" href="#id7">Official Testing</a><a class="headerlink" href="#official-testing" title="Permalink to this headline">¶</a></h3>
+<p>A few developers in the community have dedicated time to validate the release
+candidates and volunteered to be the official release testers for each
+architecture.</p>
+<p>These will be the ones testing, generating and uploading the official binaries
+to the server, and will be the minimum tests <em>necessary</em> for the release to
+proceed.</p>
+<p>This will obviously not cover all OSs and distributions, so additional community
+validation is important. However, if community input is not reached before the
+release is out, all bugs reported will have to go on the next stable release.</p>
+<p>The official release managers are:</p>
+<ul class="simple">
+<li>Major releases (X.0): Hans Wennborg</li>
+<li>Stable releases (X.n): Tom Stellard</li>
+</ul>
+<p>The official release testers are volunteered from the community and have
+consistently validated and released binaries for their targets/OSs. To contact
+them, you should email the <code class="docutils literal notranslate"><span class="pre">release-testers@lists.llvm.org</span></code> mailing list.</p>
+<p>The official testers list is in the file <code class="docutils literal notranslate"><span class="pre">RELEASE_TESTERS.TXT</span></code>, in the <code class="docutils literal notranslate"><span class="pre">LLVM</span></code>
+repository.</p>
+</div>
+<div class="section" id="community-testing">
+<h3><a class="toc-backref" href="#id8">Community Testing</a><a class="headerlink" href="#community-testing" title="Permalink to this headline">¶</a></h3>
+<p>Once all testing has been completed and appropriate bugs filed, the release
+candidate tarballs are put on the website and the LLVM community is notified.</p>
+<p>We ask that all LLVM developers test the release in any the following ways:</p>
+<ol class="arabic simple">
+<li>Download <code class="docutils literal notranslate"><span class="pre">llvm-X.Y</span></code>, <code class="docutils literal notranslate"><span class="pre">llvm-test-X.Y</span></code>, and the appropriate <code class="docutils literal notranslate"><span class="pre">clang</span></code>
+binary. Build LLVM. Run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">check</span></code> and the full LLVM test suite (<code class="docutils literal notranslate"><span class="pre">make</span>
+<span class="pre">TEST=nightly</span> <span class="pre">report</span></code>).</li>
+<li>Download <code class="docutils literal notranslate"><span class="pre">llvm-X.Y</span></code>, <code class="docutils literal notranslate"><span class="pre">llvm-test-X.Y</span></code>, and the <code class="docutils literal notranslate"><span class="pre">clang</span></code> sources. Compile
+everything. Run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">check</span></code> and the full LLVM test suite (<code class="docutils literal notranslate"><span class="pre">make</span>
+<span class="pre">TEST=nightly</span> <span class="pre">report</span></code>).</li>
+<li>Download <code class="docutils literal notranslate"><span class="pre">llvm-X.Y</span></code>, <code class="docutils literal notranslate"><span class="pre">llvm-test-X.Y</span></code>, and the appropriate <code class="docutils literal notranslate"><span class="pre">clang</span></code>
+binary. Build whole programs with it (ex. Chromium, Firefox, Apache) for
+your platform.</li>
+<li>Download <code class="docutils literal notranslate"><span class="pre">llvm-X.Y</span></code>, <code class="docutils literal notranslate"><span class="pre">llvm-test-X.Y</span></code>, and the appropriate <code class="docutils literal notranslate"><span class="pre">clang</span></code>
+binary. Build <em>your</em> programs with it and check for conformance and
+performance regressions.</li>
+<li>Run the <a class="reference internal" href="ReleaseProcess.html"><span class="doc">release process</span></a>, if your platform is
+<em>different</em> than that which is officially supported, and report back errors
+only if they were not reported by the official release tester for that
+architecture.</li>
+</ol>
+<p>We also ask that the OS distribution release managers test their packages with
+the first candidate of every release, and report any <em>new</em> errors in Bugzilla.
+If the bug can be reproduced with an unpatched upstream version of the release
+candidate (as opposed to the distributionâs own build), the priority should be
+release blocker.</p>
+<p>During the first round of testing, all regressions must be fixed before the
+second release candidate is tagged.</p>
+<p>In the subsequent stages, the testing is only to ensure that bug
+fixes previously merged in have not created new major problems. <em>This is not
+the time to solve additional and unrelated bugs!</em> If no patches are merged in,
+the release is determined to be ready and the release manager may move onto the
+next stage.</p>
+</div>
+<div class="section" id="reporting-regressions">
+<h3><a class="toc-backref" href="#id9">Reporting Regressions</a><a class="headerlink" href="#reporting-regressions" title="Permalink to this headline">¶</a></h3>
+<p>Every regression that is found during the tests (as per the criteria above),
+should be filled in a bug in Bugzilla with the priority <em>release blocker</em> and
+blocking a specific release.</p>
+<p>To help manage all the bugs reported and which ones are blockers or not, a new
+â[meta]â bug should be created and all regressions <em>blocking</em> that Meta. Once
+all blockers are done, the Meta can be closed.</p>
+<p>If a bug canât be reproduced, or stops being a blocker, it should be removed
+from the Meta and its priority decreased to <em>normal</em>. Debugging can continue,
+but on trunk.</p>
+</div>
+<div class="section" id="merge-requests">
+<h3><a class="toc-backref" href="#id10">Merge Requests</a><a class="headerlink" href="#merge-requests" title="Permalink to this headline">¶</a></h3>
+<p>You can use any of the following methods to request that a revision from trunk
+be merged into a release branch:</p>
+<ol class="arabic simple">
+<li>Use the <code class="docutils literal notranslate"><span class="pre">utils/release/merge-request.sh</span></code> script which will automatically
+file a <a class="reference external" href="https://bugs.llvm.org/">bug</a> requesting that the patch be merged. e.g. To request revision
+12345 be merged into the branch for the 5.0.1 release:
+<code class="docutils literal notranslate"><span class="pre">llvm.src/utils/release/merge-request.sh</span> <span class="pre">-stable-version</span> <span class="pre">5.0</span> <span class="pre">-r</span> <span class="pre">12345</span> <span class="pre">-user</span> <span class="pre">bugzilla@example.com</span></code></li>
+<li>Manually file a <a class="reference external" href="https://bugs.llvm.org/">bug</a> with the subject: âMerge r12345 into the X.Y branchâ,
+enter the commit(s) that you want merged in the âFixed by Commit(s)â and mark
+it as a blocker of the current release bug. Release bugs are given aliases
+in the form of release-x.y.z, so to mark a bug as a blocker for the 5.0.1
+release, just enter release-5.0.1 in the âBlocksâ field.</li>
+<li>Reply to the commit email on llvm-commits for the revision to merge and cc
+the release manager.</li>
+</ol>
+</div>
+<div class="section" id="release-patch-rules">
+<h3><a class="toc-backref" href="#id11">Release Patch Rules</a><a class="headerlink" href="#release-patch-rules" title="Permalink to this headline">¶</a></h3>
+<p>Below are the rules regarding patching the release branch:</p>
+<ol class="arabic simple">
+<li>Patches applied to the release branch may only be applied by the release
+manager, the official release testers or the code owners with approval from
+the release manager.</li>
+<li>During the first round of testing, patches that fix regressions or that are
+small and relatively risk free (verified by the appropriate code owner) are
+applied to the branch. Code owners are asked to be very conservative in
+approving patches for the branch. We reserve the right to reject any patch
+that does not fix a regression as previously defined.</li>
+<li>During the remaining rounds of testing, only patches that fix critical
+regressions may be applied.</li>
+<li>For dot releases all patches must maintain both API and ABI compatibility with
+the previous major release. Only bug-fixes will be accepted.</li>
+</ol>
+<div class="section" id="merging-patches">
+<h4><a class="toc-backref" href="#id12">Merging Patches</a><a class="headerlink" href="#merging-patches" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">utils/release/merge.sh</span></code> script can be used to merge individual revisions
+into any one of the llvm projects. To merge revision <code class="docutils literal notranslate"><span class="pre">$N</span></code> into project
+<code class="docutils literal notranslate"><span class="pre">$PROJ</span></code>, do:</p>
+<ol class="arabic simple">
+<li><code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">https://llvm.org/svn/llvm-project/$PROJ/branches/release_XX</span>
+<span class="pre">$PROJ.src</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">$PROJ.src/utils/release/merge.sh</span> <span class="pre">--proj</span> <span class="pre">$PROJ</span> <span class="pre">--rev</span> <span class="pre">$N</span></code></li>
+<li>Run regression tests.</li>
+<li><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">$PROJ.src</span></code>. Run the <code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">commit</span></code> command printed out by <code class="docutils literal notranslate"><span class="pre">merge.sh</span></code>
+in step 2.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="release-final-tasks">
+<h3><a class="toc-backref" href="#id13">Release Final Tasks</a><a class="headerlink" href="#release-final-tasks" title="Permalink to this headline">¶</a></h3>
+<p>The final stages of the release process involves tagging the âfinalâ release
+branch, updating documentation that refers to the release, and updating the
+demo page.</p>
+<div class="section" id="update-documentation">
+<h4><a class="toc-backref" href="#id14">Update Documentation</a><a class="headerlink" href="#update-documentation" title="Permalink to this headline">¶</a></h4>
+<p>Review the documentation and ensure that it is up to date. The âRelease Notesâ
+must be updated to reflect new features, bug fixes, new known issues, and
+changes in the list of supported platforms. The âGetting Started Guideâ should
+be updated to reflect the new release version number tag available from
+Subversion and changes in basic system requirements. Merge both changes from
+mainline into the release branch.</p>
+</div>
+<div class="section" id="tag-the-llvm-final-release">
+<span id="tag"></span><h4><a class="toc-backref" href="#id15">Tag the LLVM Final Release</a><a class="headerlink" href="#tag-the-llvm-final-release" title="Permalink to this headline">¶</a></h4>
+<p>Tag the final release sources using the tag.sh script in utils/release.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./tag.sh -release X.Y.Z -final
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="update-the-llvm-demo-page">
+<h3><a class="toc-backref" href="#id16">Update the LLVM Demo Page</a><a class="headerlink" href="#update-the-llvm-demo-page" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM demo page must be updated to use the new release. This consists of
+using the new <code class="docutils literal notranslate"><span class="pre">clang</span></code> binary and building LLVM.</p>
+<div class="section" id="update-the-llvm-website">
+<h4><a class="toc-backref" href="#id17">Update the LLVM Website</a><a class="headerlink" href="#update-the-llvm-website" title="Permalink to this headline">¶</a></h4>
+<p>The website must be updated before the release announcement is sent out. Here
+is what to do:</p>
+<ol class="arabic simple">
+<li>Check out the <code class="docutils literal notranslate"><span class="pre">www</span></code> module from Subversion.</li>
+<li>Create a new sub-directory <code class="docutils literal notranslate"><span class="pre">X.Y</span></code> in the releases directory.</li>
+<li>Commit the <code class="docutils literal notranslate"><span class="pre">llvm</span></code>, <code class="docutils literal notranslate"><span class="pre">test-suite</span></code>, <code class="docutils literal notranslate"><span class="pre">clang</span></code> source and binaries in this
+new directory.</li>
+<li>Copy and commit the <code class="docutils literal notranslate"><span class="pre">llvm/docs</span></code> and <code class="docutils literal notranslate"><span class="pre">LICENSE.txt</span></code> files into this new
+directory. The docs should be built with <code class="docutils literal notranslate"><span class="pre">BUILD_FOR_WEBSITE=1</span></code>.</li>
+<li>Commit the <code class="docutils literal notranslate"><span class="pre">index.html</span></code> to the <code class="docutils literal notranslate"><span class="pre">release/X.Y</span></code> directory to redirect (use
+from previous release).</li>
+<li>Update the <code class="docutils literal notranslate"><span class="pre">releases/download.html</span></code> file with the new release.</li>
+<li>Update the <code class="docutils literal notranslate"><span class="pre">releases/index.html</span></code> with the new release and link to release
+documentation.</li>
+<li>Finally, update the main page (<code class="docutils literal notranslate"><span class="pre">index.html</span></code> and sidebar) to point to the
+new release and release announcement. Make sure this all gets committed back
+into Subversion.</li>
+</ol>
+</div>
+<div class="section" id="announce-the-release">
+<h4><a class="toc-backref" href="#id18">Announce the Release</a><a class="headerlink" href="#announce-the-release" title="Permalink to this headline">¶</a></h4>
+<p>Send an email to the list announcing the release, pointing people to all the
+relevant documentation, download pages and bugs fixed.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Packaging.html" title="Advice on Packaging LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LLVMBuild.html" title="LLVMBuild Guide"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToSetUpLLVMStyleRTTI.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToSetUpLLVMStyleRTTI.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToSetUpLLVMStyleRTTI.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToSetUpLLVMStyleRTTI.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,464 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How to set up LLVM-style RTTI for your class hierarchy — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVM Programmerâs Manual" href="ProgrammersManual.html" />
+ <link rel="prev" title="Extending LLVM: Adding instructions, intrinsics, types, etc." href="ExtendingLLVM.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-set-up-llvm-style-rtti-for-your-class-hierarchy">
+<h1><a class="toc-backref" href="#id1">How to set up LLVM-style RTTI for your class hierarchy</a><a class="headerlink" href="#how-to-set-up-llvm-style-rtti-for-your-class-hierarchy" title="Permalink to this headline">¶</a></h1>
+<div class="contents topic" id="contents">
+<p class="topic-title first">Contents</p>
+<ul class="simple">
+<li><a class="reference internal" href="#how-to-set-up-llvm-style-rtti-for-your-class-hierarchy" id="id1">How to set up LLVM-style RTTI for your class hierarchy</a><ul>
+<li><a class="reference internal" href="#background" id="id2">Background</a></li>
+<li><a class="reference internal" href="#basic-setup" id="id3">Basic Setup</a></li>
+<li><a class="reference internal" href="#concrete-bases-and-deeper-hierarchies" id="id4">Concrete Bases and Deeper Hierarchies</a><ul>
+<li><a class="reference internal" href="#a-bug-to-be-aware-of" id="id5">A Bug to be Aware Of</a></li>
+<li><a class="reference internal" href="#the-contract-of-classof" id="id6">The Contract of <code class="docutils literal notranslate"><span class="pre">classof</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rules-of-thumb" id="id7">Rules of Thumb</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="background">
+<h2><a class="toc-backref" href="#id2">Background</a><a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h2>
+<p>LLVM avoids using C++âs built in RTTI. Instead, it pervasively uses its
+own hand-rolled form of RTTI which is much more efficient and flexible,
+although it requires a bit more work from you as a class author.</p>
+<p>A description of how to use LLVM-style RTTI from a clientâs perspective is
+given in the <a class="reference external" href="ProgrammersManual.html#isa">Programmerâs Manual</a>. This
+document, in contrast, discusses the steps you need to take as a class
+hierarchy author to make LLVM-style RTTI available to your clients.</p>
+<p>Before diving in, make sure that you are familiar with the Object Oriented
+Programming concept of â<a class="reference external" href="http://en.wikipedia.org/wiki/Is-a">is-a</a>â.</p>
+</div>
+<div class="section" id="basic-setup">
+<h2><a class="toc-backref" href="#id3">Basic Setup</a><a class="headerlink" href="#basic-setup" title="Permalink to this headline">¶</a></h2>
+<p>This section describes how to set up the most basic form of LLVM-style RTTI
+(which is sufficient for 99.9% of the cases). We will set up LLVM-style
+RTTI for this class hierarchy:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Shape</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">Shape</span><span class="p">()</span> <span class="p">{}</span>
+ <span class="k">virtual</span> <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Square</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">SideLength</span><span class="p">;</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">Square</span><span class="p">(</span><span class="kt">double</span> <span class="n">S</span><span class="p">)</span> <span class="o">:</span> <span class="n">SideLength</span><span class="p">(</span><span class="n">S</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="k">override</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Circle</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">Radius</span><span class="p">;</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">Circle</span><span class="p">(</span><span class="kt">double</span> <span class="n">R</span><span class="p">)</span> <span class="o">:</span> <span class="n">Radius</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="k">override</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The most basic working setup for LLVM-style RTTI requires the following
+steps:</p>
+<ol class="arabic">
+<li><p class="first">In the header where you declare <code class="docutils literal notranslate"><span class="pre">Shape</span></code>, you will want to <code class="docutils literal notranslate"><span class="pre">#include</span>
+<span class="pre">"llvm/Support/Casting.h"</span></code>, which declares LLVMâs RTTI templates. That
+way your clients donât even have to think about it.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"llvm/Support/Casting.h"</span><span class="cp"></span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">In the base class, introduce an enum which discriminates all of the
+different concrete classes in the hierarchy, and stash the enum value
+somewhere in the base class.</p>
+<p>Here is the code after introducing this change:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span> <span class="k">class</span> <span class="nc">Shape</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+<span class="o">+</span> <span class="c1">/// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)</span>
+<span class="o">+</span> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+<span class="o">+</span> <span class="n">SK_Square</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_Circle</span>
+<span class="o">+</span> <span class="p">};</span>
+<span class="o">+</span><span class="k">private</span><span class="o">:</span>
+<span class="o">+</span> <span class="k">const</span> <span class="n">ShapeKind</span> <span class="n">Kind</span><span class="p">;</span>
+<span class="o">+</span><span class="k">public</span><span class="o">:</span>
+<span class="o">+</span> <span class="n">ShapeKind</span> <span class="n">getKind</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">Kind</span><span class="p">;</span> <span class="p">}</span>
+<span class="o">+</span>
+ <span class="n">Shape</span><span class="p">()</span> <span class="p">{}</span>
+ <span class="k">virtual</span> <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+<p>You will usually want to keep the <code class="docutils literal notranslate"><span class="pre">Kind</span></code> member encapsulated and
+private, but let the enum <code class="docutils literal notranslate"><span class="pre">ShapeKind</span></code> be public along with providing a
+<code class="docutils literal notranslate"><span class="pre">getKind()</span></code> method. This is convenient for clients so that they can do
+a <code class="docutils literal notranslate"><span class="pre">switch</span></code> over the enum.</p>
+<p>A common naming convention is that these enums are âkindâs, to avoid
+ambiguity with the words âtypeâ or âclassâ which have overloaded meanings
+in many contexts within LLVM. Sometimes there will be a natural name for
+it, like âopcodeâ. Donât bikeshed over this; when in doubt use <code class="docutils literal notranslate"><span class="pre">Kind</span></code>.</p>
+<p>You might wonder why the <code class="docutils literal notranslate"><span class="pre">Kind</span></code> enum doesnât have an entry for
+<code class="docutils literal notranslate"><span class="pre">Shape</span></code>. The reason for this is that since <code class="docutils literal notranslate"><span class="pre">Shape</span></code> is abstract
+(<code class="docutils literal notranslate"><span class="pre">computeArea()</span> <span class="pre">=</span> <span class="pre">0;</span></code>), you will never actually have non-derived
+instances of exactly that class (only subclasses). See <a class="reference internal" href="#concrete-bases-and-deeper-hierarchies">Concrete Bases
+and Deeper Hierarchies</a> for information on how to deal with
+non-abstract bases. Itâs worth mentioning here that unlike
+<code class="docutils literal notranslate"><span class="pre">dynamic_cast<></span></code>, LLVM-style RTTI can be used (and is often used) for
+classes that donât have v-tables.</p>
+</li>
+<li><p class="first">Next, you need to make sure that the <code class="docutils literal notranslate"><span class="pre">Kind</span></code> gets initialized to the
+value corresponding to the dynamic type of the class. Typically, you will
+want to have it be an argument to the constructor of the base class, and
+then pass in the respective <code class="docutils literal notranslate"><span class="pre">XXXKind</span></code> from subclass constructors.</p>
+<p>Here is the code after that change:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span> <span class="k">class</span> <span class="nc">Shape</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="c1">/// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)</span>
+ <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">};</span>
+ <span class="k">private</span><span class="o">:</span>
+ <span class="k">const</span> <span class="n">ShapeKind</span> <span class="n">Kind</span><span class="p">;</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="n">ShapeKind</span> <span class="n">getKind</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">Kind</span><span class="p">;</span> <span class="p">}</span>
+
+<span class="o">-</span> <span class="n">Shape</span><span class="p">()</span> <span class="p">{}</span>
+<span class="o">+</span> <span class="n">Shape</span><span class="p">(</span><span class="n">ShapeKind</span> <span class="n">K</span><span class="p">)</span> <span class="o">:</span> <span class="n">Kind</span><span class="p">(</span><span class="n">K</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="k">virtual</span> <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">};</span>
+
+ <span class="k">class</span> <span class="nc">Square</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">SideLength</span><span class="p">;</span>
+ <span class="k">public</span><span class="o">:</span>
+<span class="o">-</span> <span class="n">Square</span><span class="p">(</span><span class="kt">double</span> <span class="n">S</span><span class="p">)</span> <span class="o">:</span> <span class="n">SideLength</span><span class="p">(</span><span class="n">S</span><span class="p">)</span> <span class="p">{}</span>
+<span class="o">+</span> <span class="n">Square</span><span class="p">(</span><span class="kt">double</span> <span class="n">S</span><span class="p">)</span> <span class="o">:</span> <span class="n">Shape</span><span class="p">(</span><span class="n">SK_Square</span><span class="p">),</span> <span class="n">SideLength</span><span class="p">(</span><span class="n">S</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="k">override</span><span class="p">;</span>
+ <span class="p">};</span>
+
+ <span class="k">class</span> <span class="nc">Circle</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">Radius</span><span class="p">;</span>
+ <span class="k">public</span><span class="o">:</span>
+<span class="o">-</span> <span class="n">Circle</span><span class="p">(</span><span class="kt">double</span> <span class="n">R</span><span class="p">)</span> <span class="o">:</span> <span class="n">Radius</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="p">{}</span>
+<span class="o">+</span> <span class="n">Circle</span><span class="p">(</span><span class="kt">double</span> <span class="n">R</span><span class="p">)</span> <span class="o">:</span> <span class="n">Shape</span><span class="p">(</span><span class="n">SK_Circle</span><span class="p">),</span> <span class="n">Radius</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="k">override</span><span class="p">;</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Finally, you need to inform LLVMâs RTTI templates how to dynamically
+determine the type of a class (i.e. whether the <code class="docutils literal notranslate"><span class="pre">isa<></span></code>/<code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code>
+should succeed). The default â99.9% of use casesâ way to accomplish this
+is through a small static member function <code class="docutils literal notranslate"><span class="pre">classof</span></code>. In order to have
+proper context for an explanation, we will display this code first, and
+then below describe each part:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span> <span class="k">class</span> <span class="nc">Shape</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="c1">/// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)</span>
+ <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">};</span>
+ <span class="k">private</span><span class="o">:</span>
+ <span class="k">const</span> <span class="n">ShapeKind</span> <span class="n">Kind</span><span class="p">;</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="n">ShapeKind</span> <span class="n">getKind</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">Kind</span><span class="p">;</span> <span class="p">}</span>
+
+ <span class="n">Shape</span><span class="p">(</span><span class="n">ShapeKind</span> <span class="n">K</span><span class="p">)</span> <span class="o">:</span> <span class="n">Kind</span><span class="p">(</span><span class="n">K</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="k">virtual</span> <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">};</span>
+
+ <span class="k">class</span> <span class="nc">Square</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">SideLength</span><span class="p">;</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="n">Square</span><span class="p">(</span><span class="kt">double</span> <span class="n">S</span><span class="p">)</span> <span class="o">:</span> <span class="n">Shape</span><span class="p">(</span><span class="n">SK_Square</span><span class="p">),</span> <span class="n">SideLength</span><span class="p">(</span><span class="n">S</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="k">override</span><span class="p">;</span>
+<span class="o">+</span>
+<span class="o">+</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">+</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">==</span> <span class="n">SK_Square</span><span class="p">;</span>
+<span class="o">+</span> <span class="p">}</span>
+ <span class="p">};</span>
+
+ <span class="k">class</span> <span class="nc">Circle</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">Radius</span><span class="p">;</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="n">Circle</span><span class="p">(</span><span class="kt">double</span> <span class="n">R</span><span class="p">)</span> <span class="o">:</span> <span class="n">Shape</span><span class="p">(</span><span class="n">SK_Circle</span><span class="p">),</span> <span class="n">Radius</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="k">override</span><span class="p">;</span>
+<span class="o">+</span>
+<span class="o">+</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">+</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">==</span> <span class="n">SK_Circle</span><span class="p">;</span>
+<span class="o">+</span> <span class="p">}</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+<p>The job of <code class="docutils literal notranslate"><span class="pre">classof</span></code> is to dynamically determine whether an object of
+a base class is in fact of a particular derived class. In order to
+downcast a type <code class="docutils literal notranslate"><span class="pre">Base</span></code> to a type <code class="docutils literal notranslate"><span class="pre">Derived</span></code>, there needs to be a
+<code class="docutils literal notranslate"><span class="pre">classof</span></code> in <code class="docutils literal notranslate"><span class="pre">Derived</span></code> which will accept an object of type <code class="docutils literal notranslate"><span class="pre">Base</span></code>.</p>
+<p>To be concrete, consider the following code:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Shape</span> <span class="o">*</span><span class="n">S</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">Circle</span><span class="o">></span><span class="p">(</span><span class="n">S</span><span class="p">))</span> <span class="p">{</span>
+ <span class="cm">/* do something ... */</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The code of the <code class="docutils literal notranslate"><span class="pre">isa<></span></code> test in this code will eventually boil
+downâafter template instantiation and some other machineryâto a
+check roughly like <code class="docutils literal notranslate"><span class="pre">Circle::classof(S)</span></code>. For more information, see
+<a class="reference internal" href="#classof-contract"><span class="std std-ref">The Contract of classof</span></a>.</p>
+<p>The argument to <code class="docutils literal notranslate"><span class="pre">classof</span></code> should always be an <em>ancestor</em> class because
+the implementation has logic to allow and optimize away
+upcasts/up-<code class="docutils literal notranslate"><span class="pre">isa<></span></code>âs automatically. It is as though every class
+<code class="docutils literal notranslate"><span class="pre">Foo</span></code> automatically has a <code class="docutils literal notranslate"><span class="pre">classof</span></code> like:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+ <span class="p">[...]</span>
+ <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+ <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span> <span class="o">*</span><span class="p">,</span>
+ <span class="o">::</span><span class="n">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span>
+ <span class="o">::</span><span class="n">std</span><span class="o">::</span><span class="n">is_base_of</span><span class="o"><</span><span class="n">Foo</span><span class="p">,</span> <span class="n">T</span><span class="o">>::</span><span class="n">value</span>
+ <span class="o">>::</span><span class="n">type</span><span class="o">*</span> <span class="o">=</span> <span class="mi">0</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>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Note that this is the reason that we did not need to introduce a
+<code class="docutils literal notranslate"><span class="pre">classof</span></code> into <code class="docutils literal notranslate"><span class="pre">Shape</span></code>: all relevant classes derive from <code class="docutils literal notranslate"><span class="pre">Shape</span></code>,
+and <code class="docutils literal notranslate"><span class="pre">Shape</span></code> itself is abstract (has no entry in the <code class="docutils literal notranslate"><span class="pre">Kind</span></code> enum),
+so this notional inferred <code class="docutils literal notranslate"><span class="pre">classof</span></code> is all we need. See <a class="reference internal" href="#concrete-bases-and-deeper-hierarchies">Concrete
+Bases and Deeper Hierarchies</a> for more information about how to extend
+this example to more general hierarchies.</p>
+</li>
+</ol>
+<p>Although for this small example setting up LLVM-style RTTI seems like a lot
+of âboilerplateâ, if your classes are doing anything interesting then this
+will end up being a tiny fraction of the code.</p>
+</div>
+<div class="section" id="concrete-bases-and-deeper-hierarchies">
+<h2><a class="toc-backref" href="#id4">Concrete Bases and Deeper Hierarchies</a><a class="headerlink" href="#concrete-bases-and-deeper-hierarchies" title="Permalink to this headline">¶</a></h2>
+<p>For concrete bases (i.e. non-abstract interior nodes of the inheritance
+tree), the <code class="docutils literal notranslate"><span class="pre">Kind</span></code> check inside <code class="docutils literal notranslate"><span class="pre">classof</span></code> needs to be a bit more
+complicated. The situation differs from the example above in that</p>
+<ul class="simple">
+<li>Since the class is concrete, it must itself have an entry in the <code class="docutils literal notranslate"><span class="pre">Kind</span></code>
+enum because it is possible to have objects with this class as a dynamic
+type.</li>
+<li>Since the class has children, the check inside <code class="docutils literal notranslate"><span class="pre">classof</span></code> must take them
+into account.</li>
+</ul>
+<p>Say that <code class="docutils literal notranslate"><span class="pre">SpecialSquare</span></code> and <code class="docutils literal notranslate"><span class="pre">OtherSpecialSquare</span></code> derive
+from <code class="docutils literal notranslate"><span class="pre">Square</span></code>, and so <code class="docutils literal notranslate"><span class="pre">ShapeKind</span></code> becomes:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_SpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_OtherSpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">}</span>
+</pre></div>
+</div>
+<p>Then in <code class="docutils literal notranslate"><span class="pre">Square</span></code>, we would need to modify the <code class="docutils literal notranslate"><span class="pre">classof</span></code> like so:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">-</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">==</span> <span class="n">SK_Square</span><span class="p">;</span>
+<span class="o">-</span> <span class="p">}</span>
+<span class="o">+</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">+</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">>=</span> <span class="n">SK_Square</span> <span class="o">&&</span>
+<span class="o">+</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o"><=</span> <span class="n">SK_OtherSpecialSquare</span><span class="p">;</span>
+<span class="o">+</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>The reason that we need to test a range like this instead of just equality
+is that both <code class="docutils literal notranslate"><span class="pre">SpecialSquare</span></code> and <code class="docutils literal notranslate"><span class="pre">OtherSpecialSquare</span></code> âis-aâ
+<code class="docutils literal notranslate"><span class="pre">Square</span></code>, and so <code class="docutils literal notranslate"><span class="pre">classof</span></code> needs to return <code class="docutils literal notranslate"><span class="pre">true</span></code> for them.</p>
+<p>This approach can be made to scale to arbitrarily deep hierarchies. The
+trick is that you arrange the enum values so that they correspond to a
+preorder traversal of the class hierarchy tree. With that arrangement, all
+subclass tests can be done with two comparisons as shown above. If you just
+list the class hierarchy like a list of bullet points, youâll get the
+ordering right:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">|</span> <span class="n">Shape</span>
+ <span class="o">|</span> <span class="n">Square</span>
+ <span class="o">|</span> <span class="n">SpecialSquare</span>
+ <span class="o">|</span> <span class="n">OtherSpecialSquare</span>
+ <span class="o">|</span> <span class="n">Circle</span>
+</pre></div>
+</div>
+<div class="section" id="a-bug-to-be-aware-of">
+<h3><a class="toc-backref" href="#id5">A Bug to be Aware Of</a><a class="headerlink" href="#a-bug-to-be-aware-of" title="Permalink to this headline">¶</a></h3>
+<p>The example just given opens the door to bugs where the <code class="docutils literal notranslate"><span class="pre">classof</span></code>s are
+not updated to match the <code class="docutils literal notranslate"><span class="pre">Kind</span></code> enum when adding (or removing) classes to
+(from) the hierarchy.</p>
+<p>Continuing the example above, suppose we add a <code class="docutils literal notranslate"><span class="pre">SomewhatSpecialSquare</span></code> as
+a subclass of <code class="docutils literal notranslate"><span class="pre">Square</span></code>, and update the <code class="docutils literal notranslate"><span class="pre">ShapeKind</span></code> enum like so:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+ <span class="n">SK_SpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_OtherSpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_SomewhatSpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">}</span>
+</pre></div>
+</div>
+<p>Now, suppose that we forget to update <code class="docutils literal notranslate"><span class="pre">Square::classof()</span></code>, so it still
+looks like:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">bool</span> <span class="nf">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// BUG: Returns false when S->getKind() == SK_SomewhatSpecialSquare,</span>
+ <span class="c1">// even though SomewhatSpecialSquare "is a" Square.</span>
+ <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">>=</span> <span class="n">SK_Square</span> <span class="o">&&</span>
+ <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o"><=</span> <span class="n">SK_OtherSpecialSquare</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>As the comment indicates, this code contains a bug. A straightforward and
+non-clever way to avoid this is to introduce an explicit <code class="docutils literal notranslate"><span class="pre">SK_LastSquare</span></code>
+entry in the enum when adding the first subclass(es). For example, we could
+rewrite the example at the beginning of <a class="reference internal" href="#concrete-bases-and-deeper-hierarchies">Concrete Bases and Deeper
+Hierarchies</a> as:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_SpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_OtherSpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_LastSquare</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">}</span>
+<span class="p">...</span>
+<span class="c1">// Square::classof()</span>
+<span class="o">-</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">-</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">==</span> <span class="n">SK_Square</span><span class="p">;</span>
+<span class="o">-</span> <span class="p">}</span>
+<span class="o">+</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">+</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">>=</span> <span class="n">SK_Square</span> <span class="o">&&</span>
+<span class="o">+</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o"><=</span> <span class="n">SK_LastSquare</span><span class="p">;</span>
+<span class="o">+</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Then, adding new subclasses is easy:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+ <span class="n">SK_SpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_OtherSpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_SomewhatSpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_LastSquare</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">}</span>
+</pre></div>
+</div>
+<p>Notice that <code class="docutils literal notranslate"><span class="pre">Square::classof</span></code> does not need to be changed.</p>
+</div>
+<div class="section" id="the-contract-of-classof">
+<span id="classof-contract"></span><h3><a class="toc-backref" href="#id6">The Contract of <code class="docutils literal notranslate"><span class="pre">classof</span></code></a><a class="headerlink" href="#the-contract-of-classof" title="Permalink to this headline">¶</a></h3>
+<p>To be more precise, let <code class="docutils literal notranslate"><span class="pre">classof</span></code> be inside a class <code class="docutils literal notranslate"><span class="pre">C</span></code>. Then the
+contract for <code class="docutils literal notranslate"><span class="pre">classof</span></code> is âreturn <code class="docutils literal notranslate"><span class="pre">true</span></code> if the dynamic type of the
+argument is-a <code class="docutils literal notranslate"><span class="pre">C</span></code>â. As long as your implementation fulfills this
+contract, you can tweak and optimize it as much as you want.</p>
+<p>For example, LLVM-style RTTI can work fine in the presence of
+multiple-inheritance by defining an appropriate <code class="docutils literal notranslate"><span class="pre">classof</span></code>.
+An example of this in practice is
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a> vs.
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1DeclContext.html">DeclContext</a>
+inside Clang.
+The <code class="docutils literal notranslate"><span class="pre">Decl</span></code> hierarchy is done very similarly to the example setup
+demonstrated in this tutorial.
+The key part is how to then incorporate <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code>: all that is needed
+is in <code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">DeclContext::classof(const</span> <span class="pre">Decl</span> <span class="pre">*)</span></code>, which asks the question
+âGiven a <code class="docutils literal notranslate"><span class="pre">Decl</span></code>, how can I determine if it is-a <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code>?â.
+It answers this with a simple switch over the set of <code class="docutils literal notranslate"><span class="pre">Decl</span></code> âkindsâ, and
+returning true for ones that are known to be <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code>âs.</p>
+</div>
+</div>
+<div class="section" id="rules-of-thumb">
+<h2><a class="toc-backref" href="#id7">Rules of Thumb</a><a class="headerlink" href="#rules-of-thumb" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic simple">
+<li>The <code class="docutils literal notranslate"><span class="pre">Kind</span></code> enum should have one entry per concrete class, ordered
+according to a preorder traversal of the inheritance tree.</li>
+<li>The argument to <code class="docutils literal notranslate"><span class="pre">classof</span></code> should be a <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">Base</span> <span class="pre">*</span></code>, where <code class="docutils literal notranslate"><span class="pre">Base</span></code>
+is some ancestor in the inheritance hierarchy. The argument should
+<em>never</em> be a derived class or the class itself: the template machinery
+for <code class="docutils literal notranslate"><span class="pre">isa<></span></code> already handles this case and optimizes it.</li>
+<li>For each class in the hierarchy that has no children, implement a
+<code class="docutils literal notranslate"><span class="pre">classof</span></code> that checks only against its <code class="docutils literal notranslate"><span class="pre">Kind</span></code>.</li>
+<li>For each class in the hierarchy that has children, implement a
+<code class="docutils literal notranslate"><span class="pre">classof</span></code> that checks a range of the first childâs <code class="docutils literal notranslate"><span class="pre">Kind</span></code> and the
+last childâs <code class="docutils literal notranslate"><span class="pre">Kind</span></code>.</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToSubmitABug.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToSubmitABug.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToSubmitABug.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToSubmitABug.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,269 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How to submit an LLVM bug report — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Sphinx Quickstart Template" href="SphinxQuickstartTemplate.html" />
+ <link rel="prev" title="yaml2obj" href="yaml2obj.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="yaml2obj.html" title="yaml2obj"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-submit-an-llvm-bug-report">
+<h1>How to submit an LLVM bug report<a class="headerlink" href="#how-to-submit-an-llvm-bug-report" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction-got-bugs">
+<h2>Introduction - Got bugs?<a class="headerlink" href="#introduction-got-bugs" title="Permalink to this headline">¶</a></h2>
+<p>If youâre working with LLVM and run into a bug, we definitely want to know
+about it. This document describes what you can do to increase the odds of
+getting it fixed quickly.</p>
+<p>Basically you have to do two things at a minimum. First, decide whether
+the bug <a class="reference internal" href="#crashes-the-compiler">crashes the compiler</a> (or an LLVM pass), or if the
+compiler is <a class="reference internal" href="#miscompiling">miscompiling</a> the program (i.e., the
+compiler successfully produces an executable, but it doesnât run right).
+Based on what type of bug it is, follow the instructions in the linked
+section to narrow down the bug so that the person who fixes it will be able
+to find the problem more easily.</p>
+<p>Once you have a reduced test-case, go to <a class="reference external" href="https://bugs.llvm.org/enter_bug.cgi">the LLVM Bug Tracking System</a> and fill out the form with the
+necessary details (note that you donât need to pick a category, just use
+the ânew-bugsâ category if youâre not sure). The bug description should
+contain the following information:</p>
+<ul class="simple">
+<li>All information necessary to reproduce the problem.</li>
+<li>The reduced test-case that triggers the bug.</li>
+<li>The location where you obtained LLVM (if not from our Subversion
+repository).</li>
+</ul>
+<p>Thanks for helping us make LLVM better!</p>
+</div>
+<div class="section" id="crashing-bugs">
+<span id="crashes-the-compiler"></span><h2>Crashing Bugs<a class="headerlink" href="#crashing-bugs" title="Permalink to this headline">¶</a></h2>
+<p>More often than not, bugs in the compiler cause it to crashâoften due to
+an assertion failure of some sort. The most important piece of the puzzle
+is to figure out if it is crashing in the Clang front-end or if it is one of
+the LLVM libraries (e.g. the optimizer or code generator) that has
+problems.</p>
+<p>To figure out which component is crashing (the front-end, optimizer or code
+generator), run the <code class="docutils literal notranslate"><span class="pre">clang</span></code> command line as you were when the crash
+occurred, but with the following extra command line options:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-O0</span> <span class="pre">-emit-llvm</span></code>: If <code class="docutils literal notranslate"><span class="pre">clang</span></code> still crashes when passed these
+options (which disable the optimizer and code generator), then the crash
+is in the front-end. Jump ahead to the section on <a class="reference internal" href="#front-end"><span class="std std-ref">front-end bugs</span></a>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-emit-llvm</span></code>: If <code class="docutils literal notranslate"><span class="pre">clang</span></code> crashes with this option (which disables
+the code generator), you found an optimizer bug. Jump ahead to
+<a class="reference internal" href="#compile-time-optimization-bugs">compile-time optimization bugs</a>.</li>
+<li>Otherwise, you have a code generator crash. Jump ahead to <a class="reference internal" href="#code-generator-bugs">code
+generator bugs</a>.</li>
+</ul>
+<div class="section" id="front-end-bugs">
+<span id="front-end"></span><span id="front-end-bug"></span><h3>Front-end bugs<a class="headerlink" href="#front-end-bugs" title="Permalink to this headline">¶</a></h3>
+<p>If the problem is in the front-end, you should re-run the same <code class="docutils literal notranslate"><span class="pre">clang</span></code>
+command that resulted in the crash, but add the <code class="docutils literal notranslate"><span class="pre">-save-temps</span></code> option.
+The compiler will crash again, but it will leave behind a <code class="docutils literal notranslate"><span class="pre">foo.i</span></code> file
+(containing preprocessed C source code) and possibly <code class="docutils literal notranslate"><span class="pre">foo.s</span></code> for each
+compiled <code class="docutils literal notranslate"><span class="pre">foo.c</span></code> file. Send us the <code class="docutils literal notranslate"><span class="pre">foo.i</span></code> file, along with the options
+you passed to <code class="docutils literal notranslate"><span class="pre">clang</span></code>, and a brief description of the error it caused.</p>
+<p>The <a class="reference external" href="http://delta.tigris.org/">delta</a> tool helps to reduce the
+preprocessed file down to the smallest amount of code that still replicates
+the problem. Youâre encouraged to use delta to reduce the code to make the
+developersâ lives easier. <a class="reference external" href="http://gcc.gnu.org/wiki/A_guide_to_testcase_reduction">This website</a> has instructions
+on the best way to use delta.</p>
+</div>
+<div class="section" id="compile-time-optimization-bugs">
+<span id="id1"></span><h3>Compile-time optimization bugs<a class="headerlink" href="#compile-time-optimization-bugs" title="Permalink to this headline">¶</a></h3>
+<p>If you find that a bug crashes in the optimizer, compile your test-case to a
+<code class="docutils literal notranslate"><span class="pre">.bc</span></code> file by passing â<code class="docutils literal notranslate"><span class="pre">-emit-llvm</span> <span class="pre">-O0</span> <span class="pre">-c</span> <span class="pre">-o</span> <span class="pre">foo.bc</span></code>â.
+Then run:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>opt -O3 -debug-pass<span class="o">=</span>Arguments foo.bc -disable-output
+</pre></div>
+</div>
+<p>This command should do two things: it should print out a list of passes, and
+then it should crash in the same way as clang. If it doesnât crash, please
+follow the instructions for a <a class="reference internal" href="#front-end-bug">front-end bug</a>.</p>
+<p>If this does crash, then you should be able to debug this with the following
+bugpoint command:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint foo.bc <list of passes printed by opt>
+</pre></div>
+</div>
+<p>Please run this, then file a bug with the instructions and reduced .bc
+files that bugpoint emits. If something goes wrong with bugpoint, please
+submit the âfoo.bcâ file and the list of passes printed by <code class="docutils literal notranslate"><span class="pre">opt</span></code>.</p>
+</div>
+<div class="section" id="code-generator-bugs">
+<span id="id2"></span><h3>Code generator bugs<a class="headerlink" href="#code-generator-bugs" title="Permalink to this headline">¶</a></h3>
+<p>If you find a bug that crashes clang in the code generator, compile your
+source file to a .bc file by passing â<code class="docutils literal notranslate"><span class="pre">-emit-llvm</span> <span class="pre">-c</span> <span class="pre">-o</span> <span class="pre">foo.bc</span></code>â to
+clang (in addition to the options you already pass). Once your have
+foo.bc, one of the following commands should fail:</p>
+<ol class="arabic simple">
+<li><code class="docutils literal notranslate"><span class="pre">llc</span> <span class="pre">foo.bc</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">llc</span> <span class="pre">foo.bc</span> <span class="pre">-relocation-model=pic</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">llc</span> <span class="pre">foo.bc</span> <span class="pre">-relocation-model=static</span></code></li>
+</ol>
+<p>If none of these crash, please follow the instructions for a <a class="reference internal" href="#front-end-bug">front-end
+bug</a>. If one of these do crash, you should be able to reduce this with
+one of the following bugpoint command lines (use the one corresponding to
+the command above that failed):</p>
+<ol class="arabic simple">
+<li><code class="docutils literal notranslate"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span> <span class="pre">--tool-args</span> <span class="pre">-relocation-model=pic</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span> <span class="pre">--tool-args</span> <span class="pre">-relocation-model=static</span></code></li>
+</ol>
+<p>Please run this, then file a bug with the instructions and reduced .bc file
+that bugpoint emits. If something goes wrong with bugpoint, please submit
+the âfoo.bcâ file and the option that llc crashes with.</p>
+</div>
+</div>
+<div class="section" id="miscompilations">
+<span id="miscompiling"></span><h2>Miscompilations<a class="headerlink" href="#miscompilations" title="Permalink to this headline">¶</a></h2>
+<p>If clang successfully produces an executable, but that executable
+doesnât run right, this is either a bug in the code or a bug in the
+compiler. The first thing to check is to make sure it is not using
+undefined behavior (e.g. reading a variable before it is defined). In
+particular, check to see if the program <a class="reference external" href="http://valgrind.org/">valgrind</a>âs clean, passes purify, or some other memory
+checker tool. Many of the âLLVM bugsâ that we have chased down ended up
+being bugs in the program being compiled, not LLVM.</p>
+<p>Once you determine that the program itself is not buggy, you should choose
+which code generator you wish to compile the program with (e.g. LLC or the JIT)
+and optionally a series of LLVM passes to run. For example:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint -run-llc <span class="o">[</span>... optzn passes ...<span class="o">]</span> file-to-test.bc --args -- <span class="o">[</span>program arguments<span class="o">]</span>
+</pre></div>
+</div>
+<p>bugpoint will try to narrow down your list of passes to the one pass that
+causes an error, and simplify the bitcode file as much as it can to assist
+you. It will print a message letting you know how to reproduce the
+resulting error.</p>
+</div>
+<div class="section" id="incorrect-code-generation">
+<h2>Incorrect code generation<a class="headerlink" href="#incorrect-code-generation" title="Permalink to this headline">¶</a></h2>
+<p>Similarly to debugging incorrect compilation by mis-behaving passes, you
+can debug incorrect code generation by either LLC or the JIT, using
+<code class="docutils literal notranslate"><span class="pre">bugpoint</span></code>. The process <code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> follows in this case is to try to
+narrow the code down to a function that is miscompiled by one or the other
+method, but since for correctness, the entire program must be run,
+<code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> will compile the code it deems to not be affected with the C
+Backend, and then link in the shared object it generates.</p>
+<p>To debug the JIT:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint -run-jit -output<span class="o">=[</span>correct output file<span class="o">]</span> <span class="o">[</span>bitcode file<span class="o">]</span> <span class="se">\</span>
+ --tool-args -- <span class="o">[</span>arguments to pass to lli<span class="o">]</span> <span class="se">\</span>
+ --args -- <span class="o">[</span>program arguments<span class="o">]</span>
+</pre></div>
+</div>
+<p>Similarly, to debug the LLC, one would run:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint -run-llc -output<span class="o">=[</span>correct output file<span class="o">]</span> <span class="o">[</span>bitcode file<span class="o">]</span> <span class="se">\</span>
+ --tool-args -- <span class="o">[</span>arguments to pass to llc<span class="o">]</span> <span class="se">\</span>
+ --args -- <span class="o">[</span>program arguments<span class="o">]</span>
+</pre></div>
+</div>
+<p><strong>Special note:</strong> if you are debugging MultiSource or SPEC tests that
+already exist in the <code class="docutils literal notranslate"><span class="pre">llvm/test</span></code> hierarchy, there is an easier way to
+debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which
+will pass the program options specified in the Makefiles:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> llvm/test/../../program
+make bugpoint-jit
+</pre></div>
+</div>
+<p>At the end of a successful <code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> run, you will be presented
+with two bitcode files: a <em>safe</em> file which can be compiled with the C
+backend and the <em>test</em> file which either LLC or the JIT
+mis-codegenerates, and thus causes the error.</p>
+<p>To reproduce the error that <code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> found, it is sufficient to do
+the following:</p>
+<ol class="arabic">
+<li><p class="first">Regenerate the shared object from the safe bitcode file:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>llc -march<span class="o">=</span>c safe.bc -o safe.c
+gcc -shared safe.c -o safe.so
+</pre></div>
+</div>
+</li>
+<li><p class="first">If debugging LLC, compile test bitcode native and link with the shared
+object:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>llc test.bc -o test.s
+gcc test.s safe.so -o test.llc
+./test.llc <span class="o">[</span>program options<span class="o">]</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">If debugging the JIT, load the shared object and supply the test
+bitcode:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>lli -load<span class="o">=</span>safe.so test.bc <span class="o">[</span>program options<span class="o">]</span>
+</pre></div>
+</div>
+</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="yaml2obj.html" title="yaml2obj"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToUseAttributes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToUseAttributes.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToUseAttributes.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToUseAttributes.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,158 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Use Attributes — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="User Guide for NVPTX Back-end" href="NVPTXUsage.html" />
+ <link rel="prev" title="Writing an LLVM Pass" href="WritingAnLLVMPass.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-use-attributes">
+<h1>How To Use Attributes<a class="headerlink" href="#how-to-use-attributes" 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="#attribute" id="id2"><code class="docutils literal notranslate"><span class="pre">Attribute</span></code></a></li>
+<li><a class="reference internal" href="#attributelist" id="id3"><code class="docutils literal notranslate"><span class="pre">AttributeList</span></code></a></li>
+<li><a class="reference internal" href="#attrbuilder" id="id4"><code class="docutils literal notranslate"><span class="pre">AttrBuilder</span></code></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>Attributes in LLVM have changed in some fundamental ways. It was necessary to
+do this to support expanding the attributes to encompass more than a handful of
+attributes â e.g. command line options. The old way of handling attributes
+consisted of representing them as a bit mask of values. This bit mask was
+stored in a âlistâ structure that was reference counted. The advantage of this
+was that attributes could be manipulated with âorâs and âandâs. The
+disadvantage of this was that there was limited room for expansion, and
+virtually no support for attribute-value pairs other than alignment.</p>
+<p>In the new scheme, an <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> object represents a single attribute thatâs
+uniqued. You use the <code class="docutils literal notranslate"><span class="pre">Attribute::get</span></code> methods to create a new <code class="docutils literal notranslate"><span class="pre">Attribute</span></code>
+object. An attribute can be a single âenumâ value (the enum being the
+<code class="docutils literal notranslate"><span class="pre">Attribute::AttrKind</span></code> enum), a string representing a target-dependent
+attribute, or an attribute-value pair. Some examples:</p>
+<ul class="simple">
+<li>Target-independent: <code class="docutils literal notranslate"><span class="pre">noinline</span></code>, <code class="docutils literal notranslate"><span class="pre">zext</span></code></li>
+<li>Target-dependent: <code class="docutils literal notranslate"><span class="pre">"no-sse"</span></code>, <code class="docutils literal notranslate"><span class="pre">"thumb2"</span></code></li>
+<li>Attribute-value pair: <code class="docutils literal notranslate"><span class="pre">"cpu"</span> <span class="pre">=</span> <span class="pre">"cortex-a8"</span></code>, <code class="docutils literal notranslate"><span class="pre">align</span> <span class="pre">=</span> <span class="pre">4</span></code></li>
+</ul>
+<p>Note: for an attribute value pair, we expect a target-dependent attribute to
+have a string for the value.</p>
+</div>
+<div class="section" id="attribute">
+<h2><a class="toc-backref" href="#id2"><code class="docutils literal notranslate"><span class="pre">Attribute</span></code></a><a class="headerlink" href="#attribute" title="Permalink to this headline">¶</a></h2>
+<p>An <code class="docutils literal notranslate"><span class="pre">Attribute</span></code> object is designed to be passed around by value.</p>
+<p>Because attributes are no longer represented as a bit mask, you will need to
+convert any code which does treat them as a bit mask to use the new query
+methods on the Attribute class.</p>
+</div>
+<div class="section" id="attributelist">
+<h2><a class="toc-backref" href="#id3"><code class="docutils literal notranslate"><span class="pre">AttributeList</span></code></a><a class="headerlink" href="#attributelist" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">AttributeList</span></code> stores a collection of Attribute objects for each kind of
+object that may have an attribute associated with it: the function as a whole,
+the return type, or the functionâs parameters. A functionâs attributes are at
+index <code class="docutils literal notranslate"><span class="pre">AttributeList::FunctionIndex</span></code>; the return typeâs attributes are at
+index <code class="docutils literal notranslate"><span class="pre">AttributeList::ReturnIndex</span></code>; and the functionâs parametersâ attributes
+are at indices 1, â¦, n (where ânâ is the number of parameters). Most methods
+on the <code class="docutils literal notranslate"><span class="pre">AttributeList</span></code> class take an index parameter.</p>
+<p>An <code class="docutils literal notranslate"><span class="pre">AttributeList</span></code> is also a uniqued and immutable object. You create an
+<code class="docutils literal notranslate"><span class="pre">AttributeList</span></code> through the <code class="docutils literal notranslate"><span class="pre">AttributeList::get</span></code> methods. You can add and
+remove attributes, which result in the creation of a new <code class="docutils literal notranslate"><span class="pre">AttributeList</span></code>.</p>
+<p>An <code class="docutils literal notranslate"><span class="pre">AttributeList</span></code> object is designed to be passed around by value.</p>
+<p>Note: It is advised that you do <em>not</em> use the <code class="docutils literal notranslate"><span class="pre">AttributeList</span></code> âintrospectionâ
+methods (e.g. <code class="docutils literal notranslate"><span class="pre">Raw</span></code>, <code class="docutils literal notranslate"><span class="pre">getRawPointer</span></code>, etc.). These methods break
+encapsulation, and may be removed in a future release (i.e. LLVM 4.0).</p>
+</div>
+<div class="section" id="attrbuilder">
+<h2><a class="toc-backref" href="#id4"><code class="docutils literal notranslate"><span class="pre">AttrBuilder</span></code></a><a class="headerlink" href="#attrbuilder" title="Permalink to this headline">¶</a></h2>
+<p>Lastly, we have a âbuilderâ class to help create the <code class="docutils literal notranslate"><span class="pre">AttributeList</span></code> object
+without having to create several different intermediate uniqued
+<code class="docutils literal notranslate"><span class="pre">AttributeList</span></code> objects. The <code class="docutils literal notranslate"><span class="pre">AttrBuilder</span></code> class allows you to add and
+remove attributes at will. The attributes wonât be uniqued until you call the
+appropriate <code class="docutils literal notranslate"><span class="pre">AttributeList::get</span></code> method.</p>
+<p>An <code class="docutils literal notranslate"><span class="pre">AttrBuilder</span></code> object is <em>not</em> designed to be passed around by value. It
+should be passed by reference.</p>
+<p>Note: It is advised that you do <em>not</em> use the <code class="docutils literal notranslate"><span class="pre">AttrBuilder::addRawValue()</span></code>
+method or the <code class="docutils literal notranslate"><span class="pre">AttrBuilder(uint64_t</span> <span class="pre">Val)</span></code> constructor. These are for
+backwards compatibility and may be removed in a future release (i.e. LLVM 4.0).</p>
+<p>And thatâs basically it! A lot of functionality is hidden behind these classes,
+but the interfaces are pretty straight forward.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/HowToUseInstrMappings.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/HowToUseInstrMappings.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/HowToUseInstrMappings.html (added)
+++ www-releases/trunk/8.0.0/docs/HowToUseInstrMappings.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,258 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Use Instruction Mappings — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Garbage Collection with LLVM" href="GarbageCollection.html" />
+ <link rel="prev" title="Writing an LLVM Backend" href="WritingAnLLVMBackend.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="GarbageCollection.html" title="Garbage Collection with LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="WritingAnLLVMBackend.html" accesskey="U">Writing an LLVM Backend</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="how-to-use-instruction-mappings">
+<h1>How To Use Instruction Mappings<a class="headerlink" href="#how-to-use-instruction-mappings" 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="#instrmapping-class-overview" id="id2"><code class="docutils literal notranslate"><span class="pre">InstrMapping</span></code> Class Overview</a><ul>
+<li><a class="reference internal" href="#sample-example" id="id3">Sample Example</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about adding instruction mapping support
+for a target. The motivation behind this feature comes from the need to switch
+between different instruction formats during various optimizations. One approach
+could be to use switch cases which list all the instructions along with formats
+they can transition to. However, it has large maintenance overhead
+because of the hardcoded instruction names. Also, whenever a new instruction is
+added in the .td files, all the relevant switch cases should be modified
+accordingly. Instead, the same functionality could be achieved with TableGen and
+some support from the .td files for a fraction of maintenance cost.</p>
+</div>
+<div class="section" id="instrmapping-class-overview">
+<h2><a class="toc-backref" href="#id2"><code class="docutils literal notranslate"><span class="pre">InstrMapping</span></code> Class Overview</a><a class="headerlink" href="#instrmapping-class-overview" title="Permalink to this headline">¶</a></h2>
+<p>TableGen uses relationship models to map instructions with each other. These
+models are described using <code class="docutils literal notranslate"><span class="pre">InstrMapping</span></code> class as a base. Each model sets
+various fields of the <code class="docutils literal notranslate"><span class="pre">InstrMapping</span></code> class such that they can uniquely
+describe all the instructions using that model. TableGen parses all the relation
+models and uses the information to construct relation tables which relate
+instructions with each other. These tables are emitted in the
+<code class="docutils literal notranslate"><span class="pre">XXXInstrInfo.inc</span></code> file along with the functions to query them. Following
+is the definition of <code class="docutils literal notranslate"><span class="pre">InstrMapping</span></code> class definied in Target.td file:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>class InstrMapping {
+ // Used to reduce search space only to the instructions using this
+ // relation model.
+ string FilterClass;
+
+ // List of fields/attributes that should be same for all the instructions in
+ // a row of the relation table. Think of this as a set of properties shared
+ // by all the instructions related by this relationship.
+ list<string> RowFields = [];
+
+ // List of fields/attributes that are same for all the instructions
+ // in a column of the relation table.
+ list<string> ColFields = [];
+
+ // Values for the fields/attributes listed in 'ColFields' corresponding to
+ // the key instruction. This is the instruction that will be transformed
+ // using this relation model.
+ list<string> KeyCol = [];
+
+ // List of values for the fields/attributes listed in 'ColFields', one for
+ // each column in the relation table. These are the instructions a key
+ // instruction will be transformed into.
+ list<list<string> > ValueCols = [];
+}
+</pre></div>
+</div>
+<div class="section" id="sample-example">
+<h3><a class="toc-backref" href="#id3">Sample Example</a><a class="headerlink" href="#sample-example" title="Permalink to this headline">¶</a></h3>
+<p>Letâs say that we want to have a function
+<code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">getPredOpcode(uint16_t</span> <span class="pre">Opcode,</span> <span class="pre">enum</span> <span class="pre">PredSense</span> <span class="pre">inPredSense)</span></code> which
+takes a non-predicated instruction and returns its predicated true or false form
+depending on some input flag, <code class="docutils literal notranslate"><span class="pre">inPredSense</span></code>. The first step in the process is
+to define a relationship model that relates predicated instructions to their
+non-predicated form by assigning appropriate values to the <code class="docutils literal notranslate"><span class="pre">InstrMapping</span></code>
+fields. For this relationship, non-predicated instructions are treated as key
+instruction since they are the one used to query the interface function.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>def getPredOpcode : InstrMapping {
+ // Choose a FilterClass that is used as a base class for all the
+ // instructions modeling this relationship. This is done to reduce the
+ // search space only to these set of instructions.
+ let FilterClass = "PredRel";
+
+ // Instructions with same values for all the fields in RowFields form a
+ // row in the resulting relation table.
+ // For example, if we want to relate 'ADD' (non-predicated) with 'Add_pt'
+ // (predicated true) and 'Add_pf' (predicated false), then all 3
+ // instructions need to have same value for BaseOpcode field. It can be any
+ // unique value (Ex: XYZ) and should not be shared with any other
+ // instruction not related to 'add'.
+ let RowFields = ["BaseOpcode"];
+
+ // List of attributes that can be used to define key and column instructions
+ // for a relation. Key instruction is passed as an argument
+ // to the function used for querying relation tables. Column instructions
+ // are the instructions they (key) can transform into.
+ //
+ // Here, we choose 'PredSense' as ColFields since this is the unique
+ // attribute of the key (non-predicated) and column (true/false)
+ // instructions involved in this relationship model.
+ let ColFields = ["PredSense"];
+
+ // The key column contains non-predicated instructions.
+ let KeyCol = ["none"];
+
+ // Two value columns - first column contains instructions with
+ // PredSense=true while second column has instructions with PredSense=false.
+ let ValueCols = [["true"], ["false"]];
+}
+</pre></div>
+</div>
+<p>TableGen uses the above relationship model to emit relation table that maps
+non-predicated instructions with their predicated forms. It also outputs the
+interface function
+<code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">getPredOpcode(uint16_t</span> <span class="pre">Opcode,</span> <span class="pre">enum</span> <span class="pre">PredSense</span> <span class="pre">inPredSense)</span></code> to query
+the table. Here, Function <code class="docutils literal notranslate"><span class="pre">getPredOpcode</span></code> takes two arguments, opcode of the
+current instruction and PredSense of the desired instruction, and returns
+predicated form of the instruction, if found in the relation table.
+In order for an instruction to be added into the relation table, it needs
+to include relevant information in its definition. For example, consider
+following to be the current definitions of ADD, ADD_pt (true) and ADD_pf (false)
+instructions:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>def ADD : ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b),
+ "$dst = add($a, $b)",
+ [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a),
+ (i32 IntRegs:$b)))]>;
+
+def ADD_Pt : ALU32_rr<(outs IntRegs:$dst),
+ (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+ "if ($p) $dst = add($a, $b)",
+ []>;
+
+def ADD_Pf : ALU32_rr<(outs IntRegs:$dst),
+ (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+ "if (!$p) $dst = add($a, $b)",
+ []>;
+</pre></div>
+</div>
+<p>In this step, we modify these instructions to include the information
+required by the relationship model, <tt>getPredOpcode</tt>, so that they can
+be related.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>def ADD : PredRel, ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b),
+ "$dst = add($a, $b)",
+ [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a),
+ (i32 IntRegs:$b)))]> {
+ let BaseOpcode = "ADD";
+ let PredSense = "none";
+}
+
+def ADD_Pt : PredRel, ALU32_rr<(outs IntRegs:$dst),
+ (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+ "if ($p) $dst = add($a, $b)",
+ []> {
+ let BaseOpcode = "ADD";
+ let PredSense = "true";
+}
+
+def ADD_Pf : PredRel, ALU32_rr<(outs IntRegs:$dst),
+ (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+ "if (!$p) $dst = add($a, $b)",
+ []> {
+ let BaseOpcode = "ADD";
+ let PredSense = "false";
+}
+</pre></div>
+</div>
+<p>Please note that all the above instructions use <code class="docutils literal notranslate"><span class="pre">PredRel</span></code> as a base class.
+This is extremely important since TableGen uses it as a filter for selecting
+instructions for <code class="docutils literal notranslate"><span class="pre">getPredOpcode</span></code> model. Any instruction not derived from
+<code class="docutils literal notranslate"><span class="pre">PredRel</span></code> is excluded from the analysis. <code class="docutils literal notranslate"><span class="pre">BaseOpcode</span></code> is another important
+field. Since itâs selected as a <code class="docutils literal notranslate"><span class="pre">RowFields</span></code> of the model, it is required
+to have the same value for all 3 instructions in order to be related. Next,
+<code class="docutils literal notranslate"><span class="pre">PredSense</span></code> is used to determine their column positions by comparing its value
+with <code class="docutils literal notranslate"><span class="pre">KeyCol</span></code> and <code class="docutils literal notranslate"><span class="pre">ValueCols</span></code>. If an instruction sets its <code class="docutils literal notranslate"><span class="pre">PredSense</span></code>
+value to something not used in the relation model, it will not be assigned
+a column in the relation table.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="GarbageCollection.html" title="Garbage Collection with LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="WritingAnLLVMBackend.html" >Writing an LLVM Backend</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/InAlloca.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/InAlloca.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/InAlloca.html (added)
+++ www-releases/trunk/8.0.0/docs/InAlloca.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,230 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Design and Usage of the InAlloca Attribute — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Using ARM NEON instructions in big endian mode" href="BigEndianNEON.html" />
+ <link rel="prev" title="Stack maps and patch points in LLVM" href="StackMaps.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="BigEndianNEON.html" title="Using ARM NEON instructions in big endian mode"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="StackMaps.html" title="Stack maps and patch points in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="design-and-usage-of-the-inalloca-attribute">
+<h1>Design and Usage of the InAlloca Attribute<a class="headerlink" href="#design-and-usage-of-the-inalloca-attribute" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The <a class="reference internal" href="LangRef.html#attr-inalloca"><span class="std std-ref">inalloca</span></a> attribute is designed to allow
+taking the address of an aggregate argument that is being passed by
+value through memory. Primarily, this feature is required for
+compatibility with the Microsoft C++ ABI. Under that ABI, class
+instances that are passed by value are constructed directly into
+argument stack memory. Prior to the addition of inalloca, calls in LLVM
+were indivisible instructions. There was no way to perform intermediate
+work, such as object construction, between the first stack adjustment
+and the final control transfer. With inalloca, all arguments passed in
+memory are modelled as a single alloca, which can be stored to prior to
+the call. Unfortunately, this complicated feature comes with a large
+set of restrictions designed to bound the lifetime of the argument
+memory around the call.</p>
+<p>For now, it is recommended that frontends and optimizers avoid producing
+this construct, primarily because it forces the use of a base pointer.
+This feature may grow in the future to allow general mid-level
+optimization, but for now, it should be regarded as less efficient than
+passing by value with a copy.</p>
+</div>
+<div class="section" id="intended-usage">
+<h2>Intended Usage<a class="headerlink" href="#intended-usage" title="Permalink to this headline">¶</a></h2>
+<p>The example below is the intended LLVM IR lowering for some C++ code
+that passes two default-constructed <code class="docutils literal notranslate"><span class="pre">Foo</span></code> objects to <code class="docutils literal notranslate"><span class="pre">g</span></code> in the
+32-bit Microsoft C++ ABI.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Foo is non-trivial.</span>
+<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">;</span> <span class="n">Foo</span><span class="p">();</span> <span class="o">~</span><span class="n">Foo</span><span class="p">();</span> <span class="n">Foo</span><span class="p">(</span><span class="k">const</span> <span class="n">Foo</span> <span class="o">&</span><span class="p">);</span> <span class="p">};</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="n">Foo</span> <span class="n">a</span><span class="p">,</span> <span class="n">Foo</span> <span class="n">b</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">g</span><span class="p">(</span><span class="n">Foo</span><span class="p">(),</span> <span class="n">Foo</span><span class="p">());</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>%struct.Foo = type { i32, i32 }
+declare void @Foo_ctor(%struct.Foo* %this)
+declare void @Foo_dtor(%struct.Foo* %this)
+declare void @g(<{ %struct.Foo, %struct.Foo }>* inalloca %memargs)
+
+define void @f() {
+entry:
+ %base = call i8* @llvm.stacksave()
+ %memargs = alloca <{ %struct.Foo, %struct.Foo }>
+ %b = getelementptr <{ %struct.Foo, %struct.Foo }>* %memargs, i32 1
+ call void @Foo_ctor(%struct.Foo* %b)
+
+ ; If a's ctor throws, we must destruct b.
+ %a = getelementptr <{ %struct.Foo, %struct.Foo }>* %memargs, i32 0
+ invoke void @Foo_ctor(%struct.Foo* %a)
+ to label %invoke.cont unwind %invoke.unwind
+
+invoke.cont:
+ call void @g(<{ %struct.Foo, %struct.Foo }>* inalloca %memargs)
+ call void @llvm.stackrestore(i8* %base)
+ ...
+
+invoke.unwind:
+ call void @Foo_dtor(%struct.Foo* %b)
+ call void @llvm.stackrestore(i8* %base)
+ ...
+}
+</pre></div>
+</div>
+<p>To avoid stack leaks, the frontend saves the current stack pointer with
+a call to <a class="reference internal" href="LangRef.html#int-stacksave"><span class="std std-ref">llvm.stacksave</span></a>. Then, it allocates the
+argument stack space with alloca and calls the default constructor. The
+default constructor could throw an exception, so the frontend has to
+create a landing pad. The frontend has to destroy the already
+constructed argument <code class="docutils literal notranslate"><span class="pre">b</span></code> before restoring the stack pointer. If the
+constructor does not unwind, <code class="docutils literal notranslate"><span class="pre">g</span></code> is called. In the Microsoft C++ ABI,
+<code class="docutils literal notranslate"><span class="pre">g</span></code> will destroy its arguments, and then the stack is restored in
+<code class="docutils literal notranslate"><span class="pre">f</span></code>.</p>
+</div>
+<div class="section" id="design-considerations">
+<h2>Design Considerations<a class="headerlink" href="#design-considerations" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="lifetime">
+<h3>Lifetime<a class="headerlink" href="#lifetime" title="Permalink to this headline">¶</a></h3>
+<p>The biggest design consideration for this feature is object lifetime.
+We cannot model the arguments as static allocas in the entry block,
+because all calls need to use the memory at the top of the stack to pass
+arguments. We cannot vend pointers to that memory at function entry
+because after code generation they will alias.</p>
+<p>The rule against allocas between argument allocations and the call site
+avoids this problem, but it creates a cleanup problem. Cleanup and
+lifetime is handled explicitly with stack save and restore calls. In
+the future, we may want to introduce a new construct such as <code class="docutils literal notranslate"><span class="pre">freea</span></code>
+or <code class="docutils literal notranslate"><span class="pre">afree</span></code> to make it clear that this stack adjusting cleanup is less
+powerful than a full stack save and restore.</p>
+</div>
+<div class="section" id="nested-calls-and-copy-elision">
+<h3>Nested Calls and Copy Elision<a class="headerlink" href="#nested-calls-and-copy-elision" title="Permalink to this headline">¶</a></h3>
+<p>We also want to be able to support copy elision into these argument
+slots. This means we have to support multiple live argument
+allocations.</p>
+<p>Consider the evaluation of:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Foo is non-trivial.</span>
+<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">;</span> <span class="n">Foo</span><span class="p">();</span> <span class="n">Foo</span><span class="p">(</span><span class="k">const</span> <span class="o">&</span><span class="n">Foo</span><span class="p">);</span> <span class="o">~</span><span class="n">Foo</span><span class="p">();</span> <span class="p">};</span>
+<span class="n">Foo</span> <span class="nf">bar</span><span class="p">(</span><span class="n">Foo</span> <span class="n">b</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">bar</span><span class="p">(</span><span class="n">bar</span><span class="p">(</span><span class="n">Foo</span><span class="p">()));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case, we want to be able to elide copies into <code class="docutils literal notranslate"><span class="pre">bar</span></code>âs argument
+slots. That means we need to have more than one set of argument frames
+active at the same time. First, we need to allocate the frame for the
+outer call so we can pass it in as the hidden struct return pointer to
+the middle call. Then we do the same for the middle call, allocating a
+frame and passing its address to <code class="docutils literal notranslate"><span class="pre">Foo</span></code>âs default constructor. By
+wrapping the evaluation of the inner <code class="docutils literal notranslate"><span class="pre">bar</span></code> with stack save and
+restore, we can have multiple overlapping active call frames.</p>
+</div>
+<div class="section" id="callee-cleanup-calling-conventions">
+<h3>Callee-cleanup Calling Conventions<a class="headerlink" href="#callee-cleanup-calling-conventions" title="Permalink to this headline">¶</a></h3>
+<p>Another wrinkle is the existence of callee-cleanup conventions. On
+Windows, all methods and many other functions adjust the stack to clear
+the memory used to pass their arguments. In some sense, this means that
+the allocas are automatically cleared by the call. However, LLVM
+instead models this as a write of undef to all of the inalloca values
+passed to the call instead of a stack adjustment. Frontends should
+still restore the stack pointer to avoid a stack leak.</p>
+</div>
+<div class="section" id="exceptions">
+<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
+<p>There is also the possibility of an exception. If argument evaluation
+or copy construction throws an exception, the landing pad must do
+cleanup, which includes adjusting the stack pointer to avoid a stack
+leak. This means the cleanup of the stack memory cannot be tied to the
+call itself. There needs to be a separate IR-level instruction that can
+perform independent cleanup of arguments.</p>
+</div>
+<div class="section" id="efficiency">
+<h3>Efficiency<a class="headerlink" href="#efficiency" title="Permalink to this headline">¶</a></h3>
+<p>Eventually, it should be possible to generate efficient code for this
+construct. In particular, using inalloca should not require a base
+pointer. If the backend can prove that all points in the CFG only have
+one possible stack level, then it can address the stack directly from
+the stack pointer. While this is not yet implemented, the plan is that
+the inalloca attribute should not change much, but the frontend IR
+generation recommendations may change.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="BigEndianNEON.html" title="Using ARM NEON instructions in big endian mode"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="StackMaps.html" title="Stack maps and patch points in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/LLVMBuild.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/LLVMBuild.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/LLVMBuild.html (added)
+++ www-releases/trunk/8.0.0/docs/LLVMBuild.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,372 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>LLVMBuild Guide — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="How To Release LLVM To The Public" href="HowToReleaseLLVM.html" />
+ <link rel="prev" title="Creating an LLVM Project" href="Projects.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToReleaseLLVM.html" title="How To Release LLVM To The Public"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Projects.html" title="Creating an LLVM Project"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvmbuild-guide">
+<h1>LLVMBuild Guide<a class="headerlink" href="#llvmbuild-guide" 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="#project-organization" id="id2">Project Organization</a></li>
+<li><a class="reference internal" href="#build-integration" id="id3">Build Integration</a></li>
+<li><a class="reference internal" href="#component-overview" id="id4">Component Overview</a></li>
+<li><a class="reference internal" href="#llvmbuild-format-reference" id="id5">LLVMBuild Format Reference</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the <code class="docutils literal notranslate"><span class="pre">LLVMBuild</span></code> organization and files which
+we use to describe parts of the LLVM ecosystem. For description of
+specific LLVMBuild related tools, please see the command guide.</p>
+<p>LLVM is designed to be a modular set of libraries which can be flexibly
+mixed together in order to build a variety of tools, like compilers,
+JITs, custom code generators, optimization passes, interpreters, and so
+on. Related projects in the LLVM system like Clang and LLDB also tend to
+follow this philosophy.</p>
+<p>In order to support this usage style, LLVM has a fairly strict structure
+as to how the source code and various components are organized. The
+<code class="docutils literal notranslate"><span class="pre">LLVMBuild.txt</span></code> files are the explicit specification of that
+structure, and are used by the build systems and other tools in order to
+develop the LLVM project.</p>
+</div>
+<div class="section" id="project-organization">
+<h2><a class="toc-backref" href="#id2">Project Organization</a><a class="headerlink" href="#project-organization" title="Permalink to this headline">¶</a></h2>
+<p>The source code for LLVM projects using the LLVMBuild system (LLVM,
+Clang, and LLDB) is organized into <em>components</em>, which define the
+separate pieces of functionality that make up the project. These
+projects may consist of many libraries, associated tools, build tools,
+or other utility tools (for example, testing tools).</p>
+<p>For the most part, the project contents are organized around defining
+one main component per each subdirectory. Each such directory contains
+an <code class="docutils literal notranslate"><span class="pre">LLVMBuild.txt</span></code> which contains the component definitions.</p>
+<p>The component descriptions for the project as a whole are automatically
+gathered by the LLVMBuild tools. The tools automatically traverse the
+source directory structure to find all of the component description
+files. NOTE: For performance/sanity reasons, we only traverse into
+subdirectories when the parent itself contains an <code class="docutils literal notranslate"><span class="pre">LLVMBuild.txt</span></code>
+description file.</p>
+</div>
+<div class="section" id="build-integration">
+<h2><a class="toc-backref" href="#id3">Build Integration</a><a class="headerlink" href="#build-integration" title="Permalink to this headline">¶</a></h2>
+<p>The LLVMBuild files themselves are just a declarative way to describe
+the project structure. The actual building of the LLVM project is
+handled by another build system (See: <a class="reference internal" href="CMake.html"><span class="doc">CMake</span></a>).</p>
+<p>The build system implementation will load the relevant contents of the
+LLVMBuild files and use that to drive the actual project build.
+Typically, the build system will only need to load this information at
+âconfigureâ time, and use it to generate native information. Build
+systems will also handle automatically reconfiguring their information
+when the contents of the <code class="docutils literal notranslate"><span class="pre">LLVMBuild.txt</span></code> files change.</p>
+<p>Developers generally are not expected to need to be aware of the details
+of how the LLVMBuild system is integrated into their build. Ideally,
+LLVM developers who are not working on the build system would only ever
+need to modify the contents of the <code class="docutils literal notranslate"><span class="pre">LLVMBuild.txt</span></code> description files
+(although we have not reached this goal yet).</p>
+<p>For more information on the utility tool we provide to help interfacing
+with the build system, please see the <a class="reference internal" href="CommandGuide/llvm-build.html"><span class="doc">llvm-build</span></a> documentation.</p>
+</div>
+<div class="section" id="component-overview">
+<h2><a class="toc-backref" href="#id4">Component Overview</a><a class="headerlink" href="#component-overview" title="Permalink to this headline">¶</a></h2>
+<p>As mentioned earlier, LLVM projects are organized into logical
+<em>components</em>. Every component is typically grouped into its own
+subdirectory. Generally, a component is organized around a coherent
+group of sources which have some kind of clear API separation from other
+parts of the code.</p>
+<p>LLVM primarily uses the following types of components:</p>
+<ul class="simple">
+<li><em>Libraries</em> - Library components define a distinct API which can be
+independently linked into LLVM client applications. Libraries typically
+have private and public header files, and may specify a link of required
+libraries that they build on top of.</li>
+<li><em>Build Tools</em> - Build tools are applications which are designed to be run
+as part of the build process (typically to generate other source files).
+Currently, LLVM uses one main build tool called <a class="reference internal" href="TableGen/index.html"><span class="doc">TableGen</span></a>
+to generate a variety of source files.</li>
+<li><em>Tools</em> - Command line applications which are built using the LLVM
+component libraries. Most LLVM tools are small and are primarily
+frontends to the library interfaces.</li>
+</ul>
+<p>Components are described using <code class="docutils literal notranslate"><span class="pre">LLVMBuild.txt</span></code> files in the directories
+that define the component. See the <a class="reference internal" href="#llvmbuild-format-reference">LLVMBuild Format Reference</a> section
+for information on the exact format of these files.</p>
+</div>
+<div class="section" id="llvmbuild-format-reference">
+<h2><a class="toc-backref" href="#id5">LLVMBuild Format Reference</a><a class="headerlink" href="#llvmbuild-format-reference" title="Permalink to this headline">¶</a></h2>
+<p>LLVMBuild files are written in a simple variant of the INI or configuration
+file format (<a class="reference external" href="http://en.wikipedia.org/wiki/INI_file">Wikipedia entry</a>). The format defines a list of sections
+each of which may contain some number of properties. A simple example of
+the file format is below:</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1">; Comments start with a semi-colon.</span>
+
+<span class="c1">; Sections are declared using square brackets.</span>
+<span class="k">[component_0]</span>
+
+<span class="c1">; Properties are declared using '=' and are contained in the previous section.</span>
+<span class="c1">;</span>
+<span class="c1">; We support simple string and boolean scalar values and list values, where</span>
+<span class="c1">; items are separated by spaces. There is no support for quoting, and so</span>
+<span class="c1">; property values may not contain spaces.</span>
+<span class="na">property_name</span> <span class="o">=</span> <span class="s">property_value</span>
+<span class="na">list_property_name</span> <span class="o">=</span> <span class="s">value_1 value_2 ... value_n</span>
+<span class="na">boolean_property_name</span> <span class="o">=</span> <span class="s">1 (or 0)</span>
+</pre></div>
+</div>
+<p>LLVMBuild files are expected to define a strict set of sections and
+properties. A typical component description file for a library
+component would look like the following example:</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[component_0]</span>
+<span class="na">type</span> <span class="o">=</span> <span class="s">Library</span>
+<span class="na">name</span> <span class="o">=</span> <span class="s">Linker</span>
+<span class="na">parent</span> <span class="o">=</span> <span class="s">Libraries</span>
+<span class="na">required_libraries</span> <span class="o">=</span> <span class="s">Archive BitReader Core Support TransformUtils</span>
+</pre></div>
+</div>
+<p>A full description of the exact sections and properties which are
+allowed follows.</p>
+<p>Each file may define exactly one common component, named <code class="docutils literal notranslate"><span class="pre">common</span></code>. The
+common component may define the following properties:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">subdirectories</span></code> <strong>[optional]</strong></p>
+<p>If given, a list of the names of the subdirectories from the current
+subpath to search for additional LLVMBuild files.</p>
+</li>
+</ul>
+<p>Each file may define multiple components. Each component is described by a
+section who name starts with <code class="docutils literal notranslate"><span class="pre">component</span></code>. The remainder of the section
+name is ignored, but each section name must be unique. Typically components
+are just number in order for files with multiple components
+(<code class="docutils literal notranslate"><span class="pre">component_0</span></code>, <code class="docutils literal notranslate"><span class="pre">component_1</span></code>, and so on).</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Section names not matching this format (or the <code class="docutils literal notranslate"><span class="pre">common</span></code> section) are
+currently unused and are disallowed.</p>
+</div>
+<p>Every component is defined by the properties in the section. The exact
+list of properties that are allowed depends on the component type.
+Components <strong>may not</strong> define any properties other than those expected
+by the component type.</p>
+<p>Every component must define the following properties:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">type</span></code> <strong>[required]</strong></p>
+<p>The type of the component. Supported component types are detailed
+below. Most components will define additional properties which may be
+required or optional.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">name</span></code> <strong>[required]</strong></p>
+<p>The name of the component. Names are required to be unique across the
+entire project.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">parent</span></code> <strong>[required]</strong></p>
+<p>The name of the logical parent of the component. Components are
+organized into a logical tree to make it easier to navigate and
+organize groups of components. The parents have no semantics as far
+as the project build is concerned, however. Typically, the parent
+will be the main component of the parent directory.</p>
+<p>Components may reference the root pseudo component using <code class="docutils literal notranslate"><span class="pre">$ROOT</span></code> to
+indicate they should logically be grouped at the top-level.</p>
+</li>
+</ul>
+<p>Components may define the following properties:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">dependencies</span></code> <strong>[optional]</strong></p>
+<p>If specified, a list of names of components which <em>must</em> be built
+prior to this one. This should only be exactly those components which
+produce some tool or source code required for building the component.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last"><code class="docutils literal notranslate"><span class="pre">Group</span></code> and <code class="docutils literal notranslate"><span class="pre">LibraryGroup</span></code> components have no semantics for the
+actual build, and are not allowed to specify dependencies.</p>
+</div>
+</li>
+</ul>
+<p>The following section lists the available component types, as well as
+the properties which are associated with that component.</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Group</span></code></p>
+<p>Group components exist purely to allow additional arbitrary structuring
+of the logical components tree. For example, one might define a
+<code class="docutils literal notranslate"><span class="pre">Libraries</span></code> group to hold all of the root library components.</p>
+<p><code class="docutils literal notranslate"><span class="pre">Group</span></code> components have no additionally properties.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Library</span></code></p>
+<p>Library components define an individual library which should be built
+from the source code in the component directory.</p>
+<p>Components with this type use the following properties:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">library_name</span></code> <strong>[optional]</strong></p>
+<p>If given, the name to use for the actual library file on disk. If
+not given, the name is derived from the component name itself.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">required_libraries</span></code> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <code class="docutils literal notranslate"><span class="pre">Library</span></code> or <code class="docutils literal notranslate"><span class="pre">LibraryGroup</span></code>
+components which must also be linked in whenever this library is
+used. That is, the link time dependencies for this component. When
+tools are built, the build system will include the transitive closure
+of all <code class="docutils literal notranslate"><span class="pre">required_libraries</span></code> for the components the tool needs.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">add_to_library_groups</span></code> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <code class="docutils literal notranslate"><span class="pre">LibraryGroup</span></code> components which
+this component is also part of. This allows nesting groups of
+components. For example, the <code class="docutils literal notranslate"><span class="pre">X86</span></code> target might define a library
+group for all of the <code class="docutils literal notranslate"><span class="pre">X86</span></code> components. That library group might
+then be included in the <code class="docutils literal notranslate"><span class="pre">all-targets</span></code> library group.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">installed</span></code> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this library is installed. Libraries that are not installed
+are only reported by <code class="docutils literal notranslate"><span class="pre">llvm-config</span></code> when it is run as part of a
+development directory.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">LibraryGroup</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">LibraryGroup</span></code> components are a mechanism to allow easy definition of
+useful sets of related components. In particular, we use them to easily
+specify things like âall targetsâ, or âall assembly printersâ.</p>
+<p>Components with this type use the following properties:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">required_libraries</span></code> <strong>[optional]</strong></p>
+<p>See the <code class="docutils literal notranslate"><span class="pre">Library</span></code> type for a description of this property.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">add_to_library_groups</span></code> <strong>[optional]</strong></p>
+<p>See the <code class="docutils literal notranslate"><span class="pre">Library</span></code> type for a description of this property.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">TargetGroup</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">TargetGroup</span></code> components are an extension of <code class="docutils literal notranslate"><span class="pre">LibraryGroup</span></code>s,
+specifically for defining LLVM targets (which are handled specially in a
+few places).</p>
+<p>The name of the component should always be the name of the target.</p>
+<p>Components with this type use the <code class="docutils literal notranslate"><span class="pre">LibraryGroup</span></code> properties in
+addition to:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">has_asmparser</span></code> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines an assembly parser.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">has_asmprinter</span></code> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines an assembly printer.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">has_disassembler</span></code> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines a disassembler.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">has_jit</span></code> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target supports JIT compilation.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Tool</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">Tool</span></code> components define standalone command line tools which should be
+built from the source code in the component directory and linked.</p>
+<p>Components with this type use the following properties:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">required_libraries</span></code> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <code class="docutils literal notranslate"><span class="pre">Library</span></code> or <code class="docutils literal notranslate"><span class="pre">LibraryGroup</span></code>
+components which this tool is required to be linked with.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The values should be the component names, which may not always
+match up with the actual library names on disk.</p>
+</div>
+<p>Build systems are expected to properly include all of the libraries
+required by the linked components (i.e., the transitive closure of
+<code class="docutils literal notranslate"><span class="pre">required_libraries</span></code>).</p>
+<p>Build systems are also expected to understand that those library
+components must be built prior to linking â they do not also need
+to be listed under <code class="docutils literal notranslate"><span class="pre">dependencies</span></code>.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">BuildTool</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">BuildTool</span></code> components are like <code class="docutils literal notranslate"><span class="pre">Tool</span></code> components, except that the
+tool is supposed to be built for the platform where the build is running
+(instead of that platform being targeted). Build systems are expected
+to handle the fact that required libraries may need to be built for
+multiple platforms in order to be able to link this tool.</p>
+<p><code class="docutils literal notranslate"><span class="pre">BuildTool</span></code> components currently use the exact same properties as
+<code class="docutils literal notranslate"><span class="pre">Tool</span></code> components, the type distinction is only used to differentiate
+what the tool is built for.</p>
+</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToReleaseLLVM.html" title="How To Release LLVM To The Public"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Projects.html" title="Creating an LLVM Project"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list