[www-releases] r331981 - Add 5.0.2 docs and update download.html
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Thu May 10 06:54:19 PDT 2018
Added: www-releases/trunk/5.0.2/docs/ExceptionHandling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/ExceptionHandling.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/ExceptionHandling.html (added)
+++ www-releases/trunk/5.0.2/docs/ExceptionHandling.html Thu May 10 06:54:16 2018
@@ -0,0 +1,869 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Exception Handling in LLVM — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="LLVM Link Time Optimization: Design and Implementation" href="LinkTimeOptimization.html" />
+ <link rel="prev" title="The LLVM Target-Independent Code Generator" href="CodeGenerator.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodeGenerator.html" title="The LLVM Target-Independent Code Generator"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="exception-handling-in-llvm">
+<h1>Exception Handling in LLVM<a class="headerlink" href="#exception-handling-in-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id7">Introduction</a><ul>
+<li><a class="reference internal" href="#itanium-abi-zero-cost-exception-handling" id="id8">Itanium ABI Zero-cost Exception Handling</a></li>
+<li><a class="reference internal" href="#setjmp-longjmp-exception-handling" id="id9">Setjmp/Longjmp Exception Handling</a></li>
+<li><a class="reference internal" href="#windows-runtime-exception-handling" id="id10">Windows Runtime Exception Handling</a></li>
+<li><a class="reference internal" href="#overview" id="id11">Overview</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#llvm-code-generation" id="id12">LLVM Code Generation</a><ul>
+<li><a class="reference internal" href="#throw" id="id13">Throw</a></li>
+<li><a class="reference internal" href="#try-catch" id="id14">Try/Catch</a></li>
+<li><a class="reference internal" href="#cleanups" id="id15">Cleanups</a></li>
+<li><a class="reference internal" href="#throw-filters" id="id16">Throw Filters</a></li>
+<li><a class="reference internal" href="#restrictions" id="id17">Restrictions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#exception-handling-intrinsics" id="id18">Exception Handling Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-eh-typeid-for" id="id19"><tt class="docutils literal"><span class="pre">llvm.eh.typeid.for</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-begincatch" id="id20"><tt class="docutils literal"><span class="pre">llvm.eh.begincatch</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-endcatch" id="id21"><tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-exceptionpointer" id="id22"><tt class="docutils literal"><span class="pre">llvm.eh.exceptionpointer</span></tt></a></li>
+<li><a class="reference internal" href="#sjlj-intrinsics" id="id23">SJLJ Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-eh-sjlj-setjmp" id="id24"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.setjmp</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-longjmp" id="id25"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-lsda" id="id26"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-callsite" id="id27"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#asm-table-formats" id="id28">Asm Table Formats</a><ul>
+<li><a class="reference internal" href="#exception-handling-frame" id="id29">Exception Handling Frame</a></li>
+<li><a class="reference internal" href="#exception-tables" id="id30">Exception Tables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#exception-handling-using-the-windows-runtime" id="id31">Exception Handling using the Windows Runtime</a><ul>
+<li><a class="reference internal" href="#background-on-windows-exceptions" id="id32">Background on Windows exceptions</a></li>
+<li><a class="reference internal" href="#seh-filter-expressions" id="id33">SEH filter expressions</a></li>
+<li><a class="reference internal" href="#new-exception-handling-instructions" id="id34">New exception handling instructions</a></li>
+<li><a class="reference internal" href="#funclet-parent-tokens" id="id35">Funclet parent tokens</a></li>
+<li><a class="reference internal" href="#funclet-transitions" id="id36">Funclet transitions</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id7">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is the central repository for all information pertaining to
+exception handling in LLVM. It describes the format that LLVM exception
+handling information takes, which is useful for those interested in creating
+front-ends or dealing directly with the information. Further, this document
+provides specific examples of what exception handling information is used for in
+C and C++.</p>
+<div class="section" id="itanium-abi-zero-cost-exception-handling">
+<h3><a class="toc-backref" href="#id8">Itanium ABI Zero-cost Exception Handling</a><a class="headerlink" href="#itanium-abi-zero-cost-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>Exception handling for most programming languages is designed to recover from
+conditions that rarely occur during general use of an application. To that end,
+exception handling should not interfere with the main flow of an application’s
+algorithm by performing checkpointing tasks, such as saving the current pc or
+register state.</p>
+<p>The Itanium ABI Exception Handling Specification defines a methodology for
+providing outlying data in the form of exception tables without inlining
+speculative exception handling code in the flow of an application’s main
+algorithm. Thus, the specification is said to add “zero-cost” to the normal
+execution of an application.</p>
+<p>A more complete description of the Itanium ABI exception handling runtime
+support of can be found at <a class="reference external" href="http://mentorembedded.github.com/cxx-abi/abi-eh.html">Itanium C++ ABI: Exception Handling</a>. A description of the
+exception frame format can be found at <a class="reference external" href="http://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception Frames</a>,
+with details of the DWARF 4 specification at <a class="reference external" href="http://dwarfstd.org/Dwarf4Std.php">DWARF 4 Standard</a>. A description for the C++ exception
+table formats can be found at <a class="reference external" href="http://mentorembedded.github.com/cxx-abi/exceptions.pdf">Exception Handling Tables</a>.</p>
+</div>
+<div class="section" id="setjmp-longjmp-exception-handling">
+<h3><a class="toc-backref" href="#id9">Setjmp/Longjmp Exception Handling</a><a class="headerlink" href="#setjmp-longjmp-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
+<a class="reference internal" href="#llvm-eh-sjlj-setjmp">llvm.eh.sjlj.setjmp</a> and <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a> to handle control flow for
+exception handling.</p>
+<p>For each function which does exception processing — be it <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt>
+blocks or cleanups — that function registers itself on a global frame
+list. When exceptions are unwinding, the runtime uses this list to identify
+which functions need processing.</p>
+<p>Landing pad selection is encoded in the call site entry of the function
+context. The runtime returns to the function via <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a>, where
+a switch table transfers control to the appropriate landing pad based on the
+index stored in the function context.</p>
+<p>In contrast to DWARF exception handling, which encodes exception regions and
+frame information in out-of-line tables, SJLJ exception handling builds and
+removes the unwind frame context at runtime. This results in faster exception
+handling at the expense of slower execution when no exceptions are thrown. As
+exceptions are, by their nature, intended for uncommon code paths, DWARF
+exception handling is generally preferred to SJLJ.</p>
+</div>
+<div class="section" id="windows-runtime-exception-handling">
+<h3><a class="toc-backref" href="#id10">Windows Runtime Exception Handling</a><a class="headerlink" href="#windows-runtime-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>LLVM supports handling exceptions produced by the Windows runtime, but it
+requires a very different intermediate representation. It is not based on the
+“<a class="reference internal" href="LangRef.html#i-landingpad"><em>landingpad</em></a>” instruction like the other two models, and is
+described later in this document under <a class="reference internal" href="#wineh"><em>Exception Handling using the Windows Runtime</em></a>.</p>
+</div>
+<div class="section" id="overview">
+<h3><a class="toc-backref" href="#id11">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h3>
+<p>When an exception is thrown in LLVM code, the runtime does its best to find a
+handler suited to processing the circumstance.</p>
+<p>The runtime first attempts to find an <em>exception frame</em> corresponding to the
+function where the exception was thrown. If the programming language supports
+exception handling (e.g. C++), the exception frame contains a reference to an
+exception table describing how to process the exception. If the language does
+not support exception handling (e.g. C), or if the exception needs to be
+forwarded to a prior activation, the exception frame contains information about
+how to unwind the current activation and restore the state of the prior
+activation. This process is repeated until the exception is handled. If the
+exception is not handled and no activations remain, then the application is
+terminated with an appropriate error message.</p>
+<p>Because different programming languages have different behaviors when handling
+exceptions, the exception handling ABI provides a mechanism for
+supplying <em>personalities</em>. An exception handling personality is defined by
+way of a <em>personality function</em> (e.g. <tt class="docutils literal"><span class="pre">__gxx_personality_v0</span></tt> in C++),
+which receives the context of the exception, an <em>exception structure</em>
+containing the exception object type and value, and a reference to the exception
+table for the current function. The personality function for the current
+compile unit is specified in a <em>common exception frame</em>.</p>
+<p>The organization of an exception table is language dependent. For C++, an
+exception table is organized as a series of code ranges defining what to do if
+an exception occurs in that range. Typically, the information associated with a
+range defines which types of exception objects (using C++ <em>type info</em>) that are
+handled in that range, and an associated action that should take place. Actions
+typically pass control to a <em>landing pad</em>.</p>
+<p>A landing pad corresponds roughly to the code found in the <tt class="docutils literal"><span class="pre">catch</span></tt> portion of
+a <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> sequence. When execution resumes at a landing pad, it
+receives an <em>exception structure</em> and a <em>selector value</em> corresponding to the
+<em>type</em> of exception thrown. The selector is then used to determine which <em>catch</em>
+should actually process the exception.</p>
+</div>
+</div>
+<div class="section" id="llvm-code-generation">
+<h2><a class="toc-backref" href="#id12">LLVM Code Generation</a><a class="headerlink" href="#llvm-code-generation" title="Permalink to this headline">¶</a></h2>
+<p>From a C++ developer’s perspective, exceptions are defined in terms of the
+<tt class="docutils literal"><span class="pre">throw</span></tt> and <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> statements. In this section we will describe the
+implementation of LLVM exception handling in terms of C++ examples.</p>
+<div class="section" id="throw">
+<h3><a class="toc-backref" href="#id13">Throw</a><a class="headerlink" href="#throw" title="Permalink to this headline">¶</a></h3>
+<p>Languages that support exception handling typically provide a <tt class="docutils literal"><span class="pre">throw</span></tt>
+operation to initiate the exception process. Internally, a <tt class="docutils literal"><span class="pre">throw</span></tt> operation
+breaks down into two steps.</p>
+<ol class="arabic simple">
+<li>A request is made to allocate exception space for an exception structure.
+This structure needs to survive beyond the current activation. This structure
+will contain the type and value of the object being thrown.</li>
+<li>A call is made to the runtime to raise the exception, passing the exception
+structure as an argument.</li>
+</ol>
+<p>In C++, the allocation of the exception structure is done by the
+<tt class="docutils literal"><span class="pre">__cxa_allocate_exception</span></tt> runtime function. The exception raising is handled
+by <tt class="docutils literal"><span class="pre">__cxa_throw</span></tt>. The type of the exception is represented using a C++ RTTI
+structure.</p>
+</div>
+<div class="section" id="try-catch">
+<h3><a class="toc-backref" href="#id14">Try/Catch</a><a class="headerlink" href="#try-catch" title="Permalink to this headline">¶</a></h3>
+<p>A call within the scope of a <em>try</em> statement can potentially raise an
+exception. In those circumstances, the LLVM C++ front-end replaces the call with
+an <tt class="docutils literal"><span class="pre">invoke</span></tt> instruction. Unlike a call, the <tt class="docutils literal"><span class="pre">invoke</span></tt> has two potential
+continuation points:</p>
+<ol class="arabic simple">
+<li>where to continue when the call succeeds as per normal, and</li>
+<li>where to continue if the call raises an exception, either by a throw or the
+unwinding of a throw</li>
+</ol>
+<p>The term used to define the place where an <tt class="docutils literal"><span class="pre">invoke</span></tt> continues after an
+exception is called a <em>landing pad</em>. LLVM landing pads are conceptually
+alternative function entry points where an exception structure reference and a
+type info index are passed in as arguments. The landing pad saves the exception
+structure reference and then proceeds to select the catch block that corresponds
+to the type info of the exception object.</p>
+<p>The LLVM <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> is used to convey information about the landing
+pad to the back end. For C++, the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction returns a pointer
+and integer pair corresponding to the pointer to the <em>exception structure</em> and
+the <em>selector value</em> respectively.</p>
+<p>The <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction looks for a reference to the personality
+function to be used for this <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> sequence in the parent
+function’s attribute list. The instruction contains a list of <em>cleanup</em>,
+<em>catch</em>, and <em>filter</em> clauses. The exception is tested against the clauses
+sequentially from first to last. The clauses have the following meanings:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">catch</span> <span class="pre"><type></span> <span class="pre">@ExcType</span></tt></p>
+<ul class="simple">
+<li>This clause means that the landingpad block should be entered if the
+exception being thrown is of type <tt class="docutils literal"><span class="pre">@ExcType</span></tt> or a subtype of
+<tt class="docutils literal"><span class="pre">@ExcType</span></tt>. For C++, <tt class="docutils literal"><span class="pre">@ExcType</span></tt> is a pointer to the <tt class="docutils literal"><span class="pre">std::type_info</span></tt>
+object (an RTTI object) representing the C++ exception type.</li>
+<li>If <tt class="docutils literal"><span class="pre">@ExcType</span></tt> is <tt class="docutils literal"><span class="pre">null</span></tt>, any exception matches, so the landingpad
+should always be entered. This is used for C++ catch-all blocks (“<tt class="docutils literal"><span class="pre">catch</span>
+<span class="pre">(...)</span></tt>”).</li>
+<li>When this clause is matched, the selector value will be equal to the value
+returned by “<tt class="docutils literal"><span class="pre">@llvm.eh.typeid.for(i8*</span> <span class="pre">@ExcType)</span></tt>”. This will always be a
+positive value.</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">filter</span> <span class="pre"><type></span> <span class="pre">[<type></span> <span class="pre">@ExcType1,</span> <span class="pre">...,</span> <span class="pre"><type></span> <span class="pre">@ExcTypeN]</span></tt></p>
+<ul class="simple">
+<li>This clause means that the landingpad should be entered if the exception
+being thrown does <em>not</em> match any of the types in the list (which, for C++,
+are again specified as <tt class="docutils literal"><span class="pre">std::type_info</span></tt> pointers).</li>
+<li>C++ front-ends use this to implement C++ exception specifications, such as
+“<tt class="docutils literal"><span class="pre">void</span> <span class="pre">foo()</span> <span class="pre">throw</span> <span class="pre">(ExcType1,</span> <span class="pre">...,</span> <span class="pre">ExcTypeN)</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">}</span></tt>”.</li>
+<li>When this clause is matched, the selector value will be negative.</li>
+<li>The array argument to <tt class="docutils literal"><span class="pre">filter</span></tt> may be empty; for example, “<tt class="docutils literal"><span class="pre">[0</span> <span class="pre">x</span> <span class="pre">i8**]</span>
+<span class="pre">undef</span></tt>”. This means that the landingpad should always be entered. (Note
+that such a <tt class="docutils literal"><span class="pre">filter</span></tt> would not be equivalent to “<tt class="docutils literal"><span class="pre">catch</span> <span class="pre">i8*</span> <span class="pre">null</span></tt>”,
+because <tt class="docutils literal"><span class="pre">filter</span></tt> and <tt class="docutils literal"><span class="pre">catch</span></tt> produce negative and positive selector
+values respectively.)</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">cleanup</span></tt></p>
+<ul>
+<li><p class="first">This clause means that the landingpad should always be entered.</p>
+</li>
+<li><p class="first">C++ front-ends use this for calling objects’ destructors.</p>
+</li>
+<li><p class="first">When this clause is matched, the selector value will be zero.</p>
+</li>
+<li><p class="first">The runtime may treat “<tt class="docutils literal"><span class="pre">cleanup</span></tt>” differently from “<tt class="docutils literal"><span class="pre">catch</span> <span class="pre"><type></span>
+<span class="pre">null</span></tt>”.</p>
+<p>In C++, if an unhandled exception occurs, the language runtime will call
+<tt class="docutils literal"><span class="pre">std::terminate()</span></tt>, but it is implementation-defined whether the runtime
+unwinds the stack and calls object destructors first. For example, the GNU
+C++ unwinder does not call object destructors when an unhandled exception
+occurs. The reason for this is to improve debuggability: it ensures that
+<tt class="docutils literal"><span class="pre">std::terminate()</span></tt> is called from the context of the <tt class="docutils literal"><span class="pre">throw</span></tt>, so that
+this context is not lost by unwinding the stack. A runtime will typically
+implement this by searching for a matching non-<tt class="docutils literal"><span class="pre">cleanup</span></tt> clause, and
+aborting if it does not find one, before entering any landingpad blocks.</p>
+</li>
+</ul>
+</li>
+</ul>
+<p>Once the landing pad has the type info selector, the code branches to the code
+for the first catch. The catch then checks the value of the type info selector
+against the index of type info for that catch. Since the type info index is not
+known until all the type infos have been gathered in the backend, the catch code
+must call the <a class="reference internal" href="#llvm-eh-typeid-for">llvm.eh.typeid.for</a> intrinsic to determine the index for a given
+type info. If the catch fails to match the selector then control is passed on to
+the next catch.</p>
+<p>Finally, the entry and exit of catch code is bracketed with calls to
+<tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt> and <tt class="docutils literal"><span class="pre">__cxa_end_catch</span></tt>.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt> takes an exception structure reference as an argument
+and returns the value of the exception object.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">__cxa_end_catch</span></tt> takes no arguments. This function:</p>
+<ol class="arabic simple">
+<li>Locates the most recently caught exception and decrements its handler
+count,</li>
+<li>Removes the exception from the <em>caught</em> stack if the handler count goes to
+zero, and</li>
+<li>Destroys the exception if the handler count goes to zero and the exception
+was not re-thrown by throw.</li>
+</ol>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">a rethrow from within the catch may replace this call with a
+<tt class="docutils literal"><span class="pre">__cxa_rethrow</span></tt>.</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="cleanups">
+<h3><a class="toc-backref" href="#id15">Cleanups</a><a class="headerlink" href="#cleanups" title="Permalink to this headline">¶</a></h3>
+<p>A cleanup is extra code which needs to be run as part of unwinding a scope. C++
+destructors are a typical example, but other languages and language extensions
+provide a variety of different kinds of cleanups. In general, a landing pad may
+need to run arbitrary amounts of cleanup code before actually entering a catch
+block. To indicate the presence of cleanups, a <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> should have
+a <em>cleanup</em> clause. Otherwise, the unwinder will not stop at the landing pad if
+there are no catches or filters that require it to.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Do not allow a new exception to propagate out of the execution of a
+cleanup. This can corrupt the internal state of the unwinder. Different
+languages describe different high-level semantics for these situations: for
+example, C++ requires that the process be terminated, whereas Ada cancels both
+exceptions and throws a third.</p>
+</div>
+<p>When all cleanups are finished, if the exception is not handled by the current
+function, resume unwinding by calling the <a class="reference internal" href="LangRef.html#i-resume"><em>resume instruction</em></a>,
+passing in the result of the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction for the original
+landing pad.</p>
+</div>
+<div class="section" id="throw-filters">
+<h3><a class="toc-backref" href="#id16">Throw Filters</a><a class="headerlink" href="#throw-filters" title="Permalink to this headline">¶</a></h3>
+<p>C++ allows the specification of which exception types may be thrown from a
+function. To represent this, a top level landing pad may exist to filter out
+invalid types. To express this in LLVM code the <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> will have a
+filter clause. The clause consists of an array of type infos.
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> will return a negative value
+if the exception does not match any of the type infos. If no match is found then
+a call to <tt class="docutils literal"><span class="pre">__cxa_call_unexpected</span></tt> should be made, otherwise
+<tt class="docutils literal"><span class="pre">_Unwind_Resume</span></tt>. Each of these functions requires a reference to the
+exception structure. Note that the most general form of a <tt class="docutils literal"><span class="pre">landingpad</span></tt>
+instruction can have any number of catch, cleanup, and filter clauses (though
+having more than one cleanup is pointless). The LLVM C++ front-end can generate
+such <tt class="docutils literal"><span class="pre">landingpad</span></tt> instructions due to inlining creating nested exception
+handling scopes.</p>
+</div>
+<div class="section" id="restrictions">
+<span id="undefined"></span><h3><a class="toc-backref" href="#id17">Restrictions</a><a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h3>
+<p>The unwinder delegates the decision of whether to stop in a call frame to that
+call frame’s language-specific personality function. Not all unwinders guarantee
+that they will stop to perform cleanups. For example, the GNU C++ unwinder
+doesn’t do so unless the exception is actually caught somewhere further up the
+stack.</p>
+<p>In order for inlining to behave correctly, landing pads must be prepared to
+handle selector results that they did not originally advertise. Suppose that a
+function catches exceptions of type <tt class="docutils literal"><span class="pre">A</span></tt>, and it’s inlined into a function that
+catches exceptions of type <tt class="docutils literal"><span class="pre">B</span></tt>. The inliner will update the <tt class="docutils literal"><span class="pre">landingpad</span></tt>
+instruction for the inlined landing pad to include the fact that <tt class="docutils literal"><span class="pre">B</span></tt> is also
+caught. If that landing pad assumes that it will only be entered to catch an
+<tt class="docutils literal"><span class="pre">A</span></tt>, it’s in for a rude awakening. Consequently, landing pads must test for
+the selector results they understand and then resume exception propagation with
+the <a class="reference external" href="LangRef.html#i_resume">resume instruction</a> if none of the conditions
+match.</p>
+</div>
+</div>
+<div class="section" id="exception-handling-intrinsics">
+<h2><a class="toc-backref" href="#id18">Exception Handling Intrinsics</a><a class="headerlink" href="#exception-handling-intrinsics" title="Permalink to this headline">¶</a></h2>
+<p>In addition to the <tt class="docutils literal"><span class="pre">landingpad</span></tt> and <tt class="docutils literal"><span class="pre">resume</span></tt> instructions, LLVM uses several
+intrinsic functions (name prefixed with <tt class="docutils literal"><span class="pre">llvm.eh</span></tt>) to provide exception
+handling information at various points in generated code.</p>
+<div class="section" id="llvm-eh-typeid-for">
+<span id="id1"></span><h3><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">llvm.eh.typeid.for</span></tt></a><a class="headerlink" href="#llvm-eh-typeid-for" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i32</span> <span class="vg">@llvm.eh.typeid.for</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%type_info</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic returns the type info index in the exception table of the current
+function. This value can be used to compare against the result of
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. The single argument is a reference to a type info.</p>
+<p>Uses of this intrinsic are generated by the C++ front-end.</p>
+</div>
+<div class="section" id="llvm-eh-begincatch">
+<span id="id2"></span><h3><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">llvm.eh.begincatch</span></tt></a><a class="headerlink" href="#llvm-eh-begincatch" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.begincatch</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%ehptr</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%ehobj</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic marks the beginning of catch handling code within the blocks
+following a <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. The exact behavior of this function
+depends on the compilation target and the personality function associated
+with the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction.</p>
+<p>The first argument to this intrinsic is a pointer that was previously extracted
+from the aggregate return value of the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. The second
+argument to the intrinsic is a pointer to stack space where the exception object
+should be stored. The runtime handles the details of copying the exception
+object into the slot. If the second parameter is null, no copy occurs.</p>
+<p>Uses of this intrinsic are generated by the C++ front-end. Many targets will
+use implementation-specific functions (such as <tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt>) instead
+of this intrinsic. The intrinsic is provided for targets that require a more
+abstract interface.</p>
+<p>When used in the native Windows C++ exception handling implementation, this
+intrinsic serves as a placeholder to delimit code before a catch handler is
+outlined. When the handler is is outlined, this intrinsic will be replaced
+by instructions that retrieve the exception object pointer from the frame
+allocation block.</p>
+</div>
+<div class="section" id="llvm-eh-endcatch">
+<span id="id3"></span><h3><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt></a><a class="headerlink" href="#llvm-eh-endcatch" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.endcatch</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>This intrinsic marks the end of catch handling code within the current block,
+which will be a successor of a block which called <tt class="docutils literal"><span class="pre">llvm.eh.begincatch''.</span>
+<span class="pre">The</span> <span class="pre">exact</span> <span class="pre">behavior</span> <span class="pre">of</span> <span class="pre">this</span> <span class="pre">function</span> <span class="pre">depends</span> <span class="pre">on</span> <span class="pre">the</span> <span class="pre">compilation</span> <span class="pre">target</span> <span class="pre">and</span> <span class="pre">the</span>
+<span class="pre">personality</span> <span class="pre">function</span> <span class="pre">associated</span> <span class="pre">with</span> <span class="pre">the</span> <span class="pre">corresponding</span> <span class="pre">``landingpad</span></tt>
+instruction.</p>
+<p>There may be more than one call to <tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt> for any given call to
+<tt class="docutils literal"><span class="pre">llvm.eh.begincatch</span></tt> with each <tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt> call corresponding to the
+end of a different control path. All control paths following a call to
+<tt class="docutils literal"><span class="pre">llvm.eh.begincatch</span></tt> must reach a call to <tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt>.</p>
+<p>Uses of this intrinsic are generated by the C++ front-end. Many targets will
+use implementation-specific functions (such as <tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt>) instead
+of this intrinsic. The intrinsic is provided for targets that require a more
+abstract interface.</p>
+<p>When used in the native Windows C++ exception handling implementation, this
+intrinsic serves as a placeholder to delimit code before a catch handler is
+outlined. After the handler is outlined, this intrinsic is simply removed.</p>
+</div>
+<div class="section" id="llvm-eh-exceptionpointer">
+<span id="id4"></span><h3><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">llvm.eh.exceptionpointer</span></tt></a><a class="headerlink" href="#llvm-eh-exceptionpointer" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-text"><div class="highlight"><pre>i8 addrspace(N)* @llvm.eh.padparam.pNi8(token %catchpad)
+</pre></div>
+</div>
+<p>This intrinsic retrieves a pointer to the exception caught by the given
+<tt class="docutils literal"><span class="pre">catchpad</span></tt>.</p>
+</div>
+<div class="section" id="sjlj-intrinsics">
+<h3><a class="toc-backref" href="#id23">SJLJ Intrinsics</a><a class="headerlink" href="#sjlj-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">llvm.eh.sjlj</span></tt> intrinsics are used internally within LLVM’s
+backend. Uses of them are generated by the backend’s
+<tt class="docutils literal"><span class="pre">SjLjEHPrepare</span></tt> pass.</p>
+<div class="section" id="llvm-eh-sjlj-setjmp">
+<span id="id5"></span><h4><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.setjmp</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-setjmp" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-text"><div class="highlight"><pre>i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, this intrinsic forces register saving for the
+current function and stores the address of the following instruction for use as
+a destination address by <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a>. The buffer format and the
+overall functioning of this intrinsic is compatible with the GCC
+<tt class="docutils literal"><span class="pre">__builtin_setjmp</span></tt> implementation allowing code built with the clang and GCC
+to interoperate.</p>
+<p>The single parameter is a pointer to a five word buffer in which the calling
+context is saved. The front end places the frame pointer in the first word, and
+the target implementation of this intrinsic should place the destination address
+for a <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a> in the second word. The following three words are
+available for use in a target-specific manner.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-longjmp">
+<span id="id6"></span><h4><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-longjmp" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.sjlj.longjmp</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%setjmp_buf</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt> intrinsic is
+used to implement <tt class="docutils literal"><span class="pre">__builtin_longjmp()</span></tt>. The single parameter is a pointer to
+a buffer populated by <a class="reference internal" href="#llvm-eh-sjlj-setjmp">llvm.eh.sjlj.setjmp</a>. The frame pointer and stack
+pointer are restored from the buffer, then control is transferred to the
+destination address.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-lsda">
+<h4><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-lsda" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.eh.sjlj.lsda</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt> intrinsic returns
+the address of the Language Specific Data Area (LSDA) for the current
+function. The SJLJ front-end code stores this address in the exception handling
+function context for use by the runtime.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-callsite">
+<h4><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-callsite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.sjlj.callsite</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%call_site_num</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt> intrinsic
+identifies the callsite value associated with the following <tt class="docutils literal"><span class="pre">invoke</span></tt>
+instruction. This is used to ensure that landing pad entries in the LSDA are
+generated in matching order.</p>
+</div>
+</div>
+</div>
+<div class="section" id="asm-table-formats">
+<h2><a class="toc-backref" href="#id28">Asm Table Formats</a><a class="headerlink" href="#asm-table-formats" title="Permalink to this headline">¶</a></h2>
+<p>There are two tables that are used by the exception handling runtime to
+determine which actions should be taken when an exception is thrown.</p>
+<div class="section" id="exception-handling-frame">
+<h3><a class="toc-backref" href="#id29">Exception Handling Frame</a><a class="headerlink" href="#exception-handling-frame" title="Permalink to this headline">¶</a></h3>
+<p>An exception handling frame <tt class="docutils literal"><span class="pre">eh_frame</span></tt> is very similar to the unwind frame
+used by DWARF debug info. The frame contains all the information necessary to
+tear down the current frame and restore the state of the prior frame. There is
+an exception handling frame for each function in a compile unit, plus a common
+exception handling frame that defines information common to all functions in the
+unit.</p>
+<p>The format of this call frame information (CFI) is often platform-dependent,
+however. ARM, for example, defines their own format. Apple has their own compact
+unwind info format. On Windows, another format is used for all architectures
+since 32-bit x86. LLVM will emit whatever information is required by the
+target.</p>
+</div>
+<div class="section" id="exception-tables">
+<h3><a class="toc-backref" href="#id30">Exception Tables</a><a class="headerlink" href="#exception-tables" title="Permalink to this headline">¶</a></h3>
+<p>An exception table contains information about what actions to take when an
+exception is thrown in a particular part of a function’s code. This is typically
+referred to as the language-specific data area (LSDA). The format of the LSDA
+table is specific to the personality function, but the majority of personalities
+out there use a variation of the tables consumed by <tt class="docutils literal"><span class="pre">__gxx_personality_v0</span></tt>.
+There is one exception table per function, except leaf functions and functions
+that have calls only to non-throwing functions. They do not need an exception
+table.</p>
+</div>
+</div>
+<div class="section" id="exception-handling-using-the-windows-runtime">
+<span id="wineh"></span><h2><a class="toc-backref" href="#id31">Exception Handling using the Windows Runtime</a><a class="headerlink" href="#exception-handling-using-the-windows-runtime" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="background-on-windows-exceptions">
+<h3><a class="toc-backref" href="#id32">Background on Windows exceptions</a><a class="headerlink" href="#background-on-windows-exceptions" title="Permalink to this headline">¶</a></h3>
+<p>Interacting with exceptions on Windows is significantly more complicated than
+on Itanium C++ ABI platforms. The fundamental difference between the two models
+is that Itanium EH is designed around the idea of “successive unwinding,” while
+Windows EH is not.</p>
+<p>Under Itanium, throwing an exception typically involes allocating thread local
+memory to hold the exception, and calling into the EH runtime. The runtime
+identifies frames with appropriate exception handling actions, and successively
+resets the register context of the current thread to the most recently active
+frame with actions to run. In LLVM, execution resumes at a <tt class="docutils literal"><span class="pre">landingpad</span></tt>
+instruction, which produces register values provided by the runtime. If a
+function is only cleaning up allocated resources, the function is responsible
+for calling <tt class="docutils literal"><span class="pre">_Unwind_Resume</span></tt> to transition to the next most recently active
+frame after it is finished cleaning up. Eventually, the frame responsible for
+handling the exception calls <tt class="docutils literal"><span class="pre">__cxa_end_catch</span></tt> to destroy the exception,
+release its memory, and resume normal control flow.</p>
+<p>The Windows EH model does not use these successive register context resets.
+Instead, the active exception is typically described by a frame on the stack.
+In the case of C++ exceptions, the exception object is allocated in stack memory
+and its address is passed to <tt class="docutils literal"><span class="pre">__CxxThrowException</span></tt>. General purpose structured
+exceptions (SEH) are more analogous to Linux signals, and they are dispatched by
+userspace DLLs provided with Windows. Each frame on the stack has an assigned EH
+personality routine, which decides what actions to take to handle the exception.
+There are a few major personalities for C and C++ code: the C++ personality
+(<tt class="docutils literal"><span class="pre">__CxxFrameHandler3</span></tt>) and the SEH personalities (<tt class="docutils literal"><span class="pre">_except_handler3</span></tt>,
+<tt class="docutils literal"><span class="pre">_except_handler4</span></tt>, and <tt class="docutils literal"><span class="pre">__C_specific_handler</span></tt>). All of them implement
+cleanups by calling back into a “funclet” contained in the parent function.</p>
+<p>Funclets, in this context, are regions of the parent function that can be called
+as though they were a function pointer with a very special calling convention.
+The frame pointer of the parent frame is passed into the funclet either using
+the standard EBP register or as the first parameter register, depending on the
+architecture. The funclet implements the EH action by accessing local variables
+in memory through the frame pointer, and returning some appropriate value,
+continuing the EH process. No variables live in to or out of the funclet can be
+allocated in registers.</p>
+<p>The C++ personality also uses funclets to contain the code for catch blocks
+(i.e. all user code between the braces in <tt class="docutils literal"><span class="pre">catch</span> <span class="pre">(Type</span> <span class="pre">obj)</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">}</span></tt>). The
+runtime must use funclets for catch bodies because the C++ exception object is
+allocated in a child stack frame of the function handling the exception. If the
+runtime rewound the stack back to frame of the catch, the memory holding the
+exception would be overwritten quickly by subsequent function calls. The use of
+funclets also allows <tt class="docutils literal"><span class="pre">__CxxFrameHandler3</span></tt> to implement rethrow without
+resorting to TLS. Instead, the runtime throws a special exception, and then uses
+SEH (<tt class="docutils literal"><span class="pre">__try</span> <span class="pre">/</span> <span class="pre">__except</span></tt>) to resume execution with new information in the child
+frame.</p>
+<p>In other words, the successive unwinding approach is incompatible with Visual
+C++ exceptions and general purpose Windows exception handling. Because the C++
+exception object lives in stack memory, LLVM cannot provide a custom personality
+function that uses landingpads. Similarly, SEH does not provide any mechanism
+to rethrow an exception or continue unwinding. Therefore, LLVM must use the IR
+constructs described later in this document to implement compatible exception
+handling.</p>
+</div>
+<div class="section" id="seh-filter-expressions">
+<h3><a class="toc-backref" href="#id33">SEH filter expressions</a><a class="headerlink" href="#seh-filter-expressions" title="Permalink to this headline">¶</a></h3>
+<p>The SEH personality functions also use funclets to implement filter expressions,
+which allow executing arbitrary user code to decide which exceptions to catch.
+Filter expressions should not be confused with the <tt class="docutils literal"><span class="pre">filter</span></tt> clause of the LLVM
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. Typically filter expressions are used to determine
+if the exception came from a particular DLL or code region, or if code faulted
+while accessing a particular memory address range. LLVM does not currently have
+IR to represent filter expressions because it is difficult to represent their
+control dependencies. Filter expressions run during the first phase of EH,
+before cleanups run, making it very difficult to build a faithful control flow
+graph. For now, the new EH instructions cannot represent SEH filter
+expressions, and frontends must outline them ahead of time. Local variables of
+the parent function can be escaped and accessed using the <tt class="docutils literal"><span class="pre">llvm.localescape</span></tt>
+and <tt class="docutils literal"><span class="pre">llvm.localrecover</span></tt> intrinsics.</p>
+</div>
+<div class="section" id="new-exception-handling-instructions">
+<h3><a class="toc-backref" href="#id34">New exception handling instructions</a><a class="headerlink" href="#new-exception-handling-instructions" title="Permalink to this headline">¶</a></h3>
+<p>The primary design goal of the new EH instructions is to support funclet
+generation while preserving information about the CFG so that SSA formation
+still works. As a secondary goal, they are designed to be generic across MSVC
+and Itanium C++ exceptions. They make very few assumptions about the data
+required by the personality, so long as it uses the familiar core EH actions:
+catch, cleanup, and terminate. However, the new instructions are hard to modify
+without knowing details of the EH personality. While they can be used to
+represent Itanium EH, the landingpad model is strictly better for optimization
+purposes.</p>
+<p>The following new instructions are considered “exception handling pads”, in that
+they must be the first non-phi instruction of a basic block that may be the
+unwind destination of an EH flow edge:
+<tt class="docutils literal"><span class="pre">catchswitch</span></tt>, <tt class="docutils literal"><span class="pre">catchpad</span></tt>, and <tt class="docutils literal"><span class="pre">cleanuppad</span></tt>.
+As with landingpads, when entering a try scope, if the
+frontend encounters a call site that may throw an exception, it should emit an
+invoke that unwinds to a <tt class="docutils literal"><span class="pre">catchswitch</span></tt> block. Similarly, inside the scope of a
+C++ object with a destructor, invokes should unwind to a <tt class="docutils literal"><span class="pre">cleanuppad</span></tt>.</p>
+<p>New instructions are also used to mark the points where control is transferred
+out of a catch/cleanup handler (which will correspond to exits from the
+generated funclet). A catch handler which reaches its end by normal execution
+executes a <tt class="docutils literal"><span class="pre">catchret</span></tt> instruction, which is a terminator indicating where in
+the function control is returned to. A cleanup handler which reaches its end
+by normal execution executes a <tt class="docutils literal"><span class="pre">cleanupret</span></tt> instruction, which is a terminator
+indicating where the active exception will unwind to next.</p>
+<p>Each of these new EH pad instructions has a way to identify which action should
+be considered after this action. The <tt class="docutils literal"><span class="pre">catchswitch</span></tt> instruction is a terminator
+and has an unwind destination operand analogous to the unwind destination of an
+invoke. The <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> instruction is not
+a terminator, so the unwind destination is stored on the <tt class="docutils literal"><span class="pre">cleanupret</span></tt>
+instruction instead. Successfully executing a catch handler should resume
+normal control flow, so neither <tt class="docutils literal"><span class="pre">catchpad</span></tt> nor <tt class="docutils literal"><span class="pre">catchret</span></tt> instructions can
+unwind. All of these “unwind edges” may refer to a basic block that contains an
+EH pad instruction, or they may unwind to the caller. Unwinding to the caller
+has roughly the same semantics as the <tt class="docutils literal"><span class="pre">resume</span></tt> instruction in the landingpad
+model. When inlining through an invoke, instructions that unwind to the caller
+are hooked up to unwind to the unwind destination of the call site.</p>
+<p>Putting things together, here is a hypothetical lowering of some C++ that uses
+all of the new IR instructions:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Cleanup</span> <span class="p">{</span>
+ <span class="n">Cleanup</span><span class="p">();</span>
+ <span class="o">~</span><span class="n">Cleanup</span><span class="p">();</span>
+ <span class="kt">int</span> <span class="n">m</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="kt">void</span> <span class="n">may_throw</span><span class="p">();</span>
+<span class="kt">int</span> <span class="n">f</span><span class="p">()</span> <span class="n">noexcept</span> <span class="p">{</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="n">Cleanup</span> <span class="n">obj</span><span class="p">;</span>
+ <span class="n">may_throw</span><span class="p">();</span>
+ <span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="kt">int</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">may_throw</span><span class="p">();</span>
+ <span class="k">return</span> <span class="n">e</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-text"><div class="highlight"><pre>define i32 @f() nounwind personality i32 (...)* @__CxxFrameHandler3 {
+entry:
+ %obj = alloca %struct.Cleanup, align 4
+ %e = alloca i32, align 4
+ %call = invoke %struct.Cleanup* @"\01??0Cleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj)
+ to label %invoke.cont unwind label %lpad.catch
+
+invoke.cont: ; preds = %entry
+ invoke void @"\01?may_throw@@YAXXZ"()
+ to label %invoke.cont.2 unwind label %lpad.cleanup
+
+invoke.cont.2: ; preds = %invoke.cont
+ call void @"\01??_DCleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj) nounwind
+ br label %return
+
+return: ; preds = %invoke.cont.3, %invoke.cont.2
+ %retval.0 = phi i32 [ 0, %invoke.cont.2 ], [ %3, %invoke.cont.3 ]
+ ret i32 %retval.0
+
+lpad.cleanup: ; preds = %invoke.cont.2
+ %0 = cleanuppad within none []
+ call void @"\01??1Cleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj) nounwind
+ cleanupret %0 unwind label %lpad.catch
+
+lpad.catch: ; preds = %lpad.cleanup, %entry
+ %1 = catchswitch within none [label %catch.body] unwind label %lpad.terminate
+
+catch.body: ; preds = %lpad.catch
+ %catch = catchpad within %1 [%rtti.TypeDescriptor2* @"\01??_R0H at 8", i32 0, i32* %e]
+ invoke void @"\01?may_throw@@YAXXZ"()
+ to label %invoke.cont.3 unwind label %lpad.terminate
+
+invoke.cont.3: ; preds = %catch.body
+ %3 = load i32, i32* %e, align 4
+ catchret from %catch to label %return
+
+lpad.terminate: ; preds = %catch.body, %lpad.catch
+ cleanuppad within none []
+ call void @"\01?terminate@@YAXXZ"
+ unreachable
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="funclet-parent-tokens">
+<h3><a class="toc-backref" href="#id35">Funclet parent tokens</a><a class="headerlink" href="#funclet-parent-tokens" title="Permalink to this headline">¶</a></h3>
+<p>In order to produce tables for EH personalities that use funclets, it is
+necessary to recover the nesting that was present in the source. This funclet
+parent relationship is encoded in the IR using tokens produced by the new “pad”
+instructions. The token operand of a “pad” or “ret” instruction indicates which
+funclet it is in, or “none” if it is not nested within another funclet.</p>
+<p>The <tt class="docutils literal"><span class="pre">catchpad</span></tt> and <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> instructions establish new funclets, and
+their tokens are consumed by other “pad” instructions to establish membership.
+The <tt class="docutils literal"><span class="pre">catchswitch</span></tt> instruction does not create a funclet, but it produces a
+token that is always consumed by its immediate successor <tt class="docutils literal"><span class="pre">catchpad</span></tt>
+instructions. This ensures that every catch handler modelled by a <tt class="docutils literal"><span class="pre">catchpad</span></tt>
+belongs to exactly one <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, which models the dispatch point after a
+C++ try.</p>
+<p>Here is an example of what this nesting looks like using some hypothetical
+C++ code:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="n">throw</span><span class="p">;</span>
+ <span class="p">}</span> <span class="n">catch</span> <span class="p">(...)</span> <span class="p">{</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="n">throw</span><span class="p">;</span>
+ <span class="p">}</span> <span class="n">catch</span> <span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-text"><div class="highlight"><pre>define void @f() #0 personality i8* bitcast (i32 (...)* @__CxxFrameHandler3 to i8*) {
+entry:
+ invoke void @_CxxThrowException(i8* null, %eh.ThrowInfo* null) #1
+ to label %unreachable unwind label %catch.dispatch
+
+catch.dispatch: ; preds = %entry
+ %0 = catchswitch within none [label %catch] unwind to caller
+
+catch: ; preds = %catch.dispatch
+ %1 = catchpad within %0 [i8* null, i32 64, i8* null]
+ invoke void @_CxxThrowException(i8* null, %eh.ThrowInfo* null) #1
+ to label %unreachable unwind label %catch.dispatch2
+
+catch.dispatch2: ; preds = %catch
+ %2 = catchswitch within %1 [label %catch3] unwind to caller
+
+catch3: ; preds = %catch.dispatch2
+ %3 = catchpad within %2 [i8* null, i32 64, i8* null]
+ catchret from %3 to label %try.cont
+
+try.cont: ; preds = %catch3
+ catchret from %1 to label %try.cont6
+
+try.cont6: ; preds = %try.cont
+ ret void
+
+unreachable: ; preds = %catch, %entry
+ unreachable
+}
+</pre></div>
+</div>
+<p>The “inner” <tt class="docutils literal"><span class="pre">catchswitch</span></tt> consumes <tt class="docutils literal"><span class="pre">%1</span></tt> which is produced by the outer
+catchswitch.</p>
+</div>
+<div class="section" id="funclet-transitions">
+<span id="wineh-constraints"></span><h3><a class="toc-backref" href="#id36">Funclet transitions</a><a class="headerlink" href="#funclet-transitions" title="Permalink to this headline">¶</a></h3>
+<p>The EH tables for personalities that use funclets make implicit use of the
+funclet nesting relationship to encode unwind destinations, and so are
+constrained in the set of funclet transitions they can represent. The related
+LLVM IR instructions accordingly have constraints that ensure encodability of
+the EH edges in the flow graph.</p>
+<p>A <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, <tt class="docutils literal"><span class="pre">catchpad</span></tt>, or <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> is said to be “entered”
+when it executes. It may subsequently be “exited” by any of the following
+means:</p>
+<ul class="simple">
+<li>A <tt class="docutils literal"><span class="pre">catchswitch</span></tt> is immediately exited when none of its constituent
+<tt class="docutils literal"><span class="pre">catchpad</span></tt>s are appropriate for the in-flight exception and it unwinds
+to its unwind destination or the caller.</li>
+<li>A <tt class="docutils literal"><span class="pre">catchpad</span></tt> and its parent <tt class="docutils literal"><span class="pre">catchswitch</span></tt> are both exited when a
+<tt class="docutils literal"><span class="pre">catchret</span></tt> from the <tt class="docutils literal"><span class="pre">catchpad</span></tt> is executed.</li>
+<li>A <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> is exited when a <tt class="docutils literal"><span class="pre">cleanupret</span></tt> from it is executed.</li>
+<li>Any of these pads is exited when control unwinds to the function’s caller,
+either by a <tt class="docutils literal"><span class="pre">call</span></tt> which unwinds all the way to the function’s caller,
+a nested <tt class="docutils literal"><span class="pre">catchswitch</span></tt> marked “<tt class="docutils literal"><span class="pre">unwinds</span> <span class="pre">to</span> <span class="pre">caller</span></tt>”, or a nested
+<tt class="docutils literal"><span class="pre">cleanuppad</span></tt>‘s <tt class="docutils literal"><span class="pre">cleanupret</span></tt> marked “<tt class="docutils literal"><span class="pre">unwinds</span> <span class="pre">to</span> <span class="pre">caller"</span></tt>.</li>
+<li>Any of these pads is exited when an unwind edge (from an <tt class="docutils literal"><span class="pre">invoke</span></tt>,
+nested <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, or nested <tt class="docutils literal"><span class="pre">cleanuppad</span></tt>‘s <tt class="docutils literal"><span class="pre">cleanupret</span></tt>)
+unwinds to a destination pad that is not a descendant of the given pad.</li>
+</ul>
+<p>Note that the <tt class="docutils literal"><span class="pre">ret</span></tt> instruction is <em>not</em> a valid way to exit a funclet pad;
+it is undefined behavior to execute a <tt class="docutils literal"><span class="pre">ret</span></tt> when a pad has been entered but
+not exited.</p>
+<p>A single unwind edge may exit any number of pads (with the restrictions that
+the edge from a <tt class="docutils literal"><span class="pre">catchswitch</span></tt> must exit at least itself, and the edge from
+a <tt class="docutils literal"><span class="pre">cleanupret</span></tt> must exit at least its <tt class="docutils literal"><span class="pre">cleanuppad</span></tt>), and then must enter
+exactly one pad, which must be distinct from all the exited pads. The parent
+of the pad that an unwind edge enters must be the most-recently-entered
+not-yet-exited pad (after exiting from any pads that the unwind edge exits),
+or “none” if there is no such pad. This ensures that the stack of executing
+funclets at run-time always corresponds to some path in the funclet pad tree
+that the parent tokens encode.</p>
+<p>All unwind edges which exit any given funclet pad (including <tt class="docutils literal"><span class="pre">cleanupret</span></tt>
+edges exiting their <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> and <tt class="docutils literal"><span class="pre">catchswitch</span></tt> edges exiting their
+<tt class="docutils literal"><span class="pre">catchswitch</span></tt>) must share the same unwind destination. Similarly, any
+funclet pad which may be exited by unwind to caller must not be exited by
+any exception edges which unwind anywhere other than the caller. This
+ensures that each funclet as a whole has only one unwind destination, which
+EH tables for funclet personalities may require. Note that any unwind edge
+which exits a <tt class="docutils literal"><span class="pre">catchpad</span></tt> also exits its parent <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, so this
+implies that for any given <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, its unwind destination must also
+be the unwind destination of any unwind edge that exits any of its constituent
+<tt class="docutils literal"><span class="pre">catchpad</span></tt>s. Because <tt class="docutils literal"><span class="pre">catchswitch</span></tt> has no <tt class="docutils literal"><span class="pre">nounwind</span></tt> variant, and
+because IR producers are not <em>required</em> to annotate calls which will not
+unwind as <tt class="docutils literal"><span class="pre">nounwind</span></tt>, it is legal to nest a <tt class="docutils literal"><span class="pre">call</span></tt> or an “<tt class="docutils literal"><span class="pre">unwind</span> <span class="pre">to</span>
+<span class="pre">caller</span></tt>” <tt class="docutils literal"><span class="pre">catchswitch</span></tt> within a funclet pad that has an unwind
+destination other than caller; it is undefined behavior for such a <tt class="docutils literal"><span class="pre">call</span></tt>
+or <tt class="docutils literal"><span class="pre">catchswitch</span></tt> to unwind.</p>
+<p>Finally, the funclet pads’ unwind destinations cannot form a cycle. This
+ensures that EH lowering can construct “try regions” with a tree-like
+structure, which funclet-based personalities may require.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodeGenerator.html" title="The LLVM Target-Independent Code Generator"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/ExtendingLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/ExtendingLLVM.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/ExtendingLLVM.html (added)
+++ www-releases/trunk/5.0.2/docs/ExtendingLLVM.html Thu May 10 06:54:16 2018
@@ -0,0 +1,381 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Extending LLVM: Adding instructions, intrinsics, types, etc. — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="How to set up LLVM-style RTTI for your class hierarchy" href="HowToSetUpLLVMStyleRTTI.html" />
+ <link rel="prev" title="Architecture & Platform Information for Compiler Writers" href="CompilerWriterInfo.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="extending-llvm-adding-instructions-intrinsics-types-etc">
+<h1>Extending LLVM: Adding instructions, intrinsics, types, etc.<a class="headerlink" href="#extending-llvm-adding-instructions-intrinsics-types-etc" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction-and-warning">
+<h2>Introduction and Warning<a class="headerlink" href="#introduction-and-warning" title="Permalink to this headline">¶</a></h2>
+<p>During the course of using LLVM, you may wish to customize it for your research
+project or for experimentation. At this point, you may realize that you need to
+add something to LLVM, whether it be a new fundamental type, a new intrinsic
+function, or a whole new instruction.</p>
+<p>When you come to this realization, stop and think. Do you really need to extend
+LLVM? Is it a new fundamental capability that LLVM does not support at its
+current incarnation or can it be synthesized from already pre-existing LLVM
+elements? If you are not sure, ask on the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">LLVM-dev</a> list. The reason is that
+extending LLVM will get involved as you need to update all the different passes
+that you intend to use with your extension, and there are <tt class="docutils literal"><span class="pre">many</span></tt> LLVM analyses
+and transformations, so it may be quite a bit of work.</p>
+<p>Adding an <a class="reference internal" href="#intrinsic-function">intrinsic function</a> is far easier than adding an
+instruction, and is transparent to optimization passes. If your added
+functionality can be expressed as a function call, an intrinsic function is the
+method of choice for LLVM extension.</p>
+<p>Before you invest a significant amount of effort into a non-trivial extension,
+<strong>ask on the list</strong> if what you are looking to do can be done with
+already-existing infrastructure, or if maybe someone else is already working on
+it. You will save yourself a lot of time and effort by doing so.</p>
+</div>
+<div class="section" id="adding-a-new-intrinsic-function">
+<span id="intrinsic-function"></span><h2>Adding a new intrinsic function<a class="headerlink" href="#adding-a-new-intrinsic-function" title="Permalink to this headline">¶</a></h2>
+<p>Adding a new intrinsic function to LLVM is much easier than adding a new
+instruction. Almost all extensions to LLVM should start as an intrinsic
+function and then be turned into an instruction if warranted.</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/docs/LangRef.html</span></tt>:</p>
+<p>Document the intrinsic. Decide whether it is code generator specific and
+what the restrictions are. Talk to other people about it so that you are
+sure it’s a good idea.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Intrinsics*.td</span></tt>:</p>
+<p>Add an entry for your intrinsic. Describe its memory access characteristics
+for optimization (this controls whether it will be DCE’d, CSE’d, etc). Note
+that any intrinsic using one of the <tt class="docutils literal"><span class="pre">llvm_any*_ty</span></tt> types for an argument or
+return type will be deemed by <tt class="docutils literal"><span class="pre">tblgen</span></tt> as overloaded and the corresponding
+suffix will be required on the intrinsic’s name.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Analysis/ConstantFolding.cpp</span></tt>:</p>
+<p>If it is possible to constant fold your intrinsic, add support to it in the
+<tt class="docutils literal"><span class="pre">canConstantFoldCallTo</span></tt> and <tt class="docutils literal"><span class="pre">ConstantFoldCall</span></tt> functions.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/*</span></tt>:</p>
+<p>Add test cases for your test cases to the test suite</p>
+</li>
+</ol>
+<p>Once the intrinsic has been added to the system, you must add code generator
+support for it. Generally you must do the following steps:</p>
+<p>Add support to the .td file for the target(s) of your choice in
+<tt class="docutils literal"><span class="pre">lib/Target/*/*.td</span></tt>.</p>
+<blockquote>
+<div>This is usually a matter of adding a pattern to the .td file that matches the
+intrinsic, though it may obviously require adding the instructions you want to
+generate as well. There are lots of examples in the PowerPC and X86 backend
+to follow.</div></blockquote>
+</div>
+<div class="section" id="adding-a-new-selectiondag-node">
+<h2>Adding a new SelectionDAG node<a class="headerlink" href="#adding-a-new-selectiondag-node" title="Permalink to this headline">¶</a></h2>
+<p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier than
+adding a new instruction. New nodes are often added to help represent
+instructions common to many targets. These nodes often map to an LLVM
+instruction (add, sub) or intrinsic (byteswap, population count). In other
+cases, new nodes have been added to allow many targets to perform a common task
+(converting between floating point and integer representation) or capture more
+complicated behavior in a single node (rotate).</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">include/llvm/CodeGen/ISDOpcodes.h</span></tt>:</p>
+<p>Add an enum value for the new SelectionDAG node.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/SelectionDAG.cpp</span></tt>:</p>
+<dl class="docutils">
+<dt>Add code to print the node to <tt class="docutils literal"><span class="pre">getOperationName</span></tt>. If your new node can be</dt>
+<dd><p class="first last">evaluated at compile time when given constant arguments (such as an add of a
+constant with another constant), find the <tt class="docutils literal"><span class="pre">getNode</span></tt> method that takes the
+appropriate number of arguments, and add a case for your node to the switch
+statement that performs constant folding for nodes that take the same number
+of arguments as your new node.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<p>Add code to <a class="reference external" href="CodeGenerator.html#selectiondag_legalize">legalize, promote, and expand</a> the node as necessary. At a
+minimum, you will need to add a case statement for your node in
+<tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> which calls LegalizeOp on the node’s operands, and returns a
+new node if any of the operands changed as a result of being legalized. It
+is likely that not all targets supported by the SelectionDAG framework will
+natively support the new node. In this case, you must also add code in your
+node’s case statement in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> to Expand your node into simpler,
+legal operations. The case for <tt class="docutils literal"><span class="pre">ISD::UREM</span></tt> for expanding a remainder into
+a divide, multiply, and a subtract is a good example.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<dl class="docutils">
+<dt>If targets may support the new node being added only at certain sizes, you</dt>
+<dd><p class="first last">will also need to add code to your node’s case statement in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt>
+to Promote your node’s operands to a larger size, and perform the correct
+operation. You will also need to add code to <tt class="docutils literal"><span class="pre">PromoteOp</span></tt> to do this as
+well. For a good example, see <tt class="docutils literal"><span class="pre">ISD::BSWAP</span></tt>, which promotes its operand to
+a wider size, performs the byteswap, and then shifts the correct bytes right
+to emulate the narrower byteswap in the wider type.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<p>Add a case for your node in <tt class="docutils literal"><span class="pre">ExpandOp</span></tt> to teach the legalizer how to
+perform the action represented by the new node on a value that has been split
+into high and low halves. This case will be used to support your node with a
+64 bit operand on a 32 bit target.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/DAGCombiner.cpp</span></tt>:</p>
+<p>If your node can be combined with itself, or other existing nodes in a
+peephole-like fashion, add a visit function for it, and call that function
+from. There are several good examples for simple combines you can do;
+<tt class="docutils literal"><span class="pre">visitFABS</span></tt> and <tt class="docutils literal"><span class="pre">visitSRL</span></tt> are good starting places.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/PowerPC/PPCISelLowering.cpp</span></tt>:</p>
+<p>Each target has an implementation of the <tt class="docutils literal"><span class="pre">TargetLowering</span></tt> class, usually in
+its own file (although some targets include it in the same file as the
+DAGToDAGISel). The default behavior for a target is to assume that your new
+node is legal for all types that are legal for that target. If this target
+does not natively support your node, then tell the target to either Promote
+it (if it is supported at a larger type) or Expand it. This will cause the
+code you wrote in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> above to decompose your new node into other
+legal nodes for this target.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/TargetSelectionDAG.td</span></tt>:</p>
+<p>Most current targets supported by LLVM generate code using the DAGToDAG
+method, where SelectionDAG nodes are pattern matched to target-specific
+nodes, which represent individual instructions. In order for the targets to
+match an instruction to your new node, you must add a def for that node to
+the list in this file, with the appropriate type constraints. Look at
+<tt class="docutils literal"><span class="pre">add</span></tt>, <tt class="docutils literal"><span class="pre">bswap</span></tt>, and <tt class="docutils literal"><span class="pre">fadd</span></tt> for examples.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/PowerPC/PPCInstrInfo.td</span></tt>:</p>
+<p>Each target has a tablegen file that describes the target’s instruction set.
+For targets that use the DAGToDAG instruction selection framework, add a
+pattern for your new node that uses one or more target nodes. Documentation
+for this is a bit sparse right now, but there are several decent examples.
+See the patterns for <tt class="docutils literal"><span class="pre">rotl</span></tt> in <tt class="docutils literal"><span class="pre">PPCInstrInfo.td</span></tt>.</p>
+</li>
+<li><p class="first">TODO: document complex patterns.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/CodeGen/*</span></tt>:</p>
+<p>Add test cases for your new node to the test suite.
+<tt class="docutils literal"><span class="pre">llvm/test/CodeGen/X86/bswap.ll</span></tt> is a good example.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="adding-a-new-instruction">
+<h2>Adding a new instruction<a class="headerlink" href="#adding-a-new-instruction" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Adding instructions changes the bitcode format, and it will take some effort
+to maintain compatibility with the previous version. Only add an instruction
+if it is absolutely necessary.</p>
+</div>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Instruction.def</span></tt>:</p>
+<p>add a number for your instruction and an enum name</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Instructions.h</span></tt>:</p>
+<p>add a definition for the class that will represent your instruction</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/InstVisitor.h</span></tt>:</p>
+<p>add a prototype for a visitor to your new instruction type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></tt>:</p>
+<p>add a new token to parse your instruction from assembly text file</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLParser.cpp</span></tt>:</p>
+<p>add the grammar on how your instruction can be read and what it will
+construct as a result</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></tt>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></tt>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/Instruction.cpp</span></tt>:</p>
+<p>add a case for how your instruction will be printed out to assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/Instructions.cpp</span></tt>:</p>
+<p>implement the class you defined in <tt class="docutils literal"><span class="pre">llvm/include/llvm/Instructions.h</span></tt></p>
+</li>
+<li><p class="first">Test your instruction</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Target/*</span></tt>:</p>
+<p>add support for your instruction to code generators, or add a lowering pass.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/*</span></tt>:</p>
+<p>add your test cases to the test suite.</p>
+</li>
+</ol>
+<p>Also, you need to implement (or modify) any analyses or passes that you want to
+understand this new instruction.</p>
+</div>
+<div class="section" id="adding-a-new-type">
+<h2>Adding a new type<a class="headerlink" href="#adding-a-new-type" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Adding new types changes the bitcode format, and will break compatibility with
+currently-existing LLVM installations. Only add new types if it is absolutely
+necessary.</p>
+</div>
+<div class="section" id="adding-a-fundamental-type">
+<h3>Adding a fundamental type<a class="headerlink" href="#adding-a-fundamental-type" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Type.h</span></tt>:</p>
+<p>add enum for the new type; add static <tt class="docutils literal"><span class="pre">Type*</span></tt> for this type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/Type.cpp</span></tt> and <tt class="docutils literal"><span class="pre">llvm/lib/IR/ValueTypes.cpp</span></tt>:</p>
+<p>add mapping from <tt class="docutils literal"><span class="pre">TypeID</span></tt> => <tt class="docutils literal"><span class="pre">Type*</span></tt>; initialize the static <tt class="docutils literal"><span class="pre">Type*</span></tt></p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/llvm/llvm-c/Core.cpp</span></tt>:</p>
+<p>add enum <tt class="docutils literal"><span class="pre">LLVMTypeKind</span></tt> and modify
+<tt class="docutils literal"><span class="pre">LLVMTypeKind</span> <span class="pre">LLVMGetTypeKind(LLVMTypeRef</span> <span class="pre">Ty)</span></tt> for the new type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/TypeBuilder.h</span></tt>:</p>
+<p>add new class to represent new type in the hierarchy</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></tt>:</p>
+<p>add ability to parse in the type from text assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLParser.cpp</span></tt>:</p>
+<p>add a token for that type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">static</span> <span class="pre">void</span> <span class="pre">WriteTypeTable(const</span> <span class="pre">ValueEnumerator</span> <span class="pre">&VE,</span>
+<span class="pre">BitstreamWriter</span> <span class="pre">&Stream)</span></tt> to serialize your type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">BitcodeReader::ParseTypeType()</span></tt> to read your data type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">include/llvm/Bitcode/LLVMBitCodes.h</span></tt>:</p>
+<p>add enum <tt class="docutils literal"><span class="pre">TypeCodes</span></tt> for the new type</p>
+</li>
+</ol>
+</div>
+<div class="section" id="adding-a-derived-type">
+<h3>Adding a derived type<a class="headerlink" href="#adding-a-derived-type" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Type.h</span></tt>:</p>
+<p>add enum for the new type; add a forward declaration of the type also</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/DerivedTypes.h</span></tt>:</p>
+<p>add new class to represent new class in the hierarchy; add forward
+declaration to the TypeMap value type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/Type.cpp</span></tt> and <tt class="docutils literal"><span class="pre">llvm/lib/IR/ValueTypes.cpp</span></tt>:</p>
+<p>add support for derived type, notably <cite>enum TypeID</cite> and <cite>is</cite>, <cite>get</cite> methods.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/llvm/llvm-c/Core.cpp</span></tt>:</p>
+<p>add enum <tt class="docutils literal"><span class="pre">LLVMTypeKind</span></tt> and modify
+<cite>LLVMTypeKind LLVMGetTypeKind(LLVMTypeRef Ty)</cite> for the new type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/TypeBuilder.h</span></tt>:</p>
+<p>add new class to represent new class in the hierarchy</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">lltok::Kind</span> <span class="pre">LLLexer::LexIdentifier()</span></tt> to add ability to
+parse in the type from text assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">static</span> <span class="pre">void</span> <span class="pre">WriteTypeTable(const</span> <span class="pre">ValueEnumerator</span> <span class="pre">&VE,</span>
+<span class="pre">BitstreamWriter</span> <span class="pre">&Stream)</span></tt> to serialize your type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">BitcodeReader::ParseTypeType()</span></tt> to read your data type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">include/llvm/Bitcode/LLVMBitCodes.h</span></tt>:</p>
+<p>add enum <tt class="docutils literal"><span class="pre">TypeCodes</span></tt> for the new type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/AsmWriter.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">void</span> <span class="pre">TypePrinting::print(Type</span> <span class="pre">*Ty,</span> <span class="pre">raw_ostream</span> <span class="pre">&OS)</span></tt>
+to output the new derived type</p>
+</li>
+</ol>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/Extensions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/Extensions.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/Extensions.html (added)
+++ www-releases/trunk/5.0.2/docs/Extensions.html Thu May 10 06:54:16 2018
@@ -0,0 +1,371 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Extensions — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="libFuzzer â a library for coverage-guided fuzz testing." href="LibFuzzer.html" />
+ <link rel="prev" title="LLVM Programmerâs Manual" href="ProgrammersManual.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-extensions">
+<h1>LLVM Extensions<a class="headerlink" href="#llvm-extensions" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>
+<li><a class="reference internal" href="#general-assembly-syntax" id="id4">General Assembly Syntax</a><ul>
+<li><a class="reference internal" href="#c99-style-hexadecimal-floating-point-constants" id="id5">C99-style Hexadecimal Floating-point Constants</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#machine-specific-assembly-syntax" id="id6">Machine-specific Assembly Syntax</a><ul>
+<li><a class="reference internal" href="#x86-coff-dependent" id="id7">X86/COFF-Dependent</a><ul>
+<li><a class="reference internal" href="#relocations" id="id8">Relocations</a></li>
+<li><a class="reference internal" href="#linkonce-directive" id="id9"><tt class="docutils literal"><span class="pre">.linkonce</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#section-directive" id="id10"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#elf-dependent" id="id11">ELF-Dependent</a><ul>
+<li><a class="reference internal" href="#id1" id="id12"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-specific-behaviour" id="id13">Target Specific Behaviour</a><ul>
+<li><a class="reference internal" href="#x86" id="id14">X86</a><ul>
+<li><a class="reference internal" href="#id2" id="id15">Relocations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#windows-on-arm" id="id16">Windows on ARM</a><ul>
+<li><a class="reference internal" href="#stack-probe-emission" id="id17">Stack Probe Emission</a></li>
+<li><a class="reference internal" href="#variable-length-arrays" id="id18">Variable Length Arrays</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="#id3">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="#id4">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="#id5">C99-style Hexadecimal Floating-point Constants</a><a class="headerlink" href="#c99-style-hexadecimal-floating-point-constants" title="Permalink to this headline">¶</a></h3>
+<p>LLVM’s assemblers allow floating-point constants to be written in C99’s
+hexadecimal format instead of decimal if desired.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.data</span>
+<span class="na">.float</span> <span class="mi">0x1c2</span><span class="no">.2ap3</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="machine-specific-assembly-syntax">
+<h2><a class="toc-backref" href="#id6">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="#id7">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="#id8">Relocations</a><a class="headerlink" href="#relocations" title="Permalink to this headline">¶</a></h4>
+<p>The following additional relocation types are supported:</p>
+<p><strong>@IMGREL</strong> (AT&T syntax only) generates an image-relative relocation that
+corresponds to the COFF relocation types <tt class="docutils literal"><span class="pre">IMAGE_REL_I386_DIR32NB</span></tt> (32-bit) or
+<tt class="docutils literal"><span class="pre">IMAGE_REL_AMD64_ADDR32NB</span></tt> (64-bit).</p>
+<div class="highlight-text"><div class="highlight"><pre>.text
+fun:
+ mov foo at IMGREL(%ebx, %ecx, 4), %eax
+
+.section .pdata
+ .long fun at IMGREL
+ .long (fun at imgrel + 0x3F)
+ .long $unwind$fun at imgrel
+</pre></div>
+</div>
+<p><strong>.secrel32</strong> generates a relocation that corresponds to the COFF relocation
+types <tt class="docutils literal"><span class="pre">IMAGE_REL_I386_SECREL</span></tt> (32-bit) or <tt class="docutils literal"><span class="pre">IMAGE_REL_AMD64_SECREL</span></tt> (64-bit).</p>
+<p><strong>.secidx</strong> relocation generates an index of the section that contains
+the target. It corresponds to the COFF relocation types
+<tt class="docutils literal"><span class="pre">IMAGE_REL_I386_SECTION</span></tt> (32-bit) or <tt class="docutils literal"><span class="pre">IMAGE_REL_AMD64_SECTION</span></tt> (64-bit).</p>
+<div class="highlight-none"><div class="highlight"><pre>.section .debug$S,"rn"
+ .long 4
+ .long 242
+ .long 40
+ .secrel32 _function_name + 0
+ .secidx _function_name
+ ...
+</pre></div>
+</div>
+</div>
+<div class="section" id="linkonce-directive">
+<h4><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">.linkonce</span></tt> Directive</a><a class="headerlink" href="#linkonce-directive" title="Permalink to this headline">¶</a></h4>
+<p>Syntax:</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">.linkonce</span> <span class="pre">[</span> <span class="pre">comdat</span> <span class="pre">type</span> <span class="pre">]</span></tt></div></blockquote>
+<p>Supported COMDAT types:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">discard</span></tt></dt>
+<dd>Discards duplicate sections with the same COMDAT symbol. This is the default
+if no type is specified.</dd>
+<dt><tt class="docutils literal"><span class="pre">one_only</span></tt></dt>
+<dd>If the symbol is defined multiple times, the linker issues an error.</dd>
+<dt><tt class="docutils literal"><span class="pre">same_size</span></tt></dt>
+<dd>Duplicates are discarded, but the linker issues an error if any have
+different sizes.</dd>
+<dt><tt class="docutils literal"><span class="pre">same_contents</span></tt></dt>
+<dd>Duplicates are discarded, but the linker issues an error if any duplicates
+do not have exactly the same content.</dd>
+<dt><tt class="docutils literal"><span class="pre">largest</span></tt></dt>
+<dd>Links the largest section from among the duplicates.</dd>
+<dt><tt class="docutils literal"><span class="pre">newest</span></tt></dt>
+<dd>Links the newest section from among the duplicates.</dd>
+</dl>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.text$foo</span>
+<span class="na">.linkonce</span>
+ <span class="na">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="section-directive">
+<h4><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a><a class="headerlink" href="#section-directive" title="Permalink to this headline">¶</a></h4>
+<p>MC supports passing the information in <tt class="docutils literal"><span class="pre">.linkonce</span></tt> at the end of
+<tt class="docutils literal"><span class="pre">.section</span></tt>. For example, these two codes are equivalent</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol1"</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span>
+<span class="na">.linkonce</span> <span class="no">discard</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<p>Note that in the combined form the COMDAT symbol is explicit. This
+extension exists to support multiple sections with the same name in
+different COMDATs:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol1"</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+
+<span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol2"</span>
+<span class="na">.globl</span> <span class="no">Symbol2</span>
+<span class="nl">Symbol2:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<p>In addition to the types allowed with <tt class="docutils literal"><span class="pre">.linkonce</span></tt>, <tt class="docutils literal"><span class="pre">.section</span></tt> also accepts
+<tt class="docutils literal"><span class="pre">associative</span></tt>. The meaning is that the section is linked if a certain other
+COMDAT section is linked. This other section is indicated by the comdat symbol
+in this directive. It can be any symbol defined in the associated section, but
+is usually the associated section’s comdat.</p>
+<blockquote>
+<div><p>The following restrictions apply to the associated section:</p>
+<ol class="arabic simple">
+<li>It must be a COMDAT section.</li>
+<li>It cannot be another associative COMDAT section.</li>
+</ol>
+</div></blockquote>
+<p>In the following example the symobl <tt class="docutils literal"><span class="pre">sym</span></tt> is the comdat symbol of <tt class="docutils literal"><span class="pre">.foo</span></tt>
+and <tt class="docutils literal"><span class="pre">.bar</span></tt> is associated to <tt class="docutils literal"><span class="pre">.foo</span></tt>.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"bw"</span><span class="p">,</span><span class="no">discard</span><span class="p">,</span> <span class="s">"sym"</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"rd"</span><span class="p">,</span><span class="no">associative</span><span class="p">,</span> <span class="s">"sym"</span>
+</pre></div>
+</div>
+<p>MC supports these flags in the COFF <tt class="docutils literal"><span class="pre">.section</span></tt> directive:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">b</span></tt>: BSS section (<tt class="docutils literal"><span class="pre">IMAGE_SCN_CNT_INITIALIZED_DATA</span></tt>)</li>
+<li><tt class="docutils literal"><span class="pre">d</span></tt>: Data section (<tt class="docutils literal"><span class="pre">IMAGE_SCN_CNT_UNINITIALIZED_DATA</span></tt>)</li>
+<li><tt class="docutils literal"><span class="pre">n</span></tt>: Section is not loaded (<tt class="docutils literal"><span class="pre">IMAGE_SCN_LNK_REMOVE</span></tt>)</li>
+<li><tt class="docutils literal"><span class="pre">r</span></tt>: Read-only</li>
+<li><tt class="docutils literal"><span class="pre">s</span></tt>: Shared section</li>
+<li><tt class="docutils literal"><span class="pre">w</span></tt>: Writable</li>
+<li><tt class="docutils literal"><span class="pre">x</span></tt>: Executable section</li>
+<li><tt class="docutils literal"><span class="pre">y</span></tt>: Not readable</li>
+<li><tt class="docutils literal"><span class="pre">D</span></tt>: Discardable (<tt class="docutils literal"><span class="pre">IMAGE_SCN_MEM_DISCARDABLE</span></tt>)</li>
+</ul>
+</div></blockquote>
+<p>These flags are all compatible with gas, with the exception of the <tt class="docutils literal"><span class="pre">D</span></tt> flag,
+which gnu as does not support. For gas compatibility, sections with a name
+starting with ”.debug” are implicitly discardable.</p>
+</div>
+</div>
+<div class="section" id="elf-dependent">
+<h3><a class="toc-backref" href="#id11">ELF-Dependent</a><a class="headerlink" href="#elf-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id1">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>In order to support creating multiple sections with the same name and comdat,
+it is possible to add an unique number at the end of the <tt class="docutils literal"><span class="pre">.seciton</span></tt> directive.
+For example, the following code creates two sections named <tt class="docutils literal"><span class="pre">.text</span></tt>.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.text</span><span class="p">,</span><span class="s">"ax"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,</span><span class="no">unique</span><span class="p">,</span><span class="mi">1</span>
+<span class="nf">nop</span>
+
+<span class="na">.section</span> <span class="no">.text</span><span class="p">,</span><span class="s">"ax"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,</span><span class="no">unique</span><span class="p">,</span><span class="mi">2</span>
+<span class="nf">nop</span>
+</pre></div>
+</div>
+<p>The unique number is not present in the resulting object at all. It is just used
+in the assembler to differentiate the sections.</p>
+<p>The ‘o’ flag is mapped to SHF_LINK_ORDER. If it is present, a symbol
+must be given that identifies the section to be placed is the
+.sh_link.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"a"</span><span class="p">,</span><span class="na">@progbits</span>
+<span class="nl">.Ltmp:</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"ao"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,.</span><span class="no">Ltmp</span>
+</pre></div>
+</div>
+<p>which is equivalent to just</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"a"</span><span class="p">,</span><span class="na">@progbits</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"ao"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,.</span><span class="no">foo</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="target-specific-behaviour">
+<h2><a class="toc-backref" href="#id13">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="#id14">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id2">
+<h4><a class="toc-backref" href="#id15">Relocations</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">@ABS8</span></tt> can be applied to symbols which appear as immediate operands to
+instructions that have an 8-bit immediate form for that operand. It causes
+the assembler to use the 8-bit form and an 8-bit relocation (e.g. <tt class="docutils literal"><span class="pre">R_386_8</span></tt>
+or <tt class="docutils literal"><span class="pre">R_X86_64_8</span></tt>) for the symbol.</p>
+<p>For example:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="nf">cmpq</span> <span class="no">$foo at ABS8</span><span class="p">,</span> <span class="nv">%rdi</span>
+</pre></div>
+</div>
+<p>This causes the assembler to select the form of the 64-bit <tt class="docutils literal"><span class="pre">cmpq</span></tt> instruction
+that takes an 8-bit immediate operand that is sign extended to 64 bits, as
+opposed to <tt class="docutils literal"><span class="pre">cmpq</span> <span class="pre">$foo,</span> <span class="pre">%rdi</span></tt> which takes a 32-bit immediate operand. This
+is also not the same as <tt class="docutils literal"><span class="pre">cmpb</span> <span class="pre">$foo,</span> <span class="pre">%dil</span></tt>, which is an 8-bit comparison.</p>
+</div>
+</div>
+<div class="section" id="windows-on-arm">
+<h3><a class="toc-backref" href="#id16">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="#id17">Stack Probe Emission</a><a class="headerlink" href="#stack-probe-emission" title="Permalink to this headline">¶</a></h4>
+<p>The reference implementation (Microsoft Visual Studio 2012) emits stack probes
+in the following fashion:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="nf">movw</span> <span class="no">r4</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="nf">bl</span> <span class="no">__chkstk</span>
+<span class="nf">sub.w</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">r4</span>
+</pre></div>
+</div>
+<p>However, this has the limitation of 32 MiB (±16MiB). In order to accommodate
+larger binaries, LLVM supports the use of <tt class="docutils literal"><span class="pre">-mcode-model=large</span></tt> to allow a 4GiB
+range via a slight deviation. It will generate an indirect jump as follows:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="nf">movw</span> <span class="no">r4</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="nf">movw</span> <span class="no">r12</span><span class="p">,</span> <span class="p">:</span><span class="no">lower16</span><span class="p">:</span><span class="no">__chkstk</span>
+<span class="nf">movt</span> <span class="no">r12</span><span class="p">,</span> <span class="p">:</span><span class="no">upper16</span><span class="p">:</span><span class="no">__chkstk</span>
+<span class="nf">blx</span> <span class="no">r12</span>
+<span class="nf">sub.w</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">r4</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="variable-length-arrays">
+<h4><a class="toc-backref" href="#id18">Variable Length Arrays</a><a class="headerlink" href="#variable-length-arrays" title="Permalink to this headline">¶</a></h4>
+<p>The reference implementation (Microsoft Visual Studio 2012) does not permit the
+emission of Variable Length Arrays (VLAs).</p>
+<p>The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
+a dynamic stack allocation. When emitting a variable stack allocation, a call
+to <tt class="docutils literal"><span class="pre">__chkstk</span></tt> is emitted unconditionally to ensure that guard pages are setup
+properly. The emission of this stack probe emission is handled similar to the
+standard stack probe emission.</p>
+<p>The MSVC environment does not emit code for VLAs currently.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/FAQ.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/FAQ.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/FAQ.html (added)
+++ www-releases/trunk/5.0.2/docs/FAQ.html Thu May 10 06:54:16 2018
@@ -0,0 +1,437 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Frequently Asked Questions (FAQ) — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="The LLVM Lexicon" href="Lexicon.html" />
+ <link rel="prev" title="Getting Started with the LLVM System using Microsoft Visual Studio" href="GettingStartedVS.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="frequently-asked-questions-faq">
+<h1>Frequently Asked Questions (FAQ)<a class="headerlink" href="#frequently-asked-questions-faq" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#license" id="id1">License</a><ul>
+<li><a class="reference internal" href="#does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license" id="id2">Does the University of Illinois Open Source License really qualify as an “open source” license?</a></li>
+<li><a class="reference internal" href="#can-i-modify-llvm-source-code-and-redistribute-the-modified-source" id="id3">Can I modify LLVM source code and redistribute the modified source?</a></li>
+<li><a class="reference internal" href="#can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source" id="id4">Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#source-code" id="id5">Source Code</a><ul>
+<li><a class="reference internal" href="#in-what-language-is-llvm-written" id="id6">In what language is LLVM written?</a></li>
+<li><a class="reference internal" href="#how-portable-is-the-llvm-source-code" id="id7">How portable is the LLVM source code?</a></li>
+<li><a class="reference internal" href="#what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation" id="id8">What API do I use to store a value to one of the virtual registers in LLVM IR’s SSA representation?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#source-languages" id="id9">Source Languages</a><ul>
+<li><a class="reference internal" href="#what-source-languages-are-supported" id="id10">What source languages are supported?</a></li>
+<li><a class="reference internal" href="#i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators" id="id11">I’d like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?</a></li>
+<li><a class="reference internal" href="#what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler" id="id12">What support is there for a higher level source language constructs for building a compiler?</a></li>
+<li><a class="reference internal" href="#i-don-t-understand-the-getelementptr-instruction-help" id="id13">I don’t understand the <tt class="docutils literal"><span class="pre">GetElementPtr</span></tt> instruction. Help!</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#using-the-c-and-c-front-ends" id="id14">Using the C and C++ Front Ends</a><ul>
+<li><a class="reference internal" href="#can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode" id="id15">Can I compile C or C++ code to platform-independent LLVM bitcode?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#questions-about-code-generated-by-the-demo-page" id="id16">Questions about code generated by the demo page</a><ul>
+<li><a class="reference internal" href="#what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream" id="id17">What is this <tt class="docutils literal"><span class="pre">llvm.global_ctors</span></tt> and <tt class="docutils literal"><span class="pre">_GLOBAL__I_a...</span></tt> stuff that happens when I <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt>?</a></li>
+<li><a class="reference internal" href="#where-did-all-of-my-code-go" id="id18">Where did all of my code go??</a></li>
+<li><a class="reference internal" href="#what-is-this-undef-thing-that-shows-up-in-my-code" id="id19">What is this “<tt class="docutils literal"><span class="pre">undef</span></tt>” thing that shows up in my code?</a></li>
+<li><a class="reference internal" href="#why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it" id="id20">Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into “unreachable”? Why not make the verifier reject it?</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="license">
+<h2><a class="toc-backref" href="#id1">License</a><a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license">
+<h3><a class="toc-backref" href="#id2">Does the University of Illinois Open Source License really qualify as an “open source” license?</a><a class="headerlink" href="#does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license" title="Permalink to this headline">¶</a></h3>
+<p>Yes, the license is <a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open Source
+Initiative (OSI).</p>
+</div>
+<div class="section" id="can-i-modify-llvm-source-code-and-redistribute-the-modified-source">
+<h3><a class="toc-backref" href="#id3">Can I modify LLVM source code and redistribute the modified source?</a><a class="headerlink" href="#can-i-modify-llvm-source-code-and-redistribute-the-modified-source" title="Permalink to this headline">¶</a></h3>
+<p>Yes. The modified source distribution must retain the copyright notice and
+follow the three bulleted conditions listed in the <a class="reference external" href="http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT">LLVM license</a>.</p>
+</div>
+<div class="section" id="can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source">
+<h3><a class="toc-backref" href="#id4">Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?</a><a class="headerlink" href="#can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source" title="Permalink to this headline">¶</a></h3>
+<p>Yes. This is why we distribute LLVM under a less restrictive license than GPL,
+as explained in the first question above.</p>
+</div>
+</div>
+<div class="section" id="source-code">
+<h2><a class="toc-backref" href="#id5">Source Code</a><a class="headerlink" href="#source-code" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="in-what-language-is-llvm-written">
+<h3><a class="toc-backref" href="#id6">In what language is LLVM written?</a><a class="headerlink" href="#in-what-language-is-llvm-written" title="Permalink to this headline">¶</a></h3>
+<p>All of the LLVM tools and libraries are written in C++ with extensive use of
+the STL.</p>
+</div>
+<div class="section" id="how-portable-is-the-llvm-source-code">
+<h3><a class="toc-backref" href="#id7">How portable is the LLVM source code?</a><a class="headerlink" href="#how-portable-is-the-llvm-source-code" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM source code should be portable to most modern Unix-like operating
+systems. Most of the code is written in standard C++ with operating system
+services abstracted to a support library. The tools required to build and
+test LLVM have been ported to a plethora of platforms.</p>
+<p>Some porting problems may exist in the following areas:</p>
+<ul class="simple">
+<li>The autoconf/makefile build system relies heavily on UNIX shell tools,
+like the Bourne Shell and sed. Porting to systems without these tools
+(MacOS 9, Plan 9) will require more effort.</li>
+</ul>
+</div>
+<div class="section" id="what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation">
+<h3><a class="toc-backref" href="#id8">What API do I use to store a value to one of the virtual registers in LLVM IR’s SSA representation?</a><a class="headerlink" href="#what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation" title="Permalink to this headline">¶</a></h3>
+<p>In short: you can’t. It’s actually kind of a silly question once you grok
+what’s going on. Basically, in code like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%result</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%foo</span><span class="p">,</span> <span class="nv">%bar</span>
+</pre></div>
+</div>
+<p>, <tt class="docutils literal"><span class="pre">%result</span></tt> is just a name given to the <tt class="docutils literal"><span class="pre">Value</span></tt> of the <tt class="docutils literal"><span class="pre">add</span></tt>
+instruction. In other words, <tt class="docutils literal"><span class="pre">%result</span></tt> <em>is</em> the add instruction. The
+“assignment” doesn’t explicitly “store” anything to any “virtual register”;
+the “<tt class="docutils literal"><span class="pre">=</span></tt>” is more like the mathematical sense of equality.</p>
+<p>Longer explanation: In order to generate a textual representation of the
+IR, some kind of name has to be given to each instruction so that other
+instructions can textually reference it. However, the isomorphic in-memory
+representation that you manipulate from C++ has no such restriction since
+instructions can simply keep pointers to any other <tt class="docutils literal"><span class="pre">Value</span></tt>‘s that they
+reference. In fact, the names of dummy numbered temporaries like <tt class="docutils literal"><span class="pre">%1</span></tt> are
+not explicitly represented in the in-memory representation at all (see
+<tt class="docutils literal"><span class="pre">Value::getName()</span></tt>).</p>
+</div>
+</div>
+<div class="section" id="source-languages">
+<h2><a class="toc-backref" href="#id9">Source Languages</a><a class="headerlink" href="#source-languages" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-source-languages-are-supported">
+<h3><a class="toc-backref" href="#id10">What source languages are supported?</a><a class="headerlink" href="#what-source-languages-are-supported" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently has full support for C and C++ source languages through
+<a class="reference external" href="http://clang.llvm.org/">Clang</a>. Many other language frontends have
+been written using LLVM, and an incomplete list is available at
+<a class="reference external" href="http://llvm.org/ProjectsWithLLVM/">projects with LLVM</a>.</p>
+</div>
+<div class="section" id="i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators">
+<h3><a class="toc-backref" href="#id11">I’d like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?</a><a class="headerlink" href="#i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators" title="Permalink to this headline">¶</a></h3>
+<p>Your compiler front-end will communicate with LLVM by creating a module in the
+LLVM intermediate representation (IR) format. Assuming you want to write your
+language’s compiler in the language itself (rather than C++), there are 3
+major ways to tackle generating LLVM IR from a front-end:</p>
+<ol class="arabic simple">
+<li><strong>Call into the LLVM libraries code using your language’s FFI (foreign
+function interface).</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc format</li>
+<li><em>for:</em> enables running LLVM optimization passes without a emit/parse
+overhead</li>
+<li><em>for:</em> adapts well to a JIT context</li>
+<li><em>against:</em> lots of ugly glue code to write</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="2">
+<li><strong>Emit LLVM assembly from your compiler’s native language.</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> very straightforward to get started</li>
+<li><em>against:</em> the .ll parser is slower than the bitcode reader when
+interfacing to the middle end</li>
+<li><em>against:</em> it may be harder to track changes to the IR</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="3">
+<li><strong>Emit LLVM bitcode from your compiler’s native language.</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> can use the more-efficient bitcode reader when interfacing to the
+middle end</li>
+<li><em>against:</em> you’ll have to re-engineer the LLVM IR object model and bitcode
+writer in your language</li>
+<li><em>against:</em> it may be harder to track changes to the IR</li>
+</ul>
+</div></blockquote>
+<p>If you go with the first option, the C bindings in include/llvm-c should help
+a lot, since most languages have strong support for interfacing with C. The
+most common hurdle with calling C from managed code is interfacing with the
+garbage collector. The C interface was designed to require very little memory
+management, and so is straightforward in this regard.</p>
+</div>
+<div class="section" id="what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler">
+<h3><a class="toc-backref" href="#id12">What support is there for a higher level source language constructs for building a compiler?</a><a class="headerlink" href="#what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler" title="Permalink to this headline">¶</a></h3>
+<p>Currently, there isn’t much. LLVM supports an intermediate representation
+which is useful for code representation but will not support the high level
+(abstract syntax tree) representation needed by most compilers. There are no
+facilities for lexical nor semantic analysis.</p>
+</div>
+<div class="section" id="i-don-t-understand-the-getelementptr-instruction-help">
+<h3><a class="toc-backref" href="#id13">I don’t understand the <tt class="docutils literal"><span class="pre">GetElementPtr</span></tt> instruction. Help!</a><a class="headerlink" href="#i-don-t-understand-the-getelementptr-instruction-help" title="Permalink to this headline">¶</a></h3>
+<p>See <a class="reference external" href="GetElementPtr.html">The Often Misunderstood GEP Instruction</a>.</p>
+</div>
+</div>
+<div class="section" id="using-the-c-and-c-front-ends">
+<h2><a class="toc-backref" href="#id14">Using the C and C++ Front Ends</a><a class="headerlink" href="#using-the-c-and-c-front-ends" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode">
+<h3><a class="toc-backref" href="#id15">Can I compile C or C++ code to platform-independent LLVM bitcode?</a><a class="headerlink" href="#can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode" title="Permalink to this headline">¶</a></h3>
+<p>No. C and C++ are inherently platform-dependent languages. The most obvious
+example of this is the preprocessor. A very common way that C code is made
+portable is by using the preprocessor to include platform-specific code. In
+practice, information about other platforms is lost after preprocessing, so
+the result is inherently dependent on the platform that the preprocessing was
+targeting.</p>
+<p>Another example is <tt class="docutils literal"><span class="pre">sizeof</span></tt>. It’s common for <tt class="docutils literal"><span class="pre">sizeof(long)</span></tt> to vary
+between platforms. In most C front-ends, <tt class="docutils literal"><span class="pre">sizeof</span></tt> is expanded to a
+constant immediately, thus hard-wiring a platform-specific detail.</p>
+<p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
+lower-level than C, front-ends currently must emit platform-specific IR in
+order to have the result conform to the platform ABI.</p>
+</div>
+</div>
+<div class="section" id="questions-about-code-generated-by-the-demo-page">
+<h2><a class="toc-backref" href="#id16">Questions about code generated by the demo page</a><a class="headerlink" href="#questions-about-code-generated-by-the-demo-page" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream">
+<h3><a class="toc-backref" href="#id17">What is this <tt class="docutils literal"><span class="pre">llvm.global_ctors</span></tt> and <tt class="docutils literal"><span class="pre">_GLOBAL__I_a...</span></tt> stuff that happens when I <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt>?</a><a class="headerlink" href="#what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream" title="Permalink to this headline">¶</a></h3>
+<p>If you <tt class="docutils literal"><span class="pre">#include</span></tt> the <tt class="docutils literal"><span class="pre"><iostream></span></tt> header into a C++ translation unit,
+the file will probably use the <tt class="docutils literal"><span class="pre">std::cin</span></tt>/<tt class="docutils literal"><span class="pre">std::cout</span></tt>/... global objects.
+However, C++ does not guarantee an order of initialization between static
+objects in different translation units, so if a static ctor/dtor in your .cpp
+file used <tt class="docutils literal"><span class="pre">std::cout</span></tt>, for example, the object would not necessarily be
+automatically initialized before your use.</p>
+<p>To make <tt class="docutils literal"><span class="pre">std::cout</span></tt> and friends work correctly in these scenarios, the STL
+that we use declares a static object that gets created in every translation
+unit that includes <tt class="docutils literal"><span class="pre"><iostream></span></tt>. This object has a static constructor
+and destructor that initializes and destroys the global iostream objects
+before they could possibly be used in the file. The code that you see in the
+<tt class="docutils literal"><span class="pre">.ll</span></tt> file corresponds to the constructor and destructor registration code.</p>
+<p>If you would like to make it easier to <em>understand</em> the LLVM code generated
+by the compiler in the demo page, consider using <tt class="docutils literal"><span class="pre">printf()</span></tt> instead of
+<tt class="docutils literal"><span class="pre">iostream</span></tt>s to print values.</p>
+</div>
+<div class="section" id="where-did-all-of-my-code-go">
+<h3><a class="toc-backref" href="#id18">Where did all of my code go??</a><a class="headerlink" href="#where-did-all-of-my-code-go" title="Permalink to this headline">¶</a></h3>
+<p>If you are using the LLVM demo page, you may often wonder what happened to
+all of the code that you typed in. Remember that the demo script is running
+the code through the LLVM optimizers, so if your code doesn’t actually do
+anything useful, it might all be deleted.</p>
+<p>To prevent this, make sure that the code is actually needed. For example, if
+you are computing some expression, return the value from the function instead
+of leaving it in a local variable. If you really want to constrain the
+optimizer, you can read from and assign to <tt class="docutils literal"><span class="pre">volatile</span></tt> global variables.</p>
+</div>
+<div class="section" id="what-is-this-undef-thing-that-shows-up-in-my-code">
+<h3><a class="toc-backref" href="#id19">What is this “<tt class="docutils literal"><span class="pre">undef</span></tt>” thing that shows up in my code?</a><a class="headerlink" href="#what-is-this-undef-thing-that-shows-up-in-my-code" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">undef</span></tt> is the LLVM way of representing a value that is not defined. You
+can get these if you do not initialize a variable before you use it. For
+example, the C function:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">X</span><span class="p">()</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="k">return</span> <span class="n">i</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Is compiled to “<tt class="docutils literal"><span class="pre">ret</span> <span class="pre">i32</span> <span class="pre">undef</span></tt>” because “<tt class="docutils literal"><span class="pre">i</span></tt>” never has a value specified
+for it.</p>
+</div>
+<div class="section" id="why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it">
+<h3><a class="toc-backref" href="#id20">Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into “unreachable”? Why not make the verifier reject it?</a><a class="headerlink" href="#why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it" title="Permalink to this headline">¶</a></h3>
+<p>This is a common problem run into by authors of front-ends that are using
+custom calling conventions: you need to make sure to set the right calling
+convention on both the function and on each call to the function. For
+example, this code:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Is optimized to:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">unreachable</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>... with “<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-instcombine</span> <span class="pre">-simplifycfg</span></tt>”. This often bites people because
+“all their code disappears”. Setting the calling convention on the caller and
+callee is required for indirect calls to work, so people often ask why not
+make the verifier reject this sort of thing.</p>
+<p>The answer is that this code has undefined behavior, but it is not illegal.
+If we made it illegal, then every transformation that could potentially create
+this would have to ensure that it doesn’t, and there is valid code that can
+create this sort of construct (in dead code). The sorts of things that can
+cause this to happen are fairly contrived, but we still need to accept them.
+Here’s an example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="k">internal</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">(</span><span class="kt">void</span><span class="p">()*</span> <span class="nv">%FP</span><span class="p">,</span> <span class="k">i1</span> <span class="nv">%cond</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%cond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F</span>
+<span class="nl">T:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="nv">%FP</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="nl">F:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="nv">%FP</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">or</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">false</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">(</span><span class="kt">void</span><span class="p">()*</span> <span class="vg">@foo</span><span class="p">,</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this example, “test” always passes <tt class="docutils literal"><span class="pre">@foo</span></tt>/<tt class="docutils literal"><span class="pre">false</span></tt> into <tt class="docutils literal"><span class="pre">bar</span></tt>, which
+ensures that it is dynamically called with the right calling conv (thus, the
+code is perfectly well defined). If you run this through the inliner, you
+get this (the explicit “or” is there so that the inliner doesn’t dead code
+eliminate a bunch of stuff):</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">or</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">false</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T.i</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F.i</span>
+<span class="nl">T.i:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">bar.exit:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here you can see that the inlining pass made an undefined call to <tt class="docutils literal"><span class="pre">@foo</span></tt>
+with the wrong calling convention. We really don’t want to make the inliner
+have to know about this sort of thing, so it needs to be valid code. In this
+case, dead code elimination can trivially remove the undefined code. However,
+if <tt class="docutils literal"><span class="pre">%X</span></tt> was an input argument to <tt class="docutils literal"><span class="pre">@test</span></tt>, the inliner would produce this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T.i</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F.i</span>
+<span class="nl">T.i:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">bar.exit:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The interesting thing about this is that <tt class="docutils literal"><span class="pre">%X</span></tt> <em>must</em> be false for the
+code to be well-defined, but no amount of dead code elimination will be able
+to delete the broken call as unreachable. However, since
+<tt class="docutils literal"><span class="pre">instcombine</span></tt>/<tt class="docutils literal"><span class="pre">simplifycfg</span></tt> turns the undefined call into unreachable, we
+end up with a branch on a condition that goes to unreachable: a branch to
+unreachable can never happen, so “<tt class="docutils literal"><span class="pre">-inline</span> <span class="pre">-instcombine</span> <span class="pre">-simplifycfg</span></tt>” is
+able to produce:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/FaultMaps.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/FaultMaps.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/FaultMaps.html (added)
+++ www-releases/trunk/5.0.2/docs/FaultMaps.html Thu May 10 06:54:16 2018
@@ -0,0 +1,225 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>FaultMaps and implicit checks — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="Machine IR (MIR) Format Reference Manual" href="MIRLangRef.html" />
+ <link rel="prev" title="Type Metadata" href="TypeMetadata.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TypeMetadata.html" title="Type Metadata"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="faultmaps-and-implicit-checks">
+<h1>FaultMaps and implicit checks<a class="headerlink" href="#faultmaps-and-implicit-checks" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#motivation" id="id1">Motivation</a></li>
+<li><a class="reference internal" href="#the-fault-map-section" id="id2">The Fault Map Section</a></li>
+<li><a class="reference internal" href="#the-implicitnullchecks-pass" id="id3">The <tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass</a><ul>
+<li><a class="reference internal" href="#make-implicit-metadata" id="id4"><tt class="docutils literal"><span class="pre">make.implicit</span></tt> metadata</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="motivation">
+<h2><a class="toc-backref" href="#id1">Motivation</a><a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2>
+<p>Code generated by managed language runtimes tend to have checks that
+are required for safety but never fail in practice. In such cases, it
+is profitable to make the non-failing case cheaper even if it makes
+the failing case significantly more expensive. This asymmetry can be
+exploited by folding such safety checks into operations that can be
+made to fault reliably if the check would have failed, and recovering
+from such a fault by using a signal handler.</p>
+<p>For example, Java requires null checks on objects before they are read
+from or written to. If the object is <tt class="docutils literal"><span class="pre">null</span></tt> then a
+<tt class="docutils literal"><span class="pre">NullPointerException</span></tt> has to be thrown, interrupting normal
+execution. In practice, however, dereferencing a <tt class="docutils literal"><span class="pre">null</span></tt> pointer is
+extremely rare in well-behaved Java programs, and typically the null
+check can be folded into a nearby memory operation that operates on
+the same memory location.</p>
+</div>
+<div class="section" id="the-fault-map-section">
+<h2><a class="toc-backref" href="#id2">The Fault Map Section</a><a class="headerlink" href="#the-fault-map-section" title="Permalink to this headline">¶</a></h2>
+<p>Information about implicit checks generated by LLVM are put in a
+special “fault map” section. On Darwin this section is named
+<tt class="docutils literal"><span class="pre">__llvm_faultmaps</span></tt>.</p>
+<p>The format of this section is</p>
+<div class="highlight-none"><div class="highlight"><pre>Header {
+ uint8 : Fault Map Version (current version is 1)
+ uint8 : Reserved (expected to be 0)
+ uint16 : Reserved (expected to be 0)
+}
+uint32 : NumFunctions
+FunctionInfo[NumFunctions] {
+ uint64 : FunctionAddress
+ uint32 : NumFaultingPCs
+ uint32 : Reserved (expected to be 0)
+ FunctionFaultInfo[NumFaultingPCs] {
+ uint32 : FaultKind
+ uint32 : FaultingPCOffset
+ uint32 : HandlerPCOffset
+ }
+}
+</pre></div>
+</div>
+<p>FailtKind describes the reason of expected fault. Currently three kind
+of faults are supported:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">FaultMaps::FaultingLoad</span></tt> - fault due to load from memory.</li>
+<li><tt class="docutils literal"><span class="pre">FaultMaps::FaultingLoadStore</span></tt> - fault due to instruction load and store.</li>
+<li><tt class="docutils literal"><span class="pre">FaultMaps::FaultingStore</span></tt> - fault due to store to memory.</li>
+</ol>
+</div></blockquote>
+</div>
+<div class="section" id="the-implicitnullchecks-pass">
+<h2><a class="toc-backref" href="#id3">The <tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass</a><a class="headerlink" href="#the-implicitnullchecks-pass" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass transforms explicit control flow for
+checking if a pointer is <tt class="docutils literal"><span class="pre">null</span></tt>, like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre> <span class="nv">%ptr</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@get_ptr</span><span class="p">()</span>
+ <span class="nv">%ptr_is_null</span> <span class="p">=</span> <span class="k">icmp</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">,</span> <span class="k">null</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ptr_is_null</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%is_null</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%not_null</span><span class="p">,</span> <span class="nv">!make.implicit</span> <span class="nv-Anonymous">!0</span>
+
+<span class="nl">not_null:</span>
+ <span class="nv">%t</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%ptr</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%do_something_with_t</span>
+
+<span class="nl">is_null:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@HFC</span><span class="p">()</span>
+ <span class="k">unreachable</span>
+
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{}</span>
+</pre></div>
+</div>
+<p>to control flow implicit in the instruction loading or storing through
+the pointer being null checked:</p>
+<div class="highlight-llvm"><div class="highlight"><pre> <span class="nv">%ptr</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@get_ptr</span><span class="p">()</span>
+ <span class="nv">%t</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%ptr</span> <span class="c">;; handler-pc = label %is_null</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%do_something_with_t</span>
+
+<span class="nl">is_null:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@HFC</span><span class="p">()</span>
+ <span class="k">unreachable</span>
+</pre></div>
+</div>
+<p>This transform happens at the <tt class="docutils literal"><span class="pre">MachineInstr</span></tt> level, not the LLVM IR
+level (so the above example is only representative, not literal). The
+<tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass runs during codegen, if
+<tt class="docutils literal"><span class="pre">-enable-implicit-null-checks</span></tt> is passed to <tt class="docutils literal"><span class="pre">llc</span></tt>.</p>
+<p>The <tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass adds entries to the
+<tt class="docutils literal"><span class="pre">__llvm_faultmaps</span></tt> section described above as needed.</p>
+<div class="section" id="make-implicit-metadata">
+<h3><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">make.implicit</span></tt> metadata</a><a class="headerlink" href="#make-implicit-metadata" title="Permalink to this headline">¶</a></h3>
+<p>Making null checks implicit is an aggressive optimization, and it can
+be a net performance pessimization if too many memory operations end
+up faulting because of it. A language runtime typically needs to
+ensure that only a negligible number of implicit null checks actually
+fault once the application has reached a steady state. A standard way
+of doing this is by healing failed implicit null checks into explicit
+null checks via code patching or recompilation. It follows that there
+are two requirements an explicit null check needs to satisfy for it to
+be profitable to convert it to an implicit null check:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li>The case where the pointer is actually null (i.e. the “failing”
+case) is extremely rare.</li>
+<li>The failing path heals the implicit null check into an explicit
+null check so that the application does not repeatedly page
+fault.</li>
+</ol>
+</div></blockquote>
+<p>The frontend is expected to mark branches that satisfy (1) and (2)
+using a <tt class="docutils literal"><span class="pre">!make.implicit</span></tt> metadata node (the actual content of the
+metadata node is ignored). Only branches that are marked with
+<tt class="docutils literal"><span class="pre">!make.implicit</span></tt> metadata are considered as candidates for
+conversion into implicit null checks.</p>
+<p>(Note that while we could deal with (1) using profiling data, dealing
+with (2) requires some information not present in branch profiles.)</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TypeMetadata.html" title="Type Metadata"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/Frontend/PerformanceTips.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/Frontend/PerformanceTips.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/Frontend/PerformanceTips.html (added)
+++ www-releases/trunk/5.0.2/docs/Frontend/PerformanceTips.html Thu May 10 06:54:16 2018
@@ -0,0 +1,374 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Performance Tips for Frontend Authors — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="../index.html" />
+ <link rel="next" title="MCJIT Design and Implementation" href="../MCJITDesignAndImplementation.html" />
+ <link rel="prev" title="The Often Misunderstood GEP Instruction" href="../GetElementPtr.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../MCJITDesignAndImplementation.html" title="MCJIT Design and Implementation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="performance-tips-for-frontend-authors">
+<h1>Performance Tips for Frontend Authors<a class="headerlink" href="#performance-tips-for-frontend-authors" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#abstract" id="id2">Abstract</a></li>
+<li><a class="reference internal" href="#ir-best-practices" id="id3">IR Best Practices</a><ul>
+<li><a class="reference internal" href="#the-basics" id="id4">The Basics</a></li>
+<li><a class="reference internal" href="#use-of-allocas" id="id5">Use of allocas</a></li>
+<li><a class="reference internal" href="#avoid-loads-and-stores-of-large-aggregate-type" id="id6">Avoid loads and stores of large aggregate type</a></li>
+<li><a class="reference internal" href="#prefer-zext-over-sext-when-legal" id="id7">Prefer zext over sext when legal</a></li>
+<li><a class="reference internal" href="#zext-gep-indices-to-machine-register-width" id="id8">Zext GEP indices to machine register width</a></li>
+<li><a class="reference internal" href="#when-to-specify-alignment" id="id9">When to specify alignment</a></li>
+<li><a class="reference internal" href="#other-things-to-consider" id="id10">Other Things to Consider</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#describing-language-specific-properties" id="id11">Describing Language Specific Properties</a><ul>
+<li><a class="reference internal" href="#restricted-operation-semantics" id="id12">Restricted Operation Semantics</a></li>
+<li><a class="reference internal" href="#describing-aliasing-properties" id="id13">Describing Aliasing Properties</a></li>
+<li><a class="reference internal" href="#modeling-memory-effects" id="id14">Modeling Memory Effects</a></li>
+<li><a class="reference internal" href="#pass-ordering" id="id15">Pass Ordering</a></li>
+<li><a class="reference internal" href="#i-still-can-t-find-what-i-m-looking-for" id="id16">I Still Can’t Find What I’m Looking For</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#adding-to-this-document" id="id17">Adding to this document</a></li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h2><a class="toc-backref" href="#id2">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>The intended audience of this document is developers of language frontends
+targeting LLVM IR. This document is home to a collection of tips on how to
+generate IR that optimizes well.</p>
+</div>
+<div class="section" id="ir-best-practices">
+<h2><a class="toc-backref" href="#id3">IR Best Practices</a><a class="headerlink" href="#ir-best-practices" title="Permalink to this headline">¶</a></h2>
+<p>As with any optimizer, LLVM has its strengths and weaknesses. In some cases,
+surprisingly small changes in the source IR can have a large effect on the
+generated code.</p>
+<p>Beyond the specific items on the list below, it’s worth noting that the most
+mature frontend for LLVM is Clang. As a result, the further your IR gets from what Clang might emit, the less likely it is to be effectively optimized. It
+can often be useful to write a quick C program with the semantics you’re trying
+to model and see what decisions Clang’s IRGen makes about what IR to emit.
+Studying Clang’s CodeGen directory can also be a good source of ideas. Note
+that Clang and LLVM are explicitly version locked so you’ll need to make sure
+you’re using a Clang built from the same svn revision or release as the LLVM
+library you’re using. As always, it’s <em>strongly</em> recommended that you track
+tip of tree development, particularly during bring up of a new project.</p>
+<div class="section" id="the-basics">
+<h3><a class="toc-backref" href="#id4">The Basics</a><a class="headerlink" href="#the-basics" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Make sure that your Modules contain both a data layout specification and
+target triple. Without these pieces, non of the target specific optimization
+will be enabled. This can have a major effect on the generated code quality.</li>
+<li>For each function or global emitted, use the most private linkage type
+possible (private, internal or linkonce_odr preferably). Doing so will
+make LLVM’s inter-procedural optimizations much more effective.</li>
+<li>Avoid high in-degree basic blocks (e.g. basic blocks with dozens or hundreds
+of predecessors). Among other issues, the register allocator is known to
+perform badly with confronted with such structures. The only exception to
+this guidance is that a unified return block with high in-degree is fine.</li>
+</ol>
+</div>
+<div class="section" id="use-of-allocas">
+<h3><a class="toc-backref" href="#id5">Use of allocas</a><a class="headerlink" href="#use-of-allocas" title="Permalink to this headline">¶</a></h3>
+<p>An alloca instruction can be used to represent a function scoped stack slot,
+but can also represent dynamic frame expansion. When representing function
+scoped variables or locations, placing alloca instructions at the beginning of
+the entry block should be preferred. In particular, place them before any
+call instructions. Call instructions might get inlined and replaced with
+multiple basic blocks. The end result is that a following alloca instruction
+would no longer be in the entry basic block afterward.</p>
+<p>The SROA (Scalar Replacement Of Aggregates) and Mem2Reg passes only attempt
+to eliminate alloca instructions that are in the entry basic block. Given
+SSA is the canonical form expected by much of the optimizer; if allocas can
+not be eliminated by Mem2Reg or SROA, the optimizer is likely to be less
+effective than it could be.</p>
+</div>
+<div class="section" id="avoid-loads-and-stores-of-large-aggregate-type">
+<h3><a class="toc-backref" href="#id6">Avoid loads and stores of large aggregate type</a><a class="headerlink" href="#avoid-loads-and-stores-of-large-aggregate-type" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently does not optimize well loads and stores of large <a class="reference internal" href="../LangRef.html#t-aggregate"><em>aggregate
+types</em></a> (i.e. structs and arrays). As an alternative, consider
+loading individual fields from memory.</p>
+<p>Aggregates that are smaller than the largest (performant) load or store
+instruction supported by the targeted hardware are well supported. These can
+be an effective way to represent collections of small packed fields.</p>
+</div>
+<div class="section" id="prefer-zext-over-sext-when-legal">
+<h3><a class="toc-backref" href="#id7">Prefer zext over sext when legal</a><a class="headerlink" href="#prefer-zext-over-sext-when-legal" title="Permalink to this headline">¶</a></h3>
+<p>On some architectures (X86_64 is one), sign extension can involve an extra
+instruction whereas zero extension can be folded into a load. LLVM will try to
+replace a sext with a zext when it can be proven safe, but if you have
+information in your source language about the range of a integer value, it can
+be profitable to use a zext rather than a sext.</p>
+<p>Alternatively, you can <a class="reference internal" href="../LangRef.html#range-metadata"><em>specify the range of the value using metadata</em></a> and LLVM can do the sext to zext conversion for you.</p>
+</div>
+<div class="section" id="zext-gep-indices-to-machine-register-width">
+<h3><a class="toc-backref" href="#id8">Zext GEP indices to machine register width</a><a class="headerlink" href="#zext-gep-indices-to-machine-register-width" title="Permalink to this headline">¶</a></h3>
+<p>Internally, LLVM often promotes the width of GEP indices to machine register
+width. When it does so, it will default to using sign extension (sext)
+operations for safety. If your source language provides information about
+the range of the index, you may wish to manually extend indices to machine
+register width using a zext instruction.</p>
+</div>
+<div class="section" id="when-to-specify-alignment">
+<h3><a class="toc-backref" href="#id9">When to specify alignment</a><a class="headerlink" href="#when-to-specify-alignment" title="Permalink to this headline">¶</a></h3>
+<p>LLVM will always generate correct code if you donât specify alignment, but may
+generate inefficient code. For example, if you are targeting MIPS (or older
+ARM ISAs) then the hardware does not handle unaligned loads and stores, and
+so you will enter a trap-and-emulate path if you do a load or store with
+lower-than-natural alignment. To avoid this, LLVM will emit a slower
+sequence of loads, shifts and masks (or load-right + load-left on MIPS) for
+all cases where the load / store does not have a sufficiently high alignment
+in the IR.</p>
+<p>The alignment is used to guarantee the alignment on allocas and globals,
+though in most cases this is unnecessary (most targets have a sufficiently
+high default alignment that theyâll be fine). It is also used to provide a
+contract to the back end saying âeither this load/store has this alignment, or
+it is undefined behaviorâ. This means that the back end is free to emit
+instructions that rely on that alignment (and mid-level optimizers are free to
+perform transforms that require that alignment). For x86, it doesnât make
+much difference, as almost all instructions are alignment-independent. For
+MIPS, it can make a big difference.</p>
+<p>Note that if your loads and stores are atomic, the backend will be unable to
+lower an under aligned access into a sequence of natively aligned accesses.
+As a result, alignment is mandatory for atomic loads and stores.</p>
+</div>
+<div class="section" id="other-things-to-consider">
+<h3><a class="toc-backref" href="#id10">Other Things to Consider</a><a class="headerlink" href="#other-things-to-consider" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Use ptrtoint/inttoptr sparingly (they interfere with pointer aliasing
+analysis), prefer GEPs</li>
+<li>Prefer globals over inttoptr of a constant address - this gives you
+dereferencability information. In MCJIT, use getSymbolAddress to provide
+actual address.</li>
+<li>Be wary of ordered and atomic memory operations. They are hard to optimize
+and may not be well optimized by the current optimizer. Depending on your
+source language, you may consider using fences instead.</li>
+<li>If calling a function which is known to throw an exception (unwind), use
+an invoke with a normal destination which contains an unreachable
+instruction. This form conveys to the optimizer that the call returns
+abnormally. For an invoke which neither returns normally or requires unwind
+code in the current function, you can use a noreturn call instruction if
+desired. This is generally not required because the optimizer will convert
+an invoke with an unreachable unwind destination to a call instruction.</li>
+<li>Use profile metadata to indicate statically known cold paths, even if
+dynamic profiling information is not available. This can make a large
+difference in code placement and thus the performance of tight loops.</li>
+<li>When generating code for loops, try to avoid terminating the header block of
+the loop earlier than necessary. If the terminator of the loop header
+block is a loop exiting conditional branch, the effectiveness of LICM will
+be limited for loads not in the header. (This is due to the fact that LLVM
+may not know such a load is safe to speculatively execute and thus can’t
+lift an otherwise loop invariant load unless it can prove the exiting
+condition is not taken.) It can be profitable, in some cases, to emit such
+instructions into the header even if they are not used along a rarely
+executed path that exits the loop. This guidance specifically does not
+apply if the condition which terminates the loop header is itself invariant,
+or can be easily discharged by inspecting the loop index variables.</li>
+<li>In hot loops, consider duplicating instructions from small basic blocks
+which end in highly predictable terminators into their successor blocks.
+If a hot successor block contains instructions which can be vectorized
+with the duplicated ones, this can provide a noticeable throughput
+improvement. Note that this is not always profitable and does involve a
+potentially large increase in code size.</li>
+<li>When checking a value against a constant, emit the check using a consistent
+comparison type. The GVN pass <em>will</em> optimize redundant equalities even if
+the type of comparison is inverted, but GVN only runs late in the pipeline.
+As a result, you may miss the opportunity to run other important
+optimizations. Improvements to EarlyCSE to remove this issue are tracked in
+Bug 23333.</li>
+<li>Avoid using arithmetic intrinsics unless you are <em>required</em> by your source
+language specification to emit a particular code sequence. The optimizer
+is quite good at reasoning about general control flow and arithmetic, it is
+not anywhere near as strong at reasoning about the various intrinsics. If
+profitable for code generation purposes, the optimizer will likely form the
+intrinsics itself late in the optimization pipeline. It is <em>very</em> rarely
+profitable to emit these directly in the language frontend. This item
+explicitly includes the use of the <a class="reference internal" href="../LangRef.html#int-overflow"><em>overflow intrinsics</em></a>.</li>
+<li>Avoid using the <a class="reference internal" href="../LangRef.html#int-assume"><em>assume intrinsic</em></a> until you’ve
+established that a) there’s no other way to express the given fact and b)
+that fact is critical for optimization purposes. Assumes are a great
+prototyping mechanism, but they can have negative effects on both compile
+time and optimization effectiveness. The former is fixable with enough
+effort, but the later is fairly fundamental to their designed purpose.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="describing-language-specific-properties">
+<h2><a class="toc-backref" href="#id11">Describing Language Specific Properties</a><a class="headerlink" href="#describing-language-specific-properties" title="Permalink to this headline">¶</a></h2>
+<p>When translating a source language to LLVM, finding ways to express concepts
+and guarantees available in your source language which are not natively
+provided by LLVM IR will greatly improve LLVM’s ability to optimize your code.
+As an example, C/C++’s ability to mark every add as “no signed wrap (nsw)” goes
+a long way to assisting the optimizer in reasoning about loop induction
+variables and thus generating more optimal code for loops.</p>
+<p>The LLVM LangRef includes a number of mechanisms for annotating the IR with
+additional semantic information. It is <em>strongly</em> recommended that you become
+highly familiar with this document. The list below is intended to highlight a
+couple of items of particular interest, but is by no means exhaustive.</p>
+<div class="section" id="restricted-operation-semantics">
+<h3><a class="toc-backref" href="#id12">Restricted Operation Semantics</a><a class="headerlink" href="#restricted-operation-semantics" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Add nsw/nuw flags as appropriate. Reasoning about overflow is
+generally hard for an optimizer so providing these facts from the frontend
+can be very impactful.</li>
+<li>Use fast-math flags on floating point operations if legal. If you don’t
+need strict IEEE floating point semantics, there are a number of additional
+optimizations that can be performed. This can be highly impactful for
+floating point intensive computations.</li>
+</ol>
+</div>
+<div class="section" id="describing-aliasing-properties">
+<h3><a class="toc-backref" href="#id13">Describing Aliasing Properties</a><a class="headerlink" href="#describing-aliasing-properties" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Add noalias/align/dereferenceable/nonnull to function arguments and return
+values as appropriate</li>
+<li>Use pointer aliasing metadata, especially tbaa metadata, to communicate
+otherwise-non-deducible pointer aliasing facts</li>
+<li>Use inbounds on geps. This can help to disambiguate some aliasing queries.</li>
+</ol>
+</div>
+<div class="section" id="modeling-memory-effects">
+<h3><a class="toc-backref" href="#id14">Modeling Memory Effects</a><a class="headerlink" href="#modeling-memory-effects" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Mark functions as readnone/readonly/argmemonly or noreturn/nounwind when
+known. The optimizer will try to infer these flags, but may not always be
+able to. Manual annotations are particularly important for external
+functions that the optimizer can not analyze.</li>
+<li>Use the lifetime.start/lifetime.end and invariant.start/invariant.end
+intrinsics where possible. Common profitable uses are for stack like data
+structures (thus allowing dead store elimination) and for describing
+life times of allocas (thus allowing smaller stack sizes).</li>
+<li>Mark invariant locations using !invariant.load and TBAA’s constant flags</li>
+</ol>
+</div>
+<div class="section" id="pass-ordering">
+<h3><a class="toc-backref" href="#id15">Pass Ordering</a><a class="headerlink" href="#pass-ordering" title="Permalink to this headline">¶</a></h3>
+<p>One of the most common mistakes made by new language frontend projects is to
+use the existing -O2 or -O3 pass pipelines as is. These pass pipelines make a
+good starting point for an optimizing compiler for any language, but they have
+been carefully tuned for C and C++, not your target language. You will almost
+certainly need to use a custom pass order to achieve optimal performance. A
+couple specific suggestions:</p>
+<ol class="arabic simple">
+<li>For languages with numerous rarely executed guard conditions (e.g. null
+checks, type checks, range checks) consider adding an extra execution or
+two of LoopUnswith and LICM to your pass order. The standard pass order,
+which is tuned for C and C++ applications, may not be sufficient to remove
+all dischargeable checks from loops.</li>
+<li>If you language uses range checks, consider using the IRCE pass. It is not
+currently part of the standard pass order.</li>
+<li>A useful sanity check to run is to run your optimized IR back through the
+-O2 pipeline again. If you see noticeable improvement in the resulting IR,
+you likely need to adjust your pass order.</li>
+</ol>
+</div>
+<div class="section" id="i-still-can-t-find-what-i-m-looking-for">
+<h3><a class="toc-backref" href="#id16">I Still Can’t Find What I’m Looking For</a><a class="headerlink" href="#i-still-can-t-find-what-i-m-looking-for" title="Permalink to this headline">¶</a></h3>
+<p>If you didn’t find what you were looking for above, consider proposing an piece
+of metadata which provides the optimization hint you need. Such extensions are
+relatively common and are generally well received by the community. You will
+need to ensure that your proposal is sufficiently general so that it benefits
+others if you wish to contribute it upstream.</p>
+<p>You should also consider describing the problem you’re facing on <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a> and asking for advice.
+It’s entirely possible someone has encountered your problem before and can
+give good advice. If there are multiple interested parties, that also
+increases the chances that a metadata extension would be well received by the
+community as a whole.</p>
+</div>
+</div>
+<div class="section" id="adding-to-this-document">
+<h2><a class="toc-backref" href="#id17">Adding to this document</a><a class="headerlink" href="#adding-to-this-document" title="Permalink to this headline">¶</a></h2>
+<p>If you run across a case that you feel deserves to be covered here, please send
+a patch to <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-commits">llvm-commits</a> for review.</p>
+<p>If you have questions on these items, please direct them to <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a>. The more relevant
+context you are able to give to your question, the more likely it is to be
+answered.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../MCJITDesignAndImplementation.html" title="MCJIT Design and Implementation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/GarbageCollection.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/GarbageCollection.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/GarbageCollection.html (added)
+++ www-releases/trunk/5.0.2/docs/GarbageCollection.html Thu May 10 06:54:16 2018
@@ -0,0 +1,1227 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Garbage Collection with LLVM — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="Writing an LLVM Pass" href="WritingAnLLVMPass.html" />
+ <link rel="prev" title="How To Use Instruction Mappings" href="HowToUseInstrMappings.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="garbage-collection-with-llvm">
+<h1>Garbage Collection with LLVM<a class="headerlink" href="#garbage-collection-with-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#abstract" id="id1">Abstract</a></li>
+<li><a class="reference internal" href="#quick-start" id="id2">Quick Start</a></li>
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a><ul>
+<li><a class="reference internal" href="#what-is-garbage-collection" id="id4">What is Garbage Collection?</a></li>
+<li><a class="reference internal" href="#goals-and-non-goals" id="id5">Goals and non-goals</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#llvm-ir-features" id="id6">LLVM IR Features</a><ul>
+<li><a class="reference internal" href="#specifying-gc-code-generation-gc" id="id7">Specifying GC code generation: <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"..."</span></tt></a></li>
+<li><a class="reference internal" href="#gcroot" id="id8">Identifying GC roots on the stack</a><ul>
+<li><a class="reference internal" href="#using-gc-statepoint" id="id9">Using <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt></a></li>
+<li><a class="reference internal" href="#using-llvm-gcwrite" id="id10">Using <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reading-and-writing-references-in-the-heap" id="id11">Reading and writing references in the heap</a><ul>
+<li><a class="reference internal" href="#write-barrier-llvm-gcwrite" id="id12">Write barrier: <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a></li>
+<li><a class="reference internal" href="#read-barrier-llvm-gcread" id="id13">Read barrier: <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#built-in-gc-strategies" id="id14">Built In GC Strategies</a><ul>
+<li><a class="reference internal" href="#the-shadow-stack-gc" id="id15">The Shadow Stack GC</a></li>
+<li><a class="reference internal" href="#the-erlang-and-ocaml-gcs" id="id16">The ‘Erlang’ and ‘Ocaml’ GCs</a></li>
+<li><a class="reference internal" href="#the-statepoint-example-gc" id="id17">The Statepoint Example GC</a></li>
+<li><a class="reference internal" href="#the-coreclr-gc" id="id18">The CoreCLR GC</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#custom-gc-strategies" id="id19">Custom GC Strategies</a><ul>
+<li><a class="reference internal" href="#collector-requirements" id="id20">Collector Requirements</a></li>
+<li><a class="reference internal" href="#implementing-a-collector-plugin" id="id21">Implementing a collector plugin</a></li>
+<li><a class="reference internal" href="#overview-of-available-features" id="id22">Overview of available features</a></li>
+<li><a class="reference internal" href="#computing-stack-maps" id="id23">Computing stack maps</a></li>
+<li><a class="reference internal" href="#initializing-roots-to-null-initroots" id="id24">Initializing roots to null: <tt class="docutils literal"><span class="pre">InitRoots</span></tt></a></li>
+<li><a class="reference internal" href="#custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers" id="id25">Custom lowering of intrinsics: <tt class="docutils literal"><span class="pre">CustomRoots</span></tt>, <tt class="docutils literal"><span class="pre">CustomReadBarriers</span></tt>, and <tt class="docutils literal"><span class="pre">CustomWriteBarriers</span></tt></a></li>
+<li><a class="reference internal" href="#generating-safe-points-neededsafepoints" id="id26">Generating safe points: <tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt></a></li>
+<li><a class="reference internal" href="#emitting-assembly-code-gcmetadataprinter" id="id27">Emitting assembly code: <tt class="docutils literal"><span class="pre">GCMetadataPrinter</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#references" id="id28">References</a></li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h2><a class="toc-backref" href="#id1">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>This document covers how to integrate LLVM into a compiler for a language which
+supports garbage collection. <strong>Note that LLVM itself does not provide a
+garbage collector.</strong> You must provide your own.</p>
+</div>
+<div class="section" id="quick-start">
+<h2><a class="toc-backref" href="#id2">Quick Start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
+<p>First, you should pick a collector strategy. LLVM includes a number of built
+in ones, but you can also implement a loadable plugin with a custom definition.
+Note that the collector strategy is a description of how LLVM should generate
+code such that it interacts with your collector and runtime, not a description
+of the collector itself.</p>
+<p>Next, mark your generated functions as using your chosen collector strategy.
+From c++, you can call:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="o"><</span><span class="n">collector</span> <span class="n">description</span> <span class="n">name</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This will produce IR like the following fragment:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="k">gc</span> <span class="s">"<collector description name>"</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>When generating LLVM IR for your functions, you will need to:</p>
+<ul class="simple">
+<li>Use <tt class="docutils literal"><span class="pre">@llvm.gcread</span></tt> and/or <tt class="docutils literal"><span class="pre">@llvm.gcwrite</span></tt> in place of standard load and
+store instructions. These intrinsics are used to represent load and store
+barriers. If you collector does not require such barriers, you can skip
+this step.</li>
+<li>Use the memory allocation routines provided by your garbage collector’s
+runtime library.</li>
+<li>If your collector requires them, generate type maps according to your
+runtime’s binary interface. LLVM is not involved in the process. In
+particular, the LLVM type system is not suitable for conveying such
+information though the compiler.</li>
+<li>Insert any coordination code required for interacting with your collector.
+Many collectors require running application code to periodically check a
+flag and conditionally call a runtime function. This is often referred to
+as a safepoint poll.</li>
+</ul>
+<p>You will need to identify roots (i.e. references to heap objects your collector
+needs to know about) in your generated IR, so that LLVM can encode them into
+your final stack maps. Depending on the collector strategy chosen, this is
+accomplished by using either the <tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> intrinsics or an
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> relocation sequence.</p>
+<p>Don’t forget to create a root for each intermediate value that is generated when
+evaluating an expression. In <tt class="docutils literal"><span class="pre">h(f(),</span> <span class="pre">g())</span></tt>, the result of <tt class="docutils literal"><span class="pre">f()</span></tt> could
+easily be collected if evaluating <tt class="docutils literal"><span class="pre">g()</span></tt> triggers a collection.</p>
+<p>Finally, you need to link your runtime library with the generated program
+executable (for a static compiler) or ensure the appropriate symbols are
+available for the runtime linker (for a JIT compiler).</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-is-garbage-collection">
+<h3><a class="toc-backref" href="#id4">What is Garbage Collection?</a><a class="headerlink" href="#what-is-garbage-collection" title="Permalink to this headline">¶</a></h3>
+<p>Garbage collection is a widely used technique that frees the programmer from
+having to know the lifetimes of heap objects, making software easier to produce
+and maintain. Many programming languages rely on garbage collection for
+automatic memory management. There are two primary forms of garbage collection:
+conservative and accurate.</p>
+<p>Conservative garbage collection often does not require any special support from
+either the language or the compiler: it can handle non-type-safe programming
+languages (such as C/C++) and does not require any special information from the
+compiler. The <a class="reference external" href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm collector</a> is an example of a
+state-of-the-art conservative collector.</p>
+<p>Accurate garbage collection requires the ability to identify all pointers in the
+program at run-time (which requires that the source-language be type-safe in
+most cases). Identifying pointers at run-time requires compiler support to
+locate all places that hold live pointer variables at run-time, including the
+<a class="reference internal" href="#gcroot"><em>processor stack and registers</em></a>.</p>
+<p>Conservative garbage collection is attractive because it does not require any
+special compiler support, but it does have problems. In particular, because the
+conservative garbage collector cannot <em>know</em> that a particular word in the
+machine is a pointer, it cannot move live objects in the heap (preventing the
+use of compacting and generational GC algorithms) and it can occasionally suffer
+from memory leaks due to integer values that happen to point to objects in the
+program. In addition, some aggressive compiler transformations can break
+conservative garbage collectors (though these seem rare in practice).</p>
+<p>Accurate garbage collectors do not suffer from any of these problems, but they
+can suffer from degraded scalar optimization of the program. In particular,
+because the runtime must be able to identify and update all pointers active in
+the program, some optimizations are less effective. In practice, however, the
+locality and performance benefits of using aggressive garbage collection
+techniques dominates any low-level losses.</p>
+<p>This document describes the mechanisms and interfaces provided by LLVM to
+support accurate garbage collection.</p>
+</div>
+<div class="section" id="goals-and-non-goals">
+<h3><a class="toc-backref" href="#id5">Goals and non-goals</a><a class="headerlink" href="#goals-and-non-goals" title="Permalink to this headline">¶</a></h3>
+<p>LLVM’s intermediate representation provides <a class="reference internal" href="#gc-intrinsics"><em>garbage collection intrinsics</em></a> that offer support for a broad class of collector models. For
+instance, the intrinsics permit:</p>
+<ul class="simple">
+<li>semi-space collectors</li>
+<li>mark-sweep collectors</li>
+<li>generational collectors</li>
+<li>incremental collectors</li>
+<li>concurrent collectors</li>
+<li>cooperative collectors</li>
+<li>reference counting</li>
+</ul>
+<p>We hope that the support built into the LLVM IR is sufficient to support a
+broad class of garbage collected languages including Scheme, ML, Java, C#,
+Perl, Python, Lua, Ruby, other scripting languages, and more.</p>
+<p>Note that LLVM <strong>does not itself provide a garbage collector</strong> — this should
+be part of your language’s runtime library. LLVM provides a framework for
+describing the garbage collectors requirements to the compiler. In particular,
+LLVM provides support for generating stack maps at call sites, polling for a
+safepoint, and emitting load and store barriers. You can also extend LLVM -
+possibly through a loadable <a class="reference internal" href="#plugin"><em>code generation plugins</em></a> - to
+generate code and data structures which conforms to the <em>binary interface</em>
+specified by the <em>runtime library</em>. This is similar to the relationship between
+LLVM and DWARF debugging info, for example. The difference primarily lies in
+the lack of an established standard in the domain of garbage collection — thus
+the need for a flexible extension mechanism.</p>
+<p>The aspects of the binary interface with which LLVM’s GC support is
+concerned are:</p>
+<ul class="simple">
+<li>Creation of GC safepoints within code where collection is allowed to execute
+safely.</li>
+<li>Computation of the stack map. For each safe point in the code, object
+references within the stack frame must be identified so that the collector may
+traverse and perhaps update them.</li>
+<li>Write barriers when storing object references to the heap. These are commonly
+used to optimize incremental scans in generational collectors.</li>
+<li>Emission of read barriers when loading object references. These are useful
+for interoperating with concurrent collectors.</li>
+</ul>
+<p>There are additional areas that LLVM does not directly address:</p>
+<ul class="simple">
+<li>Registration of global roots with the runtime.</li>
+<li>Registration of stack map entries with the runtime.</li>
+<li>The functions used by the program to allocate memory, trigger a collection,
+etc.</li>
+<li>Computation or compilation of type maps, or registration of them with the
+runtime. These are used to crawl the heap for object references.</li>
+</ul>
+<p>In general, LLVM’s support for GC does not include features which can be
+adequately addressed with other features of the IR and does not specify a
+particular binary interface. On the plus side, this means that you should be
+able to integrate LLVM with an existing runtime. On the other hand, it can
+have the effect of leaving a lot of work for the developer of a novel
+language. We try to mitigate this by providing built in collector strategy
+descriptions that can work with many common collector designs and easy
+extension points. If you don’t already have a specific binary interface
+you need to support, we recommend trying to use one of these built in collector
+strategies.</p>
+</div>
+</div>
+<div class="section" id="llvm-ir-features">
+<span id="gc-intrinsics"></span><h2><a class="toc-backref" href="#id6">LLVM IR Features</a><a class="headerlink" href="#llvm-ir-features" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the garbage collection facilities provided by the
+<a class="reference internal" href="LangRef.html"><em>LLVM intermediate representation</em></a>. The exact behavior of these
+IR features is specified by the selected <a class="reference internal" href="#plugin"><em>GC strategy description</em></a>.</p>
+<div class="section" id="specifying-gc-code-generation-gc">
+<h3><a class="toc-backref" href="#id7">Specifying GC code generation: <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"..."</span></tt></a><a class="headerlink" href="#specifying-gc-code-generation-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-text"><div class="highlight"><pre>define <returntype> @name(...) gc "name" { ... }
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">gc</span></tt> function attribute is used to specify the desired GC strategy to the
+compiler. Its programmatic equivalent is the <tt class="docutils literal"><span class="pre">setGC</span></tt> method of <tt class="docutils literal"><span class="pre">Function</span></tt>.</p>
+<p>Setting <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"name"</span></tt> on a function triggers a search for a matching subclass
+of GCStrategy. Some collector strategies are built in. You can add others
+using either the loadable plugin mechanism, or by patching your copy of LLVM.
+It is the selected GC strategy which defines the exact nature of the code
+generated to support GC. If none is found, the compiler will raise an error.</p>
+<p>Specifying the GC style on a per-function basis allows LLVM to link together
+programs that use different garbage collection algorithms (or none at all).</p>
+</div>
+<div class="section" id="gcroot">
+<span id="identifying-gc-roots-on-the-stack"></span><h3><a class="toc-backref" href="#id8">Identifying GC roots on the stack</a><a class="headerlink" href="#gcroot" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently supports two different mechanisms for describing references in
+compiled code at safepoints. <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> is the older mechanism;
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> has been added more recently. At the moment, you can choose
+either implementation (on a per <a class="reference internal" href="#plugin"><em>GC strategy</em></a> basis). Longer
+term, we will probably either migrate away from <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> entirely, or
+substantially merge their implementations. Note that most new development
+work is focused on <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>.</p>
+<div class="section" id="using-gc-statepoint">
+<h4><a class="toc-backref" href="#id9">Using <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt></a><a class="headerlink" href="#using-gc-statepoint" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference internal" href="Statepoints.html"><em>This page</em></a> contains detailed documentation for
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>.</p>
+</div>
+<div class="section" id="using-llvm-gcwrite">
+<h4><a class="toc-backref" href="#id10">Using <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a><a class="headerlink" href="#using-llvm-gcwrite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.gcroot</span><span class="p">(</span><span class="k">i8</span><span class="p">**</span> <span class="nv">%ptrloc</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> intrinsic is used to inform LLVM that a stack variable
+references an object on the heap and is to be tracked for garbage collection.
+The exact impact on generated code is specified by the Function’s selected
+<a class="reference internal" href="#plugin"><em>GC strategy</em></a>. All calls to <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> <strong>must</strong> reside
+inside the first basic block.</p>
+<p>The first argument <strong>must</strong> be a value referring to an alloca instruction or a
+bitcast of an alloca. The second contains a pointer to metadata that should be
+associated with the pointer, and <strong>must</strong> be a constant or global value
+address. If your target collector uses tags, use a null pointer for metadata.</p>
+<p>A compiler which performs manual SSA construction <strong>must</strong> ensure that SSA
+values representing GC references are stored in to the alloca passed to the
+respective <tt class="docutils literal"><span class="pre">gcroot</span></tt> before every call site and reloaded after every call.
+A compiler which uses mem2reg to raise imperative code using <tt class="docutils literal"><span class="pre">alloca</span></tt> into
+SSA form need only add a call to <tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> for those variables which
+are pointers into the GC heap.</p>
+<p>It is also important to mark intermediate values with <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt>. For
+example, consider <tt class="docutils literal"><span class="pre">h(f(),</span> <span class="pre">g())</span></tt>. Beware leaking the result of <tt class="docutils literal"><span class="pre">f()</span></tt> in the
+case that <tt class="docutils literal"><span class="pre">g()</span></tt> triggers a collection. Note, that stack variables must be
+initialized and marked with <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> in function’s prologue.</p>
+<p>The <tt class="docutils literal"><span class="pre">%metadata</span></tt> argument can be used to avoid requiring heap objects to have
+‘isa’ pointers or tag bits. [<a class="reference internal" href="#appel89">Appel89</a>, <a class="reference internal" href="#goldberg91">Goldberg91</a>, <a class="reference internal" href="#tolmach94">Tolmach94</a>] If specified,
+its value will be tracked along with the location of the pointer in the stack
+frame.</p>
+<p>Consider the following fragment of Java code:</p>
+<div class="highlight-java"><div class="highlight"><pre><span class="o">{</span>
+ <span class="n">Object</span> <span class="n">X</span><span class="o">;</span> <span class="c1">// A null-initialized reference to an object</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+</pre></div>
+</div>
+<p>This block (which may be located in the middle of a function or in a loop nest),
+could be compiled to this LLVM code:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nl">Entry:</span>
+ <span class="c">;; In the entry block for the function, allocate the</span>
+ <span class="c">;; stack space for X, which is an LLVM pointer.</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="nv">%Object</span><span class="p">*</span>
+
+ <span class="c">;; Tell LLVM that the stack space is a stack root.</span>
+ <span class="c">;; Java has type-tags on objects, so we pass null as metadata.</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span> <span class="k">to</span> <span class="k">i8</span><span class="p">**</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.gcroot</span><span class="p">(</span><span class="k">i8</span><span class="p">**</span> <span class="nv">%tmp</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="k">null</span><span class="p">)</span>
+ <span class="p">...</span>
+
+ <span class="c">;; "CodeBlock" is the block corresponding to the start</span>
+ <span class="c">;; of the scope above.</span>
+<span class="nl">CodeBlock:</span>
+ <span class="c">;; Java null-initializes pointers.</span>
+ <span class="k">store</span> <span class="nv">%Object</span><span class="p">*</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span>
+
+ <span class="p">...</span>
+
+ <span class="c">;; As the pointer goes out of scope, store a null value into</span>
+ <span class="c">;; it, to indicate that the value is no longer live.</span>
+ <span class="k">store</span> <span class="nv">%Object</span><span class="p">*</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="reading-and-writing-references-in-the-heap">
+<h3><a class="toc-backref" href="#id11">Reading and writing references in the heap</a><a class="headerlink" href="#reading-and-writing-references-in-the-heap" title="Permalink to this headline">¶</a></h3>
+<p>Some collectors need to be informed when the mutator (the program that needs
+garbage collection) either reads a pointer from or writes a pointer to a field
+of a heap object. The code fragments inserted at these points are called <em>read
+barriers</em> and <em>write barriers</em>, respectively. The amount of code that needs to
+be executed is usually quite small and not on the critical path of any
+computation, so the overall performance impact of the barrier is tolerable.</p>
+<p>Barriers often require access to the <em>object pointer</em> rather than the <em>derived
+pointer</em> (which is a pointer to the field within the object). Accordingly,
+these intrinsics take both pointers as separate arguments for completeness. In
+this snippet, <tt class="docutils literal"><span class="pre">%object</span></tt> is the object pointer, and <tt class="docutils literal"><span class="pre">%derived</span></tt> is the derived
+pointer:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">;; An array type.</span>
+<span class="nv">%class.Array</span> <span class="p">=</span> <span class="k">type</span> <span class="p">{</span> <span class="nv">%class.Object</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="p">[</span><span class="m">0</span> <span class="k">x</span> <span class="nv">%class.Object</span><span class="p">*]</span> <span class="p">}</span>
+<span class="p">...</span>
+
+<span class="c">;; Load the object pointer from a gcroot.</span>
+<span class="nv">%object</span> <span class="p">=</span> <span class="k">load</span> <span class="nv">%class.Array</span><span class="p">**</span> <span class="nv">%object_addr</span>
+
+<span class="c">;; Compute the derived pointer.</span>
+<span class="nv">%derived</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%n</span>
+</pre></div>
+</div>
+<p>LLVM does not enforce this relationship between the object and derived pointer
+(although a particular <a class="reference internal" href="#plugin"><em>collector strategy</em></a> might). However, it
+would be an unusual collector that violated it.</p>
+<p>The use of these intrinsics is naturally optional if the target GC does not
+require the corresponding barrier. The GC strategy used with such a collector
+should replace the intrinsic calls with the corresponding <tt class="docutils literal"><span class="pre">load</span></tt> or
+<tt class="docutils literal"><span class="pre">store</span></tt> instruction if they are used.</p>
+<p>One known deficiency with the current design is that the barrier intrinsics do
+not include the size or alignment of the underlying operation performed. It is
+currently assumed that the operation is of pointer size and the alignment is
+assumed to be the target machine’s default alignment.</p>
+<div class="section" id="write-barrier-llvm-gcwrite">
+<h4><a class="toc-backref" href="#id12">Write barrier: <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a><a class="headerlink" href="#write-barrier-llvm-gcwrite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.gcwrite</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%value</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%derived</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For write barriers, LLVM provides the <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt> intrinsic function. It
+has exactly the same semantics as a non-volatile <tt class="docutils literal"><span class="pre">store</span></tt> to the derived
+pointer (the third argument). The exact code generated is specified by the
+Function’s selected <a class="reference internal" href="#plugin"><em>GC strategy</em></a>.</p>
+<p>Many important algorithms require write barriers, including generational and
+concurrent collectors. Additionally, write barriers could be used to implement
+reference counting.</p>
+</div>
+<div class="section" id="read-barrier-llvm-gcread">
+<h4><a class="toc-backref" href="#id13">Read barrier: <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt></a><a class="headerlink" href="#read-barrier-llvm-gcread" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.gcread</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%derived</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For read barriers, LLVM provides the <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt> intrinsic function. It has
+exactly the same semantics as a non-volatile <tt class="docutils literal"><span class="pre">load</span></tt> from the derived pointer
+(the second argument). The exact code generated is specified by the Function’s
+selected <a class="reference internal" href="#plugin"><em>GC strategy</em></a>.</p>
+<p>Read barriers are needed by fewer algorithms than write barriers, and may have a
+greater performance impact since pointer reads are more frequent than writes.</p>
+</div>
+</div>
+</div>
+<div class="section" id="built-in-gc-strategies">
+<span id="builtin-gc-strategies"></span><span id="plugin"></span><h2><a class="toc-backref" href="#id14">Built In GC Strategies</a><a class="headerlink" href="#built-in-gc-strategies" title="Permalink to this headline">¶</a></h2>
+<p>LLVM includes built in support for several varieties of garbage collectors.</p>
+<div class="section" id="the-shadow-stack-gc">
+<h3><a class="toc-backref" href="#id15">The Shadow Stack GC</a><a class="headerlink" href="#the-shadow-stack-gc" title="Permalink to this headline">¶</a></h3>
+<p>To use this collector strategy, mark your functions with:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"shadow-stack"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Unlike many GC algorithms which rely on a cooperative code generator to compile
+stack maps, this algorithm carefully maintains a linked list of stack roots
+[<a class="reference internal" href="#henderson02"><em>Henderson2002</em></a>]. This so-called “shadow stack” mirrors the
+machine stack. Maintaining this data structure is slower than using a stack map
+compiled into the executable as constant data, but has a significant portability
+advantage because it requires no special support from the target code generator,
+and does not require tricky platform-specific code to crawl the machine stack.</p>
+<p>The tradeoff for this simplicity and portability is:</p>
+<ul class="simple">
+<li>High overhead per function call.</li>
+<li>Not thread-safe.</li>
+</ul>
+<p>Still, it’s an easy way to get started. After your compiler and runtime are up
+and running, writing a <a class="reference internal" href="#plugin"><em>plugin</em></a> will allow you to take advantage
+of <a class="reference internal" href="#collector-algos"><em>more advanced GC features</em></a> of LLVM in order to
+improve performance.</p>
+<p>The shadow stack doesn’t imply a memory allocation algorithm. A semispace
+collector or building atop <tt class="docutils literal"><span class="pre">malloc</span></tt> are great places to start, and can be
+implemented with very little code.</p>
+<p>When it comes time to collect, however, your runtime needs to traverse the stack
+roots, and for this it needs to integrate with the shadow stack. Luckily, doing
+so is very simple. (This code is heavily commented to help you understand the
+data structure, but there are only 20 lines of meaningful code.)</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">/// @brief The map for a single function's stack frame. One of these is</span>
+<span class="c1">/// compiled as constant data into the executable for each function.</span>
+<span class="c1">///</span>
+<span class="c1">/// Storage of metadata values is elided if the %metadata parameter to</span>
+<span class="c1">/// @llvm.gcroot is null.</span>
+<span class="k">struct</span> <span class="n">FrameMap</span> <span class="p">{</span>
+ <span class="n">int32_t</span> <span class="n">NumRoots</span><span class="p">;</span> <span class="c1">//< Number of roots in stack frame.</span>
+ <span class="n">int32_t</span> <span class="n">NumMeta</span><span class="p">;</span> <span class="c1">//< Number of metadata entries. May be < NumRoots.</span>
+ <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Meta</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> <span class="c1">//< Metadata for each root.</span>
+<span class="p">};</span>
+
+<span class="c1">/// @brief 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">/// @brief 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">/// @brief Calls Visitor(root, meta) for each GC root on the stack.</span>
+<span class="c1">/// root and meta are exactly the values passed to</span>
+<span class="c1">/// @llvm.gcroot.</span>
+<span class="c1">///</span>
+<span class="c1">/// Visitor could be a function to recursively mark live objects. Or it</span>
+<span class="c1">/// might copy them to another heap or generation.</span>
+<span class="c1">///</span>
+<span class="c1">/// @param Visitor A function to invoke for every GC root on the stack.</span>
+<span class="kt">void</span> <span class="n">visitGCRoots</span><span class="p">(</span><span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">Visitor</span><span class="p">)(</span><span class="kt">void</span> <span class="o">**</span><span class="n">Root</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Meta</span><span class="p">))</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">StackEntry</span> <span class="o">*</span><span class="n">R</span> <span class="o">=</span> <span class="n">llvm_gc_root_chain</span><span class="p">;</span> <span class="n">R</span><span class="p">;</span> <span class="n">R</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Next</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="c1">// For roots [0, NumMeta), the metadata pointer is in the FrameMap.</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">e</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">NumMeta</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Visitor</span><span class="p">(</span><span class="o">&</span><span class="n">R</span><span class="o">-></span><span class="n">Roots</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">Meta</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+
+ <span class="c1">// For roots [NumMeta, NumRoots), the metadata pointer is null.</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">e</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">NumRoots</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Visitor</span><span class="p">(</span><span class="o">&</span><span class="n">R</span><span class="o">-></span><span class="n">Roots</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="nb">NULL</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-erlang-and-ocaml-gcs">
+<h3><a class="toc-backref" href="#id16">The ‘Erlang’ and ‘Ocaml’ GCs</a><a class="headerlink" href="#the-erlang-and-ocaml-gcs" title="Permalink to this headline">¶</a></h3>
+<p>LLVM ships with two example collectors which leverage the <tt class="docutils literal"><span class="pre">gcroot</span></tt>
+mechanisms. To our knowledge, these are not actually used by any language
+runtime, but they do provide a reasonable starting point for someone interested
+in writing an <tt class="docutils literal"><span class="pre">gcroot</span></tt> compatible GC plugin. In particular, these are the
+only in tree examples of how to produce a custom binary stack map format using
+a <tt class="docutils literal"><span class="pre">gcroot</span></tt> strategy.</p>
+<p>As there names imply, the binary format produced is intended to model that
+used by the Erlang and OCaml compilers respectively.</p>
+</div>
+<div class="section" id="the-statepoint-example-gc">
+<span id="statepoint-example-gc"></span><h3><a class="toc-backref" href="#id17">The Statepoint Example GC</a><a class="headerlink" href="#the-statepoint-example-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"statepoint-example"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This GC provides an example of how one might use the infrastructure provided
+by <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>. This example GC is compatible with the
+<a class="reference internal" href="Statepoints.html#placesafepoints"><em>PlaceSafepoints</em></a> and <a class="reference internal" href="Statepoints.html#rewritestatepointsforgc"><em>RewriteStatepointsForGC</em></a> utility passes
+which simplify <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> sequence insertion. If you need to build a
+custom GC strategy around the <tt class="docutils literal"><span class="pre">gc.statepoints</span></tt> mechanisms, it is recommended
+that you use this one as a starting point.</p>
+<p>This GC strategy does not support read or write barriers. As a result, these
+intrinsics are lowered to normal loads and stores.</p>
+<p>The stack map format generated by this GC strategy can be found in the
+<a class="reference internal" href="StackMaps.html#stackmap-section"><em>Stack Map Section</em></a> using a format documented <a class="reference internal" href="Statepoints.html#statepoint-stackmap-format"><em>here</em></a>. This format is intended to be the standard
+format supported by LLVM going forward.</p>
+</div>
+<div class="section" id="the-coreclr-gc">
+<h3><a class="toc-backref" href="#id18">The CoreCLR GC</a><a class="headerlink" href="#the-coreclr-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"coreclr"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This GC leverages the <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> mechanism to support the
+<a class="reference external" href="https://github.com/dotnet/coreclr">CoreCLR</a> runtime.</p>
+<p>Support for this GC strategy is a work in progress. This strategy will
+differ from
+<a class="reference internal" href="#statepoint-example-gc"><em>statepoint-example GC</em></a> strategy in
+certain aspects like:</p>
+<ul class="simple">
+<li>Base-pointers of interior pointers are not explicitly
+tracked and reported.</li>
+<li>A different format is used for encoding stack maps.</li>
+<li>Safe-point polls are only needed before loop-back edges
+and before tail-calls (not needed at function-entry).</li>
+</ul>
+</div>
+</div>
+<div class="section" id="custom-gc-strategies">
+<h2><a class="toc-backref" href="#id19">Custom GC Strategies</a><a class="headerlink" href="#custom-gc-strategies" title="Permalink to this headline">¶</a></h2>
+<p>If none of the built in GC strategy descriptions met your needs above, you will
+need to define a custom GCStrategy and possibly, a custom LLVM pass to perform
+lowering. Your best example of where to start defining a custom GCStrategy
+would be to look at one of the built in strategies.</p>
+<p>You may be able to structure this additional code as a loadable plugin library.
+Loadable plugins are sufficient if all you need is to enable a different
+combination of built in functionality, but if you need to provide a custom
+lowering pass, you will need to build a patched version of LLVM. If you think
+you need a patched build, please ask for advice on llvm-dev. There may be an
+easy way we can extend the support to make it work for your use case without
+requiring a custom build.</p>
+<div class="section" id="collector-requirements">
+<h3><a class="toc-backref" href="#id20">Collector Requirements</a><a class="headerlink" href="#collector-requirements" title="Permalink to this headline">¶</a></h3>
+<p>You should be able to leverage any existing collector library that includes the following elements:</p>
+<ol class="arabic simple">
+<li>A memory allocator which exposes an allocation function your compiled
+code can call.</li>
+<li>A binary format for the stack map. A stack map describes the location
+of references at a safepoint and is used by precise collectors to identify
+references within a stack frame on the machine stack. Note that collectors
+which conservatively scan the stack don’t require such a structure.</li>
+<li>A stack crawler to discover functions on the call stack, and enumerate the
+references listed in the stack map for each call site.</li>
+<li>A mechanism for identifying references in global locations (e.g. global
+variables).</li>
+<li>If you collector requires them, an LLVM IR implementation of your collectors
+load and store barriers. Note that since many collectors don’t require
+barriers at all, LLVM defaults to lowering such barriers to normal loads
+and stores unless you arrange otherwise.</li>
+</ol>
+</div>
+<div class="section" id="implementing-a-collector-plugin">
+<h3><a class="toc-backref" href="#id21">Implementing a collector plugin</a><a class="headerlink" href="#implementing-a-collector-plugin" title="Permalink to this headline">¶</a></h3>
+<p>User code specifies which GC code generation to use with the <tt class="docutils literal"><span class="pre">gc</span></tt> function
+attribute or, equivalently, with the <tt class="docutils literal"><span class="pre">setGC</span></tt> method of <tt class="docutils literal"><span class="pre">Function</span></tt>.</p>
+<p>To implement a GC plugin, it is necessary to subclass <tt class="docutils literal"><span class="pre">llvm::GCStrategy</span></tt>,
+which can be accomplished in a few lines of boilerplate code. LLVM’s
+infrastructure provides access to several important algorithms. For an
+uncontroversial collector, all that remains may be to compile LLVM’s computed
+stack map to assembly code (using the binary representation expected by the
+runtime library). This can be accomplished in about 100 lines of code.</p>
+<p>This is not the appropriate place to implement a garbage collected heap or a
+garbage collector itself. That code should exist in the language’s runtime
+library. The compiler plugin is responsible for generating code which conforms
+to the binary interface defined by library, most essentially the <a class="reference internal" href="#stack-map"><em>stack map</em></a>.</p>
+<p>To subclass <tt class="docutils literal"><span class="pre">llvm::GCStrategy</span></tt> and register it with the compiler:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">// lib/MyGC/MyGC.cpp - Example LLVM GC plugin</span>
+
+<span class="cp">#include "llvm/CodeGen/GCStrategy.h"</span>
+<span class="cp">#include "llvm/CodeGen/GCMetadata.h"</span>
+<span class="cp">#include "llvm/Support/Compiler.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">LLVM_LIBRARY_VISIBILITY</span> <span class="n">MyGC</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCStrategy</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="n">MyGC</span><span class="p">()</span> <span class="p">{}</span>
+ <span class="p">};</span>
+
+ <span class="n">GCRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyGC</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="s">"mygc"</span><span class="p">,</span> <span class="s">"My bespoke garbage collector."</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This boilerplate collector does nothing. More specifically:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">llvm.gcread</span></tt> calls are replaced with the corresponding <tt class="docutils literal"><span class="pre">load</span></tt>
+instruction.</li>
+<li><tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt> calls are replaced with the corresponding <tt class="docutils literal"><span class="pre">store</span></tt>
+instruction.</li>
+<li>No safe points are added to the code.</li>
+<li>The stack map is not compiled into the executable.</li>
+</ul>
+<p>Using the LLVM makefiles, this code
+can be compiled as a plugin using a simple makefile:</p>
+<div class="highlight-make"><div class="highlight"><pre><span class="c"># lib/MyGC/Makefile</span>
+
+<span class="nv">LEVEL</span> <span class="o">:=</span> ../..
+<span class="nv">LIBRARYNAME</span> <span class="o">=</span> MyGC
+<span class="nv">LOADABLE_MODULE</span> <span class="o">=</span> 1
+
+<span class="cp">include $(LEVEL)/Makefile.common</span>
+</pre></div>
+</div>
+<p>Once the plugin is compiled, code using it may be compiled using <tt class="docutils literal"><span class="pre">llc</span>
+<span class="pre">-load=MyGC.so</span></tt> (though MyGC.so may have some other platform-specific
+extension):</p>
+<div class="highlight-python"><pre>$ cat sample.ll
+define void @f() gc "mygc" {
+entry:
+ ret void
+}
+$ llvm-as < sample.ll | llc -load=MyGC.so</pre>
+</div>
+<p>It is also possible to statically link the collector plugin into tools, such as
+a language-specific compiler front-end.</p>
+</div>
+<div class="section" id="overview-of-available-features">
+<span id="collector-algos"></span><h3><a class="toc-backref" href="#id22">Overview of available features</a><a class="headerlink" href="#overview-of-available-features" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">GCStrategy</span></tt> provides a range of features through which a plugin may do useful
+work. Some of these are callbacks, some are algorithms that can be enabled,
+disabled, or customized. This matrix summarizes the supported (and planned)
+features and correlates them with the collection techniques which typically
+require them.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="14%" />
+<col width="7%" />
+<col width="9%" />
+<col width="11%" />
+<col width="8%" />
+<col width="10%" />
+<col width="15%" />
+<col width="11%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Algorithm</th>
+<th class="head">Done</th>
+<th class="head">Shadow
+stack</th>
+<th class="head">refcount</th>
+<th class="head">mark-
+sweep</th>
+<th class="head">copying</th>
+<th class="head">incremental</th>
+<th class="head">threaded</th>
+<th class="head">concurrent</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>stack map</td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td>initialize
+roots</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>derived
+pointers</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong>*</td>
+<td><strong>N</strong>*</td>
+</tr>
+<tr class="row-odd"><td><strong>custom
+lowering</strong></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>gcroot</em></td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-odd"><td><em>gcwrite</em></td>
+<td>â</td>
+<td> </td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td> </td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td><em>gcread</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><strong>safe
+points</strong></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>in
+calls</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><em>before
+calls</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td><em>for
+loops</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong></td>
+<td><strong>N</strong></td>
+</tr>
+<tr class="row-odd"><td><em>before
+escape</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>emit code
+at safe
+points</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong></td>
+<td><strong>N</strong></td>
+</tr>
+<tr class="row-odd"><td><strong>output</strong></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>assembly</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><em>JIT</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-even"><td><em>obj</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-odd"><td>live
+analysis</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-even"><td>register
+map</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-odd"><td colspan="9">* Derived pointers only pose a hasard to copying collections.</td>
+</tr>
+<tr class="row-even"><td colspan="9"><strong>?</strong> denotes a feature which could be utilized if available.</td>
+</tr>
+</tbody>
+</table>
+<p>To be clear, the collection techniques above are defined as:</p>
+<dl class="docutils">
+<dt>Shadow Stack</dt>
+<dd>The mutator carefully maintains a linked list of stack roots.</dd>
+<dt>Reference Counting</dt>
+<dd>The mutator maintains a reference count for each object and frees an object
+when its count falls to zero.</dd>
+<dt>Mark-Sweep</dt>
+<dd>When the heap is exhausted, the collector marks reachable objects starting
+from the roots, then deallocates unreachable objects in a sweep phase.</dd>
+<dt>Copying</dt>
+<dd>As reachability analysis proceeds, the collector copies objects from one heap
+area to another, compacting them in the process. Copying collectors enable
+highly efficient “bump pointer” allocation and can improve locality of
+reference.</dd>
+<dt>Incremental</dt>
+<dd>(Including generational collectors.) Incremental collectors generally have all
+the properties of a copying collector (regardless of whether the mature heap
+is compacting), but bring the added complexity of requiring write barriers.</dd>
+<dt>Threaded</dt>
+<dd>Denotes a multithreaded mutator; the collector must still stop the mutator
+(“stop the world”) before beginning reachability analysis. Stopping a
+multithreaded mutator is a complicated problem. It generally requires highly
+platform-specific code in the runtime, and the production of carefully
+designed machine code at safe points.</dd>
+<dt>Concurrent</dt>
+<dd>In this technique, the mutator and the collector run concurrently, with the
+goal of eliminating pause times. In a <em>cooperative</em> collector, the mutator
+further aids with collection should a pause occur, allowing collection to take
+advantage of multiprocessor hosts. The “stop the world” problem of threaded
+collectors is generally still present to a limited extent. Sophisticated
+marking algorithms are necessary. Read barriers may be necessary.</dd>
+</dl>
+<p>As the matrix indicates, LLVM’s garbage collection infrastructure is already
+suitable for a wide variety of collectors, but does not currently extend to
+multithreaded programs. This will be added in the future as there is
+interest.</p>
+</div>
+<div class="section" id="computing-stack-maps">
+<span id="stack-map"></span><h3><a class="toc-backref" href="#id23">Computing stack maps</a><a class="headerlink" href="#computing-stack-maps" title="Permalink to this headline">¶</a></h3>
+<p>LLVM automatically computes a stack map. One of the most important features
+of a <tt class="docutils literal"><span class="pre">GCStrategy</span></tt> is to compile this information into the executable in
+the binary representation expected by the runtime library.</p>
+<p>The stack map consists of the location and identity of each GC root in the
+each function in the module. For each root:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">RootNum</span></tt>: The index of the root.</li>
+<li><tt class="docutils literal"><span class="pre">StackOffset</span></tt>: The offset of the object relative to the frame pointer.</li>
+<li><tt class="docutils literal"><span class="pre">RootMetadata</span></tt>: The value passed as the <tt class="docutils literal"><span class="pre">%metadata</span></tt> parameter to the
+<tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> intrinsic.</li>
+</ul>
+<p>Also, for the function as a whole:</p>
+<ul>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal"><span class="pre">getFrameSize()</span></tt>: The overall size of the function’s initial stack frame,</dt>
+<dd><p class="first last">not accounting for any dynamic allocation.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">roots_size()</span></tt>: The count of roots in the function.</p>
+</li>
+</ul>
+<p>To access the stack map, use <tt class="docutils literal"><span class="pre">GCFunctionMetadata::roots_begin()</span></tt> and
+-<tt class="docutils literal"><span class="pre">end()</span></tt> from the <a class="reference internal" href="#assembly"><em>GCMetadataPrinter</em></a>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">*</span><span class="n">FI</span> <span class="o">=</span> <span class="o">*</span><span class="n">I</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">FrameSize</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">getFrameSize</span><span class="p">();</span>
+ <span class="n">size_t</span> <span class="n">RootCount</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_size</span><span class="p">();</span>
+
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">roots_iterator</span> <span class="n">RI</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_begin</span><span class="p">(),</span>
+ <span class="n">RE</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_end</span><span class="p">();</span>
+ <span class="n">RI</span> <span class="o">!=</span> <span class="n">RE</span><span class="p">;</span> <span class="o">++</span><span class="n">RI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">RootNum</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">Num</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">RootStackOffset</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">StackOffset</span><span class="p">;</span>
+ <span class="n">Constant</span> <span class="o">*</span><span class="n">RootMetadata</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">Metadata</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> intrinsic is eliminated before code generation by a
+custom lowering pass, LLVM will compute an empty stack map. This may be useful
+for collector plugins which implement reference counting or a shadow stack.</p>
+</div>
+<div class="section" id="initializing-roots-to-null-initroots">
+<span id="init-roots"></span><h3><a class="toc-backref" href="#id24">Initializing roots to null: <tt class="docutils literal"><span class="pre">InitRoots</span></tt></a><a class="headerlink" href="#initializing-roots-to-null-initroots" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">InitRoots</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>When set, LLVM will automatically initialize each root to <tt class="docutils literal"><span class="pre">null</span></tt> upon entry to
+the function. This prevents the GC’s sweep phase from visiting uninitialized
+pointers, which will almost certainly cause it to crash. This initialization
+occurs before custom lowering, so the two may be used together.</p>
+<p>Since LLVM does not yet compute liveness information, there is no means of
+distinguishing an uninitialized stack root from an initialized one. Therefore,
+this feature should be used by all GC plugins. It is enabled by default.</p>
+</div>
+<div class="section" id="custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers">
+<h3><a class="toc-backref" href="#id25">Custom lowering of intrinsics: <tt class="docutils literal"><span class="pre">CustomRoots</span></tt>, <tt class="docutils literal"><span class="pre">CustomReadBarriers</span></tt>, and <tt class="docutils literal"><span class="pre">CustomWriteBarriers</span></tt></a><a class="headerlink" href="#custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers" title="Permalink to this headline">¶</a></h3>
+<p>For GCs which use barriers or unusual treatment of stack roots, these
+flags allow the collector to perform arbitrary transformations of the
+LLVM IR:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyGC</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCStrategy</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">CustomRoots</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="n">CustomReadBarriers</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="n">CustomWriteBarriers</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>If any of these flags are set, LLVM suppresses its default lowering for
+the corresponding intrinsics. Instead, you must provide a custom Pass
+which lowers the intrinsics as desired. If you have opted in to custom
+lowering of a particular intrinsic your pass <strong>must</strong> eliminate all
+instances of the corresponding intrinsic in functions which opt in to
+your GC. The best example of such a pass is the ShadowStackGC and it’s
+ShadowStackGCLowering pass.</p>
+<p>There is currently no way to register such a custom lowering pass
+without building a custom copy of LLVM.</p>
+</div>
+<div class="section" id="generating-safe-points-neededsafepoints">
+<span id="safe-points"></span><h3><a class="toc-backref" href="#id26">Generating safe points: <tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt></a><a class="headerlink" href="#generating-safe-points-neededsafepoints" title="Permalink to this headline">¶</a></h3>
+<p>LLVM can compute four kinds of safe points:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">GC</span> <span class="p">{</span>
+ <span class="c1">/// PointKind - The type of a collector-safe point.</span>
+ <span class="c1">///</span>
+ <span class="k">enum</span> <span class="n">PointKind</span> <span class="p">{</span>
+ <span class="n">Loop</span><span class="p">,</span> <span class="c1">//< Instr is a loop (backwards branch).</span>
+ <span class="n">Return</span><span class="p">,</span> <span class="c1">//< Instr is a return instruction.</span>
+ <span class="n">PreCall</span><span class="p">,</span> <span class="c1">//< Instr is a call instruction.</span>
+ <span class="n">PostCall</span> <span class="c1">//< Instr is the return address of a call.</span>
+ <span class="p">};</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A collector can request any combination of the four by setting the
+<tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt> mask:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">NeededSafePoints</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">Loop</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">Return</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">PreCall</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">PostCall</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It can then use the following routines to access safe points.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">*</span><span class="n">MD</span> <span class="o">=</span> <span class="o">*</span><span class="n">I</span><span class="p">;</span>
+ <span class="n">size_t</span> <span class="n">PointCount</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">size</span><span class="p">();</span>
+
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span>
+ <span class="n">PE</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="n">PI</span> <span class="o">!=</span> <span class="n">PE</span><span class="p">;</span> <span class="o">++</span><span class="n">PI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GC</span><span class="o">::</span><span class="n">PointKind</span> <span class="n">PointKind</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Kind</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">PointNum</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Num</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Almost every collector requires <tt class="docutils literal"><span class="pre">PostCall</span></tt> safe points, since these correspond
+to the moments when the function is suspended during a call to a subroutine.</p>
+<p>Threaded programs generally require <tt class="docutils literal"><span class="pre">Loop</span></tt> safe points to guarantee that the
+application will reach a safe point within a bounded amount of time, even if it
+is executing a long-running loop which contains no function calls.</p>
+<p>Threaded collectors may also require <tt class="docutils literal"><span class="pre">Return</span></tt> and <tt class="docutils literal"><span class="pre">PreCall</span></tt> safe points to
+implement “stop the world” techniques using self-modifying code, where it is
+important that the program not exit the function without reaching a safe point
+(because only the topmost function has been patched).</p>
+</div>
+<div class="section" id="emitting-assembly-code-gcmetadataprinter">
+<span id="assembly"></span><h3><a class="toc-backref" href="#id27">Emitting assembly code: <tt class="docutils literal"><span class="pre">GCMetadataPrinter</span></tt></a><a class="headerlink" href="#emitting-assembly-code-gcmetadataprinter" title="Permalink to this headline">¶</a></h3>
+<p>LLVM allows a plugin to print arbitrary assembly code before and after the rest
+of a module’s assembly code. At the end of the module, the GC can compile the
+LLVM stack map into assembly code. (At the beginning, this information is not
+yet computed.)</p>
+<p>Since AsmWriter and CodeGen are separate components of LLVM, a separate abstract
+base class and registry is provided for printing assembly code, the
+<tt class="docutils literal"><span class="pre">GCMetadaPrinter</span></tt> and <tt class="docutils literal"><span class="pre">GCMetadataPrinterRegistry</span></tt>. The AsmWriter will look
+for such a subclass if the <tt class="docutils literal"><span class="pre">GCStrategy</span></tt> sets <tt class="docutils literal"><span class="pre">UsesMetadata</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">UsesMetadata</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This separation allows JIT-only clients to be smaller.</p>
+<p>Note that LLVM does not currently have analogous APIs to support code generation
+in the JIT, nor using the object writers.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">// lib/MyGC/MyGCPrinter.cpp - Example LLVM GC printer</span>
+
+<span class="cp">#include "llvm/CodeGen/GCMetadataPrinter.h"</span>
+<span class="cp">#include "llvm/Support/Compiler.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">LLVM_LIBRARY_VISIBILITY</span> <span class="n">MyGCPrinter</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCMetadataPrinter</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">beginAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">);</span>
+
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">finishAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">);</span>
+ <span class="p">};</span>
+
+ <span class="n">GCMetadataPrinterRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyGCPrinter</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="s">"mygc"</span><span class="p">,</span> <span class="s">"My bespoke garbage collector."</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The collector should use <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> to print portable assembly code. The
+collector itself contains the stack map for the entire module, and may access
+the <tt class="docutils literal"><span class="pre">GCFunctionInfo</span></tt> using its own <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> methods. Here’s
+a realistic example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/CodeGen/AsmPrinter.h"</span>
+<span class="cp">#include "llvm/IR/Function.h"</span>
+<span class="cp">#include "llvm/IR/DataLayout.h"</span>
+<span class="cp">#include "llvm/Target/TargetAsmInfo.h"</span>
+<span class="cp">#include "llvm/Target/TargetMachine.h"</span>
+
+<span class="kt">void</span> <span class="n">MyGCPrinter</span><span class="o">::</span><span class="n">beginAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Nothing to do.</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="n">MyGCPrinter</span><span class="o">::</span><span class="n">finishAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MCStreamer</span> <span class="o">&</span><span class="n">OS</span> <span class="o">=</span> <span class="n">AP</span><span class="p">.</span><span class="n">OutStreamer</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">IntPtrSize</span> <span class="o">=</span> <span class="n">AP</span><span class="p">.</span><span class="n">getPointerSize</span><span class="p">();</span>
+
+ <span class="c1">// Put this in the data section.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">SwitchSection</span><span class="p">(</span><span class="n">AP</span><span class="p">.</span><span class="n">getObjFileLowering</span><span class="p">().</span><span class="n">getDataSection</span><span class="p">());</span>
+
+ <span class="c1">// For each function...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">FI</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">FE</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">FI</span> <span class="o">!=</span> <span class="n">FE</span><span class="p">;</span> <span class="o">++</span><span class="n">FI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">&</span><span class="n">MD</span> <span class="o">=</span> <span class="o">**</span><span class="n">FI</span><span class="p">;</span>
+
+ <span class="c1">// A compact GC layout. Emit this data structure:</span>
+ <span class="c1">//</span>
+ <span class="c1">// struct {</span>
+ <span class="c1">// int32_t PointCount;</span>
+ <span class="c1">// void *SafePointAddress[PointCount];</span>
+ <span class="c1">// int32_t StackFrameSize; // in words</span>
+ <span class="c1">// int32_t StackArity;</span>
+ <span class="c1">// int32_t LiveCount;</span>
+ <span class="c1">// int32_t LiveOffsets[LiveCount];</span>
+ <span class="c1">// } __gcmap_<FUNCTIONNAME>;</span>
+
+ <span class="c1">// Align to address width.</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitAlignment</span><span class="p">(</span><span class="n">IntPtrSize</span> <span class="o">==</span> <span class="mi">4</span> <span class="o">?</span> <span class="mi">2</span> <span class="o">:</span> <span class="mi">3</span><span class="p">);</span>
+
+ <span class="c1">// Emit PointCount.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"safe point count"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">size</span><span class="p">());</span>
+
+ <span class="c1">// And each safe point...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span>
+ <span class="n">PE</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">end</span><span class="p">();</span> <span class="n">PI</span> <span class="o">!=</span> <span class="n">PE</span><span class="p">;</span> <span class="o">++</span><span class="n">PI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Emit the address of the safe point.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"safe point address"</span><span class="p">);</span>
+ <span class="n">MCSymbol</span> <span class="o">*</span><span class="n">Label</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Label</span><span class="p">;</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitLabelPlusOffset</span><span class="p">(</span><span class="n">Label</span><span class="cm">/*Hi*/</span><span class="p">,</span> <span class="mi">0</span><span class="cm">/*Offset*/</span><span class="p">,</span> <span class="mi">4</span><span class="cm">/*Size*/</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="c1">// Stack information never change in safe points! Only print info from the</span>
+ <span class="c1">// first call-site.</span>
+ <span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
+
+ <span class="c1">// Emit the stack frame size.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack frame size (in words)"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">getFrameSize</span><span class="p">()</span> <span class="o">/</span> <span class="n">IntPtrSize</span><span class="p">);</span>
+
+ <span class="c1">// Emit stack arity, i.e. the number of stacked arguments.</span>
+ <span class="kt">unsigned</span> <span class="n">RegisteredArgs</span> <span class="o">=</span> <span class="n">IntPtrSize</span> <span class="o">==</span> <span class="mi">4</span> <span class="o">?</span> <span class="mi">5</span> <span class="o">:</span> <span class="mi">6</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">StackArity</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">getFunction</span><span class="p">().</span><span class="n">arg_size</span><span class="p">()</span> <span class="o">></span> <span class="n">RegisteredArgs</span> <span class="o">?</span>
+ <span class="n">MD</span><span class="p">.</span><span class="n">getFunction</span><span class="p">().</span><span class="n">arg_size</span><span class="p">()</span> <span class="o">-</span> <span class="n">RegisteredArgs</span> <span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack arity"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">StackArity</span><span class="p">);</span>
+
+ <span class="c1">// Emit the number of live roots in the function.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"live root count"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">live_size</span><span class="p">(</span><span class="n">PI</span><span class="p">));</span>
+
+ <span class="c1">// And for each live root...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">live_iterator</span> <span class="n">LI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">live_begin</span><span class="p">(</span><span class="n">PI</span><span class="p">),</span>
+ <span class="n">LE</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">live_end</span><span class="p">(</span><span class="n">PI</span><span class="p">);</span>
+ <span class="n">LI</span> <span class="o">!=</span> <span class="n">LE</span><span class="p">;</span> <span class="o">++</span><span class="n">LI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Emit live root's offset within the stack frame.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack index (offset / wordsize)"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">LI</span><span class="o">-></span><span class="n">StackOffset</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="references">
+<h2><a class="toc-backref" href="#id28">References</a><a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
+<p id="appel89">[Appel89] Runtime Tags Aren’t Necessary. Andrew W. Appel. Lisp and Symbolic
+Computation 19(7):703-705, July 1989.</p>
+<p id="goldberg91">[Goldberg91] Tag-free garbage collection for strongly typed programming
+languages. Benjamin Goldberg. ACM SIGPLAN PLDI‘91.</p>
+<p id="tolmach94">[Tolmach94] Tag-free garbage collection using explicit type parameters. Andrew
+Tolmach. Proceedings of the 1994 ACM conference on LISP and functional
+programming.</p>
+<p id="henderson02">[Henderson2002] <a class="reference external" href="http://citeseer.ist.psu.edu/henderson02accurate.html">Accurate Garbage Collection in an Uncooperative Environment</a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/GetElementPtr.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/GetElementPtr.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/GetElementPtr.html (added)
+++ www-releases/trunk/5.0.2/docs/GetElementPtr.html Thu May 10 06:54:16 2018
@@ -0,0 +1,572 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The Often Misunderstood GEP Instruction — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="Performance Tips for Frontend Authors" href="Frontend/PerformanceTips.html" />
+ <link rel="prev" title="YAML I/O" href="YamlIO.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="YamlIO.html" title="YAML I/O"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="the-often-misunderstood-gep-instruction">
+<h1>The Often Misunderstood GEP Instruction<a class="headerlink" href="#the-often-misunderstood-gep-instruction" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
+<li><a class="reference internal" href="#address-computation" id="id3">Address Computation</a><ul>
+<li><a class="reference internal" href="#what-is-the-first-index-of-the-gep-instruction" id="id4">What is the first index of the GEP instruction?</a></li>
+<li><a class="reference internal" href="#why-is-the-extra-0-index-required" id="id5">Why is the extra 0 index required?</a></li>
+<li><a class="reference internal" href="#what-is-dereferenced-by-gep" id="id6">What is dereferenced by GEP?</a></li>
+<li><a class="reference internal" href="#why-don-t-gep-x-0-0-1-and-gep-x-1-alias" id="id7">Why don’t GEP x,0,0,1 and GEP x,1 alias?</a></li>
+<li><a class="reference internal" href="#why-do-gep-x-1-0-0-and-gep-x-1-alias" id="id8">Why do GEP x,1,0,0 and GEP x,1 alias?</a></li>
+<li><a class="reference internal" href="#can-gep-index-into-vector-elements" id="id9">Can GEP index into vector elements?</a></li>
+<li><a class="reference internal" href="#what-effect-do-address-spaces-have-on-geps" id="id10">What effect do address spaces have on GEPs?</a></li>
+<li><a class="reference internal" href="#how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr" id="id11">How is GEP different from <tt class="docutils literal"><span class="pre">ptrtoint</span></tt>, arithmetic, and <tt class="docutils literal"><span class="pre">inttoptr</span></tt>?</a></li>
+<li><a class="reference internal" href="#i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this" id="id12">I’m writing a backend for a target which needs custom lowering for GEP. How do I do this?</a></li>
+<li><a class="reference internal" href="#how-does-vla-addressing-work-with-geps" id="id13">How does VLA addressing work with GEPs?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rules" id="id14">Rules</a><ul>
+<li><a class="reference internal" href="#what-happens-if-an-array-index-is-out-of-bounds" id="id15">What happens if an array index is out of bounds?</a></li>
+<li><a class="reference internal" href="#can-array-indices-be-negative" id="id16">Can array indices be negative?</a></li>
+<li><a class="reference internal" href="#can-i-compare-two-values-computed-with-geps" id="id17">Can I compare two values computed with GEPs?</a></li>
+<li><a class="reference internal" href="#can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object" id="id18">Can I do GEP with a different pointer type than the type of the underlying object?</a></li>
+<li><a class="reference internal" href="#can-i-cast-an-object-s-address-to-integer-and-add-it-to-null" id="id19">Can I cast an object’s address to integer and add it to null?</a></li>
+<li><a class="reference internal" href="#can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address" id="id20">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a></li>
+<li><a class="reference internal" href="#can-i-do-type-based-alias-analysis-on-llvm-ir" id="id21">Can I do type-based alias analysis on LLVM IR?</a></li>
+<li><a class="reference internal" href="#what-happens-if-a-gep-computation-overflows" id="id22">What happens if a GEP computation overflows?</a></li>
+<li><a class="reference internal" href="#how-can-i-tell-if-my-front-end-is-following-the-rules" id="id23">How can I tell if my front-end is following the rules?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rationale" id="id24">Rationale</a><ul>
+<li><a class="reference internal" href="#why-is-gep-designed-this-way" id="id25">Why is GEP designed this way?</a></li>
+<li><a class="reference internal" href="#why-do-struct-member-indices-always-use-i32" id="id26">Why do struct member indices always use <tt class="docutils literal"><span class="pre">i32</span></tt>?</a></li>
+<li><a class="reference internal" href="#what-s-an-uglygep" id="id27">What’s an uglygep?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#summary" id="id28">Summary</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document seeks to dispel the mystery and confusion surrounding LLVM’s
+<a class="reference external" href="LangRef.html#getelementptr-instruction">GetElementPtr</a> (GEP) instruction.
+Questions about the wily GEP instruction are probably the most frequently
+occurring questions once a developer gets down to coding with LLVM. Here we lay
+out the sources of confusion and show that the GEP instruction is really quite
+simple.</p>
+</div>
+<div class="section" id="address-computation">
+<h2><a class="toc-backref" href="#id3">Address Computation</a><a class="headerlink" href="#address-computation" title="Permalink to this headline">¶</a></h2>
+<p>When people are first confronted with the GEP instruction, they tend to relate
+it to known concepts from other programming paradigms, most notably C array
+indexing and field selection. GEP closely resembles C array indexing and field
+selection, however it is a little different and this leads to the following
+questions.</p>
+<div class="section" id="what-is-the-first-index-of-the-gep-instruction">
+<h3><a class="toc-backref" href="#id4">What is the first index of the GEP instruction?</a><a class="headerlink" href="#what-is-the-first-index-of-the-gep-instruction" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: The index stepping through the second operand.</p>
+<p>The confusion with the first index usually arises from thinking about the
+GetElementPtr instruction as if it was a C index operator. They aren’t the
+same. For example, when we write, in “C”:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">AType</span> <span class="o">*</span><span class="n">Foo</span><span class="p">;</span>
+<span class="p">...</span>
+<span class="n">X</span> <span class="o">=</span> <span class="o">&</span><span class="n">Foo</span><span class="o">-></span><span class="n">F</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>it is natural to think that there is only one index, the selection of the field
+<tt class="docutils literal"><span class="pre">F</span></tt>. However, in this example, <tt class="docutils literal"><span class="pre">Foo</span></tt> is a pointer. That pointer
+must be indexed explicitly in LLVM. C, on the other hand, indices through it
+transparently. To arrive at the same address location as the C code, you would
+provide the GEP instruction with two index operands. The first operand indexes
+through the pointer; the second operand indexes the field <tt class="docutils literal"><span class="pre">F</span></tt> of the
+structure, just as if you wrote:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">X</span> <span class="o">=</span> <span class="o">&</span><span class="n">Foo</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">F</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Sometimes this question gets rephrased as:</p>
+<blockquote id="gep-index-through-first-pointer">
+<div><em>Why is it okay to index through the first pointer, but subsequent pointers
+won’t be dereferenced?</em></div></blockquote>
+<p>The answer is simply because memory does not have to be accessed to perform the
+computation. The second operand to the GEP instruction must be a value of a
+pointer type. The value of the pointer is provided directly to the GEP
+instruction as an operand without any need for accessing memory. It must,
+therefore be indexed and requires an index operand. Consider this example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">munger_struct</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">f1</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">f2</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="kt">void</span> <span class="n">munge</span><span class="p">(</span><span class="k">struct</span> <span class="n">munger_struct</span> <span class="o">*</span><span class="n">P</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">P</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">f1</span> <span class="o">=</span> <span class="n">P</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span><span class="n">f1</span> <span class="o">+</span> <span class="n">P</span><span class="p">[</span><span class="mi">2</span><span class="p">].</span><span class="n">f2</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="p">...</span>
+<span class="n">munger_struct</span> <span class="n">Array</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span>
+<span class="p">...</span>
+<span class="n">munge</span><span class="p">(</span><span class="n">Array</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In this “C” example, the front end compiler (Clang) will generate three GEP
+instructions for the three indices through “P” in the assignment statement. The
+function argument <tt class="docutils literal"><span class="pre">P</span></tt> will be the second operand of each of these GEP
+instructions. The third operand indexes through that pointer. The fourth
+operand will be the field offset into the <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">munger_struct</span></tt> type, for
+either the <tt class="docutils literal"><span class="pre">f1</span></tt> or <tt class="docutils literal"><span class="pre">f2</span></tt> field. So, in LLVM assembly the <tt class="docutils literal"><span class="pre">munge</span></tt> function
+looks like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="nv">%munge</span><span class="p">(</span><span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp</span>
+ <span class="nv">%tmp6</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span>
+ <span class="nv">%tmp7</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp6</span>
+ <span class="nv">%tmp8</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%tmp7</span><span class="p">,</span> <span class="nv">%tmp</span>
+ <span class="nv">%tmp9</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%tmp8</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp9</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In each case the second operand is the pointer through which the GEP instruction
+starts. The same is true whether the second operand is an argument, allocated
+memory, or a global variable.</p>
+<p>To make this clear, let’s consider a more obtuse example:</p>
+<div class="highlight-text"><div class="highlight"><pre>%MyVar = uninitialized global i32
+...
+%idx1 = getelementptr i32, i32* %MyVar, i64 0
+%idx2 = getelementptr i32, i32* %MyVar, i64 1
+%idx3 = getelementptr i32, i32* %MyVar, i64 2
+</pre></div>
+</div>
+<p>These GEP instructions are simply making address computations from the base
+address of <tt class="docutils literal"><span class="pre">MyVar</span></tt>. They compute, as follows (using C syntax):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">idx1</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">0</span>
+<span class="n">idx2</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">4</span>
+<span class="n">idx3</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">8</span>
+</pre></div>
+</div>
+<p>Since the type <tt class="docutils literal"><span class="pre">i32</span></tt> is known to be four bytes long, the indices 0, 1 and 2
+translate into memory offsets of 0, 4, and 8, respectively. No memory is
+accessed to make these computations because the address of <tt class="docutils literal"><span class="pre">%MyVar</span></tt> is passed
+directly to the GEP instructions.</p>
+<p>The obtuse part of this example is in the cases of <tt class="docutils literal"><span class="pre">%idx2</span></tt> and <tt class="docutils literal"><span class="pre">%idx3</span></tt>. They
+result in the computation of addresses that point to memory past the end of the
+<tt class="docutils literal"><span class="pre">%MyVar</span></tt> global, which is only one <tt class="docutils literal"><span class="pre">i32</span></tt> long, not three <tt class="docutils literal"><span class="pre">i32</span></tt>s long.
+While this is legal in LLVM, it is inadvisable because any load or store with
+the pointer that results from these GEP instructions would produce undefined
+results.</p>
+</div>
+<div class="section" id="why-is-the-extra-0-index-required">
+<h3><a class="toc-backref" href="#id5">Why is the extra 0 index required?</a><a class="headerlink" href="#why-is-the-extra-0-index-required" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: there are no superfluous indices.</p>
+<p>This question arises most often when the GEP instruction is applied to a global
+variable which is always a pointer type. For example, consider this:</p>
+<div class="highlight-text"><div class="highlight"><pre>%MyStruct = uninitialized global { float*, i32 }
+...
+%idx = getelementptr { float*, i32 }, { float*, i32 }* %MyStruct, i64 0, i32 1
+</pre></div>
+</div>
+<p>The GEP above yields an <tt class="docutils literal"><span class="pre">i32*</span></tt> by indexing the <tt class="docutils literal"><span class="pre">i32</span></tt> typed field of the
+structure <tt class="docutils literal"><span class="pre">%MyStruct</span></tt>. When people first look at it, they wonder why the <tt class="docutils literal"><span class="pre">i64</span>
+<span class="pre">0</span></tt> index is needed. However, a closer inspection of how globals and GEPs work
+reveals the need. Becoming aware of the following facts will dispel the
+confusion:</p>
+<ol class="arabic simple">
+<li>The type of <tt class="docutils literal"><span class="pre">%MyStruct</span></tt> is <em>not</em> <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span> <span class="pre">i32</span> <span class="pre">}</span></tt> but rather <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span>
+<span class="pre">i32</span> <span class="pre">}*</span></tt>. That is, <tt class="docutils literal"><span class="pre">%MyStruct</span></tt> is a pointer to a structure containing a
+pointer to a <tt class="docutils literal"><span class="pre">float</span></tt> and an <tt class="docutils literal"><span class="pre">i32</span></tt>.</li>
+<li>Point #1 is evidenced by noticing the type of the second operand of the GEP
+instruction (<tt class="docutils literal"><span class="pre">%MyStruct</span></tt>) which is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span> <span class="pre">i32</span> <span class="pre">}*</span></tt>.</li>
+<li>The first index, <tt class="docutils literal"><span class="pre">i64</span> <span class="pre">0</span></tt> is required to step over the global variable
+<tt class="docutils literal"><span class="pre">%MyStruct</span></tt>. Since the second argument to the GEP instruction must always
+be a value of pointer type, the first index steps through that pointer. A
+value of 0 means 0 elements offset from that pointer.</li>
+<li>The second index, <tt class="docutils literal"><span class="pre">i32</span> <span class="pre">1</span></tt> selects the second field of the structure (the
+<tt class="docutils literal"><span class="pre">i32</span></tt>).</li>
+</ol>
+</div>
+<div class="section" id="what-is-dereferenced-by-gep">
+<h3><a class="toc-backref" href="#id6">What is dereferenced by GEP?</a><a class="headerlink" href="#what-is-dereferenced-by-gep" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: nothing.</p>
+<p>The GetElementPtr instruction dereferences nothing. That is, it doesn’t access
+memory in any way. That’s what the Load and Store instructions are for. GEP is
+only involved in the computation of addresses. For example, consider this:</p>
+<div class="highlight-text"><div class="highlight"><pre>%MyVar = uninitialized global { [40 x i32 ]* }
+...
+%idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+</pre></div>
+</div>
+<p>In this example, we have a global variable, <tt class="docutils literal"><span class="pre">%MyVar</span></tt> that is a pointer to a
+structure containing a pointer to an array of 40 ints. The GEP instruction seems
+to be accessing the 18th integer of the structure’s array of ints. However, this
+is actually an illegal GEP instruction. It won’t compile. The reason is that the
+pointer in the structure <em>must</em> be dereferenced in order to index into the
+array of 40 ints. Since the GEP instruction never accesses memory, it is
+illegal.</p>
+<p>In order to access the 18th integer in the array, you would need to do the
+following:</p>
+<div class="highlight-text"><div class="highlight"><pre>%idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %, i64 0, i32 0
+%arr = load [40 x i32]** %idx
+%idx = getelementptr [40 x i32], [40 x i32]* %arr, i64 0, i64 17
+</pre></div>
+</div>
+<p>In this case, we have to load the pointer in the structure with a load
+instruction before we can index into the array. If the example was changed to:</p>
+<div class="highlight-text"><div class="highlight"><pre>%MyVar = uninitialized global { [40 x i32 ] }
+...
+%idx = getelementptr { [40 x i32] }, { [40 x i32] }*, i64 0, i32 0, i64 17
+</pre></div>
+</div>
+<p>then everything works fine. In this case, the structure does not contain a
+pointer and the GEP instruction can index through the global variable, into the
+first field of the structure and access the 18th <tt class="docutils literal"><span class="pre">i32</span></tt> in the array there.</p>
+</div>
+<div class="section" id="why-don-t-gep-x-0-0-1-and-gep-x-1-alias">
+<h3><a class="toc-backref" href="#id7">Why don’t GEP x,0,0,1 and GEP x,1 alias?</a><a class="headerlink" href="#why-don-t-gep-x-0-0-1-and-gep-x-1-alias" title="Permalink to this headline">¶</a></h3>
+<p>Quick Answer: They compute different address locations.</p>
+<p>If you look at the first indices in these GEP instructions you find that they
+are different (0 and 1), therefore the address computation diverges with that
+index. Consider this example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%MyVar</span> <span class="p">=</span> <span class="k">global</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}</span>
+<span class="nv">%idx1</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+<span class="nv">%idx2</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>In this example, <tt class="docutils literal"><span class="pre">idx1</span></tt> computes the address of the second integer in the
+array that is in the structure in <tt class="docutils literal"><span class="pre">%MyVar</span></tt>, that is <tt class="docutils literal"><span class="pre">MyVar+4</span></tt>. The type of
+<tt class="docutils literal"><span class="pre">idx1</span></tt> is <tt class="docutils literal"><span class="pre">i32*</span></tt>. However, <tt class="docutils literal"><span class="pre">idx2</span></tt> computes the address of <em>the next</em>
+structure after <tt class="docutils literal"><span class="pre">%MyVar</span></tt>. The type of <tt class="docutils literal"><span class="pre">idx2</span></tt> is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">[10</span> <span class="pre">x</span> <span class="pre">i32]</span> <span class="pre">}*</span></tt> and its
+value is equivalent to <tt class="docutils literal"><span class="pre">MyVar</span> <span class="pre">+</span> <span class="pre">40</span></tt> because it indexes past the ten 4-byte
+integers in <tt class="docutils literal"><span class="pre">MyVar</span></tt>. Obviously, in such a situation, the pointers don’t
+alias.</p>
+</div>
+<div class="section" id="why-do-gep-x-1-0-0-and-gep-x-1-alias">
+<h3><a class="toc-backref" href="#id8">Why do GEP x,1,0,0 and GEP x,1 alias?</a><a class="headerlink" href="#why-do-gep-x-1-0-0-and-gep-x-1-alias" title="Permalink to this headline">¶</a></h3>
+<p>Quick Answer: They compute the same address location.</p>
+<p>These two GEP instructions will compute the same address because indexing
+through the 0th element does not change the address. However, it does change the
+type. Consider this example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%MyVar</span> <span class="p">=</span> <span class="k">global</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}</span>
+<span class="nv">%idx1</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span>
+<span class="nv">%idx2</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>In this example, the value of <tt class="docutils literal"><span class="pre">%idx1</span></tt> is <tt class="docutils literal"><span class="pre">%MyVar+40</span></tt> and its type is
+<tt class="docutils literal"><span class="pre">i32*</span></tt>. The value of <tt class="docutils literal"><span class="pre">%idx2</span></tt> is also <tt class="docutils literal"><span class="pre">MyVar+40</span></tt> but its type is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">[10</span> <span class="pre">x</span>
+<span class="pre">i32]</span> <span class="pre">}*</span></tt>.</p>
+</div>
+<div class="section" id="can-gep-index-into-vector-elements">
+<h3><a class="toc-backref" href="#id9">Can GEP index into vector elements?</a><a class="headerlink" href="#can-gep-index-into-vector-elements" title="Permalink to this headline">¶</a></h3>
+<p>This hasn’t always been forcefully disallowed, though it’s not recommended. It
+leads to awkward special cases in the optimizers, and fundamental inconsistency
+in the IR. In the future, it will probably be outright disallowed.</p>
+</div>
+<div class="section" id="what-effect-do-address-spaces-have-on-geps">
+<h3><a class="toc-backref" href="#id10">What effect do address spaces have on GEPs?</a><a class="headerlink" href="#what-effect-do-address-spaces-have-on-geps" title="Permalink to this headline">¶</a></h3>
+<p>None, except that the address space qualifier on the second operand pointer type
+always matches the address space qualifier on the result type.</p>
+</div>
+<div class="section" id="how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr">
+<h3><a class="toc-backref" href="#id11">How is GEP different from <tt class="docutils literal"><span class="pre">ptrtoint</span></tt>, arithmetic, and <tt class="docutils literal"><span class="pre">inttoptr</span></tt>?</a><a class="headerlink" href="#how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr" title="Permalink to this headline">¶</a></h3>
+<p>It’s very similar; there are only subtle differences.</p>
+<p>With ptrtoint, you have to pick an integer type. One approach is to pick i64;
+this is safe on everything LLVM supports (LLVM internally assumes pointers are
+never wider than 64 bits in many places), and the optimizer will actually narrow
+the i64 arithmetic down to the actual pointer size on targets which don’t
+support 64-bit arithmetic in most cases. However, there are some cases where it
+doesn’t do this. With GEP you can avoid this problem.</p>
+<p>Also, GEP carries additional pointer aliasing rules. It’s invalid to take a GEP
+from one object, address into a different separately allocated object, and
+dereference it. IR producers (front-ends) must follow this rule, and consumers
+(optimizers, specifically alias analysis) benefit from being able to rely on
+it. See the <a class="reference internal" href="#rules">Rules</a> section for more information.</p>
+<p>And, GEP is more concise in common cases.</p>
+<p>However, for the underlying integer computation implied, there is no
+difference.</p>
+</div>
+<div class="section" id="i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this">
+<h3><a class="toc-backref" href="#id12">I’m writing a backend for a target which needs custom lowering for GEP. How do I do this?</a><a class="headerlink" href="#i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this" title="Permalink to this headline">¶</a></h3>
+<p>You don’t. The integer computation implied by a GEP is target-independent.
+Typically what you’ll need to do is make your backend pattern-match expressions
+trees involving ADD, MUL, etc., which are what GEP is lowered into. This has the
+advantage of letting your code work correctly in more cases.</p>
+<p>GEP does use target-dependent parameters for the size and layout of data types,
+which targets can customize.</p>
+<p>If you require support for addressing units which are not 8 bits, you’ll need to
+fix a lot of code in the backend, with GEP lowering being only a small piece of
+the overall picture.</p>
+</div>
+<div class="section" id="how-does-vla-addressing-work-with-geps">
+<h3><a class="toc-backref" href="#id13">How does VLA addressing work with GEPs?</a><a class="headerlink" href="#how-does-vla-addressing-work-with-geps" title="Permalink to this headline">¶</a></h3>
+<p>GEPs don’t natively support VLAs. LLVM’s type system is entirely static, and GEP
+address computations are guided by an LLVM type.</p>
+<p>VLA indices can be implemented as linearized indices. For example, an expression
+like <tt class="docutils literal"><span class="pre">X[a][b][c]</span></tt>, must be effectively lowered into a form like
+<tt class="docutils literal"><span class="pre">X[a*m+b*n+c]</span></tt>, so that it appears to the GEP as a single-dimensional array
+reference.</p>
+<p>This means if you want to write an analysis which understands array indices and
+you want to support VLAs, your code will have to be prepared to reverse-engineer
+the linearization. One way to solve this problem is to use the ScalarEvolution
+library, which always presents VLA and non-VLA indexing in the same manner.</p>
+</div>
+</div>
+<div class="section" id="rules">
+<span id="id1"></span><h2><a class="toc-backref" href="#id14">Rules</a><a class="headerlink" href="#rules" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-happens-if-an-array-index-is-out-of-bounds">
+<h3><a class="toc-backref" href="#id15">What happens if an array index is out of bounds?</a><a class="headerlink" href="#what-happens-if-an-array-index-is-out-of-bounds" title="Permalink to this headline">¶</a></h3>
+<p>There are two senses in which an array index can be out of bounds.</p>
+<p>First, there’s the array type which comes from the (static) type of the first
+operand to the GEP. Indices greater than the number of elements in the
+corresponding static array type are valid. There is no problem with out of
+bounds indices in this sense. Indexing into an array only depends on the size of
+the array element, not the number of elements.</p>
+<p>A common example of how this is used is arrays where the size is not known.
+It’s common to use array types with zero length to represent these. The fact
+that the static type says there are zero elements is irrelevant; it’s perfectly
+valid to compute arbitrary element indices, as the computation only depends on
+the size of the array element, not the number of elements. Note that zero-sized
+arrays are not a special case here.</p>
+<p>This sense is unconnected with <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword. The <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword is
+designed to describe low-level pointer arithmetic overflow conditions, rather
+than high-level array indexing rules.</p>
+<p>Analysis passes which wish to understand array indexing should not assume that
+the static array type bounds are respected.</p>
+<p>The second sense of being out of bounds is computing an address that’s beyond
+the actual underlying allocated object.</p>
+<p>With the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the result value of the GEP is undefined if the
+address is outside the actual underlying allocated object and not the address
+one-past-the-end.</p>
+<p>Without the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, there are no restrictions on computing
+out-of-bounds addresses. Obviously, performing a load or a store requires an
+address of allocated and sufficiently aligned memory. But the GEP itself is only
+concerned with computing addresses.</p>
+</div>
+<div class="section" id="can-array-indices-be-negative">
+<h3><a class="toc-backref" href="#id16">Can array indices be negative?</a><a class="headerlink" href="#can-array-indices-be-negative" title="Permalink to this headline">¶</a></h3>
+<p>Yes. This is basically a special case of array indices being out of bounds.</p>
+</div>
+<div class="section" id="can-i-compare-two-values-computed-with-geps">
+<h3><a class="toc-backref" href="#id17">Can I compare two values computed with GEPs?</a><a class="headerlink" href="#can-i-compare-two-values-computed-with-geps" title="Permalink to this headline">¶</a></h3>
+<p>Yes. If both addresses are within the same allocated object, or
+one-past-the-end, you’ll get the comparison result you expect. If either is
+outside of it, integer arithmetic wrapping may occur, so the comparison may not
+be meaningful.</p>
+</div>
+<div class="section" id="can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object">
+<h3><a class="toc-backref" href="#id18">Can I do GEP with a different pointer type than the type of the underlying object?</a><a class="headerlink" href="#can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object" title="Permalink to this headline">¶</a></h3>
+<p>Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
+pointer type. The types in a GEP serve only to define the parameters for the
+underlying integer computation. They need not correspond with the actual type of
+the underlying object.</p>
+<p>Furthermore, loads and stores don’t have to use the same types as the type of
+the underlying object. Types in this context serve only to specify memory size
+and alignment. Beyond that there are merely a hint to the optimizer indicating
+how the value will likely be used.</p>
+</div>
+<div class="section" id="can-i-cast-an-object-s-address-to-integer-and-add-it-to-null">
+<h3><a class="toc-backref" href="#id19">Can I cast an object’s address to integer and add it to null?</a><a class="headerlink" href="#can-i-cast-an-object-s-address-to-integer-and-add-it-to-null" title="Permalink to this headline">¶</a></h3>
+<p>You can compute an address that way, but if you use GEP to do the add, you can’t
+use that pointer to actually access the object, unless the object is managed
+outside of LLVM.</p>
+<p>The underlying integer computation is sufficiently defined; null has a defined
+value — zero — and you can add whatever value you want to it.</p>
+<p>However, it’s invalid to access (load from or store to) an LLVM-aware object
+with such a pointer. This includes <tt class="docutils literal"><span class="pre">GlobalVariables</span></tt>, <tt class="docutils literal"><span class="pre">Allocas</span></tt>, and objects
+pointed to by noalias pointers.</p>
+<p>If you really need this functionality, you can do the arithmetic with explicit
+integer instructions, and use inttoptr to convert the result to an address. Most
+of GEP’s special aliasing rules do not apply to pointers computed from ptrtoint,
+arithmetic, and inttoptr sequences.</p>
+</div>
+<div class="section" id="can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address">
+<h3><a class="toc-backref" href="#id20">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a><a class="headerlink" href="#can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address" title="Permalink to this headline">¶</a></h3>
+<p>As with arithmetic on null, you can use GEP to compute an address that way, but
+you can’t use that pointer to actually access the object if you do, unless the
+object is managed outside of LLVM.</p>
+<p>Also as above, ptrtoint and inttoptr provide an alternative way to do this which
+do not have this restriction.</p>
+</div>
+<div class="section" id="can-i-do-type-based-alias-analysis-on-llvm-ir">
+<h3><a class="toc-backref" href="#id21">Can I do type-based alias analysis on LLVM IR?</a><a class="headerlink" href="#can-i-do-type-based-alias-analysis-on-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<p>You can’t do type-based alias analysis using LLVM’s built-in type system,
+because LLVM has no restrictions on mixing types in addressing, loads or stores.</p>
+<p>LLVM’s type-based alias analysis pass uses metadata to describe a different type
+system (such as the C type system), and performs type-based aliasing on top of
+that. Further details are in the
+<a class="reference external" href="LangRef.html#tbaa-metadata">language reference</a>.</p>
+</div>
+<div class="section" id="what-happens-if-a-gep-computation-overflows">
+<h3><a class="toc-backref" href="#id22">What happens if a GEP computation overflows?</a><a class="headerlink" href="#what-happens-if-a-gep-computation-overflows" title="Permalink to this headline">¶</a></h3>
+<p>If the GEP lacks the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the value is the result from
+evaluating the implied two’s complement integer computation. However, since
+there’s no guarantee of where an object will be allocated in the address space,
+such values have limited meaning.</p>
+<p>If the GEP has the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the result value is undefined (a “trap
+value”) if the GEP overflows (i.e. wraps around the end of the address space).</p>
+<p>As such, there are some ramifications of this for inbounds GEPs: scales implied
+by array/vector/pointer indices are always known to be “nsw” since they are
+signed values that are scaled by the element size. These values are also
+allowed to be negative (e.g. “<tt class="docutils literal"><span class="pre">gep</span> <span class="pre">i32</span> <span class="pre">*%P,</span> <span class="pre">i32</span> <span class="pre">-1</span></tt>”) but the pointer itself
+is logically treated as an unsigned value. This means that GEPs have an
+asymmetric relation between the pointer base (which is treated as unsigned) and
+the offset applied to it (which is treated as signed). The result of the
+additions within the offset calculation cannot have signed overflow, but when
+applied to the base pointer, there can be signed overflow.</p>
+</div>
+<div class="section" id="how-can-i-tell-if-my-front-end-is-following-the-rules">
+<h3><a class="toc-backref" href="#id23">How can I tell if my front-end is following the rules?</a><a class="headerlink" href="#how-can-i-tell-if-my-front-end-is-following-the-rules" title="Permalink to this headline">¶</a></h3>
+<p>There is currently no checker for the getelementptr rules. Currently, the only
+way to do this is to manually check each place in your front-end where
+GetElementPtr operators are created.</p>
+<p>It’s not possible to write a checker which could find all rule violations
+statically. It would be possible to write a checker which works by instrumenting
+the code with dynamic checks though. Alternatively, it would be possible to
+write a static checker which catches a subset of possible problems. However, no
+such checker exists today.</p>
+</div>
+</div>
+<div class="section" id="rationale">
+<h2><a class="toc-backref" href="#id24">Rationale</a><a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="why-is-gep-designed-this-way">
+<h3><a class="toc-backref" href="#id25">Why is GEP designed this way?</a><a class="headerlink" href="#why-is-gep-designed-this-way" title="Permalink to this headline">¶</a></h3>
+<p>The design of GEP has the following goals, in rough unofficial order of
+priority:</p>
+<ul class="simple">
+<li>Support C, C-like languages, and languages which can be conceptually lowered
+into C (this covers a lot).</li>
+<li>Support optimizations such as those that are common in C compilers. In
+particular, GEP is a cornerstone of LLVM’s <a class="reference external" href="LangRef.html#pointeraliasing">pointer aliasing
+model</a>.</li>
+<li>Provide a consistent method for computing addresses so that address
+computations don’t need to be a part of load and store instructions in the IR.</li>
+<li>Support non-C-like languages, to the extent that it doesn’t interfere with
+other goals.</li>
+<li>Minimize target-specific information in the IR.</li>
+</ul>
+</div>
+<div class="section" id="why-do-struct-member-indices-always-use-i32">
+<h3><a class="toc-backref" href="#id26">Why do struct member indices always use <tt class="docutils literal"><span class="pre">i32</span></tt>?</a><a class="headerlink" href="#why-do-struct-member-indices-always-use-i32" title="Permalink to this headline">¶</a></h3>
+<p>The specific type i32 is probably just a historical artifact, however it’s wide
+enough for all practical purposes, so there’s been no need to change it. It
+doesn’t necessarily imply i32 address arithmetic; it’s just an identifier which
+identifies a field in a struct. Requiring that all struct indices be the same
+reduces the range of possibilities for cases where two GEPs are effectively the
+same but have distinct operand types.</p>
+</div>
+<div class="section" id="what-s-an-uglygep">
+<h3><a class="toc-backref" href="#id27">What’s an uglygep?</a><a class="headerlink" href="#what-s-an-uglygep" title="Permalink to this headline">¶</a></h3>
+<p>Some LLVM optimizers operate on GEPs by internally lowering them into more
+primitive integer expressions, which allows them to be combined with other
+integer expressions and/or split into multiple separate integer expressions. If
+they’ve made non-trivial changes, translating back into LLVM IR can involve
+reverse-engineering the structure of the addressing in order to fit it into the
+static type of the original first operand. It isn’t always possibly to fully
+reconstruct this structure; sometimes the underlying addressing doesn’t
+correspond with the static type at all. In such cases the optimizer instead will
+emit a GEP with the base pointer casted to a simple address-unit pointer, using
+the name “uglygep”. This isn’t pretty, but it’s just as valid, and it’s
+sufficient to preserve the pointer aliasing guarantees that GEP provides.</p>
+</div>
+</div>
+<div class="section" id="summary">
+<h2><a class="toc-backref" href="#id28">Summary</a><a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2>
+<p>In summary, here’s some things to always remember about the GetElementPtr
+instruction:</p>
+<ol class="arabic simple">
+<li>The GEP instruction never accesses memory, it only provides pointer
+computations.</li>
+<li>The second operand to the GEP instruction is always a pointer and it must be
+indexed.</li>
+<li>There are no superfluous indices for the GEP instruction.</li>
+<li>Trailing zero indices are superfluous for pointer aliasing, but not for the
+types of the pointers.</li>
+<li>Leading zero indices are not superfluous for pointer aliasing nor the types
+of the pointers.</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="YamlIO.html" title="YAML I/O"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/GettingStarted.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/GettingStarted.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/GettingStarted.html (added)
+++ www-releases/trunk/5.0.2/docs/GettingStarted.html Thu May 10 06:54:16 2018
@@ -0,0 +1,1377 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Getting Started with the LLVM System — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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="id4">Overview</a></li>
+<li><a class="reference internal" href="#getting-started-quickly-a-summary" id="id5">Getting Started Quickly (A Summary)</a></li>
+<li><a class="reference internal" href="#requirements" id="id6">Requirements</a><ul>
+<li><a class="reference internal" href="#hardware" id="id7">Hardware</a></li>
+<li><a class="reference internal" href="#software" id="id8">Software</a></li>
+<li><a class="reference internal" href="#host-c-toolchain-both-compiler-and-standard-library" id="id9">Host C++ Toolchain, both Compiler and Standard Library</a><ul>
+<li><a class="reference internal" href="#getting-a-modern-host-c-toolchain" id="id10">Getting a Modern Host C++ Toolchain</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#getting-started-with-llvm" id="id11">Getting Started with LLVM</a><ul>
+<li><a class="reference internal" href="#terminology-and-notation" id="id12">Terminology and Notation</a></li>
+<li><a class="reference internal" href="#unpacking-the-llvm-archives" id="id13">Unpacking the LLVM Archives</a></li>
+<li><a class="reference internal" href="#checkout-llvm-from-subversion" id="id14">Checkout LLVM from Subversion</a></li>
+<li><a class="reference internal" href="#git-mirror" id="id15">Git Mirror</a><ul>
+<li><a class="reference internal" href="#sending-patches-with-git" id="id16">Sending patches with Git</a></li>
+<li><a class="reference internal" href="#for-developers-to-work-with-git-svn" id="id17">For developers to work with git-svn</a></li>
+<li><a class="reference internal" href="#for-developers-to-work-with-a-git-monorepo" id="id18">For developers to work with a git monorepo</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#local-llvm-configuration" id="id19">Local LLVM Configuration</a></li>
+<li><a class="reference internal" href="#compiling-the-llvm-suite-source-code" id="id20">Compiling the LLVM Suite Source Code</a></li>
+<li><a class="reference internal" href="#cross-compiling-llvm" id="id21">Cross-Compiling LLVM</a></li>
+<li><a class="reference internal" href="#the-location-of-llvm-object-files" id="id22">The Location of LLVM Object Files</a></li>
+<li><a class="reference internal" href="#optional-configuration-items" id="id23">Optional Configuration Items</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#directory-layout" id="id24">Directory Layout</a><ul>
+<li><a class="reference internal" href="#llvm-examples" id="id25"><tt class="docutils literal"><span class="pre">llvm/examples</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-include" id="id26"><tt class="docutils literal"><span class="pre">llvm/include</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-lib" id="id27"><tt class="docutils literal"><span class="pre">llvm/lib</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-projects" id="id28"><tt class="docutils literal"><span class="pre">llvm/projects</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-test" id="id29"><tt class="docutils literal"><span class="pre">llvm/test</span></tt></a></li>
+<li><a class="reference internal" href="#test-suite" id="id30"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-tools" id="id31"><tt class="docutils literal"><span class="pre">llvm/tools</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-utils" id="id32"><tt class="docutils literal"><span class="pre">llvm/utils</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#an-example-using-the-llvm-tool-chain" id="id33">An Example Using the LLVM Tool Chain</a><ul>
+<li><a class="reference internal" href="#example-with-clang" id="id34">Example with clang</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#common-problems" id="id35">Common Problems</a></li>
+<li><a class="reference internal" href="#links" id="id36">Links</a></li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id4">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to LLVM! In order to get started, you first need to know some basic
+information.</p>
+<p>First, LLVM comes in three pieces. 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. Once compiled into LLVM bitcode, a program can be manipulated with the
+LLVM tools from the LLVM suite.</p>
+<p>There is a third, optional piece called Test Suite. It is a suite of programs
+with a testing harness that can be used to further test LLVM’s functionality
+and performance.</p>
+</div>
+<div class="section" id="getting-started-quickly-a-summary">
+<h2><a class="toc-backref" href="#id5">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>
+<ul class="simple">
+<li>In particular, the <em>relative paths specified are important</em>.</li>
+</ul>
+</li>
+<li><p class="first">Checkout LLVM:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><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></tt></li>
+</ul>
+</li>
+<li><p class="first">Checkout Clang:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/cfe/trunk</span> <span class="pre">clang</span></tt></li>
+</ul>
+</li>
+<li><p class="first">Checkout LLD linker <strong>[Optional]</strong>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/lld/trunk</span> <span class="pre">lld</span></tt></li>
+</ul>
+</li>
+<li><p class="first">Checkout Polly Loop Optimizer <strong>[Optional]</strong>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/polly/trunk</span> <span class="pre">polly</span></tt></li>
+</ul>
+</li>
+<li><p class="first">Checkout Compiler-RT (required to build the sanitizers) <strong>[Optional]</strong>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/projects</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/compiler-rt/trunk</span> <span class="pre">compiler-rt</span></tt></li>
+</ul>
+</li>
+<li><p class="first">Checkout Libomp (required for OpenMP support) <strong>[Optional]</strong>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/projects</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/openmp/trunk</span> <span class="pre">openmp</span></tt></li>
+</ul>
+</li>
+<li><p class="first">Checkout libcxx and libcxxabi <strong>[Optional]</strong>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/projects</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/libcxx/trunk</span> <span class="pre">libcxx</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/libcxxabi/trunk</span> <span class="pre">libcxxabi</span></tt></li>
+</ul>
+</li>
+<li><p class="first">Get the Test Suite Source Code <strong>[Optional]</strong></p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/projects</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/test-suite/trunk</span> <span class="pre">test-suite</span></tt></li>
+</ul>
+</li>
+<li><p class="first">Configure and build LLVM and Clang:</p>
+<p><em>Warning:</em> Make sure you’ve checked out <em>all of</em> the source code
+before trying to configure with cmake. cmake does not pickup newly
+added source directories in incremental builds.</p>
+<p>The build uses <a class="reference external" href="CMake.html">CMake</a>. LLVM requires CMake 3.4.3 to build. It
+is generally recommended to use a recent CMake, especially if you’re
+generating Ninja build files. This is because the CMake project is constantly
+improving the quality of the generators, and the Ninja generator gets a lot
+of attention.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where</span> <span class="pre">you</span> <span class="pre">want</span> <span class="pre">to</span> <span class="pre">build</span> <span class="pre">llvm</span></tt></p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">mkdir</span> <span class="pre">build</span></tt></p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">build</span></tt></p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">cmake</span> <span class="pre">-G</span> <span class="pre"><generator></span> <span class="pre">[options]</span> <span class="pre"><path</span> <span class="pre">to</span> <span class="pre">llvm</span> <span class="pre">sources></span></tt></p>
+<p>Some common generators are:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">Unix</span> <span class="pre">Makefiles</span></tt> — for generating make-compatible parallel makefiles.</li>
+<li><tt class="docutils literal"><span class="pre">Ninja</span></tt> — for generating <a class="reference external" href="https://ninja-build.org">Ninja</a>
+build files. Most llvm developers use Ninja.</li>
+<li><tt class="docutils literal"><span class="pre">Visual</span> <span class="pre">Studio</span></tt> — for generating Visual Studio projects and
+solutions.</li>
+<li><tt class="docutils literal"><span class="pre">Xcode</span></tt> — for generating Xcode projects.</li>
+</ul>
+<p>Some Common options:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_INSTALL_PREFIX=directory</span></tt> — Specify for <em>directory</em> the full
+pathname of where you want the LLVM tools and libraries to be installed
+(default <tt class="docutils literal"><span class="pre">/usr/local</span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_BUILD_TYPE=type</span></tt> — Valid options for <em>type</em> are Debug,
+Release, RelWithDebInfo, and MinSizeRel. Default is Debug.</li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_ENABLE_ASSERTIONS=On</span></tt> — Compile with assertion checks enabled
+(default is Yes for Debug builds, No for all other build types).</li>
+</ul>
+</li>
+<li><p class="first">Run your build tool of choice!</p>
+<ul class="simple">
+<li>The default target (i.e. <tt class="docutils literal"><span class="pre">make</span></tt>) will build all of LLVM</li>
+<li>The <tt class="docutils literal"><span class="pre">check-all</span></tt> target (i.e. <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt>) 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 <tt class="docutils literal"><span class="pre">check-<project></span></tt> target.</li>
+<li>Running a serial build will be <em>slow</em>. Make sure you run a
+parallel build; for <tt class="docutils literal"><span class="pre">make</span></tt>, use <tt class="docutils literal"><span class="pre">make</span> <span class="pre">-j</span></tt>.</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="#id6">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="#id7">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<sup>4</sup></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 <tt class="docutils literal"><span class="pre">-DBUILD_SHARED_LIBS=On</span></tt>.</li>
+<li>MCJIT not working well pre-v7, old JIT engine not supported any more.</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 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="#id8">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>>=4.8.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
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> 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="#id9">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 are also planning 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>For the most popular host toolchains we check for specific minimum versions in
+our build systems:</p>
+<ul class="simple">
+<li>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 “<tt class="docutils literal"><span class="pre">.gnu.linkonce.t.*</span></tt>” 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="#id10">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 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="http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal">ask ubuntu stack exchange</a>. 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 4.8.2:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
+<span class="gp">%</span> wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.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-4.8.2.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="k">then </span><span class="nb">echo</span> <span class="s2">"Invalid signature"</span> ; <span class="nb">exit </span>1 ; <span class="k">fi</span>
+<span class="gp">%</span><span class="k"> </span>tar -xvjf gcc-4.8.2.tar.bz2
+<span class="gp">%</span> <span class="nb">cd </span>gcc-4.8.2
+<span class="gp">%</span> ./contrib/download_prerequisites
+<span class="gp">%</span> <span class="nb">cd</span> ..
+<span class="gp">%</span> mkdir gcc-4.8.2-build
+<span class="gp">%</span> <span class="nb">cd </span>gcc-4.8.2-build
+<span class="gp">%</span> <span class="nv">$PWD</span>/../gcc-4.8.2/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="http://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 (<tt class="docutils literal"><span class="pre">-L</span></tt>) and at runtime
+(<tt class="docutils literal"><span class="pre">-rpath</span></tt>). If you are using CMake, this invocation should produce working
+binaries:</p>
+<div class="highlight-console"><div class="highlight"><pre><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>
+<span class="go"> cmake .. -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/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 <tt class="docutils literal"><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></tt>. 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++11
+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 <tt class="docutils literal"><span class="pre">-stdlib=libc++</span></tt> compile and link flag,
+or install Clang into the same prefix (<tt class="docutils literal"><span class="pre">$HOME/toolchains</span></tt> 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 <tt class="docutils literal"><span class="pre">--gcc-toolchain=/opt/my/gcc/prefix</span></tt> 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="id2"></span><h2><a class="toc-backref" href="#id11">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="#id12">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><tt class="docutils literal"><span class="pre">SRC_ROOT</span></tt></p>
+<blockquote>
+<div>This is the top level directory of the LLVM source tree.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">OBJ_ROOT</span></tt></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="#id13">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 set of two files: the LLVM suite
+and the LLVM GCC front end compiled for your platform. There is an additional
+test suite that is optional. Each file 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><tt class="docutils literal"><span class="pre">llvm-x.y.tar.gz</span></tt></p>
+<blockquote>
+<div>Source release for the LLVM libraries and tools.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-test-x.y.tar.gz</span></tt></p>
+<blockquote>
+<div>Source release for the LLVM test-suite.</div></blockquote>
+</div>
+<div class="section" id="checkout-llvm-from-subversion">
+<span id="checkout"></span><h3><a class="toc-backref" href="#id14">Checkout LLVM from Subversion</a><a class="headerlink" href="#checkout-llvm-from-subversion" title="Permalink to this headline">¶</a></h3>
+<p>If you have access to our Subversion repository, you can get a fresh copy of the
+entire source code. All you need to do is check it out from Subversion as
+follows:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li>Read-Only: <tt class="docutils literal"><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></tt></li>
+<li>Read-Write: <tt class="docutils literal"><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></tt></li>
+</ul>
+<p>This will create an ‘<tt class="docutils literal"><span class="pre">llvm</span></tt>‘ 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 checkout it from the ‘<tt class="docutils literal"><span class="pre">tags</span></tt>‘ directory (instead of ‘<tt class="docutils literal"><span class="pre">trunk</span></tt>‘). The
+following releases are located in the following subdirectories of the ‘<tt class="docutils literal"><span class="pre">tags</span></tt>‘
+directory:</p>
+<ul class="simple">
+<li>Release 3.4: <strong>RELEASE_34/final</strong></li>
+<li>Release 3.3: <strong>RELEASE_33/final</strong></li>
+<li>Release 3.2: <strong>RELEASE_32/final</strong></li>
+<li>Release 3.1: <strong>RELEASE_31/final</strong></li>
+<li>Release 3.0: <strong>RELEASE_30/final</strong></li>
+<li>Release 2.9: <strong>RELEASE_29/final</strong></li>
+<li>Release 2.8: <strong>RELEASE_28</strong></li>
+<li>Release 2.7: <strong>RELEASE_27</strong></li>
+<li>Release 2.6: <strong>RELEASE_26</strong></li>
+<li>Release 2.5: <strong>RELEASE_25</strong></li>
+<li>Release 2.4: <strong>RELEASE_24</strong></li>
+<li>Release 2.3: <strong>RELEASE_23</strong></li>
+<li>Release 2.2: <strong>RELEASE_22</strong></li>
+<li>Release 2.1: <strong>RELEASE_21</strong></li>
+<li>Release 2.0: <strong>RELEASE_20</strong></li>
+<li>Release 1.9: <strong>RELEASE_19</strong></li>
+<li>Release 1.8: <strong>RELEASE_18</strong></li>
+<li>Release 1.7: <strong>RELEASE_17</strong></li>
+<li>Release 1.6: <strong>RELEASE_16</strong></li>
+<li>Release 1.5: <strong>RELEASE_15</strong></li>
+<li>Release 1.4: <strong>RELEASE_14</strong></li>
+<li>Release 1.3: <strong>RELEASE_13</strong></li>
+<li>Release 1.2: <strong>RELEASE_12</strong></li>
+<li>Release 1.1: <strong>RELEASE_11</strong></li>
+<li>Release 1.0: <strong>RELEASE_1</strong></li>
+</ul>
+<p>If you would like to get the LLVM test suite (a separate package as of 1.4), you
+get it from the Subversion repository:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/projects
+<span class="gp">%</span> svn co http://llvm.org/svn/llvm-project/test-suite/trunk <span class="nb">test</span>-suite
+</pre></div>
+</div>
+<p>By placing it in the <tt class="docutils literal"><span class="pre">llvm/projects</span></tt>, it will be automatically configured by
+the LLVM cmake configuration.</p>
+</div>
+<div class="section" id="git-mirror">
+<h3><a class="toc-backref" href="#id15">Git Mirror</a><a class="headerlink" href="#git-mirror" title="Permalink to this headline">¶</a></h3>
+<p>Git mirrors are available for a number of LLVM subprojects. These mirrors sync
+automatically with each Subversion commit and contain all necessary git-svn
+marks (so, you can recreate git-svn metadata locally). Note that right now
+mirrors reflect only <tt class="docutils literal"><span class="pre">trunk</span></tt> for each project. You can do the read-only Git
+clone of LLVM via:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git clone http://llvm.org/git/llvm.git
+</pre></div>
+</div>
+<p>If you want to check out clang too, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/tools
+<span class="gp">%</span> git clone http://llvm.org/git/clang.git
+</pre></div>
+</div>
+<p>If you want to check out compiler-rt (required to build the sanitizers), run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/projects
+<span class="gp">%</span> git clone http://llvm.org/git/compiler-rt.git
+</pre></div>
+</div>
+<p>If you want to check out libomp (required for OpenMP support), run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/projects
+<span class="gp">%</span> git clone http://llvm.org/git/openmp.git
+</pre></div>
+</div>
+<p>If you want to check out libcxx and libcxxabi (optional), run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/projects
+<span class="gp">%</span> git clone http://llvm.org/git/libcxx.git
+<span class="gp">%</span> git clone http://llvm.org/git/libcxxabi.git
+</pre></div>
+</div>
+<p>If you want to check out the Test Suite Source Code (optional), run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/projects
+<span class="gp">%</span> git clone http://llvm.org/git/test-suite.git
+</pre></div>
+</div>
+<p>Since the upstream repository is in Subversion, you should use <tt class="docutils literal"><span class="pre">git</span>
+<span class="pre">pull</span> <span class="pre">--rebase</span></tt> instead of <tt class="docutils literal"><span class="pre">git</span> <span class="pre">pull</span></tt> to avoid generating a non-linear history
+in your clone. To configure <tt class="docutils literal"><span class="pre">git</span> <span class="pre">pull</span></tt> to pass <tt class="docutils literal"><span class="pre">--rebase</span></tt> by default on the
+master branch, run the following command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git config branch.master.rebase <span class="nb">true</span>
+</pre></div>
+</div>
+<div class="section" id="sending-patches-with-git">
+<h4><a class="toc-backref" href="#id16">Sending patches with Git</a><a class="headerlink" href="#sending-patches-with-git" 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>Assume <tt class="docutils literal"><span class="pre">master</span></tt> points the upstream and <tt class="docutils literal"><span class="pre">mybranch</span></tt> points your working
+branch, and <tt class="docutils literal"><span class="pre">mybranch</span></tt> is rebased onto <tt class="docutils literal"><span class="pre">master</span></tt>. At first you may check
+sanity of whitespaces:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git diff --check master..mybranch
+</pre></div>
+</div>
+<p>The easiest way to generate a patch is as below:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git diff master..mybranch > /path/to/mybranch.diff
+</pre></div>
+</div>
+<p>It is a little different from svn-generated diff. git-diff-generated diff has
+prefixes like <tt class="docutils literal"><span class="pre">a/</span></tt> and <tt class="docutils literal"><span class="pre">b/</span></tt>. Don’t worry, most developers might know it
+could be accepted with <tt class="docutils literal"><span class="pre">patch</span> <span class="pre">-p1</span> <span class="pre">-N</span></tt>.</p>
+<p>But you may generate patchset with git-format-patch. It generates by-each-commit
+patchset. To generate patch files to attach to your article:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git format-patch --no-attach master..mybranch -o /path/to/your/patchset
+</pre></div>
+</div>
+<p>If you would like to send patches directly, you may use git-send-email or
+git-imap-send. Here is an example to generate the patchset in Gmail’s [Drafts].</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git format-patch --attach master..mybranch --stdout | git imap-send
+</pre></div>
+</div>
+<p>Then, your .git/config should have [imap] sections.</p>
+<div class="highlight-ini"><div class="highlight"><pre><span class="k">[imap]</span>
+ <span class="na">host</span> <span class="o">=</span> <span class="s">imaps://imap.gmail.com</span>
+<span class="s"> user = your.gmail.account at gmail.com</span>
+<span class="s"> pass = himitsu!</span>
+<span class="s"> port = 993</span>
+<span class="s"> sslverify = false</span>
+<span class="c">; in English</span>
+ <span class="na">folder</span> <span class="o">=</span> <span class="s">"[Gmail]/Drafts"</span>
+<span class="c">; example for Japanese, "Modified UTF-7" encoded.</span>
+ <span class="na">folder</span> <span class="o">=</span> <span class="s">"[Gmail]/&Tgtm+DBN-"</span>
+<span class="c">; example for Traditional Chinese</span>
+ <span class="na">folder</span> <span class="o">=</span> <span class="s">"[Gmail]/&g0l6Pw-"</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="for-developers-to-work-with-git-svn">
+<span id="developers-work-with-git-svn"></span><h4><a class="toc-backref" href="#id17">For developers to work with git-svn</a><a class="headerlink" href="#for-developers-to-work-with-git-svn" title="Permalink to this headline">¶</a></h4>
+<p>To set up clone from which you can submit code using <tt class="docutils literal"><span class="pre">git-svn</span></tt>, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git clone http://llvm.org/git/llvm.git
+<span class="gp">%</span> <span class="nb">cd </span>llvm
+<span class="gp">%</span> git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username<span class="o">=</span><username>
+<span class="gp">%</span> git config svn-remote.svn.fetch :refs/remotes/origin/master
+<span class="gp">%</span> git svn rebase -l <span class="c"># -l avoids fetching ahead of the git mirror.</span>
+
+<span class="gp">#</span> If you have clang too:
+<span class="gp">%</span> <span class="nb">cd </span>tools
+<span class="gp">%</span> git clone http://llvm.org/git/clang.git
+<span class="gp">%</span> <span class="nb">cd </span>clang
+<span class="gp">%</span> git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username<span class="o">=</span><username>
+<span class="gp">%</span> git config svn-remote.svn.fetch :refs/remotes/origin/master
+<span class="gp">%</span> git svn rebase -l
+</pre></div>
+</div>
+<p>Likewise for compiler-rt, libomp and test-suite.</p>
+<p>To update this clone without generating git-svn tags that conflict with the
+upstream Git repo, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git fetch <span class="o">&&</span> <span class="o">(</span><span class="nb">cd </span>tools/clang <span class="o">&&</span> git fetch<span class="o">)</span> <span class="c"># Get matching revisions of both trees.</span>
+<span class="gp">%</span> git checkout master
+<span class="gp">%</span> git svn rebase -l
+<span class="gp">%</span> <span class="o">(</span><span class="nb">cd </span>tools/clang <span class="o">&&</span>
+<span class="go"> git checkout master &&</span>
+<span class="go"> git svn rebase -l)</span>
+</pre></div>
+</div>
+<p>Likewise for compiler-rt, libomp and test-suite.</p>
+<p>This leaves your working directories on their master branches, so you’ll need to
+<tt class="docutils literal"><span class="pre">checkout</span></tt> each working branch individually and <tt class="docutils literal"><span class="pre">rebase</span></tt> it on top of its
+parent branch.</p>
+<p>For those who wish to be able to update an llvm repo/revert patches easily using
+git-svn, please look in the directory for the scripts <tt class="docutils literal"><span class="pre">git-svnup</span></tt> and
+<tt class="docutils literal"><span class="pre">git-svnrevert</span></tt>.</p>
+<p>To perform the aforementioned update steps go into your source directory and
+just type <tt class="docutils literal"><span class="pre">git-svnup</span></tt> or <tt class="docutils literal"><span class="pre">git</span> <span class="pre">svnup</span></tt> and everything will just work.</p>
+<p>If one wishes to revert a commit with git-svn, but do not want the git hash to
+escape into the commit message, one can use the script <tt class="docutils literal"><span class="pre">git-svnrevert</span></tt> or
+<tt class="docutils literal"><span class="pre">git</span> <span class="pre">svnrevert</span></tt> which will take in the git hash for the commit you want to
+revert, look up the appropriate svn revision, and output a message where all
+references to the git hash have been replaced with the svn revision.</p>
+<p>To commit back changes via git-svn, use <tt class="docutils literal"><span class="pre">git</span> <span class="pre">svn</span> <span class="pre">dcommit</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git svn dcommit
+</pre></div>
+</div>
+<p>Note that git-svn will create one SVN commit for each Git commit you have pending,
+so squash and edit each commit before executing <tt class="docutils literal"><span class="pre">dcommit</span></tt> to make sure they all
+conform to the coding standards and the developers’ policy.</p>
+<p>On success, <tt class="docutils literal"><span class="pre">dcommit</span></tt> will rebase against the HEAD of SVN, so to avoid conflict,
+please make sure your current branch is up-to-date (via fetch/rebase) before
+proceeding.</p>
+<p>The git-svn metadata can get out of sync after you mess around with branches and
+<tt class="docutils literal"><span class="pre">dcommit</span></tt>. When that happens, <tt class="docutils literal"><span class="pre">git</span> <span class="pre">svn</span> <span class="pre">dcommit</span></tt> stops working, complaining
+about files with uncommitted changes. The fix is to rebuild the metadata:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> rm -rf .git/svn
+<span class="gp">%</span> git svn rebase -l
+</pre></div>
+</div>
+<p>Please, refer to the Git-SVN manual (<tt class="docutils literal"><span class="pre">man</span> <span class="pre">git-svn</span></tt>) for more information.</p>
+</div>
+<div class="section" id="for-developers-to-work-with-a-git-monorepo">
+<h4><a class="toc-backref" href="#id18">For developers to work with a git monorepo</a><a class="headerlink" href="#for-developers-to-work-with-a-git-monorepo" title="Permalink to this headline">¶</a></h4>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This set-up is using an unofficial mirror hosted on GitHub, use with caution.</p>
+</div>
+<p>To set up a clone of all the llvm projects using a unified repository:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">export </span><span class="nv">TOP_LEVEL_DIR</span><span class="o">=</span><span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span>
+<span class="gp">%</span> git clone https://github.com/llvm-project/llvm-project-20170507/ llvm-project
+<span class="gp">%</span> <span class="nb">cd </span>llvm-project
+<span class="gp">%</span> git config branch.master.rebase <span class="nb">true</span>
+</pre></div>
+</div>
+<p>You can configure various build directory from this clone, starting with a build
+of LLVM alone:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd</span> <span class="nv">$TOP_LEVEL_DIR</span>
+<span class="gp">%</span> mkdir llvm-build <span class="o">&&</span> <span class="nb">cd </span>llvm-build
+<span class="gp">%</span> cmake -GNinja ../llvm-project/llvm
+</pre></div>
+</div>
+<p>Or lldb:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd</span> <span class="nv">$TOP_LEVEL_DIR</span>
+<span class="gp">%</span> mkdir lldb-build <span class="o">&&</span> <span class="nb">cd </span>lldb-build
+<span class="gp">%</span> cmake -GNinja ../llvm-project/llvm -DLLVM_ENABLE_PROJECTS<span class="o">=</span>lldb
+</pre></div>
+</div>
+<p>Or a combination of multiple projects:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd</span> <span class="nv">$TOP_LEVEL_DIR</span>
+<span class="gp">%</span> mkdir clang-build <span class="o">&&</span> <span class="nb">cd </span>clang-build
+<span class="gp">%</span> cmake -GNinja ../llvm-project/llvm -DLLVM_ENABLE_PROJECTS<span class="o">=</span><span class="s2">"clang;libcxx;libcxxabi"</span>
+</pre></div>
+</div>
+<p>A helper script is provided in <tt class="docutils literal"><span class="pre">llvm/utils/git-svn/git-llvm</span></tt>. After you add it
+to your path, you can push committed changes upstream with <tt class="docutils literal"><span class="pre">git</span> <span class="pre">llvm</span> <span class="pre">push</span></tt>.</p>
+<div class="highlight-console"><div class="highlight"><pre><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>While this is using SVN under the hood, it does not require any interaction from
+you with git-svn.
+After a few minutes, <tt class="docutils literal"><span class="pre">git</span> <span class="pre">pull</span></tt> should get back the changes as they were
+committed. Note that a current limitation is that <tt class="docutils literal"><span class="pre">git</span></tt> does not directly
+record file rename, and thus it is propagated to SVN as a combination of
+delete-add instead of a file rename.</p>
+<p>The SVN revision of each monorepo commit can be found in the commit notes. git
+does not fetch notes by default. The following commands will fetch the notes and
+configure git to fetch future notes. Use <tt class="docutils literal"><span class="pre">git</span> <span class="pre">notes</span> <span class="pre">show</span> <span class="pre">$commit</span></tt> to look up
+the SVN revision of a git commit. The notes show up <tt class="docutils literal"><span class="pre">git</span> <span class="pre">log</span></tt>, and searching
+the log is currently the recommended way to look up the git commit for a given
+SVN revision.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git config --add remote.origin.fetch +refs/notes/commits:refs/notes/commits
+<span class="gp">%</span> git fetch
+</pre></div>
+</div>
+<p>If you are using <cite>arc</cite> to interact with Phabricator, you need to manually put it
+at the root of the checkout:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd</span> <span class="nv">$TOP_LEVEL_DIR</span>
+<span class="gp">%</span> cp llvm/.arcconfig ./
+<span class="gp">%</span> mkdir -p .git/info/
+<span class="gp">%</span> <span class="nb">echo</span> .arcconfig >> .git/info/exclude
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="local-llvm-configuration">
+<h3><a class="toc-backref" href="#id19">Local LLVM Configuration</a><a class="headerlink" href="#local-llvm-configuration" title="Permalink to this headline">¶</a></h3>
+<p>Once checked out from the Subversion repository, the LLVM suite source code must
+be configured before being built. This process uses CMake.
+Unlinke the normal <tt class="docutils literal"><span class="pre">configure</span></tt> script, CMake
+generates the build files in whatever format you request as well as various
+<tt class="docutils literal"><span class="pre">*.inc</span></tt> files, and <tt class="docutils literal"><span class="pre">llvm/include/Config/config.h</span></tt>.</p>
+<p>Variables are passed to <tt class="docutils literal"><span class="pre">cmake</span></tt> on the command line using the format
+<tt class="docutils literal"><span class="pre">-D<variable</span> <span class="pre">name>=<value></span></tt>. 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 <tt class="docutils literal"><span class="pre">cmake</span></tt> 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 <tt class="docutils literal"><span class="pre">cmake</span></tt> 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 <tt class="docutils literal"><span class="pre">cmake</span></tt> 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 llc. This is
+equivalent to the <tt class="docutils literal"><span class="pre">--enable-targets</span></tt> option in
+the configure script. The default list is defined
+as <tt class="docutils literal"><span class="pre">LLVM_ALL_TARGETS</span></tt>, and can be set to include
+out-of-tree targets. The default value includes:
+<tt class="docutils literal"><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></tt>.</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_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-odd"><td>LLVM_BUILD_LLVM_DYLIB</td>
+<td>Generate libLLVM.so. This library contains a
+default set of LLVM components that can be
+overridden with <tt class="docutils literal"><span class="pre">LLVM_DYLIB_COMPONENTS</span></tt>. The
+default contains most of LLVM and is defined in
+<tt class="docutils literal"><span class="pre">tools/llvm-shlib/CMakelists.txt</span></tt>.</td>
+</tr>
+<tr class="row-even"><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"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>OBJ_ROOT
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the <tt class="docutils literal"><span class="pre">cmake</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cmake -G <span class="s2">"Unix Makefiles"</span> -DCMAKE_INSTALL_PREFIX<span class="o">=</span><span class="nv">prefix</span><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="#id20">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"><div class="highlight"><pre><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
+<tt class="docutils literal"><span class="pre">CMAKE_CXX_FLAGS_RELEASE</span></tt> 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 <tt class="docutils literal"><span class="pre">CMAKE_CXX_FLAGS_RELWITHDEBINFO</span></tt> 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"><div class="highlight"><pre><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"><div class="highlight"><pre><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><tt class="docutils literal"><span class="pre">make</span> <span class="pre">clean</span></tt></p>
+<blockquote>
+<div>Removes all files generated by the build. This includes object files,
+generated C/C++ files, libraries, and executables.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">make</span> <span class="pre">install</span></tt></p>
+<blockquote>
+<div>Installs LLVM header files, libraries, tools, and documentation in a hierarchy
+under <tt class="docutils literal"><span class="pre">$PREFIX</span></tt>, specified with <tt class="docutils literal"><span class="pre">CMAKE_INSTALL_PREFIX</span></tt>, which
+defaults to <tt class="docutils literal"><span class="pre">/usr/local</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">make</span> <span class="pre">docs-llvm-html</span></tt></p>
+<blockquote>
+<div>If configured with <tt class="docutils literal"><span class="pre">-DLLVM_ENABLE_SPHINX=On</span></tt>, this will generate a directory
+at <tt class="docutils literal"><span class="pre">OBJ_ROOT/docs/html</span></tt> which contains the HTML formatted documentation.</div></blockquote>
+</div>
+<div class="section" id="cross-compiling-llvm">
+<h3><a class="toc-backref" href="#id21">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 <tt class="docutils literal"><span class="pre">CMAKE_TOOLCHAIN_FILE</span></tt> 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 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"><div class="highlight"><pre><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"><em>How To Cross-Compile Clang/LLVM using Clang/LLVM</em></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="#id22">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"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>OBJ_ROOT
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run <tt class="docutils literal"><span class="pre">cmake</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">CMakeFiles</span></tt> directory in the <em>OBJ_ROOT</em>.
+Underneath that directory there is another directory with a name ending in
+<tt class="docutils literal"><span class="pre">.dir</span></tt> under which you’ll find object files for each source.</p>
+<p>For example:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><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="#id23">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"><div class="highlight"><pre><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"><div class="highlight"><pre><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="#id24">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="#id25"><tt class="docutils literal"><span class="pre">llvm/examples</span></tt></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="#id26"><tt class="docutils literal"><span class="pre">llvm/include</span></tt></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><tt class="docutils literal"><span class="pre">llvm/include/llvm</span></tt></p>
+<blockquote>
+<div>All LLVM-specific header files, and subdirectories for different portions of
+LLVM: <tt class="docutils literal"><span class="pre">Analysis</span></tt>, <tt class="docutils literal"><span class="pre">CodeGen</span></tt>, <tt class="docutils literal"><span class="pre">Target</span></tt>, <tt class="docutils literal"><span class="pre">Transforms</span></tt>, etc...</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/include/llvm/Support</span></tt></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><tt class="docutils literal"><span class="pre">llvm/include/llvm/Config</span></tt></p>
+<blockquote>
+<div>Header files configured by the <tt class="docutils literal"><span class="pre">configure</span></tt> script.
+They wrap “standard” UNIX and C header files. Source code can include these
+header files which automatically take care of the conditional #includes that
+the <tt class="docutils literal"><span class="pre">configure</span></tt> script generates.</div></blockquote>
+</div>
+<div class="section" id="llvm-lib">
+<h3><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">llvm/lib</span></tt></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><tt class="docutils literal"><span class="pre">llvm/lib/IR/</span></tt></p>
+<blockquote>
+<div>Core LLVM source files that implement core classes like Instruction and
+BasicBlock.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/</span></tt></p>
+<blockquote>
+<div>Source code for the LLVM assembly language parser library.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/</span></tt></p>
+<blockquote>
+<div>Code for reading and writing bitcode.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Analysis/</span></tt></p>
+<blockquote>
+<div>A variety of program analyses, such as Call Graphs, Induction Variables,
+Natural Loop Identification, etc.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Transforms/</span></tt></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><tt class="docutils literal"><span class="pre">llvm/lib/Target/</span></tt></p>
+<blockquote>
+<div>Files describing target architectures for code generation. For example,
+<tt class="docutils literal"><span class="pre">llvm/lib/Target/X86</span></tt> holds the X86 machine description.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/CodeGen/</span></tt></p>
+<blockquote>
+<div>The major parts of the code generator: Instruction Selector, Instruction
+Scheduling, and Register Allocation.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/MC/</span></tt></p>
+<blockquote>
+<div>(FIXME: T.B.D.) ....?</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/ExecutionEngine/</span></tt></p>
+<blockquote>
+<div>Libraries for directly executing bitcode at runtime in interpreted and
+JIT-compiled scenarios.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Support/</span></tt></p>
+<blockquote>
+<div>Source code that corresponding to the header files in <tt class="docutils literal"><span class="pre">llvm/include/ADT/</span></tt>
+and <tt class="docutils literal"><span class="pre">llvm/include/Support/</span></tt>.</div></blockquote>
+</div>
+<div class="section" id="llvm-projects">
+<h3><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">llvm/projects</span></tt></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="#id29"><tt class="docutils literal"><span class="pre">llvm/test</span></tt></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="#id30"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a><a class="headerlink" href="#test-suite" title="Permalink to this headline">¶</a></h3>
+<p>A comprehensive correctness, performance, and benchmarking test suite for LLVM.
+Comes in a separate Subversion module because not every LLVM user is interested
+in such a comprehensive suite. For details see the <a class="reference internal" href="TestingGuide.html"><em>Testing Guide</em></a> document.</p>
+</div>
+<div class="section" id="llvm-tools">
+<span id="tools"></span><h3><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">llvm/tools</span></tt></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 <tt class="docutils literal"><span class="pre">tool_name</span> <span class="pre">-help</span></tt>. 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><tt class="docutils literal"><span class="pre">bugpoint</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">bugpoint</span></tt> 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
+<tt class="docutils literal"><span class="pre">bugpoint</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-ar</span></tt></p>
+<blockquote>
+<div>The archiver produces an archive containing the given LLVM bitcode files,
+optionally with an index for faster lookup.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-as</span></tt></p>
+<blockquote>
+<div>The assembler transforms the human readable LLVM assembly to LLVM bitcode.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-dis</span></tt></p>
+<blockquote>
+<div>The disassembler transforms the LLVM bitcode to human readable LLVM assembly.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-link</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">llvm-link</span></tt>, not surprisingly, links multiple LLVM modules into a single
+program.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">lli</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">lli</span></tt> 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, <tt class="docutils literal"><span class="pre">lli</span></tt> 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><tt class="docutils literal"><span class="pre">llc</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">llc</span></tt> is the LLVM backend compiler, which translates LLVM bitcode to a
+native code assembly file.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">opt</span></tt></p>
+<blockquote>
+<div><p><tt class="docutils literal"><span class="pre">opt</span></tt> reads LLVM bitcode, applies a series of LLVM to LLVM transformations
+(which are specified on the command line), and outputs the resultant
+bitcode. ‘<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-help</span></tt>‘ is a good way to get a list of the
+program transformations available in LLVM.</p>
+<p><tt class="docutils literal"><span class="pre">opt</span></tt> 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="#id32"><tt class="docutils literal"><span class="pre">llvm/utils</span></tt></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><tt class="docutils literal"><span class="pre">codegen-diff</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">codegen-diff</span></tt> 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 <tt class="docutils literal"><span class="pre">`perldoc</span> <span class="pre">codegen-diff'</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">emacs/</span></tt></p>
+<blockquote>
+<div>Emacs and XEmacs syntax highlighting for LLVM assembly files and TableGen
+description files. See the <tt class="docutils literal"><span class="pre">README</span></tt> for information on using them.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">getsrcs.sh</span></tt></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: <tt class="docutils literal"><span class="pre">xemacs</span> <span class="pre">`utils/getsources.sh`</span></tt> from the top of the LLVM source
+tree.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvmgrep</span></tt></p>
+<blockquote>
+<div>Performs an <tt class="docutils literal"><span class="pre">egrep</span> <span class="pre">-H</span> <span class="pre">-n</span></tt> on each source file in LLVM and
+passes to it a regular expression provided on <tt class="docutils literal"><span class="pre">llvmgrep</span></tt>‘s command
+line. This is an efficient way of searching the source base for a
+particular regular expression.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">makellvm</span></tt></p>
+<blockquote>
+<div>Compiles all files in the current directory, then
+compiles and links the tool that is the first argument. For example, assuming
+you are in <tt class="docutils literal"><span class="pre">llvm/lib/Target/Sparc</span></tt>, if <tt class="docutils literal"><span class="pre">makellvm</span></tt> is in your
+path, running <tt class="docutils literal"><span class="pre">makellvm</span> <span class="pre">llc</span></tt> will make a build of the current
+directory, switch to directory <tt class="docutils literal"><span class="pre">llvm/tools/llc</span></tt> and build it, causing a
+re-linking of LLC.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">TableGen/</span></tt></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><tt class="docutils literal"><span class="pre">vim/</span></tt></p>
+<blockquote>
+<div>vim syntax-highlighting for LLVM assembly files
+and TableGen description files. See the <tt class="docutils literal"><span class="pre">README</span></tt> 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="#id33">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="#id34">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"><div class="highlight"><pre><span class="cp">#include <stdio.h></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"><div class="highlight"><pre><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"><div class="highlight"><pre><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
+<tt class="docutils literal"><span class="pre">.ll</span></tt> or <tt class="docutils literal"><span class="pre">.bc</span></tt> 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"><div class="highlight"><pre><span class="gp">%</span> ./hello
+</pre></div>
+</div>
+<p>and</p>
+<div class="highlight-console"><div class="highlight"><pre><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"><em>lli</em></a>.</p>
+</li>
+<li><p class="first">Use the <tt class="docutils literal"><span class="pre">llvm-dis</span></tt> utility to take a look at the LLVM assembly code:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> llvm-dis < hello.bc | 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"><div class="highlight"><pre><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"><div class="highlight"><pre><span class="gp">%</span> /opt/SUNWspro/bin/cc -xarch<span class="o">=</span>v9 hello.s -o hello.native <span class="c"># On Solaris</span>
+
+<span class="gp">%</span> gcc hello.s -o hello.native <span class="c"># On others</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Execute the native code program:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> ./hello.native
+</pre></div>
+</div>
+<p>Note that using clang to compile directly to native code (i.e. when the
+<tt class="docutils literal"><span class="pre">-emit-llvm</span></tt> 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="#id35">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="id3"></span><h2><a class="toc-backref" href="#id36">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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/GettingStartedVS.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/GettingStartedVS.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/GettingStartedVS.html (added)
+++ www-releases/trunk/5.0.2/docs/GettingStartedVS.html Thu May 10 06:54:16 2018
@@ -0,0 +1,334 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Getting Started with the LLVM System using Microsoft Visual Studio — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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"><em>Getting Started with the LLVM System</em></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.
+<tt class="docutils literal"><span class="pre">C:\Documents</span> <span class="pre">and</span> <span class="pre">Settings\...</span></tt>) 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><tt class="docutils literal"><span class="pre">cd</span> <span class="pre"><where-you-want-llvm-to-live></span></tt></li>
+<li><tt class="docutils literal"><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></tt>
+(<em>or use WinZip</em>)</li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm</span></tt></li>
+</ol>
+</div></blockquote>
+</li>
+<li><p class="first">With anonymous Subversion access:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre"><where-you-want-llvm-to-live></span></tt></li>
+<li><tt class="docutils literal"><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></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm</span></tt></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
+<tt class="docutils literal"><span class="pre">CMAKE_INSTALL_PREFIX</span></tt> setting to select a directory to INSTALL to
+once compiling is complete, although installation is not mandatory for
+using LLVM. Another important option is <tt class="docutils literal"><span class="pre">LLVM_TARGETS_TO_BUILD</span></tt>,
+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"><em>LLVM CMake guide</em></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
+<tt class="docutils literal"><span class="pre">/property:Configuration</span></tt> 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 <tt class="docutils literal"><span class="pre">-Thost=x64</span></tt> 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 <tt class="docutils literal"><span class="pre">llvm.sln</span></tt>
+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
+<tt class="docutils literal"><span class="pre">ALL_BUILD</span></tt> project to build everything, or the <tt class="docutils literal"><span class="pre">INSTALL</span></tt> project,
+which first builds the <tt class="docutils literal"><span class="pre">ALL_BUILD</span></tt> project, then installs the LLVM
+headers, libs, and other useful things to the directory set by the
+<tt class="docutils literal"><span class="pre">CMAKE_INSTALL_PREFIX</span></tt> 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 <tt class="docutils literal"><span class="pre">%PATH%</span></tt> does not contain GnuWin32, you may specify
+<tt class="docutils literal"><span class="pre">LLVM_LIT_TOOLS_DIR</span></tt> 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"><div class="highlight"><pre>C:\..\llvm<span class="p">></span> <span class="n">python</span> ..\build\bin\llvm-lit --param build_config<span class="o">=</span>Win<span class="m">32</span> --param build_mode<span class="o">=</span>Debug --param llvm_site_config<span class="o">=</span>..<span class="n">/build/test/lit.site.cfg</span> test
+</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"><div class="highlight"><pre>C:\..\llvm<span class="p">></span> <span class="n">python</span> ..\build\bin\llvm-lit --param build_config<span class="o">=</span>Win<span class="m">32</span> --param build_mode<span class="o">=</span>Debug --param llvm_site_config<span class="o">=</span>..<span class="n">/build/test/lit.site.cfg</span> test<span class="n">/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 ‘<tt class="docutils literal"><span class="pre">hello.c</span></tt>‘:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></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"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">clang</span> -c hello.c -emit-llvm -o hello.bc
+</pre></div>
+</div>
+<p>This will create the result file <tt class="docutils literal"><span class="pre">hello.bc</span></tt> which is the LLVM bitcode
+that corresponds the compiled program and the library facilities that
+it required. You can execute this file directly using <tt class="docutils literal"><span class="pre">lli</span></tt> tool,
+compile it to native assembly with the <tt class="docutils literal"><span class="pre">llc</span></tt>, optimize or analyze it
+further with the <tt class="docutils literal"><span class="pre">opt</span></tt> tool, etc.</p>
+<p>Alternatively you can directly output an executable with clang with:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">clang</span> hello.c -o hello.exe
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">-o</span> <span class="pre">hello.exe</span></tt> is required because clang currently outputs <tt class="docutils literal"><span class="pre">a.out</span></tt>
+when neither <tt class="docutils literal"><span class="pre">-o</span></tt> nor <tt class="docutils literal"><span class="pre">-c</span></tt> are given.</p>
+</li>
+<li><p class="first">Run the program using the just-in-time compiler:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">lli</span> hello.bc
+</pre></div>
+</div>
+</li>
+<li><p class="first">Use the <tt class="docutils literal"><span class="pre">llvm-dis</span></tt> utility to take a look at the LLVM assembly code:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">llvm</span>-dis <span class="p"><</span> <span class="n">hello</span>.bc <span class="p">|</span> <span class="n">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"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">llc</span> -filetype<span class="o">=</span>obj hello.bc
+</pre></div>
+</div>
+</li>
+<li><p class="first">Link to binary using Microsoft link:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">link</span> hello.obj -defaultlib:libcmt
+</pre></div>
+</div>
+</li>
+<li><p class="first">Execute the native code program:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">hello</span>.exe
+</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"><em>Frequently Asked Questions</em></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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/GlobalISel.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/GlobalISel.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/GlobalISel.html (added)
+++ www-releases/trunk/5.0.2/docs/GlobalISel.html Thu May 10 06:54:16 2018
@@ -0,0 +1,674 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Global Instruction Selection — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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>
+</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"><em>Generic Machine IR</em></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"><em>Core Pipeline</em></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="id18">Generic Instructions</a></li>
+<li><a class="reference internal" href="#generic-virtual-registers" id="id19">Generic Virtual Registers</a></li>
+<li><a class="reference internal" href="#register-bank" id="id20">Register Bank</a></li>
+<li><a class="reference internal" href="#low-level-type" id="id21">Low Level Type</a></li>
+</ul>
+</div>
+<p><tt class="docutils literal"><span class="pre">NOTE</span></tt>:
+The generic MIR (GMIR) representation still contains references to IR
+constructs (such as <tt class="docutils literal"><span class="pre">GlobalValue</span></tt>). 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="#id18">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.,
+<tt class="docutils literal"><span class="pre">G_ADD</span></tt>). Like other target-independent instructions (e.g., <tt class="docutils literal"><span class="pre">COPY</span></tt> or
+<tt class="docutils literal"><span class="pre">PHI</span></tt>), these are available on all targets.</p>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+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 <tt class="docutils literal"><span class="pre">MachineIRBuilder</span></tt> class wraps the <tt class="docutils literal"><span class="pre">MachineInstrBuilder</span></tt> 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="#id19">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"><em>Low Level Type</em></a>, and can be assigned
+a <a class="reference internal" href="#gmir-regbank"><em>Register Bank</em></a>.</p>
+<p><tt class="docutils literal"><span class="pre">MachineRegisterInfo</span></tt> 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"><em>Low Level Type</em></a> of the register, and, instead of the <tt class="docutils literal"><span class="pre">TargetRegisterClass</span></tt>,
+its <a class="reference internal" href="#gmir-regbank"><em>Register Bank</em></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"><em>Constant Lowering</em></a>).</li>
+<li>instead of physical register, they use a gvreg defined by a <tt class="docutils literal"><span class="pre">COPY</span></tt>.</li>
+</ul>
+<p><tt class="docutils literal"><span class="pre">NOTE</span></tt>:
+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="#id20">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"><em>RegisterBankInfo</em></a>.</p>
+</div>
+<div class="section" id="low-level-type">
+<span id="gmir-llt"></span><h3><a class="toc-backref" href="#id21">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 <tt class="docutils literal"><span class="pre">LLT</span></tt> class.</p>
+<p>Like <tt class="docutils literal"><span class="pre">EVT</span></tt>/<tt class="docutils literal"><span class="pre">MVT</span></tt>/<tt class="docutils literal"><span class="pre">Type</span></tt>, 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><tt class="docutils literal"><span class="pre">sN</span></tt> for scalars</li>
+<li><tt class="docutils literal"><span class="pre">pN</span></tt> for pointers</li>
+<li><tt class="docutils literal"><span class="pre"><N</span> <span class="pre">x</span> <span class="pre">sM></span></tt> for vectors</li>
+<li><tt class="docutils literal"><span class="pre">unsized</span></tt> for labels, etc..</li>
+</ul>
+<p><tt class="docutils literal"><span class="pre">LLT</span></tt> is intended to replace the usage of <tt class="docutils literal"><span class="pre">EVT</span></tt> in SelectionDAG.</p>
+<p>Here are some LLT examples and their <tt class="docutils literal"><span class="pre">EVT</span></tt> and <tt class="docutils literal"><span class="pre">Type</span></tt> 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><tt class="docutils literal"><span class="pre">s1</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i1</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i1</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">s8</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i8</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i8</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">s32</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i32</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i32</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">s32</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">f32</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">float</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">s17</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i17</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i17</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">s16</span></tt></td>
+<td>N/A</td>
+<td><tt class="docutils literal"><span class="pre">{i8,</span> <span class="pre">i8}</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">s32</span></tt></td>
+<td>N/A</td>
+<td><tt class="docutils literal"><span class="pre">[4</span> <span class="pre">x</span> <span class="pre">i8]</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">p0</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">iPTR</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i8*</span></tt>, <tt class="docutils literal"><span class="pre">i32*</span></tt>, <tt class="docutils literal"><span class="pre">%opaque*</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">p2</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">iPTR</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">i8</span> <span class="pre">addrspace(2)*</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre"><4</span> <span class="pre">x</span> <span class="pre">s32></span></tt></td>
+<td><tt class="docutils literal"><span class="pre">v4f32</span></tt></td>
+<td><tt class="docutils literal"><span class="pre"><4</span> <span class="pre">x</span> <span class="pre">float></span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">s64</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">v1f64</span></tt></td>
+<td><tt class="docutils literal"><span class="pre"><1</span> <span class="pre">x</span> <span class="pre">double></span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre"><3</span> <span class="pre">x</span> <span class="pre">s32></span></tt></td>
+<td><tt class="docutils literal"><span class="pre">v3i32</span></tt></td>
+<td><tt class="docutils literal"><span class="pre"><3</span> <span class="pre">x</span> <span class="pre">i32></span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">unsized</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">Other</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">label</span></tt></td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+<p>Rationale: instructions already encode a specific interpretation of types
+(e.g., <tt class="docutils literal"><span class="pre">add</span></tt> vs. <tt class="docutils literal"><span class="pre">fadd</span></tt>, or <tt class="docutils literal"><span class="pre">sdiv</span></tt> vs. <tt class="docutils literal"><span class="pre">udiv</span></tt>). 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><tt class="docutils literal"><span class="pre">NOTE</span></tt>:
+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><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+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="id22">IRTranslator</a><ul>
+<li><a class="reference internal" href="#api-calllowering" id="id23">API: CallLowering</a></li>
+<li><a class="reference internal" href="#aggregates" id="id24">Aggregates</a></li>
+<li><a class="reference internal" href="#constant-lowering" id="id25">Constant Lowering</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#legalizer" id="id26">Legalizer</a><ul>
+<li><a class="reference internal" href="#api-legalizerinfo" id="id27">API: LegalizerInfo</a></li>
+<li><a class="reference internal" href="#non-power-of-2-types" id="id28">Non-power of 2 types</a></li>
+<li><a class="reference internal" href="#vector-types" id="id29">Vector types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#regbankselect" id="id30">RegBankSelect</a><ul>
+<li><a class="reference internal" href="#api-registerbankinfo" id="id31">API: RegisterBankInfo</a></li>
+<li><a class="reference internal" href="#regbankselect-modes" id="id32">RegBankSelect Modes</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instructionselect" id="id33">InstructionSelect</a><ul>
+<li><a class="reference internal" href="#api-instructionselector" id="id34">API: InstructionSelector</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><tt class="docutils literal"><span class="pre">NOTE</span></tt>:
+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
+<tt class="docutils literal"><span class="pre">legalized</span></tt> property to avoid running the <a class="reference internal" href="#milegalizer"><em>Legalizer</em></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="#id22">IRTranslator</a><a class="headerlink" href="#irtranslator" title="Permalink to this headline">¶</a></h3>
+<p>This pass translates the input LLVM IR <tt class="docutils literal"><span class="pre">Function</span></tt> to a GMIR
+<tt class="docutils literal"><span class="pre">MachineFunction</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+This currently doesn’t support the more complex instructions, in particular
+those involving control flow (<tt class="docutils literal"><span class="pre">switch</span></tt>, <tt class="docutils literal"><span class="pre">invoke</span></tt>, ...).
+For <tt class="docutils literal"><span class="pre">switch</span></tt> in particular, we can initially use the <tt class="docutils literal"><span class="pre">LowerSwitch</span></tt> pass.</p>
+<div class="section" id="api-calllowering">
+<span id="id4"></span><h4><a class="toc-backref" href="#id23">API: CallLowering</a><a class="headerlink" href="#api-calllowering" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">IRTranslator</span></tt> (using the <tt class="docutils literal"><span class="pre">CallLowering</span></tt> 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="#id24">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 <tt class="docutils literal"><span class="pre">GetValueVTs</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+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="#id25">Constant Lowering</a><a class="headerlink" href="#constant-lowering" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">IRTranslator</span></tt> lowers <tt class="docutils literal"><span class="pre">Constant</span></tt> operands into uses of gvregs defined
+by <tt class="docutils literal"><span class="pre">G_CONSTANT</span></tt> or <tt class="docutils literal"><span class="pre">G_FCONSTANT</span></tt> instructions.
+Currently, these instructions are always emitted in the entry basic block.
+In a <tt class="docutils literal"><span class="pre">MachineFunction</span></tt>, each <tt class="docutils literal"><span class="pre">Constant</span></tt> 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"><em>InstructionSelect</em></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><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+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="#id26">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 <tt class="docutils literal"><span class="pre">G_LOAD</span></tt>/<tt class="docutils literal"><span class="pre">G_STORE</span></tt> 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><tt class="docutils literal"><span class="pre">G_SEQUENCE</span></tt> — concatenate multiple registers into a single wider
+register.</li>
+<li><tt class="docutils literal"><span class="pre">G_EXTRACT</span></tt> — extract multiple registers (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"><em>Legalizer</em></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="#id27">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 <tt class="docutils literal"><span class="pre">Expand</span></tt> (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
+<tt class="docutils literal"><span class="pre">G_ICMP</span></tt> 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 <tt class="docutils literal"><span class="pre">InstrAspect</span></tt>,
+essentially a tuple consisting of <tt class="docutils literal"><span class="pre">(Opcode,</span> <span class="pre">TypeIdx,</span> <span class="pre">Type)</span></tt> and mapping to a
+suggested course of action.</p>
+<p>An example use might be:</p>
+<blockquote>
+<div><div class="highlight-c++"><div class="highlight"><pre><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><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+An alternative worth investigating is to generalize the API to represent
+actions using <tt class="docutils literal"><span class="pre">std::function</span></tt> that implements the action, instead of explicit
+enum tokens (<tt class="docutils literal"><span class="pre">Legal</span></tt>, <tt class="docutils literal"><span class="pre">WidenScalar</span></tt>, ...).</p>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+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="#id28">Non-power of 2 types</a><a class="headerlink" href="#non-power-of-2-types" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+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="#id29">Vector types</a><a class="headerlink" href="#vector-types" title="Permalink to this headline">¶</a></h4>
+<p>Vectors first get their element type legalized: <tt class="docutils literal"><span class="pre"><A</span> <span class="pre">x</span> <span class="pre">sB></span></tt> becomes
+<tt class="docutils literal"><span class="pre"><A</span> <span class="pre">x</span> <span class="pre">sC></span></tt> such that at least one operation is legal with <tt class="docutils literal"><span class="pre">sC</span></tt>.</p>
+<p>This is currently specified by the function <tt class="docutils literal"><span class="pre">setScalarInVectorAction</span></tt>, 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 <tt class="docutils literal"><span class="pre"><2</span> <span class="pre">x</span> <span class="pre">s8></span></tt>
+operation should be scalarized or extended to <tt class="docutils literal"><span class="pre"><8</span> <span class="pre">x</span> <span class="pre">s8></span></tt>).</p>
+</div>
+</div>
+<div class="section" id="regbankselect">
+<span id="id6"></span><h3><a class="toc-backref" href="#id30">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"><em>Generic Virtual Registers</em></a> operands of generic
+instructions to some <a class="reference internal" href="#gmir-regbank"><em>Register Bank</em></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"><em>RegisterBankInfo</em></a>.
+The mapping is then applied, possibly introducing <tt class="docutils literal"><span class="pre">COPY</span></tt> instructions if
+necessary.</p>
+<p>It traverses the <tt class="docutils literal"><span class="pre">MachineFunction</span></tt> 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="#id31">API: RegisterBankInfo</a><a class="headerlink" href="#api-registerbankinfo" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">RegisterBankInfo</span></tt> class describes multiple aspects of register banks.</p>
+<ul class="simple">
+<li><strong>Banks</strong>: <tt class="docutils literal"><span class="pre">addRegBankCoverage</span></tt> — which register bank covers each
+register class.</li>
+<li><strong>Cross-Bank Copies</strong>: <tt class="docutils literal"><span class="pre">copyCost</span></tt> — the cost of a <tt class="docutils literal"><span class="pre">COPY</span></tt> from one bank
+to another.</li>
+<li><strong>Default Mapping</strong>: <tt class="docutils literal"><span class="pre">getInstrMapping</span></tt> — the default bank assignments for
+a given instruction.</li>
+<li><strong>Alternative Mapping</strong>: <tt class="docutils literal"><span class="pre">getInstrAlternativeMapping</span></tt> — the other
+possible bank assignments for a given instruction.</li>
+</ul>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+All this information should eventually be static and generated by TableGen,
+mostly using existing information augmented by bank descriptions.</p>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+<tt class="docutils literal"><span class="pre">getInstrMapping</span></tt> is currently separate from <tt class="docutils literal"><span class="pre">getInstrAlternativeMapping</span></tt>
+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="#id32">RegBankSelect Modes</a><a class="headerlink" href="#regbankselect-modes" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">RegBankSelect</span></tt> 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><tt class="docutils literal"><span class="pre">NOTE</span></tt>:
+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"><em>Low Level Type</em></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="#id33">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 <tt class="docutils literal"><span class="pre">MachineFunction</span></tt> 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="#id34">API: InstructionSelector</a><a class="headerlink" href="#api-instructionselector" title="Permalink to this headline">¶</a></h4>
+<p>The target implements the <tt class="docutils literal"><span class="pre">InstructionSelector</span></tt> 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++"><div class="highlight"><pre><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.</p>
+<p>The <tt class="docutils literal"><span class="pre">InstructionSelector</span></tt> 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>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+Currently, the Select pass is implemented with hand-written c++, similar to
+FastISel, rather than backed by tblgen’erated pattern-matching.
+We intend to eventually reuse SelectionDAG patterns.</p>
+</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"><em>Generic Machine IR</em></a> is serializable (see <a class="reference internal" href="MIRLangRef.html"><em>Machine IR (MIR) Format Reference Manual</em></a>).
+Combined with <a class="reference internal" href="#maintainability-iterative"><em>Iterative Transformations</em></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"><em>Core Pipeline</em></a> is represented by a set of
+<tt class="docutils literal"><span class="pre">MachineFunctionProperties</span></tt>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">legalized</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">regBankSelected</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">selected</span></tt></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 <tt class="docutils literal"><span class="pre">MachineVerifier</span></tt> to enforce invariants.
+For instance, a <tt class="docutils literal"><span class="pre">regBankSelected</span></tt> function may not have gvregs without
+a bank.</p>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>:
+The <tt class="docutils literal"><span class="pre">MachineVerifier</span></tt> 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><tt class="docutils literal"><span class="pre">NOTE</span></tt>:
+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"><em>Generic Virtual Registers</em></a> are stored in a separate table in <tt class="docutils literal"><span class="pre">MachineRegisterInfo</span></tt>,
+that is destroyed after <a class="reference internal" href="#instructionselect"><em>InstructionSelect</em></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><tt class="docutils literal"><span class="pre">NOTE</span></tt>:
+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"><em>Legalizer</em></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"><em>IRTranslator</em></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"><em>CallLowering</em></a> — lower calls, returns, and arguments
+according to the ABI.</li>
+<li><a class="reference internal" href="#api-registerbankinfo"><em>RegisterBankInfo</em></a> — describe
+<a class="reference internal" href="#gmir-regbank"><em>Register Bank</em></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"><em>LegalizerInfo</em></a> — describe what is legal, and how
+to legalize what isn’t.</li>
+<li><a class="reference internal" href="#api-instructionselector"><em>InstructionSelector</em></a> — select generic MIR
+to target-specific MIR.</li>
+</ul>
+<p>Additionally:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">TargetPassConfig</span></tt> — create the passes constituting the pipeline,
+including additional passes not included in the <a class="reference internal" href="#pipeline"><em>Core Pipeline</em></a>.</li>
+<li><tt class="docutils literal"><span class="pre">GISelAccessor</span></tt> — setup the various subtarget-provided classes, with a
+graceful fallback to no-op when GlobalISel isn’t enabled.</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/GoldPlugin.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/GoldPlugin.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/GoldPlugin.html (added)
+++ www-releases/trunk/5.0.2/docs/GoldPlugin.html Thu May 10 06:54:16 2018
@@ -0,0 +1,245 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The LLVM gold plugin — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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 requires that you use the
+<a class="reference external" href="http://sourceware.org/binutils">gold linker</a> or ld.bfd from binutils >= 2.21.51.0.2, as they support 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"><em>libLTO</em></a>. The same plugin can also be used by other tools such as
+<tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm</span></tt>.</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>Check for plugin support by running <tt class="docutils literal"><span class="pre">/usr/bin/ld</span> <span class="pre">-plugin</span></tt>. If it complains
+“missing argument” then you have plugin support. If not, such as an “unknown option”
+error then you will either need to build gold or install a recent version
+of ld.bfd with plugin support and then build gold plugin.</p>
+<ul>
+<li><p class="first">Download, configure and build ld.bfd with plugin support:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils
+<span class="nv">$ </span>mkdir build
+<span class="nv">$ </span><span class="nb">cd </span>build
+<span class="nv">$ </span>../binutils/configure --disable-werror <span class="c"># ld.bfd includes plugin support by default</span>
+<span class="nv">$ </span>make all-ld
+</pre></div>
+</div>
+<p>That should leave you with <tt class="docutils literal"><span class="pre">build/ld/ld-new</span></tt> which supports
+the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option. Running <tt class="docutils literal"><span class="pre">make</span></tt> will additionally build
+<tt class="docutils literal"><span class="pre">build/binutils/ar</span></tt> and <tt class="docutils literal"><span class="pre">nm-new</span></tt> binaries supporting plugins.</p>
+</li>
+<li><p class="first">Build the LLVMgold plugin. Run CMake with
+<tt class="docutils literal"><span class="pre">-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include</span></tt>. The correct include
+path will contain the file <tt class="docutils literal"><span class="pre">plugin-api.h</span></tt>.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="usage">
+<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>The linker takes a <tt class="docutils literal"><span class="pre">-plugin</span></tt> option that points to the path of
+the plugin <tt class="docutils literal"><span class="pre">.so</span></tt> file. To find out what link command <tt class="docutils literal"><span class="pre">gcc</span></tt>
+would run in a given situation, run <tt class="docutils literal"><span class="pre">gcc</span> <span class="pre">-v</span> <span class="pre">[...]</span></tt> and
+look for the line where it runs <tt class="docutils literal"><span class="pre">collect2</span></tt>. Replace that with
+<tt class="docutils literal"><span class="pre">ld-new</span> <span class="pre">-plugin</span> <span class="pre">/path/to/LLVMgold.so</span></tt> to test it out. Once you’re
+ready to switch to using gold, backup your existing <tt class="docutils literal"><span class="pre">/usr/bin/ld</span></tt>
+then replace it with <tt class="docutils literal"><span class="pre">ld-new</span></tt>.</p>
+<p>You should produce bitcode files from <tt class="docutils literal"><span class="pre">clang</span></tt> with the option
+<tt class="docutils literal"><span class="pre">-flto</span></tt>. This flag will also cause <tt class="docutils literal"><span class="pre">clang</span></tt> to look for the gold plugin in
+the <tt class="docutils literal"><span class="pre">lib</span></tt> directory under its prefix and pass the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option to
+<tt class="docutils literal"><span class="pre">ld</span></tt>. It will not look for an alternate linker, which is why you need
+gold to be the installed system linker in your path.</p>
+<p><tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm</span></tt> also accept the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option and it’s possible to
+to install <tt class="docutils literal"><span class="pre">LLVMgold.so</span></tt> to <tt class="docutils literal"><span class="pre">/usr/lib/bfd-plugins</span></tt> for a seamless setup.
+If you built your own gold, be sure to install the <tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm-new</span></tt> you
+built to <tt class="docutils literal"><span class="pre">/usr/bin</span></tt>.</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"><div class="highlight"><pre><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 <stdio.h></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="n">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 <stdio.h></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"><div class="highlight"><pre>--- <span class="nb">command </span>lines ---
+<span class="nv">$ </span>clang -flto a.c -c -o a.o <span class="c"># <-- a.o is LLVM bitcode file</span>
+<span class="nv">$ </span>ar q a.a a.o <span class="c"># <-- a.a is an archive with LLVM bitcode</span>
+<span class="nv">$ </span>clang b.c -c -o b.o <span class="c"># <-- b.o is native object file</span>
+<span class="nv">$ </span>clang -flto a.a b.o -o main <span class="c"># <-- 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"><em>libLTO
+example</em></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 <tt class="docutils literal"><span class="pre">ld</span></tt>, <tt class="docutils literal"><span class="pre">ar</span></tt>, and <tt class="docutils literal"><span class="pre">nm</span></tt> 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"><em>on how to build LLVMgold.so</em></a>.</p>
+</li>
+<li><p class="first">Install the newly built binutils to <tt class="docutils literal"><span class="pre">$PREFIX</span></tt></p>
+</li>
+<li><p class="first">Copy <tt class="docutils literal"><span class="pre">Release/lib/LLVMgold.so</span></tt> to <tt class="docutils literal"><span class="pre">$PREFIX/lib/bfd-plugins/</span></tt></p>
+</li>
+<li><p class="first">Set environment variables (<tt class="docutils literal"><span class="pre">$PREFIX</span></tt> is where you installed clang and
+binutils):</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nb">export </span><span class="nv">CC</span><span class="o">=</span><span class="s2">"$PREFIX/bin/clang -flto"</span>
+<span class="nb">export </span><span class="nv">CXX</span><span class="o">=</span><span class="s2">"$PREFIX/bin/clang++ -flto"</span>
+<span class="nb">export </span><span class="nv">AR</span><span class="o">=</span><span class="s2">"$PREFIX/bin/ar"</span>
+<span class="nb">export </span><span class="nv">NM</span><span class="o">=</span><span class="s2">"$PREFIX/bin/nm"</span>
+<span class="nb">export </span><span class="nv">RANLIB</span><span class="o">=</span>/bin/true <span class="c">#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"><div class="highlight"><pre><span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"$PREFIX/bin:$PATH"</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"><div class="highlight"><pre>% ./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 <tt class="docutils literal"><span class="pre">LD</span></tt> 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
+<tt class="docutils literal"><span class="pre">plugin-api.h</span></tt> from gold which means that the resulting <tt class="docutils literal"><span class="pre">LLVMgold.so</span></tt>
+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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/HowToAddABuilder.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/HowToAddABuilder.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/HowToAddABuilder.html (added)
+++ www-releases/trunk/5.0.2/docs/HowToAddABuilder.html Thu May 10 06:54:16 2018
@@ -0,0 +1,199 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How To Add Your Build Configuration To LLVM Buildbot Infrastructure — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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"><div class="highlight"><pre><span class="nv">$ </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-python"><pre>Windows 7 x64
+Core i7 (2.66GHz), 16GB of RAM
+
+g++.exe (TDM-1 mingw32) 4.4.0
+GNU Binutils 2.19.1
+cmake version 2.8.4
+Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86</pre>
+</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 <tt class="docutils literal"><span class="pre">buildbot/osuosl/master/config/slaves.py</span></tt></li>
+<li>builders are added to <tt class="docutils literal"><span class="pre">buildbot/osuosl/master/config/builders.py</span></tt></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 <tt class="docutils literal"><span class="pre">InformativeMailNotifier</span></tt> to
+<tt class="docutils literal"><span class="pre">buildbot/osuosl/master/config/status.py</span></tt>. 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
+<tt class="docutils literal"><span class="pre">http://lab.llvm.org:8011/buildslaves/<your-buildslave-name></span></tt> 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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/HowToBuildOnARM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/HowToBuildOnARM.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/HowToBuildOnARM.html (added)
+++ www-releases/trunk/5.0.2/docs/HowToBuildOnARM.html Thu May 10 06:54:16 2018
@@ -0,0 +1,173 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How To Build On ARM — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="How To Cross-Compile Clang/LLVM using Clang/LLVM" href="HowToCrossCompileLLVM.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">
+ <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="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">
+
+ <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"><em>How To Cross-Compile Clang/LLVM using Clang/LLVM</em></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 <tt class="docutils literal"><span class="pre">Relese</span></tt> 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"><div class="highlight"><pre>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"><div class="highlight"><pre>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=$HOME/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 <tt class="docutils literal"><span class="pre">make</span> <span class="pre">-jN</span></tt> or <tt class="docutils literal"><span class="pre">ninja</span></tt> will build everything.
+<tt class="docutils literal"><span class="pre">make</span> <span class="pre">-jN</span> <span class="pre">check-all</span></tt> or <tt class="docutils literal"><span class="pre">ninja</span> <span class="pre">check-all</span></tt> will run all compiler tests. For
+running the test suite, please refer to <a class="reference internal" href="TestingGuide.html"><em>LLVM Testing Infrastructure Guide</em></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 <tt class="docutils literal"><span class="pre">gold</span></tt> rather then GNU <tt class="docutils literal"><span class="pre">ld</span></tt>. In any case it is probably a good
+idea to set up a swap partition, too.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </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"><div class="highlight"><pre><span class="c"># 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>0; cpu<<span class="sb">`</span>grep -c proc /proc/cpuinfo<span class="sb">`</span>; cpu++<span class="o">))</span>; <span class="k">do</span>
+<span class="k"> </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">
+ <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="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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/HowToCrossCompileLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/HowToCrossCompileLLVM.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/HowToCrossCompileLLVM.html (added)
+++ www-releases/trunk/5.0.2/docs/HowToCrossCompileLLVM.html Thu May 10 06:54:16 2018
@@ -0,0 +1,288 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How To Cross-Compile Clang/LLVM using Clang/LLVM — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="next" title="LLVM Command Guide" href="CommandGuide/index.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">
+ <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="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">
+
+ <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><tt class="docutils literal"><span class="pre">cmake</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">ninja-build</span></tt> (from backports in Ubuntu)</li>
+<li><tt class="docutils literal"><span class="pre">gcc-4.7-arm-linux-gnueabihf</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">gcc-4.7-multilib-arm-linux-gnueabihf</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">binutils-arm-linux-gnueabihf</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">libgcc1-armhf-cross</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">libsfgcc1-armhf-cross</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">libstdc++6-armhf-cross</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">libstdc++6-4.7-dev-armhf-cross</span></tt></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"><em>Building LLVM with CMake</em></a>.</p>
+<p>The CMake options you need to add are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_CROSSCOMPILING=True</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_INSTALL_PREFIX=<install-dir></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_TARGET_ARCH=ARM</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_TARGETS_TO_BUILD=ARM</span></tt></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><tt class="docutils literal"><span class="pre">-DCMAKE_CXX_FLAGS='-march=armv7-a</span> <span class="pre">-mcpu=cortex-a9</span> <span class="pre">-mfloat-abi=hard'</span></tt></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><tt class="docutils literal"><span class="pre">'-target</span> <span class="pre">arm-linux-gnueabihf'</span></tt> or whatever is the triple of your cross GCC.</li>
+<li><tt class="docutils literal"><span class="pre">'--sysroot=/usr/arm-linux-gnueabihf'</span></tt>, <tt class="docutils literal"><span class="pre">'--sysroot=/opt/gcc/arm-linux-gnueabihf'</span></tt>
+or whatever is the location of your GCC’s sysroot (where /lib, /bin etc are).</li>
+<li>Appropriate use of <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-L</span></tt>, 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 <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt>) to your host
+platform before you start. The CXX flags define the target, cpu (which in this case
+defaults to <tt class="docutils literal"><span class="pre">fpu=VFP3</span></tt> 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 <tt class="docutils literal"><span class="pre">--sysroot</span></tt>
+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 <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-L</span></tt> 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
+<tt class="docutils literal"><span class="pre">TARGETS_TO_BUILD</span></tt> to only build the back-end you’re targeting to.</p>
+<p>You must set the <tt class="docutils literal"><span class="pre">CMAKE_INSTALL_PREFIX</span></tt>, otherwise a <tt class="docutils literal"><span class="pre">ninja</span> <span class="pre">install</span></tt>
+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 (<tt class="docutils literal"><span class="pre">R_ARM_THM_MOVW_ABS_NC</span></tt>), so for now, you
+should disable PIC:</p>
+<div class="highlight-bash"><div class="highlight"><pre>-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 <tt class="docutils literal"><span class="pre">multiarch</span></tt>, 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 <tt class="docutils literal"><span class="pre">libXXX</span></tt>
+will have the shared objects (<tt class="docutils literal"><span class="pre">.so</span></tt>) and the <tt class="docutils literal"><span class="pre">libXXX-dev</span></tt> will
+give you the headers and the static (<tt class="docutils literal"><span class="pre">.a</span></tt>) library. Just in
+case, download both.</p>
+<p>The ones you need for ARM are: <tt class="docutils literal"><span class="pre">libtinfo</span></tt>, <tt class="docutils literal"><span class="pre">zlib1g</span></tt>,
+<tt class="docutils literal"><span class="pre">libxml2</span></tt> and <tt class="docutils literal"><span class="pre">liblzma</span></tt>. In the Debian repository you’ll
+find downloads for all architectures.</p>
+<p>After you download and unpack all <tt class="docutils literal"><span class="pre">.deb</span></tt> packages, copy all
+<tt class="docutils literal"><span class="pre">.so</span></tt> and <tt class="docutils literal"><span class="pre">.a</span></tt> to a directory, make the appropriate
+symbolic links (if necessary), and add the relevant <tt class="docutils literal"><span class="pre">-L</span></tt>
+and <tt class="docutils literal"><span class="pre">-I</span></tt> paths to <tt class="docutils literal"><span class="pre">-DCMAKE_CXX_FLAGS</span></tt> 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"><div class="highlight"><pre><span class="nv">$ </span>cmake -G Ninja <<span class="nb">source</span>-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"><div class="highlight"><pre><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 <<span class="nb">source</span>-dir> <options above>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If you have <tt class="docutils literal"><span class="pre">clang</span></tt>/<tt class="docutils literal"><span class="pre">clang++</span></tt> on the path, it should just work, and special
+Ninja files will be created in the build directory. I strongly suggest
+you to run <tt class="docutils literal"><span class="pre">cmake</span></tt> 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"><div class="highlight"><pre><span class="nv">$ </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 <tt class="docutils literal"><span class="pre">ninja</span> <span class="pre">check-all</span></tt> 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"><div class="highlight"><pre><span class="nv">$ </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"><div class="highlight"><pre><span class="nv">$ </span>ln -sf <install-dir> arm-linux-gnueabihf-clang
+<span class="nv">$ </span>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"><div class="highlight"><pre><span class="nv">$ </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 <tt class="docutils literal"><span class="pre">-jN</span></tt> options to <tt class="docutils literal"><span class="pre">lnt</span></tt> 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">
+ <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="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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/HowToReleaseLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/HowToReleaseLLVM.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/HowToReleaseLLVM.html (added)
+++ www-releases/trunk/5.0.2/docs/HowToReleaseLLVM.html Thu May 10 06:54:16 2018
@@ -0,0 +1,417 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How To Release LLVM To The Public — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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., <tt class="docutils literal"><span class="pre">clang</span></tt> and <tt class="docutils literal"><span class="pre">compiler-rt</span></tt> — 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"><em>How To Validate a New Release</em></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="#release-patch-rules" id="id10">Release Patch Rules</a><ul>
+<li><a class="reference internal" href="#merging-patches" id="id11">Merging Patches</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#release-final-tasks" id="id12">Release Final Tasks</a><ul>
+<li><a class="reference internal" href="#update-documentation" id="id13">Update Documentation</a></li>
+<li><a class="reference internal" href="#tag-the-llvm-final-release" id="id14">Tag the LLVM Final Release</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#update-the-llvm-demo-page" id="id15">Update the LLVM Demo Page</a><ul>
+<li><a class="reference internal" href="#update-the-llvm-website" id="id16">Update the LLVM Website</a></li>
+<li><a class="reference internal" href="#announce-the-release" id="id17">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 <tt class="docutils literal"><span class="pre">llvm</span></tt>, <tt class="docutils literal"><span class="pre">clang</span></tt>, and other sub-projects,
+from the last known good revision. The branch’s name is
+<tt class="docutils literal"><span class="pre">release_XY</span></tt>, where <tt class="docutils literal"><span class="pre">X</span></tt> is the major and <tt class="docutils literal"><span class="pre">Y</span></tt> the minor release
+numbers. Use <tt class="docutils literal"><span class="pre">utils/release/tag.sh</span></tt> 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-python"><pre>$ 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>
+</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’
+<tt class="docutils literal"><span class="pre">autoconf</span></tt> and <tt class="docutils literal"><span class="pre">configure.ac</span></tt> versions from ‘<tt class="docutils literal"><span class="pre">X.Ysvn</span></tt>‘ to ‘<tt class="docutils literal"><span class="pre">X.Y</span></tt>‘.
+Update it on mainline as well to be the next version (‘<tt class="docutils literal"><span class="pre">X.Y+1svn</span></tt>‘).
+Regenerate the configure scripts for both <tt class="docutils literal"><span class="pre">llvm</span></tt> and the <tt class="docutils literal"><span class="pre">test-suite</span></tt>.</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-python"><pre>$ ./tag.sh -release X.Y.Z -rc $RC</pre>
+</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-python"><pre>$ ./export.sh -release X.Y.Z -rc $RC</pre>
+</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 <tt class="docutils literal"><span class="pre">clang</span></tt> binary distribution requires following the instructions
+<a class="reference internal" href="ReleaseProcess.html"><em>here</em></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 <tt class="docutils literal"><span class="pre">final/Phase3/Release+Asserts/llvmCore-3.8.1-RCn.install/</span></tt>,
+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"><em>here</em></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 (<tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt>), per target, and it has no
+regressions with the <tt class="docutils literal"><span class="pre">test-suite</span></tt> 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 <tt class="docutils literal"><span class="pre">release-testers@lists.llvm.org</span></tt> mailing list.</p>
+<p>The official testers list is in the file <tt class="docutils literal"><span class="pre">RELEASE_TESTERS.TXT</span></tt>, in the <tt class="docutils literal"><span class="pre">LLVM</span></tt>
+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 <tt class="docutils literal"><span class="pre">llvm-X.Y</span></tt>, <tt class="docutils literal"><span class="pre">llvm-test-X.Y</span></tt>, and the appropriate <tt class="docutils literal"><span class="pre">clang</span></tt>
+binary. Build LLVM. Run <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt> and the full LLVM test suite (<tt class="docutils literal"><span class="pre">make</span>
+<span class="pre">TEST=nightly</span> <span class="pre">report</span></tt>).</li>
+<li>Download <tt class="docutils literal"><span class="pre">llvm-X.Y</span></tt>, <tt class="docutils literal"><span class="pre">llvm-test-X.Y</span></tt>, and the <tt class="docutils literal"><span class="pre">clang</span></tt> sources. Compile
+everything. Run <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt> and the full LLVM test suite (<tt class="docutils literal"><span class="pre">make</span>
+<span class="pre">TEST=nightly</span> <span class="pre">report</span></tt>).</li>
+<li>Download <tt class="docutils literal"><span class="pre">llvm-X.Y</span></tt>, <tt class="docutils literal"><span class="pre">llvm-test-X.Y</span></tt>, and the appropriate <tt class="docutils literal"><span class="pre">clang</span></tt>
+binary. Build whole programs with it (ex. Chromium, Firefox, Apache) for
+your platform.</li>
+<li>Download <tt class="docutils literal"><span class="pre">llvm-X.Y</span></tt>, <tt class="docutils literal"><span class="pre">llvm-test-X.Y</span></tt>, and the appropriate <tt class="docutils literal"><span class="pre">clang</span></tt>
+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"><em>release process</em></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="release-patch-rules">
+<h3><a class="toc-backref" href="#id10">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="#id11">Merging Patches</a><a class="headerlink" href="#merging-patches" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">utils/release/merge.sh</span></tt> script can be used to merge individual revisions
+into any one of the llvm projects. To merge revision <tt class="docutils literal"><span class="pre">$N</span></tt> into project
+<tt class="docutils literal"><span class="pre">$PROJ</span></tt>, do:</p>
+<ol class="arabic simple">
+<li><tt class="docutils literal"><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></tt></li>
+<li><tt class="docutils literal"><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></tt></li>
+<li>Run regression tests.</li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">$PROJ.src</span></tt>. Run the <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">commit</span></tt> command printed out by <tt class="docutils literal"><span class="pre">merge.sh</span></tt>
+in step 2.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="release-final-tasks">
+<h3><a class="toc-backref" href="#id12">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="#id13">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="#id14">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-python"><pre>$ ./tag.sh -release X.Y.Z -final</pre>
+</div>
+</div>
+</div>
+<div class="section" id="update-the-llvm-demo-page">
+<h3><a class="toc-backref" href="#id15">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 <tt class="docutils literal"><span class="pre">clang</span></tt> binary and building LLVM.</p>
+<div class="section" id="update-the-llvm-website">
+<h4><a class="toc-backref" href="#id16">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 <tt class="docutils literal"><span class="pre">www</span></tt> module from Subversion.</li>
+<li>Create a new sub-directory <tt class="docutils literal"><span class="pre">X.Y</span></tt> in the releases directory.</li>
+<li>Commit the <tt class="docutils literal"><span class="pre">llvm</span></tt>, <tt class="docutils literal"><span class="pre">test-suite</span></tt>, <tt class="docutils literal"><span class="pre">clang</span></tt> source and binaries in this
+new directory.</li>
+<li>Copy and commit the <tt class="docutils literal"><span class="pre">llvm/docs</span></tt> and <tt class="docutils literal"><span class="pre">LICENSE.txt</span></tt> files into this new
+directory. The docs should be built with <tt class="docutils literal"><span class="pre">BUILD_FOR_WEBSITE=1</span></tt>.</li>
+<li>Commit the <tt class="docutils literal"><span class="pre">index.html</span></tt> to the <tt class="docutils literal"><span class="pre">release/X.Y</span></tt> directory to redirect (use
+from previous release).</li>
+<li>Update the <tt class="docutils literal"><span class="pre">releases/download.html</span></tt> file with the new release.</li>
+<li>Update the <tt class="docutils literal"><span class="pre">releases/index.html</span></tt> with the new release and link to release
+documentation.</li>
+<li>Finally, update the main page (<tt class="docutils literal"><span class="pre">index.html</span></tt> 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="#id17">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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/HowToSetUpLLVMStyleRTTI.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/HowToSetUpLLVMStyleRTTI.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/HowToSetUpLLVMStyleRTTI.html (added)
+++ www-releases/trunk/5.0.2/docs/HowToSetUpLLVMStyleRTTI.html Thu May 10 06:54:16 2018
@@ -0,0 +1,474 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How to set up LLVM-style RTTI for your class hierarchy — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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 <tt class="docutils literal"><span class="pre">classof</span></tt></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++"><div class="highlight"><pre><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="n">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="n">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 <tt class="docutils literal"><span class="pre">Shape</span></tt>, you will want to <tt class="docutils literal"><span class="pre">#include</span>
+<span class="pre">"llvm/Support/Casting.h"</span></tt>, which declares LLVM’s RTTI templates. That
+way your clients don’t even have to think about it.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Support/Casting.h"</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++"><div class="highlight"><pre> <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 <tt class="docutils literal"><span class="pre">Kind</span></tt> member encapsulated and
+private, but let the enum <tt class="docutils literal"><span class="pre">ShapeKind</span></tt> be public along with providing a
+<tt class="docutils literal"><span class="pre">getKind()</span></tt> method. This is convenient for clients so that they can do
+a <tt class="docutils literal"><span class="pre">switch</span></tt> 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 <tt class="docutils literal"><span class="pre">Kind</span></tt>.</p>
+<p>You might wonder why the <tt class="docutils literal"><span class="pre">Kind</span></tt> enum doesn’t have an entry for
+<tt class="docutils literal"><span class="pre">Shape</span></tt>. The reason for this is that since <tt class="docutils literal"><span class="pre">Shape</span></tt> is abstract
+(<tt class="docutils literal"><span class="pre">computeArea()</span> <span class="pre">=</span> <span class="pre">0;</span></tt>), 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
+<tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt>, 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 <tt class="docutils literal"><span class="pre">Kind</span></tt> 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 <tt class="docutils literal"><span class="pre">XXXKind</span></tt> from subclass constructors.</p>
+<p>Here is the code after that change:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <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="n">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="n">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 <tt class="docutils literal"><span class="pre">isa<></span></tt>/<tt class="docutils literal"><span class="pre">dyn_cast<></span></tt>
+should succeed). The default “99.9% of use cases” way to accomplish this
+is through a small static member function <tt class="docutils literal"><span class="pre">classof</span></tt>. 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++"><div class="highlight"><pre> <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="n">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="n">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 <tt class="docutils literal"><span class="pre">classof</span></tt> 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 <tt class="docutils literal"><span class="pre">Base</span></tt> to a type <tt class="docutils literal"><span class="pre">Derived</span></tt>, there needs to be a
+<tt class="docutils literal"><span class="pre">classof</span></tt> in <tt class="docutils literal"><span class="pre">Derived</span></tt> which will accept an object of type <tt class="docutils literal"><span class="pre">Base</span></tt>.</p>
+<p>To be concrete, consider the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">isa<></span></tt> test in this code will eventually boil
+down—after template instantiation and some other machinery—to a
+check roughly like <tt class="docutils literal"><span class="pre">Circle::classof(S)</span></tt>. For more information, see
+<a class="reference internal" href="#classof-contract"><em>The Contract of classof</em></a>.</p>
+<p>The argument to <tt class="docutils literal"><span class="pre">classof</span></tt> should always be an <em>ancestor</em> class because
+the implementation has logic to allow and optimize away
+upcasts/up-<tt class="docutils literal"><span class="pre">isa<></span></tt>‘s automatically. It is as though every class
+<tt class="docutils literal"><span class="pre">Foo</span></tt> automatically has a <tt class="docutils literal"><span class="pre">classof</span></tt> like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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="kc">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
+<tt class="docutils literal"><span class="pre">classof</span></tt> into <tt class="docutils literal"><span class="pre">Shape</span></tt>: all relevant classes derive from <tt class="docutils literal"><span class="pre">Shape</span></tt>,
+and <tt class="docutils literal"><span class="pre">Shape</span></tt> itself is abstract (has no entry in the <tt class="docutils literal"><span class="pre">Kind</span></tt> enum),
+so this notional inferred <tt class="docutils literal"><span class="pre">classof</span></tt> 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 <tt class="docutils literal"><span class="pre">Kind</span></tt> check inside <tt class="docutils literal"><span class="pre">classof</span></tt> 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 <tt class="docutils literal"><span class="pre">Kind</span></tt>
+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 <tt class="docutils literal"><span class="pre">classof</span></tt> must take them
+into account.</li>
+</ul>
+<p>Say that <tt class="docutils literal"><span class="pre">SpecialSquare</span></tt> and <tt class="docutils literal"><span class="pre">OtherSpecialSquare</span></tt> derive
+from <tt class="docutils literal"><span class="pre">Square</span></tt>, and so <tt class="docutils literal"><span class="pre">ShapeKind</span></tt> becomes:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <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 <tt class="docutils literal"><span class="pre">Square</span></tt>, we would need to modify the <tt class="docutils literal"><span class="pre">classof</span></tt> like so:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">SpecialSquare</span></tt> and <tt class="docutils literal"><span class="pre">OtherSpecialSquare</span></tt> “is-a”
+<tt class="docutils literal"><span class="pre">Square</span></tt>, and so <tt class="docutils literal"><span class="pre">classof</span></tt> needs to return <tt class="docutils literal"><span class="pre">true</span></tt> 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-python"><pre>| Shape
+ | Square
+ | SpecialSquare
+ | OtherSpecialSquare
+ | Circle</pre>
+</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 <tt class="docutils literal"><span class="pre">classof</span></tt>s are
+not updated to match the <tt class="docutils literal"><span class="pre">Kind</span></tt> enum when adding (or removing) classes to
+(from) the hierarchy.</p>
+<p>Continuing the example above, suppose we add a <tt class="docutils literal"><span class="pre">SomewhatSpecialSquare</span></tt> as
+a subclass of <tt class="docutils literal"><span class="pre">Square</span></tt>, and update the <tt class="docutils literal"><span class="pre">ShapeKind</span></tt> enum like so:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <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 <tt class="docutils literal"><span class="pre">Square::classof()</span></tt>, so it still
+looks like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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="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 <tt class="docutils literal"><span class="pre">SK_LastSquare</span></tt>
+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++"><div class="highlight"><pre> <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++"><div class="highlight"><pre> <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 <tt class="docutils literal"><span class="pre">Square::classof</span></tt> 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 <tt class="docutils literal"><span class="pre">classof</span></tt></a><a class="headerlink" href="#the-contract-of-classof" title="Permalink to this headline">¶</a></h3>
+<p>To be more precise, let <tt class="docutils literal"><span class="pre">classof</span></tt> be inside a class <tt class="docutils literal"><span class="pre">C</span></tt>. Then the
+contract for <tt class="docutils literal"><span class="pre">classof</span></tt> is “return <tt class="docutils literal"><span class="pre">true</span></tt> if the dynamic type of the
+argument is-a <tt class="docutils literal"><span class="pre">C</span></tt>”. 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 <tt class="docutils literal"><span class="pre">classof</span></tt>.
+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 <tt class="docutils literal"><span class="pre">Decl</span></tt> hierarchy is done very similarly to the example setup
+demonstrated in this tutorial.
+The key part is how to then incorporate <tt class="docutils literal"><span class="pre">DeclContext</span></tt>: all that is needed
+is in <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">DeclContext::classof(const</span> <span class="pre">Decl</span> <span class="pre">*)</span></tt>, which asks the question
+“Given a <tt class="docutils literal"><span class="pre">Decl</span></tt>, how can I determine if it is-a <tt class="docutils literal"><span class="pre">DeclContext</span></tt>?”.
+It answers this with a simple switch over the set of <tt class="docutils literal"><span class="pre">Decl</span></tt> “kinds”, and
+returning true for ones that are known to be <tt class="docutils literal"><span class="pre">DeclContext</span></tt>‘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 <tt class="docutils literal"><span class="pre">Kind</span></tt> enum should have one entry per concrete class, ordered
+according to a preorder traversal of the inheritance tree.</li>
+<li>The argument to <tt class="docutils literal"><span class="pre">classof</span></tt> should be a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">Base</span> <span class="pre">*</span></tt>, where <tt class="docutils literal"><span class="pre">Base</span></tt>
+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 <tt class="docutils literal"><span class="pre">isa<></span></tt> already handles this case and optimizes it.</li>
+<li>For each class in the hierarchy that has no children, implement a
+<tt class="docutils literal"><span class="pre">classof</span></tt> that checks only against its <tt class="docutils literal"><span class="pre">Kind</span></tt>.</li>
+<li>For each class in the hierarchy that has children, implement a
+<tt class="docutils literal"><span class="pre">classof</span></tt> that checks a range of the first child’s <tt class="docutils literal"><span class="pre">Kind</span></tt> and the
+last child’s <tt class="docutils literal"><span class="pre">Kind</span></tt>.</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/HowToSubmitABug.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/HowToSubmitABug.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/HowToSubmitABug.html (added)
+++ www-releases/trunk/5.0.2/docs/HowToSubmitABug.html Thu May 10 06:54:16 2018
@@ -0,0 +1,280 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How to submit an LLVM bug report — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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 GCC 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 <tt class="docutils literal"><span class="pre">clang</span></tt> command line as you were when the crash
+occurred, but with the following extra command line options:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-O0</span> <span class="pre">-emit-llvm</span></tt>: If <tt class="docutils literal"><span class="pre">clang</span></tt> 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"><em>front-end bugs</em></a>.</li>
+<li><tt class="docutils literal"><span class="pre">-emit-llvm</span></tt>: If <tt class="docutils literal"><span class="pre">clang</span></tt> 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 <tt class="docutils literal"><span class="pre">clang</span></tt>
+command that resulted in the crash, but add the <tt class="docutils literal"><span class="pre">-save-temps</span></tt> option.
+The compiler will crash again, but it will leave behind a <tt class="docutils literal"><span class="pre">foo.i</span></tt> file
+(containing preprocessed C source code) and possibly <tt class="docutils literal"><span class="pre">foo.s</span></tt> for each
+compiled <tt class="docutils literal"><span class="pre">foo.c</span></tt> file. Send us the <tt class="docutils literal"><span class="pre">foo.i</span></tt> file, along with the options
+you passed to <tt class="docutils literal"><span class="pre">clang</span></tt>, 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
+<tt class="docutils literal"><span class="pre">.bc</span></tt> file by passing “<tt class="docutils literal"><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></tt>”.
+Then run:</p>
+<div class="highlight-bash"><div class="highlight"><pre>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"><div class="highlight"><pre>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 <tt class="docutils literal"><span class="pre">opt</span></tt>.</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 “<tt class="docutils literal"><span class="pre">-emit-llvm</span> <span class="pre">-c</span> <span class="pre">-o</span> <span class="pre">foo.bc</span></tt>” 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><tt class="docutils literal"><span class="pre">llc</span> <span class="pre">foo.bc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">llc</span> <span class="pre">foo.bc</span> <span class="pre">-relocation-model=pic</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">llc</span> <span class="pre">foo.bc</span> <span class="pre">-relocation-model=static</span></tt></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><tt class="docutils literal"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span></tt></li>
+<li><tt class="docutils literal"><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></tt></li>
+<li><tt class="docutils literal"><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></tt></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"><div class="highlight"><pre>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
+<tt class="docutils literal"><span class="pre">bugpoint</span></tt>. The process <tt class="docutils literal"><span class="pre">bugpoint</span></tt> 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,
+<tt class="docutils literal"><span class="pre">bugpoint</span></tt> 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"><div class="highlight"><pre>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"><div class="highlight"><pre>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 <tt class="docutils literal"><span class="pre">llvm/test</span></tt> 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"><div class="highlight"><pre><span class="nb">cd </span>llvm/test/../../program
+make bugpoint-jit
+</pre></div>
+</div>
+<p>At the end of a successful <tt class="docutils literal"><span class="pre">bugpoint</span></tt> 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 <tt class="docutils literal"><span class="pre">bugpoint</span></tt> 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"><div class="highlight"><pre>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"><div class="highlight"><pre>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"><div class="highlight"><pre>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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/HowToUseAttributes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/HowToUseAttributes.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/HowToUseAttributes.html (added)
+++ www-releases/trunk/5.0.2/docs/HowToUseAttributes.html Thu May 10 06:54:16 2018
@@ -0,0 +1,169 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How To Use Attributes — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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"><tt class="docutils literal"><span class="pre">Attribute</span></tt></a></li>
+<li><a class="reference internal" href="#attributelist" id="id3"><tt class="docutils literal"><span class="pre">AttributeList</span></tt></a></li>
+<li><a class="reference internal" href="#attrbuilder" id="id4"><tt class="docutils literal"><span class="pre">AttrBuilder</span></tt></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 <tt class="docutils literal"><span class="pre">Attribute</span></tt> object represents a single attribute that’s
+uniqued. You use the <tt class="docutils literal"><span class="pre">Attribute::get</span></tt> methods to create a new <tt class="docutils literal"><span class="pre">Attribute</span></tt>
+object. An attribute can be a single “enum” value (the enum being the
+<tt class="docutils literal"><span class="pre">Attribute::AttrKind</span></tt> enum), a string representing a target-dependent
+attribute, or an attribute-value pair. Some examples:</p>
+<ul class="simple">
+<li>Target-independent: <tt class="docutils literal"><span class="pre">noinline</span></tt>, <tt class="docutils literal"><span class="pre">zext</span></tt></li>
+<li>Target-dependent: <tt class="docutils literal"><span class="pre">"no-sse"</span></tt>, <tt class="docutils literal"><span class="pre">"thumb2"</span></tt></li>
+<li>Attribute-value pair: <tt class="docutils literal"><span class="pre">"cpu"</span> <span class="pre">=</span> <span class="pre">"cortex-a8"</span></tt>, <tt class="docutils literal"><span class="pre">align</span> <span class="pre">=</span> <span class="pre">4</span></tt></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"><tt class="docutils literal"><span class="pre">Attribute</span></tt></a><a class="headerlink" href="#attribute" title="Permalink to this headline">¶</a></h2>
+<p>An <tt class="docutils literal"><span class="pre">Attribute</span></tt> 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"><tt class="docutils literal"><span class="pre">AttributeList</span></tt></a><a class="headerlink" href="#attributelist" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">AttributeList</span></tt> 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 <tt class="docutils literal"><span class="pre">AttributeList::FunctionIndex</span></tt>; the return type’s attributes are at
+index <tt class="docutils literal"><span class="pre">AttributeList::ReturnIndex</span></tt>; and the function’s parameters’ attributes
+are at indices 1, ..., n (where ‘n’ is the number of parameters). Most methods
+on the <tt class="docutils literal"><span class="pre">AttributeList</span></tt> class take an index parameter.</p>
+<p>An <tt class="docutils literal"><span class="pre">AttributeList</span></tt> is also a uniqued and immutable object. You create an
+<tt class="docutils literal"><span class="pre">AttributeList</span></tt> through the <tt class="docutils literal"><span class="pre">AttributeList::get</span></tt> methods. You can add and
+remove attributes, which result in the creation of a new <tt class="docutils literal"><span class="pre">AttributeList</span></tt>.</p>
+<p>An <tt class="docutils literal"><span class="pre">AttributeList</span></tt> object is designed to be passed around by value.</p>
+<p>Note: It is advised that you do <em>not</em> use the <tt class="docutils literal"><span class="pre">AttributeList</span></tt> “introspection”
+methods (e.g. <tt class="docutils literal"><span class="pre">Raw</span></tt>, <tt class="docutils literal"><span class="pre">getRawPointer</span></tt>, 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"><tt class="docutils literal"><span class="pre">AttrBuilder</span></tt></a><a class="headerlink" href="#attrbuilder" title="Permalink to this headline">¶</a></h2>
+<p>Lastly, we have a “builder” class to help create the <tt class="docutils literal"><span class="pre">AttributeList</span></tt> object
+without having to create several different intermediate uniqued
+<tt class="docutils literal"><span class="pre">AttributeList</span></tt> objects. The <tt class="docutils literal"><span class="pre">AttrBuilder</span></tt> class allows you to add and
+remove attributes at will. The attributes won’t be uniqued until you call the
+appropriate <tt class="docutils literal"><span class="pre">AttributeList::get</span></tt> method.</p>
+<p>An <tt class="docutils literal"><span class="pre">AttrBuilder</span></tt> 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 <tt class="docutils literal"><span class="pre">AttrBuilder::addRawValue()</span></tt>
+method or the <tt class="docutils literal"><span class="pre">AttrBuilder(uint64_t</span> <span class="pre">Val)</span></tt> 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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/HowToUseInstrMappings.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/HowToUseInstrMappings.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/HowToUseInstrMappings.html (added)
+++ www-releases/trunk/5.0.2/docs/HowToUseInstrMappings.html Thu May 10 06:54:16 2018
@@ -0,0 +1,270 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How To Use Instruction Mappings — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.html" />
+ <link rel="up" title="Writing an LLVM Backend" href="WritingAnLLVMBackend.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">
+ <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><a href="WritingAnLLVMBackend.html" accesskey="U">Writing an LLVM Backend</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <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"><tt class="docutils literal"><span class="pre">InstrMapping</span></tt> 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"><tt class="docutils literal"><span class="pre">InstrMapping</span></tt> 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 <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> class as a base. Each model sets
+various fields of the <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> 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
+<tt class="docutils literal"><span class="pre">XXXInstrInfo.inc</span></tt> file along with the functions to query them. Following
+is the definition of <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> class definied in Target.td file:</p>
+<div class="highlight-text"><div class="highlight"><pre>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
+<tt class="docutils literal"><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></tt> which
+takes a non-predicated instruction and returns its predicated true or false form
+depending on some input flag, <tt class="docutils literal"><span class="pre">inPredSense</span></tt>. 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 <tt class="docutils literal"><span class="pre">InstrMapping</span></tt>
+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"><div class="highlight"><pre>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
+<tt class="docutils literal"><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></tt> to query
+the table. Here, Function <tt class="docutils literal"><span class="pre">getPredOpcode</span></tt> 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"><div class="highlight"><pre>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"><div class="highlight"><pre>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 <tt class="docutils literal"><span class="pre">PredRel</span></tt> as a base class.
+This is extremely important since TableGen uses it as a filter for selecting
+instructions for <tt class="docutils literal"><span class="pre">getPredOpcode</span></tt> model. Any instruction not derived from
+<tt class="docutils literal"><span class="pre">PredRel</span></tt> is excluded from the analysis. <tt class="docutils literal"><span class="pre">BaseOpcode</span></tt> is another important
+field. Since it’s selected as a <tt class="docutils literal"><span class="pre">RowFields</span></tt> of the model, it is required
+to have the same value for all 3 instructions in order to be related. Next,
+<tt class="docutils literal"><span class="pre">PredSense</span></tt> is used to determine their column positions by comparing its value
+with <tt class="docutils literal"><span class="pre">KeyCol</span></tt> and <tt class="docutils literal"><span class="pre">ValueCols</span></tt>. If an instruction sets its <tt class="docutils literal"><span class="pre">PredSense</span></tt>
+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">
+ <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><a href="WritingAnLLVMBackend.html" >Writing an LLVM Backend</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/InAlloca.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/InAlloca.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/InAlloca.html (added)
+++ www-releases/trunk/5.0.2/docs/InAlloca.html Thu May 10 06:54:16 2018
@@ -0,0 +1,241 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Design and Usage of the InAlloca Attribute — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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"><em>inalloca</em></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 <tt class="docutils literal"><span class="pre">Foo</span></tt> objects to <tt class="docutils literal"><span class="pre">g</span></tt> in the
+32-bit Microsoft C++ ABI.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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="n">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="n">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"><div class="highlight"><pre>%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"><em>llvm.stacksave</em></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 <tt class="docutils literal"><span class="pre">b</span></tt> before restoring the stack pointer. If the
+constructor does not unwind, <tt class="docutils literal"><span class="pre">g</span></tt> is called. In the Microsoft C++ ABI,
+<tt class="docutils literal"><span class="pre">g</span></tt> will destroy its arguments, and then the stack is restored in
+<tt class="docutils literal"><span class="pre">f</span></tt>.</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 <tt class="docutils literal"><span class="pre">freea</span></tt>
+or <tt class="docutils literal"><span class="pre">afree</span></tt> 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++"><div class="highlight"><pre><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="n">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="n">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 <tt class="docutils literal"><span class="pre">bar</span></tt>‘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 <tt class="docutils literal"><span class="pre">Foo</span></tt>‘s default constructor. By
+wrapping the evaluation of the inner <tt class="docutils literal"><span class="pre">bar</span></tt> 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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/docs/LLVMBuild.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/docs/LLVMBuild.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/docs/LLVMBuild.html (added)
+++ www-releases/trunk/5.0.2/docs/LLVMBuild.html Thu May 10 06:54:16 2018
@@ -0,0 +1,383 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVMBuild Guide — LLVM 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 5 documentation" href="index.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">
+ <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">
+
+ <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 <tt class="docutils literal"><span class="pre">LLVMBuild</span></tt> 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
+<tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> 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 <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> 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 <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt>
+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"><em>CMake</em></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 <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> 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 <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> 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"><em>llvm-build</em></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"><em>TableGen</em></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 <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> 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"><div class="highlight"><pre><span class="c">; Comments start with a semi-colon.</span>
+
+<span class="c">; Sections are declared using square brackets.</span>
+<span class="k">[component_0]</span>
+
+<span class="c">; Properties are declared using '=' and are contained in the previous section.</span>
+<span class="c">;</span>
+<span class="c">; We support simple string and boolean scalar values and list values, where</span>
+<span class="c">; items are separated by spaces. There is no support for quoting, and so</span>
+<span class="c">; 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"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">common</span></tt>. The
+common component may define the following properties:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">subdirectories</span></tt> <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 <tt class="docutils literal"><span class="pre">component</span></tt>. 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
+(<tt class="docutils literal"><span class="pre">component_0</span></tt>, <tt class="docutils literal"><span class="pre">component_1</span></tt>, 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 <tt class="docutils literal"><span class="pre">common</span></tt> 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"><tt class="docutils literal"><span class="pre">type</span></tt> <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"><tt class="docutils literal"><span class="pre">name</span></tt> <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"><tt class="docutils literal"><span class="pre">parent</span></tt> <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 <tt class="docutils literal"><span class="pre">$ROOT</span></tt> 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"><tt class="docutils literal"><span class="pre">dependencies</span></tt> <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"><tt class="docutils literal"><span class="pre">Group</span></tt> and <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt> 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"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Group</span></tt></p>
+<p>Group components exist purely to allow additional arbitrary structuring
+of the logical components tree. For example, one might define a
+<tt class="docutils literal"><span class="pre">Libraries</span></tt> group to hold all of the root library components.</p>
+<p><tt class="docutils literal"><span class="pre">Group</span></tt> components have no additionally properties.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Library</span></tt></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"><tt class="docutils literal"><span class="pre">library_name</span></tt> <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"><tt class="docutils literal"><span class="pre">required_libraries</span></tt> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <tt class="docutils literal"><span class="pre">Library</span></tt> or <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt>
+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 <tt class="docutils literal"><span class="pre">required_libraries</span></tt> for the components the tool needs.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">add_to_library_groups</span></tt> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt> components which
+this component is also part of. This allows nesting groups of
+components. For example, the <tt class="docutils literal"><span class="pre">X86</span></tt> target might define a library
+group for all of the <tt class="docutils literal"><span class="pre">X86</span></tt> components. That library group might
+then be included in the <tt class="docutils literal"><span class="pre">all-targets</span></tt> library group.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">installed</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this library is installed. Libraries that are not installed
+are only reported by <tt class="docutils literal"><span class="pre">llvm-config</span></tt> when it is run as part of a
+development directory.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">LibraryGroup</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">LibraryGroup</span></tt> 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"><tt class="docutils literal"><span class="pre">required_libraries</span></tt> <strong>[optional]</strong></p>
+<p>See the <tt class="docutils literal"><span class="pre">Library</span></tt> type for a description of this property.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">add_to_library_groups</span></tt> <strong>[optional]</strong></p>
+<p>See the <tt class="docutils literal"><span class="pre">Library</span></tt> type for a description of this property.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">TargetGroup</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">TargetGroup</span></tt> components are an extension of <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt>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 <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt> properties in
+addition to:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">has_asmparser</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines an assembly parser.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">has_asmprinter</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines an assembly printer.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">has_disassembler</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines a disassembler.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">has_jit</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target supports JIT compilation.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Tool</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">Tool</span></tt> 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"><tt class="docutils literal"><span class="pre">required_libraries</span></tt> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <tt class="docutils literal"><span class="pre">Library</span></tt> or <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt>
+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
+<tt class="docutils literal"><span class="pre">required_libraries</span></tt>).</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 <tt class="docutils literal"><span class="pre">dependencies</span></tt>.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">BuildTool</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">BuildTool</span></tt> components are like <tt class="docutils literal"><span class="pre">Tool</span></tt> 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><tt class="docutils literal"><span class="pre">BuildTool</span></tt> components currently use the exact same properties as
+<tt class="docutils literal"><span class="pre">Tool</span></tt> 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">
+ <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">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-05-10.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list