[www-releases] r290368 - Add 3.9.1 docs.
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Thu Dec 22 12:04:06 PST 2016
Added: www-releases/trunk/3.9.1/docs/SourceLevelDebugging.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/SourceLevelDebugging.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/SourceLevelDebugging.html (added)
+++ www-releases/trunk/3.9.1/docs/SourceLevelDebugging.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,1455 @@
+
+<!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>Source Level Debugging with LLVM — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="Auto-Vectorization in LLVM" href="Vectorizers.html" />
+ <link rel="prev" title="System Library" href="SystemLibrary.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="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SystemLibrary.html" title="System Library"
+ 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="source-level-debugging-with-llvm">
+<h1>Source Level Debugging with LLVM<a class="headerlink" href="#source-level-debugging-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="#introduction" id="id7">Introduction</a><ul>
+<li><a class="reference internal" href="#philosophy-behind-llvm-debugging-information" id="id8">Philosophy behind LLVM debugging information</a></li>
+<li><a class="reference internal" href="#debug-information-consumers" id="id9">Debug information consumers</a></li>
+<li><a class="reference internal" href="#debugging-optimized-code" id="id10">Debugging optimized code</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#debugging-information-format" id="id11">Debugging information format</a><ul>
+<li><a class="reference internal" href="#debugger-intrinsic-functions" id="id12">Debugger intrinsic functions</a><ul>
+<li><a class="reference internal" href="#llvm-dbg-declare" id="id13"><tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-dbg-value" id="id14"><tt class="docutils literal"><span class="pre">llvm.dbg.value</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#object-lifetimes-and-scoping" id="id15">Object lifetimes and scoping</a></li>
+<li><a class="reference internal" href="#c-c-front-end-specific-debug-information" id="id16">C/C++ front-end specific debug information</a><ul>
+<li><a class="reference internal" href="#c-c-source-file-information" id="id17">C/C++ source file information</a></li>
+<li><a class="reference internal" href="#c-c-global-variable-information" id="id18">C/C++ global variable information</a></li>
+<li><a class="reference internal" href="#c-c-function-information" id="id19">C/C++ function information</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id3" id="id20">Debugging information format</a><ul>
+<li><a class="reference internal" href="#debugging-information-extension-for-objective-c-properties" id="id21">Debugging Information Extension for Objective C Properties</a><ul>
+<li><a class="reference internal" href="#id4" id="id22">Introduction</a></li>
+<li><a class="reference internal" href="#proposal" id="id23">Proposal</a></li>
+<li><a class="reference internal" href="#new-dwarf-tags" id="id24">New DWARF Tags</a></li>
+<li><a class="reference internal" href="#new-dwarf-attributes" id="id25">New DWARF Attributes</a></li>
+<li><a class="reference internal" href="#new-dwarf-constants" id="id26">New DWARF Constants</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#name-accelerator-tables" id="id27">Name Accelerator Tables</a><ul>
+<li><a class="reference internal" href="#id5" id="id28">Introduction</a></li>
+<li><a class="reference internal" href="#hash-tables" id="id29">Hash Tables</a><ul>
+<li><a class="reference internal" href="#standard-hash-tables" id="id30">Standard Hash Tables</a></li>
+<li><a class="reference internal" href="#name-hash-tables" id="id31">Name Hash Tables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#details" id="id32">Details</a><ul>
+<li><a class="reference internal" href="#header-layout" id="id33">Header Layout</a></li>
+<li><a class="reference internal" href="#fixed-lookup" id="id34">Fixed Lookup</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id6" id="id35">Contents</a></li>
+<li><a class="reference internal" href="#language-extensions-and-file-format-changes" id="id36">Language Extensions and File Format Changes</a><ul>
+<li><a class="reference internal" href="#objective-c-extensions" id="id37">Objective-C Extensions</a></li>
+<li><a class="reference internal" href="#mach-o-changes" id="id38">Mach-O Changes</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#codeview-debug-info-format" id="id39">CodeView Debug Info Format</a><ul>
+<li><a class="reference internal" href="#format-background" id="id40">Format Background</a></li>
+<li><a class="reference internal" href="#working-with-codeview" id="id41">Working with CodeView</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 debug
+information in LLVM. It describes the <a class="reference internal" href="#format"><em>actual format that the LLVM debug
+information takes</em></a>, which is useful for those interested in creating
+front-ends or dealing directly with the information. Further, this document
+provides specific examples of what debug information for C/C++ looks like.</p>
+<div class="section" id="philosophy-behind-llvm-debugging-information">
+<h3><a class="toc-backref" href="#id8">Philosophy behind LLVM debugging information</a><a class="headerlink" href="#philosophy-behind-llvm-debugging-information" title="Permalink to this headline">¶</a></h3>
+<p>The idea of the LLVM debugging information is to capture how the important
+pieces of the source-language’s Abstract Syntax Tree map onto LLVM code.
+Several design aspects have shaped the solution that appears here. The
+important ones are:</p>
+<ul class="simple">
+<li>Debugging information should have very little impact on the rest of the
+compiler. No transformations, analyses, or code generators should need to
+be modified because of debugging information.</li>
+<li>LLVM optimizations should interact in <a class="reference internal" href="#intro-debugopt"><em>well-defined and easily described
+ways</em></a> with the debugging information.</li>
+<li>Because LLVM is designed to support arbitrary programming languages,
+LLVM-to-LLVM tools should not need to know anything about the semantics of
+the source-level-language.</li>
+<li>Source-level languages are often <strong>widely</strong> different from one another.
+LLVM should not put any restrictions of the flavor of the source-language,
+and the debugging information should work with any language.</li>
+<li>With code generator support, it should be possible to use an LLVM compiler
+to compile a program to native machine code and standard debugging
+formats. This allows compatibility with traditional machine-code level
+debuggers, like GDB or DBX.</li>
+</ul>
+<p>The approach used by the LLVM implementation is to use a small set of
+<a class="reference internal" href="#format-common-intrinsics"><em>intrinsic functions</em></a> to define a mapping
+between LLVM program objects and the source-level objects. The description of
+the source-level program is maintained in LLVM metadata in an
+<a class="reference internal" href="#ccxx-frontend"><em>implementation-defined format</em></a> (the C/C++ front-end
+currently uses working draft 7 of the <a class="reference external" href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3 standard</a>).</p>
+<p>When a program is being debugged, a debugger interacts with the user and turns
+the stored debug information into source-language specific information. As
+such, a debugger must be aware of the source-language, and is thus tied to a
+specific language or family of languages.</p>
+</div>
+<div class="section" id="debug-information-consumers">
+<h3><a class="toc-backref" href="#id9">Debug information consumers</a><a class="headerlink" href="#debug-information-consumers" title="Permalink to this headline">¶</a></h3>
+<p>The role of debug information is to provide meta information normally stripped
+away during the compilation process. This meta information provides an LLVM
+user a relationship between generated code and the original program source
+code.</p>
+<p>Currently, there are two backend consumers of debug info: DwarfDebug and
+CodeViewDebug. DwarfDebug produces DWARF sutable for use with GDB, LLDB, and
+other DWARF-based debuggers. <a class="reference internal" href="#codeview"><em>CodeViewDebug</em></a> produces CodeView,
+the Microsoft debug info format, which is usable with Microsoft debuggers such
+as Visual Studio and WinDBG. LLVM’s debug information format is mostly derived
+from and inspired by DWARF, but it is feasible to translate into other target
+debug info formats such as STABS.</p>
+<p>It would also be reasonable to use debug information to feed profiling tools
+for analysis of generated code, or, tools for reconstructing the original
+source from generated code.</p>
+</div>
+<div class="section" id="debugging-optimized-code">
+<span id="intro-debugopt"></span><h3><a class="toc-backref" href="#id10">Debugging optimized code</a><a class="headerlink" href="#debugging-optimized-code" title="Permalink to this headline">¶</a></h3>
+<p>An extremely high priority of LLVM debugging information is to make it interact
+well with optimizations and analysis. In particular, the LLVM debug
+information provides the following guarantees:</p>
+<ul class="simple">
+<li>LLVM debug information <strong>always provides information to accurately read
+the source-level state of the program</strong>, regardless of which LLVM
+optimizations have been run, and without any modification to the
+optimizations themselves. However, some optimizations may impact the
+ability to modify the current state of the program with a debugger, such
+as setting program variables, or calling functions that have been
+deleted.</li>
+<li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM
+debugging information, allowing them to update the debugging information
+as they perform aggressive optimizations. This means that, with effort,
+the LLVM optimizers could optimize debug code just as well as non-debug
+code.</li>
+<li>LLVM debug information does not prevent optimizations from
+happening (for example inlining, basic block reordering/merging/cleanup,
+tail duplication, etc).</li>
+<li>LLVM debug information is automatically optimized along with the rest of
+the program, using existing facilities. For example, duplicate
+information is automatically merged by the linker, and unused information
+is automatically removed.</li>
+</ul>
+<p>Basically, the debug information allows you to compile a program with
+“<tt class="docutils literal"><span class="pre">-O0</span> <span class="pre">-g</span></tt>” and get full debug information, allowing you to arbitrarily modify
+the program as it executes from a debugger. Compiling a program with
+“<tt class="docutils literal"><span class="pre">-O3</span> <span class="pre">-g</span></tt>” gives you full debug information that is always available and
+accurate for reading (e.g., you get accurate stack traces despite tail call
+elimination and inlining), but you might lose the ability to modify the program
+and call functions where were optimized out of the program, or inlined away
+completely.</p>
+<p><a class="reference internal" href="TestingGuide.html#test-suite-quickstart"><em>LLVM test suite</em></a> provides a framework to test
+optimizer’s handling of debugging information. It can be run like this:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>llvm/projects/test-suite/MultiSource/Benchmarks <span class="c"># or some other level</span>
+% make <span class="nv">TEST</span><span class="o">=</span>dbgopt
+</pre></div>
+</div>
+<p>This will test impact of debugging information on optimization passes. If
+debugging information influences optimization passes then it will be reported
+as a failure. See <a class="reference internal" href="TestingGuide.html"><em>LLVM Testing Infrastructure Guide</em></a> for more information on LLVM test
+infrastructure and how to run various tests.</p>
+</div>
+</div>
+<div class="section" id="debugging-information-format">
+<span id="format"></span><h2><a class="toc-backref" href="#id11">Debugging information format</a><a class="headerlink" href="#debugging-information-format" title="Permalink to this headline">¶</a></h2>
+<p>LLVM debugging information has been carefully designed to make it possible for
+the optimizer to optimize the program and debugging information without
+necessarily having to know anything about debugging information. In
+particular, the use of metadata avoids duplicated debugging information from
+the beginning, and the global dead code elimination pass automatically deletes
+debugging information for a function if it decides to delete the function.</p>
+<p>To do this, most of the debugging information (descriptors for types,
+variables, functions, source files, etc) is inserted by the language front-end
+in the form of LLVM metadata.</p>
+<p>Debug information is designed to be agnostic about the target debugger and
+debugging information representation (e.g. DWARF/Stabs/etc). It uses a generic
+pass to decode the information that represents variables, types, functions,
+namespaces, etc: this allows for arbitrary source-language semantics and
+type-systems to be used, as long as there is a module written for the target
+debugger to interpret the information.</p>
+<p>To provide basic functionality, the LLVM debugger does have to make some
+assumptions about the source-level language being debugged, though it keeps
+these to a minimum. The only common features that the LLVM debugger assumes
+exist are <a class="reference external" href="LangRef.html#difile">source files</a>, and <a class="reference external" href="LangRef.html#diglobalvariable">program objects</a>. These abstract objects are used by a
+debugger to form stack traces, show information about local variables, etc.</p>
+<p>This section of the documentation first describes the representation aspects
+common to any source-language. <a class="reference internal" href="#ccxx-frontend"><em>C/C++ front-end specific debug information</em></a> describes the data layout
+conventions used by the C and C++ front-ends.</p>
+<p>Debug information descriptors are <a class="reference external" href="LangRef.html#specialized-metadata">specialized metadata nodes</a>, first-class subclasses of <tt class="docutils literal"><span class="pre">Metadata</span></tt>.</p>
+<div class="section" id="debugger-intrinsic-functions">
+<span id="format-common-intrinsics"></span><h3><a class="toc-backref" href="#id12">Debugger intrinsic functions</a><a class="headerlink" href="#debugger-intrinsic-functions" title="Permalink to this headline">¶</a></h3>
+<p>LLVM uses several intrinsic functions (name prefixed with “<tt class="docutils literal"><span class="pre">llvm.dbg</span></tt>”) to
+provide debug information at various points in generated code.</p>
+<div class="section" id="llvm-dbg-declare">
+<h4><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt></a><a class="headerlink" href="#llvm-dbg-declare" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic provides information about a local element (e.g., variable).
+The first argument is metadata holding the alloca for the variable. The second
+argument is a <a class="reference external" href="LangRef.html#dilocalvariable">local variable</a> containing a
+description of the variable. The third argument is a <a class="reference external" href="LangRef.html#diexpression">complex expression</a>.</p>
+</div>
+<div class="section" id="llvm-dbg-value">
+<h4><a class="toc-backref" href="#id14"><tt class="docutils literal"><span class="pre">llvm.dbg.value</span></tt></a><a class="headerlink" href="#llvm-dbg-value" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.dbg.value</span><span class="p">(</span><span class="kt">metadata</span><span class="p">,</span> <span class="k">i64</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic provides information when a user source variable is set to a new
+value. The first argument is the new value (wrapped as metadata). The second
+argument is the offset in the user source variable where the new value is
+written. The third argument is a <a class="reference external" href="LangRef.html#dilocalvariable">local variable</a> containing a description of the variable. The
+fourth argument is a <a class="reference external" href="LangRef.html#diexpression">complex expression</a>.</p>
+</div>
+</div>
+</div>
+<div class="section" id="object-lifetimes-and-scoping">
+<h2><a class="toc-backref" href="#id15">Object lifetimes and scoping</a><a class="headerlink" href="#object-lifetimes-and-scoping" title="Permalink to this headline">¶</a></h2>
+<p>In many languages, the local variables in functions can have their lifetimes or
+scopes limited to a subset of a function. In the C family of languages, for
+example, variables are only live (readable and writable) within the source
+block that they are defined in. In functional languages, values are only
+readable after they have been defined. Though this is a very obvious concept,
+it is non-trivial to model in LLVM, because it has no notion of scoping in this
+sense, and does not want to be tied to a language’s scoping rules.</p>
+<p>In order to handle this, the LLVM debug format uses the metadata attached to
+llvm instructions to encode line number and scoping information. Consider the
+following C fragment, for example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="mf">1.</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
+<span class="mf">2.</span> <span class="kt">int</span> <span class="n">X</span> <span class="o">=</span> <span class="mi">21</span><span class="p">;</span>
+<span class="mf">3.</span> <span class="kt">int</span> <span class="n">Y</span> <span class="o">=</span> <span class="mi">22</span><span class="p">;</span>
+<span class="mf">4.</span> <span class="p">{</span>
+<span class="mf">5.</span> <span class="kt">int</span> <span class="n">Z</span> <span class="o">=</span> <span class="mi">23</span><span class="p">;</span>
+<span class="mf">6.</span> <span class="n">Z</span> <span class="o">=</span> <span class="n">X</span><span class="p">;</span>
+<span class="mf">7.</span> <span class="p">}</span>
+<span class="mf">8.</span> <span class="n">X</span> <span class="o">=</span> <span class="n">Y</span><span class="p">;</span>
+<span class="mf">9.</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Compiled to LLVM, this function would be represented like this:</p>
+<div class="highlight-text"><div class="highlight"><pre>; Function Attrs: nounwind ssp uwtable
+define void @foo() #0 !dbg !4 {
+entry:
+ %X = alloca i32, align 4
+ %Y = alloca i32, align 4
+ %Z = alloca i32, align 4
+ call void @llvm.dbg.declare(metadata i32* %X, metadata !11, metadata !13), !dbg !14
+ store i32 21, i32* %X, align 4, !dbg !14
+ call void @llvm.dbg.declare(metadata i32* %Y, metadata !15, metadata !13), !dbg !16
+ store i32 22, i32* %Y, align 4, !dbg !16
+ call void @llvm.dbg.declare(metadata i32* %Z, metadata !17, metadata !13), !dbg !19
+ store i32 23, i32* %Z, align 4, !dbg !19
+ %0 = load i32, i32* %X, align 4, !dbg !20
+ store i32 %0, i32* %Z, align 4, !dbg !21
+ %1 = load i32, i32* %Y, align 4, !dbg !22
+ store i32 %1, i32* %X, align 4, !dbg !23
+ ret void, !dbg !24
+}
+
+; Function Attrs: nounwind readnone
+declare void @llvm.dbg.declare(metadata, metadata, metadata) #1
+
+attributes #0 = { nounwind ssp uwtable "less-precise-fpmad"="false" "no-frame-pointer-elim"="true" "no-frame-pointer-elim-non-leaf" "no-infs-fp-math"="false" "no-nans-fp-math"="false" "stack-protector-buffer-size"="8" "unsafe-fp-math"="false" "use-soft-float"="false" }
+attributes #1 = { nounwind readnone }
+
+!llvm.dbg.cu = !{!0}
+!llvm.module.flags = !{!7, !8, !9}
+!llvm.ident = !{!10}
+
+!0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)", isOptimized: false, runtimeVersion: 0, emissionKind: FullDebug, enums: !2, retainedTypes: !2, subprograms: !3, globals: !2, imports: !2)
+!1 = !DIFile(filename: "/dev/stdin", directory: "/Users/dexonsmith/data/llvm/debug-info")
+!2 = !{}
+!3 = !{!4}
+!4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: false, variables: !2)
+!5 = !DISubroutineType(types: !6)
+!6 = !{null}
+!7 = !{i32 2, !"Dwarf Version", i32 2}
+!8 = !{i32 2, !"Debug Info Version", i32 3}
+!9 = !{i32 1, !"PIC Level", i32 2}
+!10 = !{!"clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)"}
+!11 = !DILocalVariable(name: "X", scope: !4, file: !1, line: 2, type: !12)
+!12 = !DIBasicType(name: "int", size: 32, align: 32, encoding: DW_ATE_signed)
+!13 = !DIExpression()
+!14 = !DILocation(line: 2, column: 9, scope: !4)
+!15 = !DILocalVariable(name: "Y", scope: !4, file: !1, line: 3, type: !12)
+!16 = !DILocation(line: 3, column: 9, scope: !4)
+!17 = !DILocalVariable(name: "Z", scope: !18, file: !1, line: 5, type: !12)
+!18 = distinct !DILexicalBlock(scope: !4, file: !1, line: 4, column: 5)
+!19 = !DILocation(line: 5, column: 11, scope: !18)
+!20 = !DILocation(line: 6, column: 11, scope: !18)
+!21 = !DILocation(line: 6, column: 9, scope: !18)
+!22 = !DILocation(line: 8, column: 9, scope: !4)
+!23 = !DILocation(line: 8, column: 7, scope: !4)
+!24 = !DILocation(line: 9, column: 3, scope: !4)
+</pre></div>
+</div>
+<p>This example illustrates a few important details about LLVM debugging
+information. In particular, it shows how the <tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt> intrinsic and
+location information, which are attached to an instruction, are applied
+together to allow a debugger to analyze the relationship between statements,
+variable definitions, and the code used to implement the function.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!11</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!13</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!14</span>
+ <span class="c">; [debug line = 2:7] [debug variable = X]</span>
+</pre></div>
+</div>
+<p>The first intrinsic <tt class="docutils literal"><span class="pre">%llvm.dbg.declare</span></tt> encodes debugging information for the
+variable <tt class="docutils literal"><span class="pre">X</span></tt>. The metadata <tt class="docutils literal"><span class="pre">!dbg</span> <span class="pre">!14</span></tt> attached to the intrinsic provides
+scope information for the variable <tt class="docutils literal"><span class="pre">X</span></tt>.</p>
+<div class="highlight-text"><div class="highlight"><pre>!14 = !DILocation(line: 2, column: 9, scope: !4)
+!4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5,
+ isLocal: false, isDefinition: true, scopeLine: 1,
+ isOptimized: false, variables: !2)
+</pre></div>
+</div>
+<p>Here <tt class="docutils literal"><span class="pre">!14</span></tt> is metadata providing <a class="reference external" href="LangRef.html#dilocation">location information</a>. In this example, scope is encoded by <tt class="docutils literal"><span class="pre">!4</span></tt>, a
+<a class="reference external" href="LangRef.html#disubprogram">subprogram descriptor</a>. This way the location
+information attached to the intrinsics indicates that the variable <tt class="docutils literal"><span class="pre">X</span></tt> is
+declared at line number 2 at a function level scope in function <tt class="docutils literal"><span class="pre">foo</span></tt>.</p>
+<p>Now lets take another example.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Z</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!17</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!13</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!19</span>
+ <span class="c">; [debug line = 5:9] [debug variable = Z]</span>
+</pre></div>
+</div>
+<p>The third intrinsic <tt class="docutils literal"><span class="pre">%llvm.dbg.declare</span></tt> encodes debugging information for
+variable <tt class="docutils literal"><span class="pre">Z</span></tt>. The metadata <tt class="docutils literal"><span class="pre">!dbg</span> <span class="pre">!19</span></tt> attached to the intrinsic provides
+scope information for the variable <tt class="docutils literal"><span class="pre">Z</span></tt>.</p>
+<div class="highlight-text"><div class="highlight"><pre>!18 = distinct !DILexicalBlock(scope: !4, file: !1, line: 4, column: 5)
+!19 = !DILocation(line: 5, column: 11, scope: !18)
+</pre></div>
+</div>
+<p>Here <tt class="docutils literal"><span class="pre">!19</span></tt> indicates that <tt class="docutils literal"><span class="pre">Z</span></tt> is declared at line number 5 and column
+number 0 inside of lexical scope <tt class="docutils literal"><span class="pre">!18</span></tt>. The lexical scope itself resides
+inside of subprogram <tt class="docutils literal"><span class="pre">!4</span></tt> described above.</p>
+<p>The scope information attached with each instruction provides a straightforward
+way to find instructions covered by a scope.</p>
+</div>
+<div class="section" id="c-c-front-end-specific-debug-information">
+<span id="ccxx-frontend"></span><h2><a class="toc-backref" href="#id16">C/C++ front-end specific debug information</a><a class="headerlink" href="#c-c-front-end-specific-debug-information" title="Permalink to this headline">¶</a></h2>
+<p>The C and C++ front-ends represent information about the program in a format
+that is effectively identical to <a class="reference external" href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in terms of information
+content. This allows code generators to trivially support native debuggers by
+generating standard dwarf information, and contains enough information for
+non-dwarf targets to translate it as needed.</p>
+<p>This section describes the forms used to represent C and C++ programs. Other
+languages could pattern themselves after this (which itself is tuned to
+representing programs in the same way that DWARF 3 does), or they could choose
+to provide completely different forms if they don’t fit into the DWARF model.
+As support for debugging information gets added to the various LLVM
+source-language front-ends, the information used should be documented here.</p>
+<p>The following sections provide examples of a few C/C++ constructs and the debug
+information that would best describe those constructs. The canonical
+references are the <tt class="docutils literal"><span class="pre">DIDescriptor</span></tt> classes defined in
+<tt class="docutils literal"><span class="pre">include/llvm/IR/DebugInfo.h</span></tt> and the implementations of the helper functions
+in <tt class="docutils literal"><span class="pre">lib/IR/DIBuilder.cpp</span></tt>.</p>
+<div class="section" id="c-c-source-file-information">
+<h3><a class="toc-backref" href="#id17">C/C++ source file information</a><a class="headerlink" href="#c-c-source-file-information" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">llvm::Instruction</span></tt> provides easy access to metadata attached with an
+instruction. One can extract line number information encoded in LLVM IR using
+<tt class="docutils literal"><span class="pre">Instruction::getDebugLoc()</span></tt> and <tt class="docutils literal"><span class="pre">DILocation::getLine()</span></tt>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">DILocation</span> <span class="o">*</span><span class="n">Loc</span> <span class="o">=</span> <span class="n">I</span><span class="o">-></span><span class="n">getDebugLoc</span><span class="p">())</span> <span class="p">{</span> <span class="c1">// Here I is an LLVM instruction</span>
+ <span class="kt">unsigned</span> <span class="n">Line</span> <span class="o">=</span> <span class="n">Loc</span><span class="o">-></span><span class="n">getLine</span><span class="p">();</span>
+ <span class="n">StringRef</span> <span class="n">File</span> <span class="o">=</span> <span class="n">Loc</span><span class="o">-></span><span class="n">getFilename</span><span class="p">();</span>
+ <span class="n">StringRef</span> <span class="n">Dir</span> <span class="o">=</span> <span class="n">Loc</span><span class="o">-></span><span class="n">getDirectory</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="c-c-global-variable-information">
+<h3><a class="toc-backref" href="#id18">C/C++ global variable information</a><a class="headerlink" href="#c-c-global-variable-information" title="Permalink to this headline">¶</a></h3>
+<p>Given an integer global variable declared as follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">MyGlobal</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-text"><div class="highlight"><pre>;;
+;; Define the global itself.
+;;
+ at MyGlobal = global i32 100, align 4
+
+;;
+;; List of debug info of globals
+;;
+!llvm.dbg.cu = !{!0}
+
+;; Some unrelated metadata.
+!llvm.module.flags = !{!6, !7}
+
+;; Define the compile unit.
+!0 = !DICompileUnit(language: DW_LANG_C99, file: !1,
+ producer:
+ "clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)",
+ isOptimized: false, runtimeVersion: 0, emissionKind: FullDebug,
+ enums: !2, retainedTypes: !2, subprograms: !2, globals:
+ !3, imports: !2)
+
+;;
+;; Define the file
+;;
+!1 = !DIFile(filename: "/dev/stdin",
+ directory: "/Users/dexonsmith/data/llvm/debug-info")
+
+;; An empty array.
+!2 = !{}
+
+;; The Array of Global Variables
+!3 = !{!4}
+
+;;
+;; Define the global variable itself.
+;;
+!4 = !DIGlobalVariable(name: "MyGlobal", scope: !0, file: !1, line: 1,
+ type: !5, isLocal: false, isDefinition: true,
+ variable: i32* @MyGlobal)
+
+;;
+;; Define the type
+;;
+!5 = !DIBasicType(name: "int", size: 32, align: 32, encoding: DW_ATE_signed)
+
+;; Dwarf version to output.
+!6 = !{i32 2, !"Dwarf Version", i32 2}
+
+;; Debug info schema version.
+!7 = !{i32 2, !"Debug Info Version", i32 3}
+</pre></div>
+</div>
+</div>
+<div class="section" id="c-c-function-information">
+<h3><a class="toc-backref" href="#id19">C/C++ function information</a><a class="headerlink" href="#c-c-function-information" title="Permalink to this headline">¶</a></h3>
+<p>Given a function declared as follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-text"><div class="highlight"><pre>;;
+;; Define the anchor for subprograms.
+;;
+!4 = !DISubprogram(name: "main", scope: !1, file: !1, line: 1, type: !5,
+ isLocal: false, isDefinition: true, scopeLine: 1,
+ flags: DIFlagPrototyped, isOptimized: false,
+ variables: !2)
+
+;;
+;; Define the subprogram itself.
+;;
+define i32 @main(i32 %argc, i8** %argv) !dbg !4 {
+...
+}
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="id3">
+<h2><a class="toc-backref" href="#id20">Debugging information format</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="debugging-information-extension-for-objective-c-properties">
+<h3><a class="toc-backref" href="#id21">Debugging Information Extension for Objective C Properties</a><a class="headerlink" href="#debugging-information-extension-for-objective-c-properties" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id4">
+<h4><a class="toc-backref" href="#id22">Introduction</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>Objective C provides a simpler way to declare and define accessor methods using
+declared properties. The language provides features to declare a property and
+to let compiler synthesize accessor methods.</p>
+<p>The debugger lets developer inspect Objective C interfaces and their instance
+variables and class variables. However, the debugger does not know anything
+about the properties defined in Objective C interfaces. The debugger consumes
+information generated by compiler in DWARF format. The format does not support
+encoding of Objective C properties. This proposal describes DWARF extensions to
+encode Objective C properties, which the debugger can use to let developers
+inspect Objective C properties.</p>
+</div>
+<div class="section" id="proposal">
+<h4><a class="toc-backref" href="#id23">Proposal</a><a class="headerlink" href="#proposal" title="Permalink to this headline">¶</a></h4>
+<p>Objective C properties exist separately from class members. A property can be
+defined only by “setter” and “getter” selectors, and be calculated anew on each
+access. Or a property can just be a direct access to some declared ivar.
+Finally it can have an ivar “automatically synthesized” for it by the compiler,
+in which case the property can be referred to in user code directly using the
+standard C dereference syntax as well as through the property “dot” syntax, but
+there is no entry in the <tt class="docutils literal"><span class="pre">@interface</span></tt> declaration corresponding to this ivar.</p>
+<p>To facilitate debugging, these properties we will add a new DWARF TAG into the
+<tt class="docutils literal"><span class="pre">DW_TAG_structure_type</span></tt> definition for the class to hold the description of a
+given property, and a set of DWARF attributes that provide said description.
+The property tag will also contain the name and declared type of the property.</p>
+<p>If there is a related ivar, there will also be a DWARF property attribute placed
+in the <tt class="docutils literal"><span class="pre">DW_TAG_member</span></tt> DIE for that ivar referring back to the property TAG
+for that property. And in the case where the compiler synthesizes the ivar
+directly, the compiler is expected to generate a <tt class="docutils literal"><span class="pre">DW_TAG_member</span></tt> for that
+ivar (with the <tt class="docutils literal"><span class="pre">DW_AT_artificial</span></tt> set to 1), whose name will be the name used
+to access this ivar directly in code, and with the property attribute pointing
+back to the property it is backing.</p>
+<p>The following examples will serve as illustration for our discussion:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">I1</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">n2</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="k">@property</span> <span class="kt">int</span> <span class="n">p1</span><span class="p">;</span>
+<span class="k">@property</span> <span class="kt">int</span> <span class="n">p2</span><span class="p">;</span>
+<span class="k">@end</span>
+
+<span class="k">@implementation</span> <span class="nc">I1</span>
+<span class="k">@synthesize</span> <span class="n">p1</span><span class="p">;</span>
+<span class="k">@synthesize</span> <span class="n">p2</span> <span class="o">=</span> <span class="n">n2</span><span class="p">;</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>This produces the following DWARF (this is a “pseudo dwarfdump” output):</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00000100: TAG_structure_type [7] *
+ AT_APPLE_runtime_class( 0x10 )
+ AT_name( "I1" )
+ AT_decl_file( "Objc_Property.m" )
+ AT_decl_line( 3 )
+
+0x00000110 TAG_APPLE_property
+ AT_name ( "p1" )
+ AT_type ( {0x00000150} ( int ) )
+
+0x00000120: TAG_APPLE_property
+ AT_name ( "p2" )
+ AT_type ( {0x00000150} ( int ) )
+
+0x00000130: TAG_member [8]
+ AT_name( "_p1" )
+ AT_APPLE_property ( {0x00000110} "p1" )
+ AT_type( {0x00000150} ( int ) )
+ AT_artificial ( 0x1 )
+
+0x00000140: TAG_member [8]
+ AT_name( "n2" )
+ AT_APPLE_property ( {0x00000120} "p2" )
+ AT_type( {0x00000150} ( int ) )
+
+0x00000150: AT_type( ( int ) )
+</pre></div>
+</div>
+<p>Note, the current convention is that the name of the ivar for an
+auto-synthesized property is the name of the property from which it derives
+with an underscore prepended, as is shown in the example. But we actually
+don’t need to know this convention, since we are given the name of the ivar
+directly.</p>
+<p>Also, it is common practice in ObjC to have different property declarations in
+the @interface and @implementation - e.g. to provide a read-only property in
+the interface,and a read-write interface in the implementation. In that case,
+the compiler should emit whichever property declaration will be in force in the
+current translation unit.</p>
+<p>Developers can decorate a property with attributes which are encoded using
+<tt class="docutils literal"><span class="pre">DW_AT_APPLE_property_attribute</span></tt>.</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@property</span> <span class="p">(</span><span class="n">readonly</span><span class="p">,</span> <span class="n">nonatomic</span><span class="p">)</span> <span class="kt">int</span> <span class="n">pr</span><span class="p">;</span>
+</pre></div>
+</div>
+<div class="highlight-none"><div class="highlight"><pre>TAG_APPLE_property [8]
+ AT_name( "pr" )
+ AT_type ( {0x00000147} (int) )
+ AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
+</pre></div>
+</div>
+<p>The setter and getter method names are attached to the property using
+<tt class="docutils literal"><span class="pre">DW_AT_APPLE_property_setter</span></tt> and <tt class="docutils literal"><span class="pre">DW_AT_APPLE_property_getter</span></tt> attributes.</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">I1</span>
+<span class="k">@property</span> <span class="p">(</span><span class="n">setter</span><span class="o">=</span><span class="n">myOwnP3Setter</span><span class="o">:</span><span class="p">)</span> <span class="kt">int</span> <span class="n">p3</span><span class="p">;</span>
+<span class="k">-</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">myOwnP3Setter:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">a</span><span class="p">;</span>
+<span class="k">@end</span>
+
+<span class="k">@implementation</span> <span class="nc">I1</span>
+<span class="k">@synthesize</span> <span class="n">p3</span><span class="p">;</span>
+<span class="k">-</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">myOwnP3Setter:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">a</span><span class="p">{</span> <span class="p">}</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>The DWARF for this would be:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x000003bd: TAG_structure_type [7] *
+ AT_APPLE_runtime_class( 0x10 )
+ AT_name( "I1" )
+ AT_decl_file( "Objc_Property.m" )
+ AT_decl_line( 3 )
+
+0x000003cd TAG_APPLE_property
+ AT_name ( "p3" )
+ AT_APPLE_property_setter ( "myOwnP3Setter:" )
+ AT_type( {0x00000147} ( int ) )
+
+0x000003f3: TAG_member [8]
+ AT_name( "_p3" )
+ AT_type ( {0x00000147} ( int ) )
+ AT_APPLE_property ( {0x000003cd} )
+ AT_artificial ( 0x1 )
+</pre></div>
+</div>
+</div>
+<div class="section" id="new-dwarf-tags">
+<h4><a class="toc-backref" href="#id24">New DWARF Tags</a><a class="headerlink" href="#new-dwarf-tags" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils">
+<colgroup>
+<col width="74%" />
+<col width="26%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">TAG</th>
+<th class="head">Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>DW_TAG_APPLE_property</td>
+<td>0x4200</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="new-dwarf-attributes">
+<h4><a class="toc-backref" href="#id25">New DWARF Attributes</a><a class="headerlink" href="#new-dwarf-attributes" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils">
+<colgroup>
+<col width="63%" />
+<col width="16%" />
+<col width="22%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Attribute</th>
+<th class="head">Value</th>
+<th class="head">Classes</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>DW_AT_APPLE_property</td>
+<td>0x3fed</td>
+<td>Reference</td>
+</tr>
+<tr class="row-odd"><td>DW_AT_APPLE_property_getter</td>
+<td>0x3fe9</td>
+<td>String</td>
+</tr>
+<tr class="row-even"><td>DW_AT_APPLE_property_setter</td>
+<td>0x3fea</td>
+<td>String</td>
+</tr>
+<tr class="row-odd"><td>DW_AT_APPLE_property_attribute</td>
+<td>0x3feb</td>
+<td>Constant</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="new-dwarf-constants">
+<h4><a class="toc-backref" href="#id26">New DWARF Constants</a><a class="headerlink" href="#new-dwarf-constants" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils">
+<colgroup>
+<col width="84%" />
+<col width="16%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Name</th>
+<th class="head">Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>DW_APPLE_PROPERTY_readonly</td>
+<td>0x01</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_getter</td>
+<td>0x02</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_assign</td>
+<td>0x04</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_readwrite</td>
+<td>0x08</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_retain</td>
+<td>0x10</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_copy</td>
+<td>0x20</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_nonatomic</td>
+<td>0x40</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_setter</td>
+<td>0x80</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_atomic</td>
+<td>0x100</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_weak</td>
+<td>0x200</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_strong</td>
+<td>0x400</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_unsafe_unretained</td>
+<td>0x800</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_nullability</td>
+<td>0x1000</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_null_resettable</td>
+<td>0x2000</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_class</td>
+<td>0x4000</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="name-accelerator-tables">
+<h3><a class="toc-backref" href="#id27">Name Accelerator Tables</a><a class="headerlink" href="#name-accelerator-tables" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id5">
+<h4><a class="toc-backref" href="#id28">Introduction</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h4>
+<p>The “<tt class="docutils literal"><span class="pre">.debug_pubnames</span></tt>” and “<tt class="docutils literal"><span class="pre">.debug_pubtypes</span></tt>” formats are not what a
+debugger needs. The “<tt class="docutils literal"><span class="pre">pub</span></tt>” in the section name indicates that the entries
+in the table are publicly visible names only. This means no static or hidden
+functions show up in the “<tt class="docutils literal"><span class="pre">.debug_pubnames</span></tt>”. No static variables or private
+class variables are in the “<tt class="docutils literal"><span class="pre">.debug_pubtypes</span></tt>”. Many compilers add different
+things to these tables, so we can’t rely upon the contents between gcc, icc, or
+clang.</p>
+<p>The typical query given by users tends not to match up with the contents of
+these tables. For example, the DWARF spec states that “In the case of the name
+of a function member or static data member of a C++ structure, class or union,
+the name presented in the “<tt class="docutils literal"><span class="pre">.debug_pubnames</span></tt>” section is not the simple name
+given by the <tt class="docutils literal"><span class="pre">DW_AT_name</span> <span class="pre">attribute</span></tt> of the referenced debugging information
+entry, but rather the fully qualified name of the data or function member.”
+So the only names in these tables for complex C++ entries is a fully
+qualified name. Debugger users tend not to enter their search strings as
+“<tt class="docutils literal"><span class="pre">a::b::c(int,const</span> <span class="pre">Foo&)</span> <span class="pre">const</span></tt>”, but rather as “<tt class="docutils literal"><span class="pre">c</span></tt>”, “<tt class="docutils literal"><span class="pre">b::c</span></tt>” , or
+“<tt class="docutils literal"><span class="pre">a::b::c</span></tt>”. So the name entered in the name table must be demangled in
+order to chop it up appropriately and additional names must be manually entered
+into the table to make it effective as a name lookup table for debuggers to
+use.</p>
+<p>All debuggers currently ignore the “<tt class="docutils literal"><span class="pre">.debug_pubnames</span></tt>” table as a result of
+its inconsistent and useless public-only name content making it a waste of
+space in the object file. These tables, when they are written to disk, are not
+sorted in any way, leaving every debugger to do its own parsing and sorting.
+These tables also include an inlined copy of the string values in the table
+itself making the tables much larger than they need to be on disk, especially
+for large C++ programs.</p>
+<p>Can’t we just fix the sections by adding all of the names we need to this
+table? No, because that is not what the tables are defined to contain and we
+won’t know the difference between the old bad tables and the new good tables.
+At best we could make our own renamed sections that contain all of the data we
+need.</p>
+<p>These tables are also insufficient for what a debugger like LLDB needs. LLDB
+uses clang for its expression parsing where LLDB acts as a PCH. LLDB is then
+often asked to look for type “<tt class="docutils literal"><span class="pre">foo</span></tt>” or namespace “<tt class="docutils literal"><span class="pre">bar</span></tt>”, or list items in
+namespace “<tt class="docutils literal"><span class="pre">baz</span></tt>”. Namespaces are not included in the pubnames or pubtypes
+tables. Since clang asks a lot of questions when it is parsing an expression,
+we need to be very fast when looking up names, as it happens a lot. Having new
+accelerator tables that are optimized for very quick lookups will benefit this
+type of debugging experience greatly.</p>
+<p>We would like to generate name lookup tables that can be mapped into memory
+from disk, and used as is, with little or no up-front parsing. We would also
+be able to control the exact content of these different tables so they contain
+exactly what we need. The Name Accelerator Tables were designed to fix these
+issues. In order to solve these issues we need to:</p>
+<ul class="simple">
+<li>Have a format that can be mapped into memory from disk and used as is</li>
+<li>Lookups should be very fast</li>
+<li>Extensible table format so these tables can be made by many producers</li>
+<li>Contain all of the names needed for typical lookups out of the box</li>
+<li>Strict rules for the contents of tables</li>
+</ul>
+<p>Table size is important and the accelerator table format should allow the reuse
+of strings from common string tables so the strings for the names are not
+duplicated. We also want to make sure the table is ready to be used as-is by
+simply mapping the table into memory with minimal header parsing.</p>
+<p>The name lookups need to be fast and optimized for the kinds of lookups that
+debuggers tend to do. Optimally we would like to touch as few parts of the
+mapped table as possible when doing a name lookup and be able to quickly find
+the name entry we are looking for, or discover there are no matches. In the
+case of debuggers we optimized for lookups that fail most of the time.</p>
+<p>Each table that is defined should have strict rules on exactly what is in the
+accelerator tables and documented so clients can rely on the content.</p>
+</div>
+<div class="section" id="hash-tables">
+<h4><a class="toc-backref" href="#id29">Hash Tables</a><a class="headerlink" href="#hash-tables" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="standard-hash-tables">
+<h5><a class="toc-backref" href="#id30">Standard Hash Tables</a><a class="headerlink" href="#standard-hash-tables" title="Permalink to this headline">¶</a></h5>
+<p>Typical hash tables have a header, buckets, and each bucket points to the
+bucket contents:</p>
+<div class="highlight-none"><div class="highlight"><pre>.------------.
+| HEADER |
+|------------|
+| BUCKETS |
+|------------|
+| DATA |
+`------------'
+</pre></div>
+</div>
+<p>The BUCKETS are an array of offsets to DATA for each hash:</p>
+<div class="highlight-none"><div class="highlight"><pre>.------------.
+| 0x00001000 | BUCKETS[0]
+| 0x00002000 | BUCKETS[1]
+| 0x00002200 | BUCKETS[2]
+| 0x000034f0 | BUCKETS[3]
+| | ...
+| 0xXXXXXXXX | BUCKETS[n_buckets]
+'------------'
+</pre></div>
+</div>
+<p>So for <tt class="docutils literal"><span class="pre">bucket[3]</span></tt> in the example above, we have an offset into the table
+0x000034f0 which points to a chain of entries for the bucket. Each bucket must
+contain a next pointer, full 32 bit hash value, the string itself, and the data
+for the current string value.</p>
+<div class="highlight-none"><div class="highlight"><pre> .------------.
+0x000034f0: | 0x00003500 | next pointer
+ | 0x12345678 | 32 bit hash
+ | "erase" | string value
+ | data[n] | HashData for this bucket
+ |------------|
+0x00003500: | 0x00003550 | next pointer
+ | 0x29273623 | 32 bit hash
+ | "dump" | string value
+ | data[n] | HashData for this bucket
+ |------------|
+0x00003550: | 0x00000000 | next pointer
+ | 0x82638293 | 32 bit hash
+ | "main" | string value
+ | data[n] | HashData for this bucket
+ `------------'
+</pre></div>
+</div>
+<p>The problem with this layout for debuggers is that we need to optimize for the
+negative lookup case where the symbol we’re searching for is not present. So
+if we were to lookup “<tt class="docutils literal"><span class="pre">printf</span></tt>” in the table above, we would make a 32 hash
+for “<tt class="docutils literal"><span class="pre">printf</span></tt>”, it might match <tt class="docutils literal"><span class="pre">bucket[3]</span></tt>. We would need to go to the
+offset 0x000034f0 and start looking to see if our 32 bit hash matches. To do
+so, we need to read the next pointer, then read the hash, compare it, and skip
+to the next bucket. Each time we are skipping many bytes in memory and
+touching new cache pages just to do the compare on the full 32 bit hash. All
+of these accesses then tell us that we didn’t have a match.</p>
+</div>
+<div class="section" id="name-hash-tables">
+<h5><a class="toc-backref" href="#id31">Name Hash Tables</a><a class="headerlink" href="#name-hash-tables" title="Permalink to this headline">¶</a></h5>
+<p>To solve the issues mentioned above we have structured the hash tables a bit
+differently: a header, buckets, an array of all unique 32 bit hash values,
+followed by an array of hash value data offsets, one for each hash value, then
+the data for all hash values:</p>
+<div class="highlight-none"><div class="highlight"><pre>.-------------.
+| HEADER |
+|-------------|
+| BUCKETS |
+|-------------|
+| HASHES |
+|-------------|
+| OFFSETS |
+|-------------|
+| DATA |
+`-------------'
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">BUCKETS</span></tt> in the name tables are an index into the <tt class="docutils literal"><span class="pre">HASHES</span></tt> array. By
+making all of the full 32 bit hash values contiguous in memory, we allow
+ourselves to efficiently check for a match while touching as little memory as
+possible. Most often checking the 32 bit hash values is as far as the lookup
+goes. If it does match, it usually is a match with no collisions. So for a
+table with “<tt class="docutils literal"><span class="pre">n_buckets</span></tt>” buckets, and “<tt class="docutils literal"><span class="pre">n_hashes</span></tt>” unique 32 bit hash
+values, we can clarify the contents of the <tt class="docutils literal"><span class="pre">BUCKETS</span></tt>, <tt class="docutils literal"><span class="pre">HASHES</span></tt> and
+<tt class="docutils literal"><span class="pre">OFFSETS</span></tt> as:</p>
+<div class="highlight-none"><div class="highlight"><pre>.-------------------------.
+| HEADER.magic | uint32_t
+| HEADER.version | uint16_t
+| HEADER.hash_function | uint16_t
+| HEADER.bucket_count | uint32_t
+| HEADER.hashes_count | uint32_t
+| HEADER.header_data_len | uint32_t
+| HEADER_DATA | HeaderData
+|-------------------------|
+| BUCKETS | uint32_t[n_buckets] // 32 bit hash indexes
+|-------------------------|
+| HASHES | uint32_t[n_hashes] // 32 bit hash values
+|-------------------------|
+| OFFSETS | uint32_t[n_hashes] // 32 bit offsets to hash value data
+|-------------------------|
+| ALL HASH DATA |
+`-------------------------'
+</pre></div>
+</div>
+<p>So taking the exact same data from the standard hash example above we end up
+with:</p>
+<div class="highlight-none"><div class="highlight"><pre> .------------.
+ | HEADER |
+ |------------|
+ | 0 | BUCKETS[0]
+ | 2 | BUCKETS[1]
+ | 5 | BUCKETS[2]
+ | 6 | BUCKETS[3]
+ | | ...
+ | ... | BUCKETS[n_buckets]
+ |------------|
+ | 0x........ | HASHES[0]
+ | 0x........ | HASHES[1]
+ | 0x........ | HASHES[2]
+ | 0x........ | HASHES[3]
+ | 0x........ | HASHES[4]
+ | 0x........ | HASHES[5]
+ | 0x12345678 | HASHES[6] hash for BUCKETS[3]
+ | 0x29273623 | HASHES[7] hash for BUCKETS[3]
+ | 0x82638293 | HASHES[8] hash for BUCKETS[3]
+ | 0x........ | HASHES[9]
+ | 0x........ | HASHES[10]
+ | 0x........ | HASHES[11]
+ | 0x........ | HASHES[12]
+ | 0x........ | HASHES[13]
+ | 0x........ | HASHES[n_hashes]
+ |------------|
+ | 0x........ | OFFSETS[0]
+ | 0x........ | OFFSETS[1]
+ | 0x........ | OFFSETS[2]
+ | 0x........ | OFFSETS[3]
+ | 0x........ | OFFSETS[4]
+ | 0x........ | OFFSETS[5]
+ | 0x000034f0 | OFFSETS[6] offset for BUCKETS[3]
+ | 0x00003500 | OFFSETS[7] offset for BUCKETS[3]
+ | 0x00003550 | OFFSETS[8] offset for BUCKETS[3]
+ | 0x........ | OFFSETS[9]
+ | 0x........ | OFFSETS[10]
+ | 0x........ | OFFSETS[11]
+ | 0x........ | OFFSETS[12]
+ | 0x........ | OFFSETS[13]
+ | 0x........ | OFFSETS[n_hashes]
+ |------------|
+ | |
+ | |
+ | |
+ | |
+ | |
+ |------------|
+0x000034f0: | 0x00001203 | .debug_str ("erase")
+ | 0x00000004 | A 32 bit array count - number of HashData with name "erase"
+ | 0x........ | HashData[0]
+ | 0x........ | HashData[1]
+ | 0x........ | HashData[2]
+ | 0x........ | HashData[3]
+ | 0x00000000 | String offset into .debug_str (terminate data for hash)
+ |------------|
+0x00003500: | 0x00001203 | String offset into .debug_str ("collision")
+ | 0x00000002 | A 32 bit array count - number of HashData with name "collision"
+ | 0x........ | HashData[0]
+ | 0x........ | HashData[1]
+ | 0x00001203 | String offset into .debug_str ("dump")
+ | 0x00000003 | A 32 bit array count - number of HashData with name "dump"
+ | 0x........ | HashData[0]
+ | 0x........ | HashData[1]
+ | 0x........ | HashData[2]
+ | 0x00000000 | String offset into .debug_str (terminate data for hash)
+ |------------|
+0x00003550: | 0x00001203 | String offset into .debug_str ("main")
+ | 0x00000009 | A 32 bit array count - number of HashData with name "main"
+ | 0x........ | HashData[0]
+ | 0x........ | HashData[1]
+ | 0x........ | HashData[2]
+ | 0x........ | HashData[3]
+ | 0x........ | HashData[4]
+ | 0x........ | HashData[5]
+ | 0x........ | HashData[6]
+ | 0x........ | HashData[7]
+ | 0x........ | HashData[8]
+ | 0x00000000 | String offset into .debug_str (terminate data for hash)
+ `------------'
+</pre></div>
+</div>
+<p>So we still have all of the same data, we just organize it more efficiently for
+debugger lookup. If we repeat the same “<tt class="docutils literal"><span class="pre">printf</span></tt>” lookup from above, we
+would hash “<tt class="docutils literal"><span class="pre">printf</span></tt>” and find it matches <tt class="docutils literal"><span class="pre">BUCKETS[3]</span></tt> by taking the 32 bit
+hash value and modulo it by <tt class="docutils literal"><span class="pre">n_buckets</span></tt>. <tt class="docutils literal"><span class="pre">BUCKETS[3]</span></tt> contains “6” which
+is the index into the <tt class="docutils literal"><span class="pre">HASHES</span></tt> table. We would then compare any consecutive
+32 bit hashes values in the <tt class="docutils literal"><span class="pre">HASHES</span></tt> array as long as the hashes would be in
+<tt class="docutils literal"><span class="pre">BUCKETS[3]</span></tt>. We do this by verifying that each subsequent hash value modulo
+<tt class="docutils literal"><span class="pre">n_buckets</span></tt> is still 3. In the case of a failed lookup we would access the
+memory for <tt class="docutils literal"><span class="pre">BUCKETS[3]</span></tt>, and then compare a few consecutive 32 bit hashes
+before we know that we have no match. We don’t end up marching through
+multiple words of memory and we really keep the number of processor data cache
+lines being accessed as small as possible.</p>
+<p>The string hash that is used for these lookup tables is the Daniel J.
+Bernstein hash which is also used in the ELF <tt class="docutils literal"><span class="pre">GNU_HASH</span></tt> sections. It is a
+very good hash for all kinds of names in programs with very few hash
+collisions.</p>
+<p>Empty buckets are designated by using an invalid hash index of <tt class="docutils literal"><span class="pre">UINT32_MAX</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="details">
+<h4><a class="toc-backref" href="#id32">Details</a><a class="headerlink" href="#details" title="Permalink to this headline">¶</a></h4>
+<p>These name hash tables are designed to be generic where specializations of the
+table get to define additional data that goes into the header (“<tt class="docutils literal"><span class="pre">HeaderData</span></tt>”),
+how the string value is stored (“<tt class="docutils literal"><span class="pre">KeyType</span></tt>”) and the content of the data for each
+hash value.</p>
+<div class="section" id="header-layout">
+<h5><a class="toc-backref" href="#id33">Header Layout</a><a class="headerlink" href="#header-layout" title="Permalink to this headline">¶</a></h5>
+<p>The header has a fixed part, and the specialized part. The exact format of the
+header is:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Header</span>
+<span class="p">{</span>
+ <span class="kt">uint32_t</span> <span class="n">magic</span><span class="p">;</span> <span class="c1">// 'HASH' magic value to allow endian detection</span>
+ <span class="kt">uint16_t</span> <span class="n">version</span><span class="p">;</span> <span class="c1">// Version number</span>
+ <span class="kt">uint16_t</span> <span class="n">hash_function</span><span class="p">;</span> <span class="c1">// The hash function enumeration that was used</span>
+ <span class="kt">uint32_t</span> <span class="n">bucket_count</span><span class="p">;</span> <span class="c1">// The number of buckets in this hash table</span>
+ <span class="kt">uint32_t</span> <span class="n">hashes_count</span><span class="p">;</span> <span class="c1">// The total number of unique hash values and hash data offsets in this table</span>
+ <span class="kt">uint32_t</span> <span class="n">header_data_len</span><span class="p">;</span> <span class="c1">// The bytes to skip to get to the hash indexes (buckets) for correct alignment</span>
+ <span class="c1">// Specifically the length of the following HeaderData field - this does not</span>
+ <span class="c1">// include the size of the preceding fields</span>
+ <span class="n">HeaderData</span> <span class="n">header_data</span><span class="p">;</span> <span class="c1">// Implementation specific header data</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The header starts with a 32 bit “<tt class="docutils literal"><span class="pre">magic</span></tt>” value which must be <tt class="docutils literal"><span class="pre">'HASH'</span></tt>
+encoded as an ASCII integer. This allows the detection of the start of the
+hash table and also allows the table’s byte order to be determined so the table
+can be correctly extracted. The “<tt class="docutils literal"><span class="pre">magic</span></tt>” value is followed by a 16 bit
+<tt class="docutils literal"><span class="pre">version</span></tt> number which allows the table to be revised and modified in the
+future. The current version number is 1. <tt class="docutils literal"><span class="pre">hash_function</span></tt> is a <tt class="docutils literal"><span class="pre">uint16_t</span></tt>
+enumeration that specifies which hash function was used to produce this table.
+The current values for the hash function enumerations include:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="n">HashFunctionType</span>
+<span class="p">{</span>
+ <span class="n">eHashFunctionDJB</span> <span class="o">=</span> <span class="mi">0u</span><span class="p">,</span> <span class="c1">// Daniel J Bernstein hash function</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">bucket_count</span></tt> is a 32 bit unsigned integer that represents how many buckets
+are in the <tt class="docutils literal"><span class="pre">BUCKETS</span></tt> array. <tt class="docutils literal"><span class="pre">hashes_count</span></tt> is the number of unique 32 bit
+hash values that are in the <tt class="docutils literal"><span class="pre">HASHES</span></tt> array, and is the same number of offsets
+are contained in the <tt class="docutils literal"><span class="pre">OFFSETS</span></tt> array. <tt class="docutils literal"><span class="pre">header_data_len</span></tt> specifies the size
+in bytes of the <tt class="docutils literal"><span class="pre">HeaderData</span></tt> that is filled in by specialized versions of
+this table.</p>
+</div>
+<div class="section" id="fixed-lookup">
+<h5><a class="toc-backref" href="#id34">Fixed Lookup</a><a class="headerlink" href="#fixed-lookup" title="Permalink to this headline">¶</a></h5>
+<p>The header is followed by the buckets, hashes, offsets, and hash value data.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">FixedTable</span>
+<span class="p">{</span>
+ <span class="kt">uint32_t</span> <span class="n">buckets</span><span class="p">[</span><span class="n">Header</span><span class="p">.</span><span class="n">bucket_count</span><span class="p">];</span> <span class="c1">// An array of hash indexes into the "hashes[]" array below</span>
+ <span class="kt">uint32_t</span> <span class="n">hashes</span> <span class="p">[</span><span class="n">Header</span><span class="p">.</span><span class="n">hashes_count</span><span class="p">];</span> <span class="c1">// Every unique 32 bit hash for the entire table is in this table</span>
+ <span class="kt">uint32_t</span> <span class="n">offsets</span><span class="p">[</span><span class="n">Header</span><span class="p">.</span><span class="n">hashes_count</span><span class="p">];</span> <span class="c1">// An offset that corresponds to each item in the "hashes[]" array above</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">buckets</span></tt> is an array of 32 bit indexes into the <tt class="docutils literal"><span class="pre">hashes</span></tt> array. The
+<tt class="docutils literal"><span class="pre">hashes</span></tt> array contains all of the 32 bit hash values for all names in the
+hash table. Each hash in the <tt class="docutils literal"><span class="pre">hashes</span></tt> table has an offset in the <tt class="docutils literal"><span class="pre">offsets</span></tt>
+array that points to the data for the hash value.</p>
+<p>This table setup makes it very easy to repurpose these tables to contain
+different data, while keeping the lookup mechanism the same for all tables.
+This layout also makes it possible to save the table to disk and map it in
+later and do very efficient name lookups with little or no parsing.</p>
+<p>DWARF lookup tables can be implemented in a variety of ways and can store a lot
+of information for each name. We want to make the DWARF tables extensible and
+able to store the data efficiently so we have used some of the DWARF features
+that enable efficient data storage to define exactly what kind of data we store
+for each name.</p>
+<p>The <tt class="docutils literal"><span class="pre">HeaderData</span></tt> contains a definition of the contents of each HashData chunk.
+We might want to store an offset to all of the debug information entries (DIEs)
+for each name. To keep things extensible, we create a list of items, or
+Atoms, that are contained in the data for each name. First comes the type of
+the data in each atom:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="n">AtomType</span>
+<span class="p">{</span>
+ <span class="n">eAtomTypeNULL</span> <span class="o">=</span> <span class="mi">0u</span><span class="p">,</span>
+ <span class="n">eAtomTypeDIEOffset</span> <span class="o">=</span> <span class="mi">1u</span><span class="p">,</span> <span class="c1">// DIE offset, check form for encoding</span>
+ <span class="n">eAtomTypeCUOffset</span> <span class="o">=</span> <span class="mi">2u</span><span class="p">,</span> <span class="c1">// DIE offset of the compiler unit header that contains the item in question</span>
+ <span class="n">eAtomTypeTag</span> <span class="o">=</span> <span class="mi">3u</span><span class="p">,</span> <span class="c1">// DW_TAG_xxx value, should be encoded as DW_FORM_data1 (if no tags exceed 255) or DW_FORM_data2</span>
+ <span class="n">eAtomTypeNameFlags</span> <span class="o">=</span> <span class="mi">4u</span><span class="p">,</span> <span class="c1">// Flags from enum NameFlags</span>
+ <span class="n">eAtomTypeTypeFlags</span> <span class="o">=</span> <span class="mi">5u</span><span class="p">,</span> <span class="c1">// Flags from enum TypeFlags</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The enumeration values and their meanings are:</p>
+<div class="highlight-none"><div class="highlight"><pre>eAtomTypeNULL - a termination atom that specifies the end of the atom list
+eAtomTypeDIEOffset - an offset into the .debug_info section for the DWARF DIE for this name
+eAtomTypeCUOffset - an offset into the .debug_info section for the CU that contains the DIE
+eAtomTypeDIETag - The DW_TAG_XXX enumeration value so you don't have to parse the DWARF to see what it is
+eAtomTypeNameFlags - Flags for functions and global variables (isFunction, isInlined, isExternal...)
+eAtomTypeTypeFlags - Flags for types (isCXXClass, isObjCClass, ...)
+</pre></div>
+</div>
+<p>Then we allow each atom type to define the atom type and how the data for each
+atom type data is encoded:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Atom</span>
+<span class="p">{</span>
+ <span class="kt">uint16_t</span> <span class="n">type</span><span class="p">;</span> <span class="c1">// AtomType enum value</span>
+ <span class="kt">uint16_t</span> <span class="n">form</span><span class="p">;</span> <span class="c1">// DWARF DW_FORM_XXX defines</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">form</span></tt> type above is from the DWARF specification and defines the exact
+encoding of the data for the Atom type. See the DWARF specification for the
+<tt class="docutils literal"><span class="pre">DW_FORM_</span></tt> definitions.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">HeaderData</span>
+<span class="p">{</span>
+ <span class="kt">uint32_t</span> <span class="n">die_offset_base</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">atom_count</span><span class="p">;</span>
+ <span class="n">Atoms</span> <span class="n">atoms</span><span class="p">[</span><span class="n">atom_count0</span><span class="p">];</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">HeaderData</span></tt> defines the base DIE offset that should be added to any atoms
+that are encoded using the <tt class="docutils literal"><span class="pre">DW_FORM_ref1</span></tt>, <tt class="docutils literal"><span class="pre">DW_FORM_ref2</span></tt>,
+<tt class="docutils literal"><span class="pre">DW_FORM_ref4</span></tt>, <tt class="docutils literal"><span class="pre">DW_FORM_ref8</span></tt> or <tt class="docutils literal"><span class="pre">DW_FORM_ref_udata</span></tt>. It also defines
+what is contained in each <tt class="docutils literal"><span class="pre">HashData</span></tt> object – <tt class="docutils literal"><span class="pre">Atom.form</span></tt> tells us how large
+each field will be in the <tt class="docutils literal"><span class="pre">HashData</span></tt> and the <tt class="docutils literal"><span class="pre">Atom.type</span></tt> tells us how this data
+should be interpreted.</p>
+<p>For the current implementations of the “<tt class="docutils literal"><span class="pre">.apple_names</span></tt>” (all functions +
+globals), the “<tt class="docutils literal"><span class="pre">.apple_types</span></tt>” (names of all types that are defined), and
+the “<tt class="docutils literal"><span class="pre">.apple_namespaces</span></tt>” (all namespaces), we currently set the <tt class="docutils literal"><span class="pre">Atom</span></tt>
+array to be:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">HeaderData</span><span class="p">.</span><span class="n">atom_count</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="n">HeaderData</span><span class="p">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">type</span> <span class="o">=</span> <span class="n">eAtomTypeDIEOffset</span><span class="p">;</span>
+<span class="n">HeaderData</span><span class="p">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">form</span> <span class="o">=</span> <span class="n">DW_FORM_data4</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This defines the contents to be the DIE offset (eAtomTypeDIEOffset) that is
+encoded as a 32 bit value (DW_FORM_data4). This allows a single name to have
+multiple matching DIEs in a single file, which could come up with an inlined
+function for instance. Future tables could include more information about the
+DIE such as flags indicating if the DIE is a function, method, block,
+or inlined.</p>
+<p>The KeyType for the DWARF table is a 32 bit string table offset into the
+”.debug_str” table. The ”.debug_str” is the string table for the DWARF which
+may already contain copies of all of the strings. This helps make sure, with
+help from the compiler, that we reuse the strings between all of the DWARF
+sections and keeps the hash table size down. Another benefit to having the
+compiler generate all strings as DW_FORM_strp in the debug info, is that
+DWARF parsing can be made much faster.</p>
+<p>After a lookup is made, we get an offset into the hash data. The hash data
+needs to be able to deal with 32 bit hash collisions, so the chunk of data
+at the offset in the hash data consists of a triple:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">uint32_t</span> <span class="n">str_offset</span>
+<span class="kt">uint32_t</span> <span class="n">hash_data_count</span>
+<span class="n">HashData</span><span class="p">[</span><span class="n">hash_data_count</span><span class="p">]</span>
+</pre></div>
+</div>
+<p>If “str_offset” is zero, then the bucket contents are done. 99.9% of the
+hash data chunks contain a single item (no 32 bit hash collision):</p>
+<div class="highlight-none"><div class="highlight"><pre>.------------.
+| 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")
+| 0x00000004 | uint32_t HashData count
+| 0x........ | uint32_t HashData[0] DIE offset
+| 0x........ | uint32_t HashData[1] DIE offset
+| 0x........ | uint32_t HashData[2] DIE offset
+| 0x........ | uint32_t HashData[3] DIE offset
+| 0x00000000 | uint32_t KeyType (end of hash chain)
+`------------'
+</pre></div>
+</div>
+<p>If there are collisions, you will have multiple valid string offsets:</p>
+<div class="highlight-none"><div class="highlight"><pre>.------------.
+| 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")
+| 0x00000004 | uint32_t HashData count
+| 0x........ | uint32_t HashData[0] DIE offset
+| 0x........ | uint32_t HashData[1] DIE offset
+| 0x........ | uint32_t HashData[2] DIE offset
+| 0x........ | uint32_t HashData[3] DIE offset
+| 0x00002023 | uint32_t KeyType (.debug_str[0x0002023] => "print")
+| 0x00000002 | uint32_t HashData count
+| 0x........ | uint32_t HashData[0] DIE offset
+| 0x........ | uint32_t HashData[1] DIE offset
+| 0x00000000 | uint32_t KeyType (end of hash chain)
+`------------'
+</pre></div>
+</div>
+<p>Current testing with real world C++ binaries has shown that there is around 1
+32 bit hash collision per 100,000 name entries.</p>
+</div>
+</div>
+<div class="section" id="id6">
+<h4><a class="toc-backref" href="#id35">Contents</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+<p>As we said, we want to strictly define exactly what is included in the
+different tables. For DWARF, we have 3 tables: “<tt class="docutils literal"><span class="pre">.apple_names</span></tt>”,
+“<tt class="docutils literal"><span class="pre">.apple_types</span></tt>”, and “<tt class="docutils literal"><span class="pre">.apple_namespaces</span></tt>”.</p>
+<p>“<tt class="docutils literal"><span class="pre">.apple_names</span></tt>” sections should contain an entry for each DWARF DIE whose
+<tt class="docutils literal"><span class="pre">DW_TAG</span></tt> is a <tt class="docutils literal"><span class="pre">DW_TAG_label</span></tt>, <tt class="docutils literal"><span class="pre">DW_TAG_inlined_subroutine</span></tt>, or
+<tt class="docutils literal"><span class="pre">DW_TAG_subprogram</span></tt> that has address attributes: <tt class="docutils literal"><span class="pre">DW_AT_low_pc</span></tt>,
+<tt class="docutils literal"><span class="pre">DW_AT_high_pc</span></tt>, <tt class="docutils literal"><span class="pre">DW_AT_ranges</span></tt> or <tt class="docutils literal"><span class="pre">DW_AT_entry_pc</span></tt>. It also contains
+<tt class="docutils literal"><span class="pre">DW_TAG_variable</span></tt> DIEs that have a <tt class="docutils literal"><span class="pre">DW_OP_addr</span></tt> in the location (global and
+static variables). All global and static variables should be included,
+including those scoped within functions and classes. For example using the
+following code:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">int</span> <span class="n">var</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">f</span> <span class="p">()</span>
+<span class="p">{</span>
+ <span class="k">static</span> <span class="kt">int</span> <span class="n">var</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Both of the static <tt class="docutils literal"><span class="pre">var</span></tt> variables would be included in the table. All
+functions should emit both their full names and their basenames. For C or C++,
+the full name is the mangled name (if available) which is usually in the
+<tt class="docutils literal"><span class="pre">DW_AT_MIPS_linkage_name</span></tt> attribute, and the <tt class="docutils literal"><span class="pre">DW_AT_name</span></tt> contains the
+function basename. If global or static variables have a mangled name in a
+<tt class="docutils literal"><span class="pre">DW_AT_MIPS_linkage_name</span></tt> attribute, this should be emitted along with the
+simple name found in the <tt class="docutils literal"><span class="pre">DW_AT_name</span></tt> attribute.</p>
+<p>“<tt class="docutils literal"><span class="pre">.apple_types</span></tt>” sections should contain an entry for each DWARF DIE whose
+tag is one of:</p>
+<ul class="simple">
+<li>DW_TAG_array_type</li>
+<li>DW_TAG_class_type</li>
+<li>DW_TAG_enumeration_type</li>
+<li>DW_TAG_pointer_type</li>
+<li>DW_TAG_reference_type</li>
+<li>DW_TAG_string_type</li>
+<li>DW_TAG_structure_type</li>
+<li>DW_TAG_subroutine_type</li>
+<li>DW_TAG_typedef</li>
+<li>DW_TAG_union_type</li>
+<li>DW_TAG_ptr_to_member_type</li>
+<li>DW_TAG_set_type</li>
+<li>DW_TAG_subrange_type</li>
+<li>DW_TAG_base_type</li>
+<li>DW_TAG_const_type</li>
+<li>DW_TAG_file_type</li>
+<li>DW_TAG_namelist</li>
+<li>DW_TAG_packed_type</li>
+<li>DW_TAG_volatile_type</li>
+<li>DW_TAG_restrict_type</li>
+<li>DW_TAG_interface_type</li>
+<li>DW_TAG_unspecified_type</li>
+<li>DW_TAG_shared_type</li>
+</ul>
+<p>Only entries with a <tt class="docutils literal"><span class="pre">DW_AT_name</span></tt> attribute are included, and the entry must
+not be a forward declaration (<tt class="docutils literal"><span class="pre">DW_AT_declaration</span></tt> attribute with a non-zero
+value). For example, using the following code:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span> <span class="p">()</span>
+<span class="p">{</span>
+ <span class="kt">int</span> <span class="o">*</span><span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">return</span> <span class="o">*</span><span class="n">b</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>We get a few type DIEs:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00000067: TAG_base_type [5]
+ AT_encoding( DW_ATE_signed )
+ AT_name( "int" )
+ AT_byte_size( 0x04 )
+
+0x0000006e: TAG_pointer_type [6]
+ AT_type( {0x00000067} ( int ) )
+ AT_byte_size( 0x08 )
+</pre></div>
+</div>
+<p>The DW_TAG_pointer_type is not included because it does not have a <tt class="docutils literal"><span class="pre">DW_AT_name</span></tt>.</p>
+<p>“<tt class="docutils literal"><span class="pre">.apple_namespaces</span></tt>” section should contain all <tt class="docutils literal"><span class="pre">DW_TAG_namespace</span></tt> DIEs.
+If we run into a namespace that has no name this is an anonymous namespace, and
+the name should be output as “<tt class="docutils literal"><span class="pre">(anonymous</span> <span class="pre">namespace)</span></tt>” (without the quotes).
+Why? This matches the output of the <tt class="docutils literal"><span class="pre">abi::cxa_demangle()</span></tt> that is in the
+standard C++ library that demangles mangled names.</p>
+</div>
+<div class="section" id="language-extensions-and-file-format-changes">
+<h4><a class="toc-backref" href="#id36">Language Extensions and File Format Changes</a><a class="headerlink" href="#language-extensions-and-file-format-changes" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="objective-c-extensions">
+<h5><a class="toc-backref" href="#id37">Objective-C Extensions</a><a class="headerlink" href="#objective-c-extensions" title="Permalink to this headline">¶</a></h5>
+<p>“<tt class="docutils literal"><span class="pre">.apple_objc</span></tt>” section should contain all <tt class="docutils literal"><span class="pre">DW_TAG_subprogram</span></tt> DIEs for an
+Objective-C class. The name used in the hash table is the name of the
+Objective-C class itself. If the Objective-C class has a category, then an
+entry is made for both the class name without the category, and for the class
+name with the category. So if we have a DIE at offset 0x1234 with a name of
+method “<tt class="docutils literal"><span class="pre">-[NSString(my_additions)</span> <span class="pre">stringWithSpecialString:]</span></tt>”, we would add
+an entry for “<tt class="docutils literal"><span class="pre">NSString</span></tt>” that points to DIE 0x1234, and an entry for
+“<tt class="docutils literal"><span class="pre">NSString(my_additions)</span></tt>” that points to 0x1234. This allows us to quickly
+track down all Objective-C methods for an Objective-C class when doing
+expressions. It is needed because of the dynamic nature of Objective-C where
+anyone can add methods to a class. The DWARF for Objective-C methods is also
+emitted differently from C++ classes where the methods are not usually
+contained in the class definition, they are scattered about across one or more
+compile units. Categories can also be defined in different shared libraries.
+So we need to be able to quickly find all of the methods and class functions
+given the Objective-C class name, or quickly find all methods and class
+functions for a class + category name. This table does not contain any
+selector names, it just maps Objective-C class names (or class names +
+category) to all of the methods and class functions. The selectors are added
+as function basenames in the “<tt class="docutils literal"><span class="pre">.debug_names</span></tt>” section.</p>
+<p>In the “<tt class="docutils literal"><span class="pre">.apple_names</span></tt>” section for Objective-C functions, the full name is
+the entire function name with the brackets (“<tt class="docutils literal"><span class="pre">-[NSString</span>
+<span class="pre">stringWithCString:]</span></tt>”) and the basename is the selector only
+(“<tt class="docutils literal"><span class="pre">stringWithCString:</span></tt>”).</p>
+</div>
+<div class="section" id="mach-o-changes">
+<h5><a class="toc-backref" href="#id38">Mach-O Changes</a><a class="headerlink" href="#mach-o-changes" title="Permalink to this headline">¶</a></h5>
+<p>The sections names for the apple hash tables are for non-mach-o files. For
+mach-o files, the sections should be contained in the <tt class="docutils literal"><span class="pre">__DWARF</span></tt> segment with
+names as follows:</p>
+<ul class="simple">
+<li>“<tt class="docutils literal"><span class="pre">.apple_names</span></tt>” -> “<tt class="docutils literal"><span class="pre">__apple_names</span></tt>“</li>
+<li>“<tt class="docutils literal"><span class="pre">.apple_types</span></tt>” -> “<tt class="docutils literal"><span class="pre">__apple_types</span></tt>“</li>
+<li>“<tt class="docutils literal"><span class="pre">.apple_namespaces</span></tt>” -> “<tt class="docutils literal"><span class="pre">__apple_namespac</span></tt>” (16 character limit)</li>
+<li>“<tt class="docutils literal"><span class="pre">.apple_objc</span></tt>” -> “<tt class="docutils literal"><span class="pre">__apple_objc</span></tt>“</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="codeview-debug-info-format">
+<span id="codeview"></span><h2><a class="toc-backref" href="#id39">CodeView Debug Info Format</a><a class="headerlink" href="#codeview-debug-info-format" title="Permalink to this headline">¶</a></h2>
+<p>LLVM supports emitting CodeView, the Microsoft debug info format, and this
+section describes the design and implementation of that support.</p>
+<div class="section" id="format-background">
+<h3><a class="toc-backref" href="#id40">Format Background</a><a class="headerlink" href="#format-background" title="Permalink to this headline">¶</a></h3>
+<p>CodeView as a format is clearly oriented around C++ debugging, and in C++, the
+majority of debug information tends to be type information. Therefore, the
+overriding design constraint of CodeView is the separation of type information
+from other “symbol” information so that type information can be efficiently
+merged across translation units. Both type information and symbol information is
+generally stored as a sequence of records, where each record begins with a
+16-bit record size and a 16-bit record kind.</p>
+<p>Type information is usually stored in the <tt class="docutils literal"><span class="pre">.debug$T</span></tt> section of the object
+file. All other debug info, such as line info, string table, symbol info, and
+inlinee info, is stored in one or more <tt class="docutils literal"><span class="pre">.debug$S</span></tt> sections. There may only be
+one <tt class="docutils literal"><span class="pre">.debug$T</span></tt> section per object file, since all other debug info refers to
+it. If a PDB (enabled by the <tt class="docutils literal"><span class="pre">/Zi</span></tt> MSVC option) was used during compilation,
+the <tt class="docutils literal"><span class="pre">.debug$T</span></tt> section will contain only an <tt class="docutils literal"><span class="pre">LF_TYPESERVER2</span></tt> record pointing
+to the PDB. When using PDBs, symbol information appears to remain in the object
+file <tt class="docutils literal"><span class="pre">.debug$S</span></tt> sections.</p>
+<p>Type records are referred to by their index, which is the number of records in
+the stream before a given record plus <tt class="docutils literal"><span class="pre">0x1000</span></tt>. Many common basic types, such
+as the basic integral types and unqualified pointers to them, are represented
+using type indices less than <tt class="docutils literal"><span class="pre">0x1000</span></tt>. Such basic types are built in to
+CodeView consumers and do not require type records.</p>
+<p>Each type record may only contain type indices that are less than its own type
+index. This ensures that the graph of type stream references is acyclic. While
+the source-level type graph may contain cycles through pointer types (consider a
+linked list struct), these cycles are removed from the type stream by always
+referring to the forward declaration record of user-defined record types. Only
+“symbol” records in the <tt class="docutils literal"><span class="pre">.debug$S</span></tt> streams may refer to complete,
+non-forward-declaration type records.</p>
+</div>
+<div class="section" id="working-with-codeview">
+<h3><a class="toc-backref" href="#id41">Working with CodeView</a><a class="headerlink" href="#working-with-codeview" title="Permalink to this headline">¶</a></h3>
+<p>These are instructions for some common tasks for developers working to improve
+LLVM’s CodeView support. Most of them revolve around using the CodeView dumper
+embedded in <tt class="docutils literal"><span class="pre">llvm-readobj</span></tt>.</p>
+<ul>
+<li><p class="first">Testing MSVC’s output:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ cl -c -Z7 foo.cpp # Use /Z7 to keep types in the object file
+$ llvm-readobj -codeview foo.obj
+</pre></div>
+</div>
+</li>
+<li><p class="first">Getting LLVM IR debug info out of Clang:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ clang -g -gcodeview --target=x86_64-windows-msvc foo.cpp -S -emit-llvm
+</pre></div>
+</div>
+<p>Use this to generate LLVM IR for LLVM test cases.</p>
+</li>
+<li><p class="first">Generate and dump CodeView from LLVM IR metadata:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ llc foo.ll -filetype=obj -o foo.obj
+$ llvm-readobj -codeview foo.obj > foo.txt
+</pre></div>
+</div>
+<p>Use this pattern in lit test cases and FileCheck the output of llvm-readobj</p>
+</li>
+</ul>
+<p>Improving LLVM’s CodeView support is a process of finding interesting type
+records, constructing a C++ test case that makes MSVC emit those records,
+dumping the records, understanding them, and then generating equivalent records
+in LLVM’s backend.</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="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SystemLibrary.html" title="System Library"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/SphinxQuickstartTemplate.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/SphinxQuickstartTemplate.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/SphinxQuickstartTemplate.html (added)
+++ www-releases/trunk/3.9.1/docs/SphinxQuickstartTemplate.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,223 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Sphinx Quickstart Template — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="Code Reviews with Phabricator" href="Phabricator.html" />
+ <link rel="prev" title="How to submit an LLVM bug report" href="HowToSubmitABug.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="Phabricator.html" title="Code Reviews with Phabricator"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
+ 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="sphinx-quickstart-template">
+<h1>Sphinx Quickstart Template<a class="headerlink" href="#sphinx-quickstart-template" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction-and-quickstart">
+<h2>Introduction and Quickstart<a class="headerlink" href="#introduction-and-quickstart" title="Permalink to this headline">¶</a></h2>
+<p>This document is meant to get you writing documentation as fast as possible
+even if you have no previous experience with Sphinx. The goal is to take
+someone in the state of “I want to write documentation and get it added to
+LLVM’s docs” and turn that into useful documentation mailed to llvm-commits
+with as little nonsense as possible.</p>
+<p>You can find this document in <tt class="docutils literal"><span class="pre">docs/SphinxQuickstartTemplate.rst</span></tt>. You
+should copy it, open the new file in your text editor, write your docs, and
+then send the new document to llvm-commits for review.</p>
+<p>Focus on <em>content</em>. It is easy to fix the Sphinx (reStructuredText) syntax
+later if necessary, although reStructuredText tries to imitate common
+plain-text conventions so it should be quite natural. A basic knowledge of
+reStructuredText syntax is useful when writing the document, so the last
+~half of this document (starting with <a class="reference internal" href="#example-section">Example Section</a>) gives examples
+which should cover 99% of use cases.</p>
+<p>Let me say that again: focus on <em>content</em>. But if you really need to verify
+Sphinx’s output, see <tt class="docutils literal"><span class="pre">docs/README.txt</span></tt> for information.</p>
+<p>Once you have finished with the content, please send the <tt class="docutils literal"><span class="pre">.rst</span></tt> file to
+llvm-commits for review.</p>
+</div>
+<div class="section" id="guidelines">
+<h2>Guidelines<a class="headerlink" href="#guidelines" title="Permalink to this headline">¶</a></h2>
+<p>Try to answer the following questions in your first section:</p>
+<ol class="arabic simple">
+<li>Why would I want to read this document?</li>
+<li>What should I know to be able to follow along with this document?</li>
+<li>What will I have learned by the end of this document?</li>
+</ol>
+<p>Common names for the first section are <tt class="docutils literal"><span class="pre">Introduction</span></tt>, <tt class="docutils literal"><span class="pre">Overview</span></tt>, or
+<tt class="docutils literal"><span class="pre">Background</span></tt>.</p>
+<p>If possible, make your document a “how to”. Give it a name <tt class="docutils literal"><span class="pre">HowTo*.rst</span></tt>
+like the other “how to” documents. This format is usually the easiest
+for another person to understand and also the most useful.</p>
+<p>You generally should not be writing documentation other than a “how to”
+unless there is already a “how to” about your topic. The reason for this
+is that without a “how to” document to read first, it is difficult for a
+person to understand a more advanced document.</p>
+<p>Focus on content (yes, I had to say it again).</p>
+<p>The rest of this document shows example reStructuredText markup constructs
+that are meant to be read by you in your text editor after you have copied
+this file into a new file for the documentation you are about to write.</p>
+</div>
+<div class="section" id="example-section">
+<h2>Example Section<a class="headerlink" href="#example-section" title="Permalink to this headline">¶</a></h2>
+<p>Your text can be <em>emphasized</em>, <strong>bold</strong>, or <tt class="docutils literal"><span class="pre">monospace</span></tt>.</p>
+<p>Use blank lines to separate paragraphs.</p>
+<p>Headings (like <tt class="docutils literal"><span class="pre">Example</span> <span class="pre">Section</span></tt> just above) give your document its
+structure. Use the same kind of adornments (e.g. <tt class="docutils literal"><span class="pre">======</span></tt> vs. <tt class="docutils literal"><span class="pre">------</span></tt>)
+as are used in this document. The adornment must be the same length as the
+text above it. For Vim users, variations of <tt class="docutils literal"><span class="pre">yypVr=</span></tt> might be handy.</p>
+<div class="section" id="example-subsection">
+<h3>Example Subsection<a class="headerlink" href="#example-subsection" title="Permalink to this headline">¶</a></h3>
+<p>Make a link <a class="reference external" href="http://llvm.org/">like this</a>. There is also a more
+sophisticated syntax which <a class="reference external" href="http://en.wikipedia.org/wiki/LLVM">can be more readable</a> for longer links since
+it disrupts the flow less. You can put the <tt class="docutils literal"><span class="pre">..</span> <span class="pre">_`link</span> <span class="pre">text`:</span> <span class="pre"><URL></span></tt> block
+pretty much anywhere later in the document.</p>
+<p>Lists can be made like this:</p>
+<ol class="arabic simple">
+<li>A list starting with <tt class="docutils literal"><span class="pre">#.</span></tt> will be automatically numbered.</li>
+<li>This is a second list element.<ol class="arabic">
+<li>Use indentation to create nested lists.</li>
+</ol>
+</li>
+</ol>
+<p>You can also use unordered lists.</p>
+<ul class="simple">
+<li>Stuff.<ul>
+<li>Deeper stuff.</li>
+</ul>
+</li>
+<li>More stuff.</li>
+</ul>
+<div class="section" id="example-subsubsection">
+<h4>Example Subsubsection<a class="headerlink" href="#example-subsubsection" title="Permalink to this headline">¶</a></h4>
+<p>You can make blocks of code like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For a shell session, use a <tt class="docutils literal"><span class="pre">console</span></tt> code block (some existing docs use
+<tt class="docutils literal"><span class="pre">bash</span></tt>):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"Goodbye cruel world!"</span>
+<span class="gp">$</span> rm -rf /
+</pre></div>
+</div>
+<p>If you need to show LLVM IR use the <tt class="docutils literal"><span class="pre">llvm</span></tt> code block.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@test1</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Some other common code blocks you might need are <tt class="docutils literal"><span class="pre">c</span></tt>, <tt class="docutils literal"><span class="pre">objc</span></tt>, <tt class="docutils literal"><span class="pre">make</span></tt>,
+and <tt class="docutils literal"><span class="pre">cmake</span></tt>. If you need something beyond that, you can look at the <a class="reference external" href="http://pygments.org/docs/lexers/">full
+list</a> of supported code blocks.</p>
+<p>However, don’t waste time fiddling with syntax highlighting when you could
+be adding meaningful content. When in doubt, show preformatted text
+without any syntax highlighting like this:</p>
+<div class="highlight-python"><div class="highlight"><pre> .
+ +:.
+ ..:: ::
+ .++:+:: ::+:.:.
+ .:+ :
+ ::.::..:: .+.
+ ..:+ :: :
+......+:. ..
+ :++. .. :
+ .+:::+:: :
+ .. . .+ ::
+ +.: .::+.
+ ...+. .: .
+ .++:..
+ ...
+</pre></div>
+</div>
+<div class="section" id="hopefully-you-won-t-need-to-be-this-deep">
+<h5>Hopefully you won’t need to be this deep<a class="headerlink" href="#hopefully-you-won-t-need-to-be-this-deep" title="Permalink to this headline">¶</a></h5>
+<p>If you need to do fancier things than what has been shown in this document,
+you can mail the list or check Sphinx’s <a class="reference external" href="http://sphinx.pocoo.org/rest.html">reStructuredText Primer</a>.</p>
+</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="Phabricator.html" title="Code Reviews with Phabricator"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/StackMaps.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/StackMaps.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/StackMaps.html (added)
+++ www-releases/trunk/3.9.1/docs/StackMaps.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,582 @@
+
+<!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>Stack maps and patch points in LLVM — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="Design and Usage of the InAlloca Attribute" href="InAlloca.html" />
+ <link rel="prev" title="User Guide for AMDGPU Back-end" href="AMDGPUUsage.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="InAlloca.html" title="Design and Usage of the InAlloca Attribute"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="AMDGPUUsage.html" title="User Guide for AMDGPU Back-end"
+ 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="stack-maps-and-patch-points-in-llvm">
+<h1>Stack maps and patch points in LLVM<a class="headerlink" href="#stack-maps-and-patch-points-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="#definitions" id="id5">Definitions</a></li>
+<li><a class="reference internal" href="#motivation" id="id6">Motivation</a></li>
+<li><a class="reference internal" href="#intrinsics" id="id7">Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-experimental-stackmap-intrinsic" id="id8">‘<tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt>‘ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-experimental-patchpoint-intrinsic" id="id9">‘<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint.*</span></tt>‘ Intrinsic</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#stack-map-format" id="id10">Stack Map Format</a><ul>
+<li><a class="reference internal" href="#stack-map-section" id="id11">Stack Map Section</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#stack-map-usage" id="id12">Stack Map Usage</a><ul>
+<li><a class="reference internal" href="#direct-stack-map-entries" id="id13">Direct Stack Map Entries</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-architectures" id="id14">Supported Architectures</a></li>
+</ul>
+</div>
+<div class="section" id="definitions">
+<h2><a class="toc-backref" href="#id5">Definitions</a><a class="headerlink" href="#definitions" title="Permalink to this headline">¶</a></h2>
+<p>In this document we refer to the “runtime” collectively as all
+components that serve as the LLVM client, including the LLVM IR
+generator, object code consumer, and code patcher.</p>
+<p>A stack map records the location of <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> at a particular
+instruction address. These <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> do not refer to all the
+LLVM values live across the stack map. Instead, they are only the
+values that the runtime requires to be live at this point. For
+example, they may be the values the runtime will need to resume
+program execution at that point independent of the compiled function
+containing the stack map.</p>
+<p>LLVM emits stack map data into the object code within a designated
+<a class="reference internal" href="#stackmap-section"><em>Stack Map Section</em></a>. This stack map data contains a record for
+each stack map. The record stores the stack map’s instruction address
+and contains a entry for each mapped value. Each entry encodes a
+value’s location as a register, stack offset, or constant.</p>
+<p>A patch point is an instruction address at which space is reserved for
+patching a new instruction sequence at run time. Patch points look
+much like calls to LLVM. They take arguments that follow a calling
+convention and may return a value. They also imply stack map
+generation, which allows the runtime to locate the patchpoint and
+find the location of <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> at that point.</p>
+</div>
+<div class="section" id="motivation">
+<h2><a class="toc-backref" href="#id6">Motivation</a><a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2>
+<p>This functionality is currently experimental but is potentially useful
+in a variety of settings, the most obvious being a runtime (JIT)
+compiler. Example applications of the patchpoint intrinsics are
+implementing an inline call cache for polymorphic method dispatch or
+optimizing the retrieval of properties in dynamically typed languages
+such as JavaScript.</p>
+<p>The intrinsics documented here are currently used by the JavaScript
+compiler within the open source WebKit project, see the <a class="reference external" href="https://trac.webkit.org/wiki/FTLJIT">FTL JIT</a>, but they are designed to be
+used whenever stack maps or code patching are needed. Because the
+intrinsics have experimental status, compatibility across LLVM
+releases is not guaranteed.</p>
+<p>The stack map functionality described in this document is separate
+from the functionality described in
+<a class="reference internal" href="GarbageCollection.html#stack-map"><em>Computing stack maps</em></a>. <cite>GCFunctionMetadata</cite> provides the location of
+pointers into a collected heap captured by the <cite>GCRoot</cite> intrinsic,
+which can also be considered a “stack map”. Unlike the stack maps
+defined above, the <cite>GCFunctionMetadata</cite> stack map interface does not
+provide a way to associate live register values of arbitrary type with
+an instruction address, nor does it specify a format for the resulting
+stack map. The stack maps described here could potentially provide
+richer information to a garbage collecting runtime, but that usage
+will not be discussed in this document.</p>
+</div>
+<div class="section" id="intrinsics">
+<h2><a class="toc-backref" href="#id7">Intrinsics</a><a class="headerlink" href="#intrinsics" title="Permalink to this headline">¶</a></h2>
+<p>The following two kinds of intrinsics can be used to implement stack
+maps and patch points: <tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt> and
+<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt>. Both kinds of intrinsics generate a
+stack map record, and they both allow some form of code patching. They
+can be used independently (i.e. <tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt>
+implicitly generates a stack map without the need for an additional
+call to <tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt>). The choice of which to use
+depends on whether it is necessary to reserve space for code patching
+and whether any of the intrinsic arguments should be lowered according
+to calling conventions. <tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt> does not
+reserve any space, nor does it expect any call arguments. If the
+runtime patches code at the stack map’s address, it will destructively
+overwrite the program text. This is unlike
+<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt>, which reserves space for in-place
+patching without overwriting surrounding code. The
+<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt> intrinsic also lowers a specified
+number of arguments according to its calling convention. This allows
+patched code to make in-place function calls without marshaling.</p>
+<p>Each instance of one of these intrinsics generates a stack map record
+in the <a class="reference internal" href="#stackmap-section"><em>Stack Map Section</em></a>. The record includes an ID, allowing
+the runtime to uniquely identify the stack map, and the offset within
+the code from the beginning of the enclosing function.</p>
+<div class="section" id="llvm-experimental-stackmap-intrinsic">
+<h3><a class="toc-backref" href="#id8">‘<tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt>‘ Intrinsic</a><a class="headerlink" href="#llvm-experimental-stackmap-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="syntax">
+<h4>Syntax:<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare void
+ @llvm.experimental.stackmap(i64 <id>, i32 <numShadowBytes>, ...)
+</pre></div>
+</div>
+</div>
+<div class="section" id="overview">
+<h4>Overview:<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h4>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt>‘ intrinsic records the location of
+specified values in the stack map without generating any code.</p>
+</div>
+<div class="section" id="operands">
+<h4>Operands:<a class="headerlink" href="#operands" title="Permalink to this headline">¶</a></h4>
+<p>The first operand is an ID to be encoded within the stack map. The
+second operand is the number of shadow bytes following the
+intrinsic. The variable number of operands that follow are the <tt class="docutils literal"><span class="pre">live</span>
+<span class="pre">values</span></tt> for which locations will be recorded in the stack map.</p>
+<p>To use this intrinsic as a bare-bones stack map, with no code patching
+support, the number of shadow bytes can be set to zero.</p>
+</div>
+<div class="section" id="semantics">
+<h4>Semantics:<a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h4>
+<p>The stack map intrinsic generates no code in place, unless nops are
+needed to cover its shadow (see below). However, its offset from
+function entry is stored in the stack map. This is the relative
+instruction address immediately following the instructions that
+precede the stack map.</p>
+<p>The stack map ID allows a runtime to locate the desired stack map
+record. LLVM passes this ID through directly to the stack map
+record without checking uniqueness.</p>
+<p>LLVM guarantees a shadow of instructions following the stack map’s
+instruction offset during which neither the end of the basic block nor
+another call to <tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt> or
+<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt> may occur. This allows the runtime to
+patch the code at this point in response to an event triggered from
+outside the code. The code for instructions following the stack map
+may be emitted in the stack map’s shadow, and these instructions may
+be overwritten by destructive patching. Without shadow bytes, this
+destructive patching could overwrite program text or data outside the
+current function. We disallow overlapping stack map shadows so that
+the runtime does not need to consider this corner case.</p>
+<p>For example, a stack map with 8 byte shadow:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">call</span> <span class="kt">void</span> <span class="vg">@runtime</span><span class="p">()</span>
+<span class="k">call</span> <span class="kt">void</span> <span class="p">(</span><span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="p">...)*</span> <span class="vg">@llvm.experimental.stackmap</span><span class="p">(</span><span class="k">i64</span> <span class="m">77</span><span class="p">,</span> <span class="k">i32</span> <span class="m">8</span><span class="p">,</span>
+ <span class="k">i64</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">)</span>
+<span class="nv">%val</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i64</span><span class="p">*</span> <span class="nv">%ptr</span>
+<span class="nv">%add</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i64</span> <span class="nv">%val</span><span class="p">,</span> <span class="m">3</span>
+<span class="k">ret</span> <span class="k">i64</span> <span class="nv">%add</span>
+</pre></div>
+</div>
+<p>May require one byte of nop-padding:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00 callq _runtime
+0x05 nop <--- stack map address
+0x06 movq (%rdi), %rax
+0x07 addq $3, %rax
+0x0a popq %rdx
+0x0b ret <---- end of 8-byte shadow
+</pre></div>
+</div>
+<p>Now, if the runtime needs to invalidate the compiled code, it may
+patch 8 bytes of code at the stack map’s address at follows:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00 callq _runtime
+0x05 movl $0xffff, %rax <--- patched code at stack map address
+0x0a callq *%rax <---- end of 8-byte shadow
+</pre></div>
+</div>
+<p>This way, after the normal call to the runtime returns, the code will
+execute a patched call to a special entry point that can rebuild a
+stack frame from the values located by the stack map.</p>
+</div>
+</div>
+<div class="section" id="llvm-experimental-patchpoint-intrinsic">
+<h3><a class="toc-backref" href="#id9">‘<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint.*</span></tt>‘ Intrinsic</a><a class="headerlink" href="#llvm-experimental-patchpoint-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id1">
+<h4>Syntax:<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare void
+ @llvm.experimental.patchpoint.void(i64 <id>, i32 <numBytes>,
+ i8* <target>, i32 <numArgs>, ...)
+declare i64
+ @llvm.experimental.patchpoint.i64(i64 <id>, i32 <numBytes>,
+ i8* <target>, i32 <numArgs>, ...)
+</pre></div>
+</div>
+</div>
+<div class="section" id="id2">
+<h4>Overview:<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint.*</span></tt>‘ intrinsics creates a function
+call to the specified <tt class="docutils literal"><span class="pre"><target></span></tt> and records the location of specified
+values in the stack map.</p>
+</div>
+<div class="section" id="id3">
+<h4>Operands:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>The first operand is an ID, the second operand is the number of bytes
+reserved for the patchable region, the third operand is the target
+address of a function (optionally null), and the fourth operand
+specifies how many of the following variable operands are considered
+function call arguments. The remaining variable number of operands are
+the <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> for which locations will be recorded in the stack
+map.</p>
+</div>
+<div class="section" id="id4">
+<h4>Semantics:<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>The patch point intrinsic generates a stack map. It also emits a
+function call to the address specified by <tt class="docutils literal"><span class="pre"><target></span></tt> if the address
+is not a constant null. The function call and its arguments are
+lowered according to the calling convention specified at the
+intrinsic’s callsite. Variants of the intrinsic with non-void return
+type also return a value according to calling convention.</p>
+<p>On PowerPC, note that <tt class="docutils literal"><span class="pre"><target></span></tt> must be the ABI function pointer for the
+intended target of the indirect call. Specifically, when compiling for the
+ELF V1 ABI, <tt class="docutils literal"><span class="pre"><target></span></tt> is the function-descriptor address normally used as
+the C/C++ function-pointer representation.</p>
+<p>Requesting zero patch point arguments is valid. In this case, all
+variable operands are handled just like
+<tt class="docutils literal"><span class="pre">llvm.experimental.stackmap.*</span></tt>. The difference is that space will
+still be reserved for patching, a call will be emitted, and a return
+value is allowed.</p>
+<p>The location of the arguments are not normally recorded in the stack
+map because they are already fixed by the calling convention. The
+remaining <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> will have their location recorded, which
+could be a register, stack location, or constant. A special calling
+convention has been introduced for use with stack maps, anyregcc,
+which forces the arguments to be loaded into registers but allows
+those register to be dynamically allocated. These argument registers
+will have their register locations recorded in the stack map in
+addition to the remaining <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt>.</p>
+<p>The patch point also emits nops to cover at least <tt class="docutils literal"><span class="pre"><numBytes></span></tt> of
+instruction encoding space. Hence, the client must ensure that
+<tt class="docutils literal"><span class="pre"><numBytes></span></tt> is enough to encode a call to the target address on the
+supported targets. If the call target is constant null, then there is
+no minimum requirement. A zero-byte null target patchpoint is
+valid.</p>
+<p>The runtime may patch the code emitted for the patch point, including
+the call sequence and nops. However, the runtime may not assume
+anything about the code LLVM emits within the reserved space. Partial
+patching is not allowed. The runtime must patch all reserved bytes,
+padding with nops if necessary.</p>
+<p>This example shows a patch point reserving 15 bytes, with one argument
+in $rdi, and a return value in $rax per native calling convention:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%target</span> <span class="p">=</span> <span class="k">inttoptr</span> <span class="k">i64</span> <span class="m">-281474976710654</span> <span class="k">to</span> <span class="k">i8</span><span class="p">*</span>
+<span class="nv">%val</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i64</span> <span class="p">(</span><span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="p">...)*</span>
+ <span class="vg">@llvm.experimental.patchpoint.i64</span><span class="p">(</span><span class="k">i64</span> <span class="m">78</span><span class="p">,</span> <span class="k">i32</span> <span class="m">15</span><span class="p">,</span>
+ <span class="k">i8</span><span class="p">*</span> <span class="nv">%target</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="k">i64</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">)</span>
+<span class="nv">%add</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i64</span> <span class="nv">%val</span><span class="p">,</span> <span class="m">3</span>
+<span class="k">ret</span> <span class="k">i64</span> <span class="nv">%add</span>
+</pre></div>
+</div>
+<p>May generate:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00 movabsq $0xffff000000000002, %r11 <--- patch point address
+0x0a callq *%r11
+0x0d nop
+0x0e nop <--- end of reserved 15-bytes
+0x0f addq $0x3, %rax
+0x10 movl %rax, 8(%rsp)
+</pre></div>
+</div>
+<p>Note that no stack map locations will be recorded. If the patched code
+sequence does not need arguments fixed to specific calling convention
+registers, then the <tt class="docutils literal"><span class="pre">anyregcc</span></tt> convention may be used:</p>
+<div class="highlight-none"><div class="highlight"><pre>%val = call anyregcc @llvm.experimental.patchpoint(i64 78, i32 15,
+ i8* %target, i32 1,
+ i64* %ptr)
+</pre></div>
+</div>
+<p>The stack map now indicates the location of the %ptr argument and
+return value:</p>
+<div class="highlight-none"><div class="highlight"><pre>Stack Map: ID=78, Loc0=%r9 Loc1=%r8
+</pre></div>
+</div>
+<p>The patch code sequence may now use the argument that happened to be
+allocated in %r8 and return a value allocated in %r9:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00 movslq 4(%r8) %r9 <--- patched code at patch point address
+0x03 nop
+...
+0x0e nop <--- end of reserved 15-bytes
+0x0f addq $0x3, %r9
+0x10 movl %r9, 8(%rsp)
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="stack-map-format">
+<span id="stackmap-format"></span><h2><a class="toc-backref" href="#id10">Stack Map Format</a><a class="headerlink" href="#stack-map-format" title="Permalink to this headline">¶</a></h2>
+<p>The existence of a stack map or patch point intrinsic within an LLVM
+Module forces code emission to create a <a class="reference internal" href="#stackmap-section"><em>Stack Map Section</em></a>. The
+format of this section follows:</p>
+<div class="highlight-none"><div class="highlight"><pre>Header {
+ uint8 : Stack Map Version (current version is 1)
+ uint8 : Reserved (expected to be 0)
+ uint16 : Reserved (expected to be 0)
+}
+uint32 : NumFunctions
+uint32 : NumConstants
+uint32 : NumRecords
+StkSizeRecord[NumFunctions] {
+ uint64 : Function Address
+ uint64 : Stack Size
+}
+Constants[NumConstants] {
+ uint64 : LargeConstant
+}
+StkMapRecord[NumRecords] {
+ uint64 : PatchPoint ID
+ uint32 : Instruction Offset
+ uint16 : Reserved (record flags)
+ uint16 : NumLocations
+ Location[NumLocations] {
+ uint8 : Register | Direct | Indirect | Constant | ConstantIndex
+ uint8 : Reserved (location flags)
+ uint16 : Dwarf RegNum
+ int32 : Offset or SmallConstant
+ }
+ uint16 : Padding
+ uint16 : NumLiveOuts
+ LiveOuts[NumLiveOuts]
+ uint16 : Dwarf RegNum
+ uint8 : Reserved
+ uint8 : Size in Bytes
+ }
+ uint32 : Padding (only if required to align to 8 byte)
+}
+</pre></div>
+</div>
+<p>The first byte of each location encodes a type that indicates how to
+interpret the <tt class="docutils literal"><span class="pre">RegNum</span></tt> and <tt class="docutils literal"><span class="pre">Offset</span></tt> fields as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="13%" />
+<col width="16%" />
+<col width="30%" />
+<col width="42%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>Encoding</td>
+<td>Type</td>
+<td>Value</td>
+<td>Description</td>
+</tr>
+<tr class="row-even"><td>0x1</td>
+<td>Register</td>
+<td>Reg</td>
+<td>Value in a register</td>
+</tr>
+<tr class="row-odd"><td>0x2</td>
+<td>Direct</td>
+<td>Reg + Offset</td>
+<td>Frame index value</td>
+</tr>
+<tr class="row-even"><td>0x3</td>
+<td>Indirect</td>
+<td>[Reg + Offset]</td>
+<td>Spilled value</td>
+</tr>
+<tr class="row-odd"><td>0x4</td>
+<td>Constant</td>
+<td>Offset</td>
+<td>Small constant</td>
+</tr>
+<tr class="row-even"><td>0x5</td>
+<td>ConstIndex</td>
+<td>Constants[Offset]</td>
+<td>Large constant</td>
+</tr>
+</tbody>
+</table>
+<p>In the common case, a value is available in a register, and the
+<tt class="docutils literal"><span class="pre">Offset</span></tt> field will be zero. Values spilled to the stack are encoded
+as <tt class="docutils literal"><span class="pre">Indirect</span></tt> locations. The runtime must load those values from a
+stack address, typically in the form <tt class="docutils literal"><span class="pre">[BP</span> <span class="pre">+</span> <span class="pre">Offset]</span></tt>. If an
+<tt class="docutils literal"><span class="pre">alloca</span></tt> value is passed directly to a stack map intrinsic, then
+LLVM may fold the frame index into the stack map as an optimization to
+avoid allocating a register or stack slot. These frame indices will be
+encoded as <tt class="docutils literal"><span class="pre">Direct</span></tt> locations in the form <tt class="docutils literal"><span class="pre">BP</span> <span class="pre">+</span> <span class="pre">Offset</span></tt>. LLVM may
+also optimize constants by emitting them directly in the stack map,
+either in the <tt class="docutils literal"><span class="pre">Offset</span></tt> of a <tt class="docutils literal"><span class="pre">Constant</span></tt> location or in the constant
+pool, referred to by <tt class="docutils literal"><span class="pre">ConstantIndex</span></tt> locations.</p>
+<p>At each callsite, a “liveout” register list is also recorded. These
+are the registers that are live across the stackmap and therefore must
+be saved by the runtime. This is an important optimization when the
+patchpoint intrinsic is used with a calling convention that by default
+preserves most registers as callee-save.</p>
+<p>Each entry in the liveout register list contains a DWARF register
+number and size in bytes. The stackmap format deliberately omits
+specific subregister information. Instead the runtime must interpret
+this information conservatively. For example, if the stackmap reports
+one byte at <tt class="docutils literal"><span class="pre">%rax</span></tt>, then the value may be in either <tt class="docutils literal"><span class="pre">%al</span></tt> or
+<tt class="docutils literal"><span class="pre">%ah</span></tt>. It doesn’t matter in practice, because the runtime will
+simply save <tt class="docutils literal"><span class="pre">%rax</span></tt>. However, if the stackmap reports 16 bytes at
+<tt class="docutils literal"><span class="pre">%ymm0</span></tt>, then the runtime can safely optimize by saving only
+<tt class="docutils literal"><span class="pre">%xmm0</span></tt>.</p>
+<p>The stack map format is a contract between an LLVM SVN revision and
+the runtime. It is currently experimental and may change in the short
+term, but minimizing the need to update the runtime is
+important. Consequently, the stack map design is motivated by
+simplicity and extensibility. Compactness of the representation is
+secondary because the runtime is expected to parse the data
+immediately after compiling a module and encode the information in its
+own format. Since the runtime controls the allocation of sections, it
+can reuse the same stack map space for multiple modules.</p>
+<p>Stackmap support is currently only implemented for 64-bit
+platforms. However, a 32-bit implementation should be able to use the
+same format with an insignificant amount of wasted space.</p>
+<div class="section" id="stack-map-section">
+<span id="stackmap-section"></span><h3><a class="toc-backref" href="#id11">Stack Map Section</a><a class="headerlink" href="#stack-map-section" title="Permalink to this headline">¶</a></h3>
+<p>A JIT compiler can easily access this section by providing its own
+memory manager via the LLVM C API
+<tt class="docutils literal"><span class="pre">LLVMCreateSimpleMCJITMemoryManager()</span></tt>. When creating the memory
+manager, the JIT provides a callback:
+<tt class="docutils literal"><span class="pre">LLVMMemoryManagerAllocateDataSectionCallback()</span></tt>. When LLVM creates
+this section, it invokes the callback and passes the section name. The
+JIT can record the in-memory address of the section at this time and
+later parse it to recover the stack map data.</p>
+<p>On Darwin, the stack map section name is “__llvm_stackmaps”. The
+segment name is “__LLVM_STACKMAPS”.</p>
+</div>
+</div>
+<div class="section" id="stack-map-usage">
+<h2><a class="toc-backref" href="#id12">Stack Map Usage</a><a class="headerlink" href="#stack-map-usage" title="Permalink to this headline">¶</a></h2>
+<p>The stack map support described in this document can be used to
+precisely determine the location of values at a specific position in
+the code. LLVM does not maintain any mapping between those values and
+any higher-level entity. The runtime must be able to interpret the
+stack map record given only the ID, offset, and the order of the
+locations, which LLVM preserves.</p>
+<p>Note that this is quite different from the goal of debug information,
+which is a best-effort attempt to track the location of named
+variables at every instruction.</p>
+<p>An important motivation for this design is to allow a runtime to
+commandeer a stack frame when execution reaches an instruction address
+associated with a stack map. The runtime must be able to rebuild a
+stack frame and resume program execution using the information
+provided by the stack map. For example, execution may resume in an
+interpreter or a recompiled version of the same function.</p>
+<p>This usage restricts LLVM optimization. Clearly, LLVM must not move
+stores across a stack map. However, loads must also be handled
+conservatively. If the load may trigger an exception, hoisting it
+above a stack map could be invalid. For example, the runtime may
+determine that a load is safe to execute without a type check given
+the current state of the type system. If the type system changes while
+some activation of the load’s function exists on the stack, the load
+becomes unsafe. The runtime can prevent subsequent execution of that
+load by immediately patching any stack map location that lies between
+the current call site and the load (typically, the runtime would
+simply patch all stack map locations to invalidate the function). If
+the compiler had hoisted the load above the stack map, then the
+program could crash before the runtime could take back control.</p>
+<p>To enforce these semantics, stackmap and patchpoint intrinsics are
+considered to potentially read and write all memory. This may limit
+optimization more than some clients desire. This limitation may be
+avoided by marking the call site as “readonly”. In the future we may
+also allow meta-data to be added to the intrinsic call to express
+aliasing, thereby allowing optimizations to hoist certain loads above
+stack maps.</p>
+<div class="section" id="direct-stack-map-entries">
+<h3><a class="toc-backref" href="#id13">Direct Stack Map Entries</a><a class="headerlink" href="#direct-stack-map-entries" title="Permalink to this headline">¶</a></h3>
+<p>As shown in <a class="reference internal" href="#stackmap-section"><em>Stack Map Section</em></a>, a Direct stack map location
+records the address of frame index. This address is itself the value
+that the runtime requested. This differs from Indirect locations,
+which refer to a stack locations from which the requested values must
+be loaded. Direct locations can communicate the address if an alloca,
+while Indirect locations handle register spills.</p>
+<p>For example:</p>
+<div class="highlight-none"><div class="highlight"><pre>entry:
+ %a = alloca i64...
+ llvm.experimental.stackmap(i64 <ID>, i32 <shadowBytes>, i64* %a)
+</pre></div>
+</div>
+<p>The runtime can determine this alloca’s relative location on the
+stack immediately after compilation, or at any time thereafter. This
+differs from Register and Indirect locations, because the runtime can
+only read the values in those locations when execution reaches the
+instruction address of the stack map.</p>
+<p>This functionality requires LLVM to treat entry-block allocas
+specially when they are directly consumed by an intrinsics. (This is
+the same requirement imposed by the llvm.gcroot intrinsic.) LLVM
+transformations must not substitute the alloca with any intervening
+value. This can be verified by the runtime simply by checking that the
+stack map’s location is a Direct location type.</p>
+</div>
+</div>
+<div class="section" id="supported-architectures">
+<h2><a class="toc-backref" href="#id14">Supported Architectures</a><a class="headerlink" href="#supported-architectures" title="Permalink to this headline">¶</a></h2>
+<p>Support for StackMap generation and the related intrinsics requires
+some code for each backend. Today, only a subset of LLVM’s backends
+are supported. The currently supported architectures are X86_64,
+PowerPC, and Aarch64.</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="InAlloca.html" title="Design and Usage of the InAlloca Attribute"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="AMDGPUUsage.html" title="User Guide for AMDGPU Back-end"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/Statepoints.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/Statepoints.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/Statepoints.html (added)
+++ www-releases/trunk/3.9.1/docs/Statepoints.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,854 @@
+
+<!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 Safepoints in LLVM — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="MergeFunctions pass, how it works" href="MergeFunctions.html" />
+ <link rel="prev" title="LLVM Code Coverage Mapping Format" href="CoverageMappingFormat.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="MergeFunctions.html" title="MergeFunctions pass, how it works"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CoverageMappingFormat.html" title="LLVM Code Coverage Mapping Format"
+ 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-safepoints-in-llvm">
+<h1>Garbage Collection Safepoints in LLVM<a class="headerlink" href="#garbage-collection-safepoints-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="#status" id="id12">Status</a></li>
+<li><a class="reference internal" href="#overview" id="id13">Overview</a><ul>
+<li><a class="reference internal" href="#base-derived-pointers" id="id14">Base & Derived Pointers</a></li>
+<li><a class="reference internal" href="#gc-transitions" id="id15">GC Transitions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#intrinsics" id="id16">Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-experimental-gc-statepoint-intrinsic" id="id17">‘llvm.experimental.gc.statepoint’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-experimental-gc-result-intrinsic" id="id18">‘llvm.experimental.gc.result’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-experimental-gc-relocate-intrinsic" id="id19">‘llvm.experimental.gc.relocate’ Intrinsic</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#stack-map-format" id="id20">Stack Map Format</a></li>
+<li><a class="reference internal" href="#safepoint-semantics-verification" id="id21">Safepoint Semantics & Verification</a></li>
+<li><a class="reference internal" href="#utility-passes-for-safepoint-insertion" id="id22">Utility Passes for Safepoint Insertion</a><ul>
+<li><a class="reference internal" href="#rewritestatepointsforgc" id="id23">RewriteStatepointsForGC</a></li>
+<li><a class="reference internal" href="#placesafepoints" id="id24">PlaceSafepoints</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-architectures" id="id25">Supported Architectures</a></li>
+<li><a class="reference internal" href="#problem-areas-and-active-work" id="id26">Problem Areas and Active Work</a></li>
+<li><a class="reference internal" href="#bugs-and-enhancements" id="id27">Bugs and Enhancements</a></li>
+</ul>
+</div>
+<div class="section" id="status">
+<h2><a class="toc-backref" href="#id12">Status</a><a class="headerlink" href="#status" title="Permalink to this headline">¶</a></h2>
+<p>This document describes a set of experimental extensions to LLVM. Use
+with caution. Because the intrinsics have experimental status,
+compatibility across LLVM releases is not guaranteed.</p>
+<p>LLVM currently supports an alternate mechanism for conservative
+garbage collection support using the <tt class="docutils literal"><span class="pre">gcroot</span></tt> intrinsic. The mechanism
+described here shares little in common with the alternate <tt class="docutils literal"><span class="pre">gcroot</span></tt>
+implementation and it is hoped that this mechanism will eventually
+replace the gc_root mechanism.</p>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id13">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>To collect dead objects, garbage collectors must be able to identify
+any references to objects contained within executing code, and,
+depending on the collector, potentially update them. The collector
+does not need this information at all points in code - that would make
+the problem much harder - but only at well-defined points in the
+execution known as ‘safepoints’ For most collectors, it is sufficient
+to track at least one copy of each unique pointer value. However, for
+a collector which wishes to relocate objects directly reachable from
+running code, a higher standard is required.</p>
+<p>One additional challenge is that the compiler may compute intermediate
+results (“derived pointers”) which point outside of the allocation or
+even into the middle of another allocation. The eventual use of this
+intermediate value must yield an address within the bounds of the
+allocation, but such “exterior derived pointers” may be visible to the
+collector. Given this, a garbage collector can not safely rely on the
+runtime value of an address to indicate the object it is associated
+with. If the garbage collector wishes to move any object, the
+compiler must provide a mapping, for each pointer, to an indication of
+its allocation.</p>
+<p>To simplify the interaction between a collector and the compiled code,
+most garbage collectors are organized in terms of three abstractions:
+load barriers, store barriers, and safepoints.</p>
+<ol class="arabic simple">
+<li>A load barrier is a bit of code executed immediately after the
+machine load instruction, but before any use of the value loaded.
+Depending on the collector, such a barrier may be needed for all
+loads, merely loads of a particular type (in the original source
+language), or none at all.</li>
+<li>Analogously, a store barrier is a code fragment that runs
+immediately before the machine store instruction, but after the
+computation of the value stored. The most common use of a store
+barrier is to update a ‘card table’ in a generational garbage
+collector.</li>
+<li>A safepoint is a location at which pointers visible to the compiled
+code (i.e. currently in registers or on the stack) are allowed to
+change. After the safepoint completes, the actual pointer value
+may differ, but the ‘object’ (as seen by the source language)
+pointed to will not.</li>
+</ol>
+<blockquote>
+<div>Note that the term ‘safepoint’ is somewhat overloaded. It refers to
+both the location at which the machine state is parsable and the
+coordination protocol involved in bring application threads to a
+point at which the collector can safely use that information. The
+term “statepoint” as used in this document refers exclusively to the
+former.</div></blockquote>
+<p>This document focuses on the last item - compiler support for
+safepoints in generated code. We will assume that an outside
+mechanism has decided where to place safepoints. From our
+perspective, all safepoints will be function calls. To support
+relocation of objects directly reachable from values in compiled code,
+the collector must be able to:</p>
+<ol class="arabic simple">
+<li>identify every copy of a pointer (including copies introduced by
+the compiler itself) at the safepoint,</li>
+<li>identify which object each pointer relates to, and</li>
+<li>potentially update each of those copies.</li>
+</ol>
+<p>This document describes the mechanism by which an LLVM based compiler
+can provide this information to a language runtime/collector, and
+ensure that all pointers can be read and updated if desired. The
+heart of the approach is to construct (or rewrite) the IR in a manner
+where the possible updates performed by the garbage collector are
+explicitly visible in the IR. Doing so requires that we:</p>
+<ol class="arabic simple">
+<li>create a new SSA value for each potentially relocated pointer, and
+ensure that no uses of the original (non relocated) value is
+reachable after the safepoint,</li>
+<li>specify the relocation in a way which is opaque to the compiler to
+ensure that the optimizer can not introduce new uses of an
+unrelocated value after a statepoint. This prevents the optimizer
+from performing unsound optimizations.</li>
+<li>recording a mapping of live pointers (and the allocation they’re
+associated with) for each statepoint.</li>
+</ol>
+<p>At the most abstract level, inserting a safepoint can be thought of as
+replacing a call instruction with a call to a multiple return value
+function which both calls the original target of the call, returns
+it’s result, and returns updated values for any live pointers to
+garbage collected objects.</p>
+<blockquote>
+<div>Note that the task of identifying all live pointers to garbage
+collected values, transforming the IR to expose a pointer giving the
+base object for every such live pointer, and inserting all the
+intrinsics correctly is explicitly out of scope for this document.
+The recommended approach is to use the <a class="reference internal" href="#statepoint-utilities"><em>utility passes</em></a> described below.</div></blockquote>
+<p>This abstract function call is concretely represented by a sequence of
+intrinsic calls known collectively as a “statepoint relocation sequence”.</p>
+<p>Let’s consider a simple call in LLVM IR:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="vg">@test1</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%obj</span><span class="p">)</span>
+ <span class="k">gc</span> <span class="s">"statepoint-example"</span> <span class="p">{</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="p">()*</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%obj</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Depending on our language we may need to allow a safepoint during the execution
+of <tt class="docutils literal"><span class="pre">foo</span></tt>. If so, we need to let the collector update local values in the
+current frame. If we don’t, we’ll be accessing a potential invalid reference
+once we eventually return from the call.</p>
+<p>In this example, we need to relocate the SSA value <tt class="docutils literal"><span class="pre">%obj</span></tt>. Since we can’t
+actually change the value in the SSA value <tt class="docutils literal"><span class="pre">%obj</span></tt>, we need to introduce a new
+SSA value <tt class="docutils literal"><span class="pre">%obj.relocated</span></tt> which represents the potentially changed value of
+<tt class="docutils literal"><span class="pre">%obj</span></tt> after the safepoint and update any following uses appropriately. The
+resulting relocation sequence is:</p>
+<div class="highlight-text"><div class="highlight"><pre>define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
+ gc "statepoint-example" {
+ %0 = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj)
+ %obj.relocated = call coldcc i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %0, i32 7, i32 7)
+ ret i8 addrspace(1)* %obj.relocated
+}
+</pre></div>
+</div>
+<p>Ideally, this sequence would have been represented as a M argument, N
+return value function (where M is the number of values being
+relocated + the original call arguments and N is the original return
+value + each relocated value), but LLVM does not easily support such a
+representation.</p>
+<p>Instead, the statepoint intrinsic marks the actual site of the
+safepoint or statepoint. The statepoint returns a token value (which
+exists only at compile time). To get back the original return value
+of the call, we use the <tt class="docutils literal"><span class="pre">gc.result</span></tt> intrinsic. To get the relocation
+of each pointer in turn, we use the <tt class="docutils literal"><span class="pre">gc.relocate</span></tt> intrinsic with the
+appropriate index. Note that both the <tt class="docutils literal"><span class="pre">gc.relocate</span></tt> and <tt class="docutils literal"><span class="pre">gc.result</span></tt> are
+tied to the statepoint. The combination forms a “statepoint relocation
+sequence” and represents the entirety of a parseable call or ‘statepoint’.</p>
+<p>When lowered, this example would generate the following x86 assembly:</p>
+<div class="highlight-gas"><div class="highlight"><pre> <span class="na">.globl</span> <span class="no">test1</span>
+ <span class="na">.align</span> <span class="mi">16</span><span class="p">,</span> <span class="mi">0x90</span>
+ <span class="nf">pushq</span> <span class="nv">%rax</span>
+ <span class="nf">callq</span> <span class="no">foo</span>
+<span class="nl">.Ltmp1:</span>
+ <span class="nf">movq</span> <span class="p">(</span><span class="nv">%rsp</span><span class="p">),</span> <span class="nv">%rax</span> <span class="c"># This load is redundant (oops!)</span>
+ <span class="nf">popq</span> <span class="nv">%rdx</span>
+ <span class="nf">retq</span>
+</pre></div>
+</div>
+<p>Each of the potentially relocated values has been spilled to the
+stack, and a record of that location has been recorded to the
+<a class="reference internal" href="StackMaps.html#stackmap-section"><em>Stack Map section</em></a>. If the garbage collector
+needs to update any of these pointers during the call, it knows
+exactly what to change.</p>
+<p>The relevant parts of the StackMap section for our example are:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="c"># This describes the call site</span>
+<span class="c"># Stack Maps: callsite 2882400000</span>
+ <span class="na">.quad</span> <span class="mi">2882400000</span>
+ <span class="na">.long</span> <span class="no">.Ltmp1-test1</span>
+ <span class="na">.short</span> <span class="mi">0</span>
+<span class="c"># .. 8 entries skipped ..</span>
+<span class="c"># This entry describes the spill slot which is directly addressable</span>
+<span class="c"># off RSP with offset 0. Given the value was spilled with a pushq,</span>
+<span class="c"># that makes sense.</span>
+<span class="c"># Stack Maps: Loc 8: Direct RSP [encoding: .byte 2, .byte 8, .short 7, .int 0]</span>
+ <span class="na">.byte</span> <span class="mi">2</span>
+ <span class="na">.byte</span> <span class="mi">8</span>
+ <span class="na">.short</span> <span class="mi">7</span>
+ <span class="na">.long</span> <span class="mi">0</span>
+</pre></div>
+</div>
+<p>This example was taken from the tests for the <a class="reference internal" href="#rewritestatepointsforgc"><em>RewriteStatepointsForGC</em></a> utility pass. As such, it’s full StackMap can be easily examined with the following command.</p>
+<div class="highlight-bash"><div class="highlight"><pre>opt -rewrite-statepoints-for-gc <span class="nb">test</span>/Transforms/RewriteStatepointsForGC/basics.ll -S | llc -debug-only<span class="o">=</span>stackmaps
+</pre></div>
+</div>
+<div class="section" id="base-derived-pointers">
+<h3><a class="toc-backref" href="#id14">Base & Derived Pointers</a><a class="headerlink" href="#base-derived-pointers" title="Permalink to this headline">¶</a></h3>
+<p>A “base pointer” is one which points to the starting address of an allocation
+(object). A “derived pointer” is one which is offset from a base pointer by
+some amount. When relocating objects, a garbage collector needs to be able
+to relocate each derived pointer associated with an allocation to the same
+offset from the new address.</p>
+<p>“Interior derived pointers” remain within the bounds of the allocation
+they’re associated with. As a result, the base object can be found at
+runtime provided the bounds of allocations are known to the runtime system.</p>
+<p>“Exterior derived pointers” are outside the bounds of the associated object;
+they may even fall within <em>another</em> allocations address range. As a result,
+there is no way for a garbage collector to determine which allocation they
+are associated with at runtime and compiler support is needed.</p>
+<p>The <tt class="docutils literal"><span class="pre">gc.relocate</span></tt> intrinsic supports an explicit operand for describing the
+allocation associated with a derived pointer. This operand is frequently
+referred to as the base operand, but does not strictly speaking have to be
+a base pointer, but it does need to lie within the bounds of the associated
+allocation. Some collectors may require that the operand be an actual base
+pointer rather than merely an internal derived pointer. Note that during
+lowering both the base and derived pointer operands are required to be live
+over the associated call safepoint even if the base is otherwise unused
+afterwards.</p>
+<p>If we extend our previous example to include a pointless derived pointer,
+we get:</p>
+<div class="highlight-text"><div class="highlight"><pre>define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
+ gc "statepoint-example" {
+ %gep = getelementptr i8, i8 addrspace(1)* %obj, i64 20000
+ %token = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj, i8 addrspace(1)* %gep)
+ %obj.relocated = call i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %token, i32 7, i32 7)
+ %gep.relocated = call i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %token, i32 7, i32 8)
+ %p = getelementptr i8, i8 addrspace(1)* %gep, i64 -20000
+ ret i8 addrspace(1)* %p
+}
+</pre></div>
+</div>
+<p>Note that in this example %p and %obj.relocate are the same address and we
+could replace one with the other, potentially removing the derived pointer
+from the live set at the safepoint entirely.</p>
+</div>
+<div class="section" id="gc-transitions">
+<span id="gc-transition-args"></span><h3><a class="toc-backref" href="#id15">GC Transitions</a><a class="headerlink" href="#gc-transitions" title="Permalink to this headline">¶</a></h3>
+<p>As a practical consideration, many garbage-collected systems allow code that is
+collector-aware (“managed code”) to call code that is not collector-aware
+(“unmanaged code”). It is common that such calls must also be safepoints, since
+it is desirable to allow the collector to run during the execution of
+unmanaged code. Furthermore, it is common that coordinating the transition from
+managed to unmanaged code requires extra code generation at the call site to
+inform the collector of the transition. In order to support these needs, a
+statepoint may be marked as a GC transition, and data that is necessary to
+perform the transition (if any) may be provided as additional arguments to the
+statepoint.</p>
+<blockquote>
+<div>Note that although in many cases statepoints may be inferred to be GC
+transitions based on the function symbols involved (e.g. a call from a
+function with GC strategy “foo” to a function with GC strategy “bar”),
+indirect calls that are also GC transitions must also be supported. This
+requirement is the driving force behind the decision to require that GC
+transitions are explicitly marked.</div></blockquote>
+<p>Let’s revisit the sample given above, this time treating the call to <tt class="docutils literal"><span class="pre">@foo</span></tt>
+as a GC transition. Depending on our target, the transition code may need to
+access some extra state in order to inform the collector of the transition.
+Let’s assume a hypothetical GC–somewhat unimaginatively named “hypothetical-gc”
+–that requires that a TLS variable must be written to before and after a call
+to unmanaged code. The resulting relocation sequence is:</p>
+<div class="highlight-text"><div class="highlight"><pre>@flag = thread_local global i32 0, align 4
+
+define i8 addrspace(1)* @test1(i8 addrspace(1) *%obj)
+ gc "hypothetical-gc" {
+
+ %0 = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, void ()* @foo, i32 0, i32 1, i32* @Flag, i32 0, i8 addrspace(1)* %obj)
+ %obj.relocated = call coldcc i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %0, i32 7, i32 7)
+ ret i8 addrspace(1)* %obj.relocated
+}
+</pre></div>
+</div>
+<p>During lowering, this will result in a instruction selection DAG that looks
+something like:</p>
+<div class="highlight-python"><div class="highlight"><pre>CALLSEQ_START
+...
+GC_TRANSITION_START (lowered i32 *@Flag), SRCVALUE i32* Flag
+STATEPOINT
+GC_TRANSITION_END (lowered i32 *@Flag), SRCVALUE i32 *Flag
+...
+CALLSEQ_END
+</pre></div>
+</div>
+<p>In order to generate the necessary transition code, the backend for each target
+supported by “hypothetical-gc” must be modified to lower <tt class="docutils literal"><span class="pre">GC_TRANSITION_START</span></tt>
+and <tt class="docutils literal"><span class="pre">GC_TRANSITION_END</span></tt> nodes appropriately when the “hypothetical-gc”
+strategy is in use for a particular function. Assuming that such lowering has
+been added for X86, the generated assembly would be:</p>
+<div class="highlight-gas"><div class="highlight"><pre> <span class="na">.globl</span> <span class="no">test1</span>
+ <span class="na">.align</span> <span class="mi">16</span><span class="p">,</span> <span class="mi">0x90</span>
+ <span class="nf">pushq</span> <span class="nv">%rax</span>
+ <span class="nf">movl</span> <span class="no">$1</span><span class="p">,</span> <span class="nv">%fs</span><span class="p">:</span><span class="no">Flag at TPOFF</span>
+ <span class="nf">callq</span> <span class="no">foo</span>
+ <span class="nf">movl</span> <span class="no">$0</span><span class="p">,</span> <span class="nv">%fs</span><span class="p">:</span><span class="no">Flag at TPOFF</span>
+<span class="nl">.Ltmp1:</span>
+ <span class="nf">movq</span> <span class="p">(</span><span class="nv">%rsp</span><span class="p">),</span> <span class="nv">%rax</span> <span class="c"># This load is redundant (oops!)</span>
+ <span class="nf">popq</span> <span class="nv">%rdx</span>
+ <span class="nf">retq</span>
+</pre></div>
+</div>
+<p>Note that the design as presented above is not fully implemented: in particular,
+strategy-specific lowering is not present, and all GC transitions are emitted as
+as single no-op before and after the call instruction. These no-ops are often
+removed by the backend during dead machine instruction elimination.</p>
+</div>
+</div>
+<div class="section" id="intrinsics">
+<h2><a class="toc-backref" href="#id16">Intrinsics</a><a class="headerlink" href="#intrinsics" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="llvm-experimental-gc-statepoint-intrinsic">
+<h3><a class="toc-backref" href="#id17">‘llvm.experimental.gc.statepoint’ Intrinsic</a><a class="headerlink" href="#llvm-experimental-gc-statepoint-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="syntax">
+<h4>Syntax:<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare token
+ @llvm.experimental.gc.statepoint(i64 <id>, i32 <num patch bytes>,
+ func_type <target>,
+ i64 <#call args>, i64 <flags>,
+ ... (call parameters),
+ i64 <# transition args>, ... (transition parameters),
+ i64 <# deopt args>, ... (deopt parameters),
+ ... (gc parameters))
+</pre></div>
+</div>
+</div>
+<div class="section" id="id1">
+<h4>Overview:<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>The statepoint intrinsic represents a call which is parse-able by the
+runtime.</p>
+</div>
+<div class="section" id="operands">
+<h4>Operands:<a class="headerlink" href="#operands" title="Permalink to this headline">¶</a></h4>
+<p>The ‘id’ operand is a constant integer that is reported as the ID
+field in the generated stackmap. LLVM does not interpret this
+parameter in any way and its meaning is up to the statepoint user to
+decide. Note that LLVM is free to duplicate code containing
+statepoint calls, and this may transform IR that had a unique ‘id’ per
+lexical call to statepoint to IR that does not.</p>
+<p>If ‘num patch bytes’ is non-zero then the call instruction
+corresponding to the statepoint is not emitted and LLVM emits ‘num
+patch bytes’ bytes of nops in its place. LLVM will emit code to
+prepare the function arguments and retrieve the function return value
+in accordance to the calling convention; the former before the nop
+sequence and the latter after the nop sequence. It is expected that
+the user will patch over the ‘num patch bytes’ bytes of nops with a
+calling sequence specific to their runtime before executing the
+generated machine code. There are no guarantees with respect to the
+alignment of the nop sequence. Unlike <a class="reference internal" href="StackMaps.html"><em>Stack maps and patch points in LLVM</em></a> statepoints do
+not have a concept of shadow bytes. Note that semantically the
+statepoint still represents a call or invoke to ‘target’, and the nop
+sequence after patching is expected to represent an operation
+equivalent to a call or invoke to ‘target’.</p>
+<p>The ‘target’ operand is the function actually being called. The
+target can be specified as either a symbolic LLVM function, or as an
+arbitrary Value of appropriate function type. Note that the function
+type must match the signature of the callee and the types of the ‘call
+parameters’ arguments.</p>
+<p>The ‘#call args’ operand is the number of arguments to the actual
+call. It must exactly match the number of arguments passed in the
+‘call parameters’ variable length section.</p>
+<p>The ‘flags’ operand is used to specify extra information about the
+statepoint. This is currently only used to mark certain statepoints
+as GC transitions. This operand is a 64-bit integer with the following
+layout, where bit 0 is the least significant bit:</p>
+<blockquote>
+<div><table border="1" class="docutils">
+<colgroup>
+<col width="12%" />
+<col width="88%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Bit #</th>
+<th class="head">Usage</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>0</td>
+<td>Set if the statepoint is a GC transition, cleared
+otherwise.</td>
+</tr>
+<tr class="row-odd"><td>1-63</td>
+<td>Reserved for future use; must be cleared.</td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+<p>The ‘call parameters’ arguments are simply the arguments which need to
+be passed to the call target. They will be lowered according to the
+specified calling convention and otherwise handled like a normal call
+instruction. The number of arguments must exactly match what is
+specified in ‘# call args’. The types must match the signature of
+‘target’.</p>
+<p>The ‘transition parameters’ arguments contain an arbitrary list of
+Values which need to be passed to GC transition code. They will be
+lowered and passed as operands to the appropriate GC_TRANSITION nodes
+in the selection DAG. It is assumed that these arguments must be
+available before and after (but not necessarily during) the execution
+of the callee. The ‘# transition args’ field indicates how many operands
+are to be interpreted as ‘transition parameters’.</p>
+<p>The ‘deopt parameters’ arguments contain an arbitrary list of Values
+which is meaningful to the runtime. The runtime may read any of these
+values, but is assumed not to modify them. If the garbage collector
+might need to modify one of these values, it must also be listed in
+the ‘gc pointer’ argument list. The ‘# deopt args’ field indicates
+how many operands are to be interpreted as ‘deopt parameters’.</p>
+<p>The ‘gc parameters’ arguments contain every pointer to a garbage
+collector object which potentially needs to be updated by the garbage
+collector. Note that the argument list must explicitly contain a base
+pointer for every derived pointer listed. The order of arguments is
+unimportant. Unlike the other variable length parameter sets, this
+list is not length prefixed.</p>
+</div>
+<div class="section" id="semantics">
+<h4>Semantics:<a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h4>
+<p>A statepoint is assumed to read and write all memory. As a result,
+memory operations can not be reordered past a statepoint. It is
+illegal to mark a statepoint as being either ‘readonly’ or ‘readnone’.</p>
+<p>Note that legal IR can not perform any memory operation on a ‘gc
+pointer’ argument of the statepoint in a location statically reachable
+from the statepoint. Instead, the explicitly relocated value (from a
+<tt class="docutils literal"><span class="pre">gc.relocate</span></tt>) must be used.</p>
+</div>
+</div>
+<div class="section" id="llvm-experimental-gc-result-intrinsic">
+<h3><a class="toc-backref" href="#id18">‘llvm.experimental.gc.result’ Intrinsic</a><a class="headerlink" href="#llvm-experimental-gc-result-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id2">
+<h4>Syntax:<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare type*
+ @llvm.experimental.gc.result(token %statepoint_token)
+</pre></div>
+</div>
+</div>
+<div class="section" id="id3">
+<h4>Overview:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">gc.result</span></tt> extracts the result of the original call instruction
+which was replaced by the <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>. The <tt class="docutils literal"><span class="pre">gc.result</span></tt>
+intrinsic is actually a family of three intrinsics due to an
+implementation limitation. Other than the type of the return value,
+the semantics are the same.</p>
+</div>
+<div class="section" id="id4">
+<h4>Operands:<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>The first and only argument is the <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> which starts
+the safepoint sequence of which this <tt class="docutils literal"><span class="pre">gc.result</span></tt> is a part.
+Despite the typing of this as a generic token, <em>only</em> the value defined
+by a <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> is legal here.</p>
+</div>
+<div class="section" id="id5">
+<h4>Semantics:<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">gc.result</span></tt> represents the return value of the call target of
+the <tt class="docutils literal"><span class="pre">statepoint</span></tt>. The type of the <tt class="docutils literal"><span class="pre">gc.result</span></tt> must exactly match
+the type of the target. If the call target returns void, there will
+be no <tt class="docutils literal"><span class="pre">gc.result</span></tt>.</p>
+<p>A <tt class="docutils literal"><span class="pre">gc.result</span></tt> is modeled as a ‘readnone’ pure function. It has no
+side effects since it is just a projection of the return value of the
+previous call represented by the <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="llvm-experimental-gc-relocate-intrinsic">
+<h3><a class="toc-backref" href="#id19">‘llvm.experimental.gc.relocate’ Intrinsic</a><a class="headerlink" href="#llvm-experimental-gc-relocate-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id6">
+<h4>Syntax:<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare <pointer type>
+ @llvm.experimental.gc.relocate(token %statepoint_token,
+ i32 %base_offset,
+ i32 %pointer_offset)
+</pre></div>
+</div>
+</div>
+<div class="section" id="id7">
+<h4>Overview:<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h4>
+<p>A <tt class="docutils literal"><span class="pre">gc.relocate</span></tt> returns the potentially relocated value of a pointer
+at the safepoint.</p>
+</div>
+<div class="section" id="id8">
+<h4>Operands:<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h4>
+<p>The first argument is the <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> which starts the
+safepoint sequence of which this <tt class="docutils literal"><span class="pre">gc.relocation</span></tt> is a part.
+Despite the typing of this as a generic token, <em>only</em> the value defined
+by a <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> is legal here.</p>
+<p>The second argument is an index into the statepoints list of arguments
+which specifies the allocation for the pointer being relocated.
+This index must land within the ‘gc parameter’ section of the
+statepoint’s argument list. The associated value must be within the
+object with which the pointer being relocated is associated. The optimizer
+is free to change <em>which</em> interior derived pointer is reported, provided that
+it does not replace an actual base pointer with another interior derived
+pointer. Collectors are allowed to rely on the base pointer operand
+remaining an actual base pointer if so constructed.</p>
+<p>The third argument is an index into the statepoint’s list of arguments
+which specify the (potentially) derived pointer being relocated. It
+is legal for this index to be the same as the second argument
+if-and-only-if a base pointer is being relocated. This index must land
+within the ‘gc parameter’ section of the statepoint’s argument list.</p>
+</div>
+<div class="section" id="id9">
+<h4>Semantics:<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h4>
+<p>The return value of <tt class="docutils literal"><span class="pre">gc.relocate</span></tt> is the potentially relocated value
+of the pointer specified by it’s arguments. It is unspecified how the
+value of the returned pointer relates to the argument to the
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> other than that a) it points to the same source
+language object with the same offset, and b) the ‘based-on’
+relationship of the newly relocated pointers is a projection of the
+unrelocated pointers. In particular, the integer value of the pointer
+returned is unspecified.</p>
+<p>A <tt class="docutils literal"><span class="pre">gc.relocate</span></tt> is modeled as a <tt class="docutils literal"><span class="pre">readnone</span></tt> pure function. It has no
+side effects since it is just a way to extract information about work
+done during the actual call modeled by the <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>.</p>
+</div>
+</div>
+</div>
+<div class="section" id="stack-map-format">
+<span id="statepoint-stackmap-format"></span><h2><a class="toc-backref" href="#id20">Stack Map Format</a><a class="headerlink" href="#stack-map-format" title="Permalink to this headline">¶</a></h2>
+<p>Locations for each pointer value which may need read and/or updated by
+the runtime or collector are provided via the <a class="reference internal" href="StackMaps.html#stackmap-format"><em>Stack Map format</em></a> specified in the PatchPoint documentation.</p>
+<p>Each statepoint generates the following Locations:</p>
+<ul class="simple">
+<li>Constant which describes the calling convention of the call target. This
+constant is a valid <a class="reference internal" href="LangRef.html#callingconv"><em>calling convention identifier</em></a> for
+the version of LLVM used to generate the stackmap. No additional compatibility
+guarantees are made for this constant over what LLVM provides elsewhere w.r.t.
+these identifiers.</li>
+<li>Constant which describes the flags passed to the statepoint intrinsic</li>
+<li>Constant which describes number of following deopt <em>Locations</em> (not
+operands)</li>
+<li>Variable number of Locations, one for each deopt parameter listed in
+the IR statepoint (same number as described by previous Constant). At
+the moment, only deopt parameters with a bitwidth of 64 bits or less
+are supported. Values of a type larger than 64 bits can be specified
+and reported only if a) the value is constant at the call site, and b)
+the constant can be represented with less than 64 bits (assuming zero
+extension to the original bitwidth).</li>
+<li>Variable number of relocation records, each of which consists of
+exactly two Locations. Relocation records are described in detail
+below.</li>
+</ul>
+<p>Each relocation record provides sufficient information for a collector to
+relocate one or more derived pointers. Each record consists of a pair of
+Locations. The second element in the record represents the pointer (or
+pointers) which need updated. The first element in the record provides a
+pointer to the base of the object with which the pointer(s) being relocated is
+associated. This information is required for handling generalized derived
+pointers since a pointer may be outside the bounds of the original allocation,
+but still needs to be relocated with the allocation. Additionally:</p>
+<ul class="simple">
+<li>It is guaranteed that the base pointer must also appear explicitly as a
+relocation pair if used after the statepoint.</li>
+<li>There may be fewer relocation records then gc parameters in the IR
+statepoint. Each <em>unique</em> pair will occur at least once; duplicates
+are possible.</li>
+<li>The Locations within each record may either be of pointer size or a
+multiple of pointer size. In the later case, the record must be
+interpreted as describing a sequence of pointers and their corresponding
+base pointers. If the Location is of size N x sizeof(pointer), then
+there will be N records of one pointer each contained within the Location.
+Both Locations in a pair can be assumed to be of the same size.</li>
+</ul>
+<p>Note that the Locations used in each section may describe the same
+physical location. e.g. A stack slot may appear as a deopt location,
+a gc base pointer, and a gc derived pointer.</p>
+<p>The LiveOut section of the StkMapRecord will be empty for a statepoint
+record.</p>
+</div>
+<div class="section" id="safepoint-semantics-verification">
+<h2><a class="toc-backref" href="#id21">Safepoint Semantics & Verification</a><a class="headerlink" href="#safepoint-semantics-verification" title="Permalink to this headline">¶</a></h2>
+<p>The fundamental correctness property for the compiled code’s
+correctness w.r.t. the garbage collector is a dynamic one. It must be
+the case that there is no dynamic trace such that a operation
+involving a potentially relocated pointer is observably-after a
+safepoint which could relocate it. ‘observably-after’ is this usage
+means that an outside observer could observe this sequence of events
+in a way which precludes the operation being performed before the
+safepoint.</p>
+<p>To understand why this ‘observable-after’ property is required,
+consider a null comparison performed on the original copy of a
+relocated pointer. Assuming that control flow follows the safepoint,
+there is no way to observe externally whether the null comparison is
+performed before or after the safepoint. (Remember, the original
+Value is unmodified by the safepoint.) The compiler is free to make
+either scheduling choice.</p>
+<p>The actual correctness property implemented is slightly stronger than
+this. We require that there be no <em>static path</em> on which a
+potentially relocated pointer is ‘observably-after’ it may have been
+relocated. This is slightly stronger than is strictly necessary (and
+thus may disallow some otherwise valid programs), but greatly
+simplifies reasoning about correctness of the compiled code.</p>
+<p>By construction, this property will be upheld by the optimizer if
+correctly established in the source IR. This is a key invariant of
+the design.</p>
+<p>The existing IR Verifier pass has been extended to check most of the
+local restrictions on the intrinsics mentioned in their respective
+documentation. The current implementation in LLVM does not check the
+key relocation invariant, but this is ongoing work on developing such
+a verifier. Please ask on llvm-dev if you’re interested in
+experimenting with the current version.</p>
+</div>
+<div class="section" id="utility-passes-for-safepoint-insertion">
+<span id="statepoint-utilities"></span><h2><a class="toc-backref" href="#id22">Utility Passes for Safepoint Insertion</a><a class="headerlink" href="#utility-passes-for-safepoint-insertion" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="rewritestatepointsforgc">
+<span id="id10"></span><h3><a class="toc-backref" href="#id23">RewriteStatepointsForGC</a><a class="headerlink" href="#rewritestatepointsforgc" title="Permalink to this headline">¶</a></h3>
+<p>The pass RewriteStatepointsForGC transforms a functions IR by replacing a
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> (with an optional <tt class="docutils literal"><span class="pre">gc.result</span></tt>) with a full relocation
+sequence, including all required <tt class="docutils literal"><span class="pre">gc.relocates</span></tt>. To function, the pass
+requires that the GC strategy specified for the function be able to reliably
+distinguish between GC references and non-GC references in IR it is given.</p>
+<p>As an example, given this code:</p>
+<div class="highlight-text"><div class="highlight"><pre>define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
+ gc "statepoint-example" {
+ call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 5, i32 0, i32 -1, i32 0, i32 0, i32 0)
+ ret i8 addrspace(1)* %obj
+}
+</pre></div>
+</div>
+<p>The pass would produce this IR:</p>
+<div class="highlight-text"><div class="highlight"><pre>define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
+ gc "statepoint-example" {
+ %0 = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 5, i32 0, i32 -1, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj)
+ %obj.relocated = call coldcc i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %0, i32 12, i32 12)
+ ret i8 addrspace(1)* %obj.relocated
+}
+</pre></div>
+</div>
+<p>In the above examples, the addrspace(1) marker on the pointers is the mechanism
+that the <tt class="docutils literal"><span class="pre">statepoint-example</span></tt> GC strategy uses to distinguish references from
+non references. Address space 1 is not globally reserved for this purpose.</p>
+<p>This pass can be used an utility function by a language frontend that doesn’t
+want to manually reason about liveness, base pointers, or relocation when
+constructing IR. As currently implemented, RewriteStatepointsForGC must be
+run after SSA construction (i.e. mem2ref).</p>
+<p>RewriteStatepointsForGC will ensure that appropriate base pointers are listed
+for every relocation created. It will do so by duplicating code as needed to
+propagate the base pointer associated with each pointer being relocated to
+the appropriate safepoints. The implementation assumes that the following
+IR constructs produce base pointers: loads from the heap, addresses of global
+variables, function arguments, function return values. Constant pointers (such
+as null) are also assumed to be base pointers. In practice, this constraint
+can be relaxed to producing interior derived pointers provided the target
+collector can find the associated allocation from an arbitrary interior
+derived pointer.</p>
+<p>In practice, RewriteStatepointsForGC can be run much later in the pass
+pipeline, after most optimization is already done. This helps to improve
+the quality of the generated code when compiled with garbage collection support.
+In the long run, this is the intended usage model. At this time, a few details
+have yet to be worked out about the semantic model required to guarantee this
+is always correct. As such, please use with caution and report bugs.</p>
+</div>
+<div class="section" id="placesafepoints">
+<span id="id11"></span><h3><a class="toc-backref" href="#id24">PlaceSafepoints</a><a class="headerlink" href="#placesafepoints" title="Permalink to this headline">¶</a></h3>
+<p>The pass PlaceSafepoints transforms a function’s IR by replacing any call or
+invoke instructions with appropriate <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> and <tt class="docutils literal"><span class="pre">gc.result</span></tt> pairs,
+and inserting safepoint polls sufficient to ensure running code checks for a
+safepoint request on a timely manner. This pass is expected to be run before
+RewriteStatepointsForGC and thus does not produce full relocation sequences.</p>
+<p>As an example, given input IR of the following:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">()</span> <span class="k">gc</span> <span class="s">"statepoint-example"</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>
+
+<span class="k">declare</span> <span class="kt">void</span> <span class="vg">@do_safepoint</span><span class="p">()</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@gc.safepoint_poll</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@do_safepoint</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This pass would produce the following IR:</p>
+<div class="highlight-text"><div class="highlight"><pre>define void @test() gc "statepoint-example" {
+ %safepoint_token = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @do_safepoint, i32 0, i32 0, i32 0, i32 0)
+ %safepoint_token1 = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 0)
+ ret void
+}
+</pre></div>
+</div>
+<p>In this case, we’ve added an (unconditional) entry safepoint poll and converted the call into a <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>. Note that despite appearances, the entry poll is not necessarily redundant. We’d have to know that <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">test</span></tt> were not mutually recursive for the poll to be redundant. In practice, you’d probably want to your poll definition to contain a conditional branch of some form.</p>
+<p>At the moment, PlaceSafepoints can insert safepoint polls at method entry and
+loop backedges locations. Extending this to work with return polls would be
+straight forward if desired.</p>
+<p>PlaceSafepoints includes a number of optimizations to avoid placing safepoint
+polls at particular sites unless needed to ensure timely execution of a poll
+under normal conditions. PlaceSafepoints does not attempt to ensure timely
+execution of a poll under worst case conditions such as heavy system paging.</p>
+<p>The implementation of a safepoint poll action is specified by looking up a
+function of the name <tt class="docutils literal"><span class="pre">gc.safepoint_poll</span></tt> in the containing Module. The body
+of this function is inserted at each poll site desired. While calls or invokes
+inside this method are transformed to a <tt class="docutils literal"><span class="pre">gc.statepoints</span></tt>, recursive poll
+insertion is not performed.</p>
+<p>By default PlaceSafepoints passes in <tt class="docutils literal"><span class="pre">0xABCDEF00</span></tt> as the statepoint
+ID and <tt class="docutils literal"><span class="pre">0</span></tt> as the number of patchable bytes to the newly constructed
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>. These values can be configured on a per-callsite
+basis using the attributes <tt class="docutils literal"><span class="pre">"statepoint-id"</span></tt> and
+<tt class="docutils literal"><span class="pre">"statepoint-num-patch-bytes"</span></tt>. If a call site is marked with a
+<tt class="docutils literal"><span class="pre">"statepoint-id"</span></tt> function attribute and its value is a positive
+integer (represented as a string), then that value is used as the ID
+of the newly constructed <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>. If a call site is marked
+with a <tt class="docutils literal"><span class="pre">"statepoint-num-patch-bytes"</span></tt> function attribute and its
+value is a positive integer, then that value is used as the ‘num patch
+bytes’ parameter of the newly constructed <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>. The
+<tt class="docutils literal"><span class="pre">"statepoint-id"</span></tt> and <tt class="docutils literal"><span class="pre">"statepoint-num-patch-bytes"</span></tt> attributes
+are not propagated to the <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> call or invoke if they
+could be successfully parsed.</p>
+<p>If you are scheduling the RewriteStatepointsForGC pass late in the pass order,
+you should probably schedule this pass immediately before it. The exception
+would be if you need to preserve abstract frame information (e.g. for
+deoptimization or introspection) at safepoints. In that case, ask on the
+llvm-dev mailing list for suggestions.</p>
+</div>
+</div>
+<div class="section" id="supported-architectures">
+<h2><a class="toc-backref" href="#id25">Supported Architectures</a><a class="headerlink" href="#supported-architectures" title="Permalink to this headline">¶</a></h2>
+<p>Support for statepoint generation requires some code for each backend.
+Today, only X86_64 is supported.</p>
+</div>
+<div class="section" id="problem-areas-and-active-work">
+<h2><a class="toc-backref" href="#id26">Problem Areas and Active Work</a><a class="headerlink" href="#problem-areas-and-active-work" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic simple">
+<li>As the existing users of the late rewriting model have matured, we’ve found
+cases where the optimizer breaks the assumption that an SSA value of
+gc-pointer type actually contains a gc-pointer and vice-versa. We need to
+clarify our expectations and propose at least one small IR change. (Today,
+the gc-pointer distinction is managed via address spaces. This turns out
+not to be quite strong enough.)</li>
+<li>Support for languages which allow unmanaged pointers to garbage collected
+objects (i.e. pass a pointer to an object to a C routine) via pinning.</li>
+<li>Support for garbage collected objects allocated on the stack. Specifically,
+allocas are always assumed to be in address space 0 and we need a
+cast/promotion operator to let rewriting identify them.</li>
+<li>The current statepoint lowering is known to be somewhat poor. In the very
+long term, we’d like to integrate statepoints with the register allocator;
+in the near term this is unlikely to happen. We’ve found the quality of
+lowering to be relatively unimportant as hot-statepoints are almost always
+inliner bugs.</li>
+<li>Concerns have been raised that the statepoint representation results in a
+large amount of IR being produced for some examples and that this
+contributes to higher than expected memory usage and compile times. There’s
+no immediate plans to make changes due to this, but alternate models may be
+explored in the future.</li>
+<li>Relocations along exceptional paths are currently broken in ToT. In
+particular, there is current no way to represent a rethrow on a path which
+also has relocations. See <a class="reference external" href="https://groups.google.com/forum/#!topic/llvm-dev/AE417XjgxvI">this llvm-dev discussion</a> for more
+detail.</li>
+</ol>
+</div>
+<div class="section" id="bugs-and-enhancements">
+<h2><a class="toc-backref" href="#id27">Bugs and Enhancements</a><a class="headerlink" href="#bugs-and-enhancements" title="Permalink to this headline">¶</a></h2>
+<p>Currently known bugs and enhancements under consideration can be
+tracked by performing a <a class="reference external" href="http://llvm.org/bugs/buglist.cgi?cmdtype=runnamed&namedcmd=Statepoint%20Bugs&list_id=64342">bugzilla search</a>
+for [Statepoint] in the summary field. When filing new bugs, please
+use this tag so that interested parties see the newly filed bug. As
+with most LLVM features, design discussions take place on <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a>, and patches
+should be sent to <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-commits">llvm-commits</a> for review.</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="MergeFunctions.html" title="MergeFunctions pass, how it works"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CoverageMappingFormat.html" title="LLVM Code Coverage Mapping Format"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/SystemLibrary.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/SystemLibrary.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/SystemLibrary.html (added)
+++ www-releases/trunk/3.9.1/docs/SystemLibrary.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,311 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>System Library — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="Source Level Debugging with LLVM" href="SourceLevelDebugging.html" />
+ <link rel="prev" title="LLVMâs Optional Rich Disassembly Output" href="MarkedUpDisassembly.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="system-library">
+<h1>System Library<a class="headerlink" href="#system-library" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="abstract">
+<h2>Abstract<a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>This document provides some details on LLVM’s System Library, located in the
+source at <tt class="docutils literal"><span class="pre">lib/System</span></tt> and <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt>. The library’s purpose is
+to shield LLVM from the differences between operating systems for the few
+services LLVM needs from the operating system. Much of LLVM is written using
+portability features of standard C++. However, in a few areas, system dependent
+facilities are needed and the System Library is the wrapper around those system
+calls.</p>
+<p>By centralizing LLVM’s use of operating system interfaces, we make it possible
+for the LLVM tool chain and runtime libraries to be more easily ported to new
+platforms since (theoretically) only <tt class="docutils literal"><span class="pre">lib/System</span></tt> needs to be ported. This
+library also unclutters the rest of LLVM from #ifdef use and special cases for
+specific operating systems. Such uses are replaced with simple calls to the
+interfaces provided in <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt>.</p>
+<p>Note that the System Library is not intended to be a complete operating system
+wrapper (such as the Adaptive Communications Environment (ACE) or Apache
+Portable Runtime (APR)), but only provides the functionality necessary to
+support LLVM.</p>
+<p>The System Library was written by Reid Spencer who formulated the design based
+on similar work originating from the eXtensible Programming System (XPS).
+Several people helped with the effort; especially, Jeff Cohen and Henrik Bach
+on the Win32 port.</p>
+</div>
+<div class="section" id="keeping-llvm-portable">
+<h2>Keeping LLVM Portable<a class="headerlink" href="#keeping-llvm-portable" title="Permalink to this headline">¶</a></h2>
+<p>In order to keep LLVM portable, LLVM developers should adhere to a set of
+portability rules associated with the System Library. Adherence to these rules
+should help the System Library achieve its goal of shielding LLVM from the
+variations in operating system interfaces and doing so efficiently. The
+following sections define the rules needed to fulfill this objective.</p>
+<div class="section" id="don-t-include-system-headers">
+<h3>Don’t Include System Headers<a class="headerlink" href="#don-t-include-system-headers" title="Permalink to this headline">¶</a></h3>
+<p>Except in <tt class="docutils literal"><span class="pre">lib/System</span></tt>, no LLVM source code should directly <tt class="docutils literal"><span class="pre">#include</span></tt> a
+system header. Care has been taken to remove all such <tt class="docutils literal"><span class="pre">#includes</span></tt> from LLVM
+while <tt class="docutils literal"><span class="pre">lib/System</span></tt> was being developed. Specifically this means that header
+files like “<tt class="docutils literal"><span class="pre">unistd.h</span></tt>”, “<tt class="docutils literal"><span class="pre">windows.h</span></tt>”, “<tt class="docutils literal"><span class="pre">stdio.h</span></tt>”, and “<tt class="docutils literal"><span class="pre">string.h</span></tt>”
+are forbidden to be included by LLVM source code outside the implementation of
+<tt class="docutils literal"><span class="pre">lib/System</span></tt>.</p>
+<p>To obtain system-dependent functionality, existing interfaces to the system
+found in <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt> should be used. If an appropriate interface is
+not available, it should be added to <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt> and implemented in
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> for all supported platforms.</p>
+</div>
+<div class="section" id="don-t-expose-system-headers">
+<h3>Don’t Expose System Headers<a class="headerlink" href="#don-t-expose-system-headers" title="Permalink to this headline">¶</a></h3>
+<p>The System Library must shield LLVM from <strong>all</strong> system headers. To obtain
+system level functionality, LLVM source must <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/System/Thing.h"</span></tt>
+and nothing else. This means that <tt class="docutils literal"><span class="pre">Thing.h</span></tt> cannot expose any system header
+files. This protects LLVM from accidentally using system specific functionality
+and only allows it via the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface.</p>
+</div>
+<div class="section" id="use-standard-c-headers">
+<h3>Use Standard C Headers<a class="headerlink" href="#use-standard-c-headers" title="Permalink to this headline">¶</a></h3>
+<p>The <strong>standard</strong> C headers (the ones beginning with “c”) are allowed to be
+exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface. These headers and the things they
+declare are considered to be platform agnostic. LLVM source files may include
+them directly or obtain their inclusion through <tt class="docutils literal"><span class="pre">lib/System</span></tt> interfaces.</p>
+</div>
+<div class="section" id="id1">
+<h3>Use Standard C++ Headers<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>The <strong>standard</strong> C++ headers from the standard C++ library and standard
+template library may be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface. These
+headers and the things they declare are considered to be platform agnostic.
+LLVM source files may include them or obtain their inclusion through
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> interfaces.</p>
+</div>
+<div class="section" id="high-level-interface">
+<h3>High Level Interface<a class="headerlink" href="#high-level-interface" title="Permalink to this headline">¶</a></h3>
+<p>The entry points specified in the interface of <tt class="docutils literal"><span class="pre">lib/System</span></tt> must be aimed at
+completing some reasonably high level task needed by LLVM. We do not want to
+simply wrap each operating system call. It would be preferable to wrap several
+operating system calls that are always used in conjunction with one another by
+LLVM.</p>
+<p>For example, consider what is needed to execute a program, wait for it to
+complete, and return its result code. On Unix, this involves the following
+operating system calls: <tt class="docutils literal"><span class="pre">getenv</span></tt>, <tt class="docutils literal"><span class="pre">fork</span></tt>, <tt class="docutils literal"><span class="pre">execve</span></tt>, and <tt class="docutils literal"><span class="pre">wait</span></tt>. The
+correct thing for <tt class="docutils literal"><span class="pre">lib/System</span></tt> to provide is a function, say
+<tt class="docutils literal"><span class="pre">ExecuteProgramAndWait</span></tt>, that implements the functionality completely. what
+we don’t want is wrappers for the operating system calls involved.</p>
+<p>There must <strong>not</strong> be a one-to-one relationship between operating system
+calls and the System library’s interface. Any such interface function will be
+suspicious.</p>
+</div>
+<div class="section" id="no-unused-functionality">
+<h3>No Unused Functionality<a class="headerlink" href="#no-unused-functionality" title="Permalink to this headline">¶</a></h3>
+<p>There must be no functionality specified in the interface of <tt class="docutils literal"><span class="pre">lib/System</span></tt>
+that isn’t actually used by LLVM. We’re not writing a general purpose operating
+system wrapper here, just enough to satisfy LLVM’s needs. And, LLVM doesn’t
+need much. This design goal aims to keep the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface small and
+understandable which should foster its actual use and adoption.</p>
+</div>
+<div class="section" id="no-duplicate-implementations">
+<h3>No Duplicate Implementations<a class="headerlink" href="#no-duplicate-implementations" title="Permalink to this headline">¶</a></h3>
+<p>The implementation of a function for a given platform must be written exactly
+once. This implies that it must be possible to apply a function’s
+implementation to multiple operating systems if those operating systems can
+share the same implementation. This rule applies to the set of operating
+systems supported for a given class of operating system (e.g. Unix, Win32).</p>
+</div>
+<div class="section" id="no-virtual-methods">
+<h3>No Virtual Methods<a class="headerlink" href="#no-virtual-methods" title="Permalink to this headline">¶</a></h3>
+<p>The System Library interfaces can be called quite frequently by LLVM. In order
+to make those calls as efficient as possible, we discourage the use of virtual
+methods. There is no need to use inheritance for implementation differences, it
+just adds complexity. The <tt class="docutils literal"><span class="pre">#include</span></tt> mechanism works just fine.</p>
+</div>
+<div class="section" id="no-exposed-functions">
+<h3>No Exposed Functions<a class="headerlink" href="#no-exposed-functions" title="Permalink to this headline">¶</a></h3>
+<p>Any functions defined by system libraries (i.e. not defined by <tt class="docutils literal"><span class="pre">lib/System</span></tt>)
+must not be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface, even if the header
+file for that function is not exposed. This prevents inadvertent use of system
+specific functionality.</p>
+<p>For example, the <tt class="docutils literal"><span class="pre">stat</span></tt> system call is notorious for having variations in the
+data it provides. <tt class="docutils literal"><span class="pre">lib/System</span></tt> must not declare <tt class="docutils literal"><span class="pre">stat</span></tt> nor allow it to be
+declared. Instead it should provide its own interface to discovering
+information about files and directories. Those interfaces may be implemented in
+terms of <tt class="docutils literal"><span class="pre">stat</span></tt> but that is strictly an implementation detail. The interface
+provided by the System Library must be implemented on all platforms (even those
+without <tt class="docutils literal"><span class="pre">stat</span></tt>).</p>
+</div>
+<div class="section" id="no-exposed-data">
+<h3>No Exposed Data<a class="headerlink" href="#no-exposed-data" title="Permalink to this headline">¶</a></h3>
+<p>Any data defined by system libraries (i.e. not defined by <tt class="docutils literal"><span class="pre">lib/System</span></tt>) must
+not be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface, even if the header file
+for that function is not exposed. As with functions, this prevents inadvertent
+use of data that might not exist on all platforms.</p>
+</div>
+<div class="section" id="minimize-soft-errors">
+<h3>Minimize Soft Errors<a class="headerlink" href="#minimize-soft-errors" title="Permalink to this headline">¶</a></h3>
+<p>Operating system interfaces will generally provide error results for every
+little thing that could go wrong. In almost all cases, you can divide these
+error results into two groups: normal/good/soft and abnormal/bad/hard. That is,
+some of the errors are simply information like “file not found”, “insufficient
+privileges”, etc. while other errors are much harder like “out of space”, “bad
+disk sector”, or “system call interrupted”. We’ll call the first group “<em>soft</em>”
+errors and the second group “<em>hard</em>” errors.</p>
+<p><tt class="docutils literal"><span class="pre">lib/System</span></tt> must always attempt to minimize soft errors. This is a design
+requirement because the minimization of soft errors can affect the granularity
+and the nature of the interface. In general, if you find that you’re wanting to
+throw soft errors, you must review the granularity of the interface because it
+is likely you’re trying to implement something that is too low level. The rule
+of thumb is to provide interface functions that <strong>can’t</strong> fail, except when
+faced with hard errors.</p>
+<p>For a trivial example, suppose we wanted to add an “<tt class="docutils literal"><span class="pre">OpenFileForWriting</span></tt>”
+function. For many operating systems, if the file doesn’t exist, attempting to
+open the file will produce an error. However, <tt class="docutils literal"><span class="pre">lib/System</span></tt> should not simply
+throw that error if it occurs because its a soft error. The problem is that the
+interface function, <tt class="docutils literal"><span class="pre">OpenFileForWriting</span></tt> is too low level. It should be
+<tt class="docutils literal"><span class="pre">OpenOrCreateFileForWriting</span></tt>. In the case of the soft “doesn’t exist” error,
+this function would just create it and then open it for writing.</p>
+<p>This design principle needs to be maintained in <tt class="docutils literal"><span class="pre">lib/System</span></tt> because it
+avoids the propagation of soft error handling throughout the rest of LLVM.
+Hard errors will generally just cause a termination for an LLVM tool so don’t
+be bashful about throwing them.</p>
+<p>Rules of thumb:</p>
+<ol class="arabic simple">
+<li>Don’t throw soft errors, only hard errors.</li>
+<li>If you’re tempted to throw a soft error, re-think the interface.</li>
+<li>Handle internally the most common normal/good/soft error conditions
+so the rest of LLVM doesn’t have to.</li>
+</ol>
+</div>
+<div class="section" id="no-throw-specifications">
+<h3>No throw Specifications<a class="headerlink" href="#no-throw-specifications" title="Permalink to this headline">¶</a></h3>
+<p>None of the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface functions may be declared with C++
+<tt class="docutils literal"><span class="pre">throw()</span></tt> specifications on them. This requirement makes sure that the
+compiler does not insert additional exception handling code into the interface
+functions. This is a performance consideration: <tt class="docutils literal"><span class="pre">lib/System</span></tt> functions are at
+the bottom of many call chains and as such can be frequently called. We need
+them to be as efficient as possible. However, no routines in the system
+library should actually throw exceptions.</p>
+</div>
+<div class="section" id="code-organization">
+<h3>Code Organization<a class="headerlink" href="#code-organization" title="Permalink to this headline">¶</a></h3>
+<p>Implementations of the System Library interface are separated by their general
+class of operating system. Currently only Unix and Win32 classes are defined
+but more could be added for other operating system classifications. To
+distinguish which implementation to compile, the code in <tt class="docutils literal"><span class="pre">lib/System</span></tt> uses
+the <tt class="docutils literal"><span class="pre">LLVM_ON_UNIX</span></tt> and <tt class="docutils literal"><span class="pre">LLVM_ON_WIN32</span></tt> <tt class="docutils literal"><span class="pre">#defines</span></tt> provided via configure
+through the <tt class="docutils literal"><span class="pre">llvm/Config/config.h</span></tt> file. Each source file in <tt class="docutils literal"><span class="pre">lib/System</span></tt>,
+after implementing the generic (operating system independent) functionality
+needs to include the correct implementation using a set of
+<tt class="docutils literal"><span class="pre">#if</span> <span class="pre">defined(LLVM_ON_XYZ)</span></tt> directives. For example, if we had
+<tt class="docutils literal"><span class="pre">lib/System/File.cpp</span></tt>, we’d expect to see in that file:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if defined(LLVM_ON_UNIX)</span>
+<span class="cp">#include "Unix/File.cpp"</span>
+<span class="cp">#endif</span>
+<span class="cp">#if defined(LLVM_ON_WIN32)</span>
+<span class="cp">#include "Win32/File.cpp"</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>The implementation in <tt class="docutils literal"><span class="pre">lib/System/Unix/File.cpp</span></tt> should handle all Unix
+variants. The implementation in <tt class="docutils literal"><span class="pre">lib/System/Win32/File.cpp</span></tt> should handle all
+Win32 variants. What this does is quickly differentiate the basic class of
+operating system that will provide the implementation. The specific details for
+a given platform must still be determined through the use of <tt class="docutils literal"><span class="pre">#ifdef</span></tt>.</p>
+</div>
+<div class="section" id="consistent-semantics">
+<h3>Consistent Semantics<a class="headerlink" href="#consistent-semantics" title="Permalink to this headline">¶</a></h3>
+<p>The implementation of a <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface can vary drastically between
+platforms. That’s okay as long as the end result of the interface function is
+the same. For example, a function to create a directory is pretty straight
+forward on all operating system. System V IPC on the other hand isn’t even
+supported on all platforms. Instead of “supporting” System V IPC,
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> should provide an interface to the basic concept of
+inter-process communications. The implementations might use System V IPC if
+that was available or named pipes, or whatever gets the job done effectively
+for a given operating system. In all cases, the interface and the
+implementation must be semantically consistent.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TableGen/BackEnds.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TableGen/BackEnds.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TableGen/BackEnds.html (added)
+++ www-releases/trunk/3.9.1/docs/TableGen/BackEnds.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,496 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen BackEnds — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="../index.html" />
+ <link rel="up" title="TableGen" href="index.html" />
+ <link rel="next" title="TableGen Language Reference" href="LangRef.html" />
+ <link rel="prev" title="TableGen" href="index.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LangRef.html" title="TableGen Language Reference"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="TableGen"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">TableGen</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-backends">
+<h1>TableGen BackEnds<a class="headerlink" href="#tablegen-backends" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#llvm-backends" id="id2">LLVM BackEnds</a><ul>
+<li><a class="reference internal" href="#codeemitter" id="id3">CodeEmitter</a></li>
+<li><a class="reference internal" href="#registerinfo" id="id4">RegisterInfo</a></li>
+<li><a class="reference internal" href="#instrinfo" id="id5">InstrInfo</a></li>
+<li><a class="reference internal" href="#asmwriter" id="id6">AsmWriter</a></li>
+<li><a class="reference internal" href="#asmmatcher" id="id7">AsmMatcher</a></li>
+<li><a class="reference internal" href="#disassembler" id="id8">Disassembler</a></li>
+<li><a class="reference internal" href="#pseudolowering" id="id9">PseudoLowering</a></li>
+<li><a class="reference internal" href="#callingconv" id="id10">CallingConv</a></li>
+<li><a class="reference internal" href="#dagisel" id="id11">DAGISel</a></li>
+<li><a class="reference internal" href="#dfapacketizer" id="id12">DFAPacketizer</a></li>
+<li><a class="reference internal" href="#fastisel" id="id13">FastISel</a></li>
+<li><a class="reference internal" href="#subtarget" id="id14">Subtarget</a></li>
+<li><a class="reference internal" href="#intrinsic" id="id15">Intrinsic</a></li>
+<li><a class="reference internal" href="#optparserdefs" id="id16">OptParserDefs</a></li>
+<li><a class="reference internal" href="#ctags" id="id17">CTags</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-backends" id="id18">Clang BackEnds</a><ul>
+<li><a class="reference internal" href="#clangattrclasses" id="id19">ClangAttrClasses</a></li>
+<li><a class="reference internal" href="#clangattrparserstringswitches" id="id20">ClangAttrParserStringSwitches</a></li>
+<li><a class="reference internal" href="#clangattrimpl" id="id21">ClangAttrImpl</a></li>
+<li><a class="reference internal" href="#clangattrlist" id="id22">ClangAttrList</a></li>
+<li><a class="reference internal" href="#clangattrpchread" id="id23">ClangAttrPCHRead</a></li>
+<li><a class="reference internal" href="#clangattrpchwrite" id="id24">ClangAttrPCHWrite</a></li>
+<li><a class="reference internal" href="#clangattrspellings" id="id25">ClangAttrSpellings</a></li>
+<li><a class="reference internal" href="#clangattrspellinglistindex" id="id26">ClangAttrSpellingListIndex</a></li>
+<li><a class="reference internal" href="#clangattrvisitor" id="id27">ClangAttrVisitor</a></li>
+<li><a class="reference internal" href="#clangattrtemplateinstantiate" id="id28">ClangAttrTemplateInstantiate</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrlist" id="id29">ClangAttrParsedAttrList</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrimpl" id="id30">ClangAttrParsedAttrImpl</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrkinds" id="id31">ClangAttrParsedAttrKinds</a></li>
+<li><a class="reference internal" href="#clangattrdump" id="id32">ClangAttrDump</a></li>
+<li><a class="reference internal" href="#clangdiagsdefs" id="id33">ClangDiagsDefs</a></li>
+<li><a class="reference internal" href="#clangdiaggroups" id="id34">ClangDiagGroups</a></li>
+<li><a class="reference internal" href="#clangdiagsindexname" id="id35">ClangDiagsIndexName</a></li>
+<li><a class="reference internal" href="#clangcommentnodes" id="id36">ClangCommentNodes</a></li>
+<li><a class="reference internal" href="#clangdeclnodes" id="id37">ClangDeclNodes</a></li>
+<li><a class="reference internal" href="#clangstmtnodes" id="id38">ClangStmtNodes</a></li>
+<li><a class="reference internal" href="#clangsacheckers" id="id39">ClangSACheckers</a></li>
+<li><a class="reference internal" href="#clangcommenthtmltags" id="id40">ClangCommentHTMLTags</a></li>
+<li><a class="reference internal" href="#clangcommenthtmltagsproperties" id="id41">ClangCommentHTMLTagsProperties</a></li>
+<li><a class="reference internal" href="#clangcommenthtmlnamedcharacterreferences" id="id42">ClangCommentHTMLNamedCharacterReferences</a></li>
+<li><a class="reference internal" href="#clangcommentcommandinfo" id="id43">ClangCommentCommandInfo</a></li>
+<li><a class="reference internal" href="#clangcommentcommandlist" id="id44">ClangCommentCommandList</a></li>
+<li><a class="reference internal" href="#armneon" id="id45">ArmNeon</a></li>
+<li><a class="reference internal" href="#armneonsema" id="id46">ArmNeonSema</a></li>
+<li><a class="reference internal" href="#armneontest" id="id47">ArmNeonTest</a></li>
+<li><a class="reference internal" href="#attrdocs" id="id48">AttrDocs</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-write-a-back-end" id="id49">How to write a back-end</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>TableGen backends are at the core of TableGen’s functionality. The source files
+provide the semantics to a generated (in memory) structure, but it’s up to the
+backend to print this out in a way that is meaningful to the user (normally a
+C program including a file or a textual list of warnings, options and error
+messages).</p>
+<p>TableGen is used by both LLVM and Clang with very different goals. LLVM uses it
+as a way to automate the generation of massive amounts of information regarding
+instructions, schedules, cores and architecture features. Some backends generate
+output that is consumed by more than one source file, so they need to be created
+in a way that is easy to use pre-processor tricks. Some backends can also print
+C code structures, so that they can be directly included as-is.</p>
+<p>Clang, on the other hand, uses it mainly for diagnostic messages (errors,
+warnings, tips) and attributes, so more on the textual end of the scale.</p>
+</div>
+<div class="section" id="llvm-backends">
+<h2><a class="toc-backref" href="#id2">LLVM BackEnds</a><a class="headerlink" href="#llvm-backends" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is raw. Each section below needs three sub-sections: description
+of its purpose with a list of users, output generated from generic input, and
+finally why it needed a new backend (in case there’s something similar).</p>
+</div>
+<p>Overall, each backend will take the same TableGen file type and transform into
+similar output for different targets/uses. There is an implicit contract between
+the TableGen files, the back-ends and their users.</p>
+<p>For instance, a global contract is that each back-end produces macro-guarded
+sections. Based on whether the file is included by a header or a source file,
+or even in which context of each file the include is being used, you have
+todefine a macro just before including it, to get the right output:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_REGINFO_TARGET_DESC</span>
+<span class="cp">#include "ARMGenRegisterInfo.inc"</span>
+</pre></div>
+</div>
+<p>And just part of the generated file would be included. This is useful if
+you need the same information in multiple formats (instantiation, initialization,
+getter/setter functions, etc) from the same source TableGen file without having
+to re-compile the TableGen file multiple times.</p>
+<p>Sometimes, multiple macros might be defined before the same include file to
+output multiple blocks:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_REGISTER_MATCHER</span>
+<span class="cp">#define GET_SUBTARGET_FEATURE_NAME</span>
+<span class="cp">#define GET_MATCHER_IMPLEMENTATION</span>
+<span class="cp">#include "ARMGenAsmMatcher.inc"</span>
+</pre></div>
+</div>
+<p>The macros will be undef’d automatically as they’re used, in the include file.</p>
+<p>On all LLVM back-ends, the <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt> binary will be executed on the root
+TableGen file <tt class="docutils literal"><span class="pre"><Target>.td</span></tt>, which should include all others. This guarantees
+that all information needed is accessible, and that no duplication is needed
+in the TbleGen files.</p>
+<div class="section" id="codeemitter">
+<h3><a class="toc-backref" href="#id3">CodeEmitter</a><a class="headerlink" href="#codeemitter" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: CodeEmitterGen uses the descriptions of instructions and their fields to
+construct an automated code emitter: a function that, given a MachineInstr,
+returns the (currently, 32-bit unsigned) value of the instruction.</p>
+<p><strong>Output</strong>: C++ code, implementing the target’s CodeEmitter
+class by overriding the virtual functions as <tt class="docutils literal"><span class="pre"><Target>CodeEmitter::function()</span></tt>.</p>
+<p><strong>Usage</strong>: Used to include directly at the end of <tt class="docutils literal"><span class="pre"><Target>MCCodeEmitter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="registerinfo">
+<h3><a class="toc-backref" href="#id4">RegisterInfo</a><a class="headerlink" href="#registerinfo" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend is responsible for emitting a description of a target
+register file for a code generator. It uses instances of the Register,
+RegisterAliases, and RegisterClass classes to gather this information.</p>
+<p><strong>Output</strong>: C++ code with enums and structures representing the register mappings,
+properties, masks, etc.</p>
+<p><strong>Usage</strong>: Both on <tt class="docutils literal"><span class="pre"><Target>BaseRegisterInfo</span></tt> and <tt class="docutils literal"><span class="pre"><Target>MCTargetDesc</span></tt> (headers
+and source files) with macros defining in which they are for declaration vs.
+initialization issues.</p>
+</div>
+<div class="section" id="instrinfo">
+<h3><a class="toc-backref" href="#id5">InstrInfo</a><a class="headerlink" href="#instrinfo" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend is responsible for emitting a description of the target
+instruction set for the code generator. (what are the differences from CodeEmitter?)</p>
+<p><strong>Output</strong>: C++ code with enums and structures representing the register mappings,
+properties, masks, etc.</p>
+<p><strong>Usage</strong>: Both on <tt class="docutils literal"><span class="pre"><Target>BaseInstrInfo</span></tt> and <tt class="docutils literal"><span class="pre"><Target>MCTargetDesc</span></tt> (headers
+and source files) with macros defining in which they are for declaration vs.</p>
+</div>
+<div class="section" id="asmwriter">
+<h3><a class="toc-backref" href="#id6">AsmWriter</a><a class="headerlink" href="#asmwriter" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Emits an assembly printer for the current target.</p>
+<p><strong>Output</strong>: Implementation of <tt class="docutils literal"><span class="pre"><Target>InstPrinter::printInstruction()</span></tt>, among
+other things.</p>
+<p><strong>Usage</strong>: Included directly into <tt class="docutils literal"><span class="pre">InstPrinter/<Target>InstPrinter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="asmmatcher">
+<h3><a class="toc-backref" href="#id7">AsmMatcher</a><a class="headerlink" href="#asmmatcher" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Emits a target specifier matcher for
+converting parsed assembly operands in the MCInst structures. It also
+emits a matcher for custom operand parsing. Extensive documentation is
+written on the <tt class="docutils literal"><span class="pre">AsmMatcherEmitter.cpp</span></tt> file.</p>
+<p><strong>Output</strong>: Assembler parsers’ matcher functions, declarations, etc.</p>
+<p><strong>Usage</strong>: Used in back-ends’ <tt class="docutils literal"><span class="pre">AsmParser/<Target>AsmParser.cpp</span></tt> for
+building the AsmParser class.</p>
+</div>
+<div class="section" id="disassembler">
+<h3><a class="toc-backref" href="#id8">Disassembler</a><a class="headerlink" href="#disassembler" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Contains disassembler table emitters for various
+architectures. Extensive documentation is written on the
+<tt class="docutils literal"><span class="pre">DisassemblerEmitter.cpp</span></tt> file.</p>
+<p><strong>Output</strong>: Decoding tables, static decoding functions, etc.</p>
+<p><strong>Usage</strong>: Directly included in <tt class="docutils literal"><span class="pre">Disassembler/<Target>Disassembler.cpp</span></tt>
+to cater for all default decodings, after all hand-made ones.</p>
+</div>
+<div class="section" id="pseudolowering">
+<h3><a class="toc-backref" href="#id9">PseudoLowering</a><a class="headerlink" href="#pseudolowering" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate pseudo instruction lowering.</p>
+<p><strong>Output</strong>: Implements <tt class="docutils literal"><span class="pre">ARMAsmPrinter::emitPseudoExpansionLowering()</span></tt>.</p>
+<p><strong>Usage</strong>: Included directly into <tt class="docutils literal"><span class="pre"><Target>AsmPrinter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="callingconv">
+<h3><a class="toc-backref" href="#id10">CallingConv</a><a class="headerlink" href="#callingconv" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Responsible for emitting descriptions of the calling
+conventions supported by this target.</p>
+<p><strong>Output</strong>: Implement static functions to deal with calling conventions
+chained by matching styles, returning false on no match.</p>
+<p><strong>Usage</strong>: Used in ISelLowering and FastIsel as function pointers to
+implementation returned by a CC sellection function.</p>
+</div>
+<div class="section" id="dagisel">
+<h3><a class="toc-backref" href="#id11">DAGISel</a><a class="headerlink" href="#dagisel" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate a DAG instruction selector.</p>
+<p><strong>Output</strong>: Creates huge functions for automating DAG selection.</p>
+<p><strong>Usage</strong>: Included in <tt class="docutils literal"><span class="pre"><Target>ISelDAGToDAG.cpp</span></tt> inside the target’s
+implementation of <tt class="docutils literal"><span class="pre">SelectionDAGISel</span></tt>.</p>
+</div>
+<div class="section" id="dfapacketizer">
+<h3><a class="toc-backref" href="#id12">DFAPacketizer</a><a class="headerlink" href="#dfapacketizer" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This class parses the Schedule.td file and produces an API that
+can be used to reason about whether an instruction can be added to a packet
+on a VLIW architecture. The class internally generates a deterministic finite
+automaton (DFA) that models all possible mappings of machine instructions
+to functional units as instructions are added to a packet.</p>
+<p><strong>Output</strong>: Scheduling tables for GPU back-ends (Hexagon, AMD).</p>
+<p><strong>Usage</strong>: Included directly on <tt class="docutils literal"><span class="pre"><Target>InstrInfo.cpp</span></tt>.</p>
+</div>
+<div class="section" id="fastisel">
+<h3><a class="toc-backref" href="#id13">FastISel</a><a class="headerlink" href="#fastisel" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend emits code for use by the “fast”
+instruction selection algorithm. See the comments at the top of
+lib/CodeGen/SelectionDAG/FastISel.cpp for background. This file
+scans through the target’s tablegen instruction-info files
+and extracts instructions with obvious-looking patterns, and it emits
+code to look up these instructions by type and operator.</p>
+<p><strong>Output</strong>: Generates <tt class="docutils literal"><span class="pre">Predicate</span></tt> and <tt class="docutils literal"><span class="pre">FastEmit</span></tt> methods.</p>
+<p><strong>Usage</strong>: Implements private methods of the targets’ implementation
+of <tt class="docutils literal"><span class="pre">FastISel</span></tt> class.</p>
+</div>
+<div class="section" id="subtarget">
+<h3><a class="toc-backref" href="#id14">Subtarget</a><a class="headerlink" href="#subtarget" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate subtarget enumerations.</p>
+<p><strong>Output</strong>: Enums, globals, local tables for sub-target information.</p>
+<p><strong>Usage</strong>: Populates <tt class="docutils literal"><span class="pre"><Target>Subtarget</span></tt> and
+<tt class="docutils literal"><span class="pre">MCTargetDesc/<Target>MCTargetDesc</span></tt> files (both headers and source).</p>
+</div>
+<div class="section" id="intrinsic">
+<h3><a class="toc-backref" href="#id15">Intrinsic</a><a class="headerlink" href="#intrinsic" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate (target) intrinsic information.</p>
+</div>
+<div class="section" id="optparserdefs">
+<h3><a class="toc-backref" href="#id16">OptParserDefs</a><a class="headerlink" href="#optparserdefs" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Print enum values for a class.</p>
+</div>
+<div class="section" id="ctags">
+<h3><a class="toc-backref" href="#id17">CTags</a><a class="headerlink" href="#ctags" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend emits an index of definitions in ctags(1)
+format. A helper script, utils/TableGen/tdtags, provides an easier-to-use
+interface; run ‘tdtags -H’ for documentation.</p>
+</div>
+</div>
+<div class="section" id="clang-backends">
+<h2><a class="toc-backref" href="#id18">Clang BackEnds</a><a class="headerlink" href="#clang-backends" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="clangattrclasses">
+<h3><a class="toc-backref" href="#id19">ClangAttrClasses</a><a class="headerlink" href="#clangattrclasses" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates Attrs.inc, which contains semantic attribute class
+declarations for any attribute in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> that has not set <tt class="docutils literal"><span class="pre">ASTNode</span> <span class="pre">=</span> <span class="pre">0</span></tt>.
+This file is included as part of <tt class="docutils literal"><span class="pre">Attr.h</span></tt>.</p>
+</div>
+<div class="section" id="clangattrparserstringswitches">
+<h3><a class="toc-backref" href="#id20">ClangAttrParserStringSwitches</a><a class="headerlink" href="#clangattrparserstringswitches" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParserStringSwitches.inc, which contains
+StringSwitch::Case statements for parser-related string switches. Each switch
+is given its own macro (such as <tt class="docutils literal"><span class="pre">CLANG_ATTR_ARG_CONTEXT_LIST</span></tt>, or
+<tt class="docutils literal"><span class="pre">CLANG_ATTR_IDENTIFIER_ARG_LIST</span></tt>), which is expected to be defined before
+including AttrParserStringSwitches.inc, and undefined after.</p>
+</div>
+<div class="section" id="clangattrimpl">
+<h3><a class="toc-backref" href="#id21">ClangAttrImpl</a><a class="headerlink" href="#clangattrimpl" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrImpl.inc, which contains semantic attribute class
+definitions for any attribute in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> that has not set <tt class="docutils literal"><span class="pre">ASTNode</span> <span class="pre">=</span> <span class="pre">0</span></tt>.
+This file is included as part of <tt class="docutils literal"><span class="pre">AttrImpl.cpp</span></tt>.</p>
+</div>
+<div class="section" id="clangattrlist">
+<h3><a class="toc-backref" href="#id22">ClangAttrList</a><a class="headerlink" href="#clangattrlist" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrList.inc, which is used when a list of semantic
+attribute identifiers is required. For instance, <tt class="docutils literal"><span class="pre">AttrKinds.h</span></tt> includes this
+file to generate the list of <tt class="docutils literal"><span class="pre">attr::Kind</span></tt> enumeration values. This list is
+separated out into multiple categories: attributes, inheritable attributes, and
+inheritable parameter attributes. This categorization happens automatically
+based on information in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> and is used to implement the <tt class="docutils literal"><span class="pre">classof</span></tt>
+functionality required for <tt class="docutils literal"><span class="pre">dyn_cast</span></tt> and similar APIs.</p>
+</div>
+<div class="section" id="clangattrpchread">
+<h3><a class="toc-backref" href="#id23">ClangAttrPCHRead</a><a class="headerlink" href="#clangattrpchread" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrPCHRead.inc, which is used to deserialize attributes
+in the <tt class="docutils literal"><span class="pre">ASTReader::ReadAttributes</span></tt> function.</p>
+</div>
+<div class="section" id="clangattrpchwrite">
+<h3><a class="toc-backref" href="#id24">ClangAttrPCHWrite</a><a class="headerlink" href="#clangattrpchwrite" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrPCHWrite.inc, which is used to serialize attributes in
+the <tt class="docutils literal"><span class="pre">ASTWriter::WriteAttributes</span></tt> function.</p>
+</div>
+<div class="section" id="clangattrspellings">
+<h3><a class="toc-backref" href="#id25">ClangAttrSpellings</a><a class="headerlink" href="#clangattrspellings" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrSpellings.inc, which is used to implement the
+<tt class="docutils literal"><span class="pre">__has_attribute</span></tt> feature test macro.</p>
+</div>
+<div class="section" id="clangattrspellinglistindex">
+<h3><a class="toc-backref" href="#id26">ClangAttrSpellingListIndex</a><a class="headerlink" href="#clangattrspellinglistindex" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrSpellingListIndex.inc, which is used to map parsed
+attribute spellings (including which syntax or scope was used) to an attribute
+spelling list index. These spelling list index values are internal
+implementation details exposed via
+<tt class="docutils literal"><span class="pre">AttributeList::getAttributeSpellingListIndex</span></tt>.</p>
+</div>
+<div class="section" id="clangattrvisitor">
+<h3><a class="toc-backref" href="#id27">ClangAttrVisitor</a><a class="headerlink" href="#clangattrvisitor" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrVisitor.inc, which is used when implementing
+recursive AST visitors.</p>
+</div>
+<div class="section" id="clangattrtemplateinstantiate">
+<h3><a class="toc-backref" href="#id28">ClangAttrTemplateInstantiate</a><a class="headerlink" href="#clangattrtemplateinstantiate" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrTemplateInstantiate.inc, which implements the
+<tt class="docutils literal"><span class="pre">instantiateTemplateAttribute</span></tt> function, used when instantiating a template
+that requires an attribute to be cloned.</p>
+</div>
+<div class="section" id="clangattrparsedattrlist">
+<h3><a class="toc-backref" href="#id29">ClangAttrParsedAttrList</a><a class="headerlink" href="#clangattrparsedattrlist" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrList.inc, which is used to generate the
+<tt class="docutils literal"><span class="pre">AttributeList::Kind</span></tt> parsed attribute enumeration.</p>
+</div>
+<div class="section" id="clangattrparsedattrimpl">
+<h3><a class="toc-backref" href="#id30">ClangAttrParsedAttrImpl</a><a class="headerlink" href="#clangattrparsedattrimpl" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrImpl.inc, which is used by
+<tt class="docutils literal"><span class="pre">AttributeList.cpp</span></tt> to implement several functions on the <tt class="docutils literal"><span class="pre">AttributeList</span></tt>
+class. This functionality is implemented via the <tt class="docutils literal"><span class="pre">AttrInfoMap</span> <span class="pre">ParsedAttrInfo</span></tt>
+array, which contains one element per parsed attribute object.</p>
+</div>
+<div class="section" id="clangattrparsedattrkinds">
+<h3><a class="toc-backref" href="#id31">ClangAttrParsedAttrKinds</a><a class="headerlink" href="#clangattrparsedattrkinds" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrKinds.inc, which is used to implement the
+<tt class="docutils literal"><span class="pre">AttributeList::getKind</span></tt> function, mapping a string (and syntax) to a parsed
+attribute <tt class="docutils literal"><span class="pre">AttributeList::Kind</span></tt> enumeration.</p>
+</div>
+<div class="section" id="clangattrdump">
+<h3><a class="toc-backref" href="#id32">ClangAttrDump</a><a class="headerlink" href="#clangattrdump" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrDump.inc, which dumps information about an attribute.
+It is used to implement <tt class="docutils literal"><span class="pre">ASTDumper::dumpAttr</span></tt>.</p>
+</div>
+<div class="section" id="clangdiagsdefs">
+<h3><a class="toc-backref" href="#id33">ClangDiagsDefs</a><a class="headerlink" href="#clangdiagsdefs" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostics definitions.</p>
+</div>
+<div class="section" id="clangdiaggroups">
+<h3><a class="toc-backref" href="#id34">ClangDiagGroups</a><a class="headerlink" href="#clangdiaggroups" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostic groups.</p>
+</div>
+<div class="section" id="clangdiagsindexname">
+<h3><a class="toc-backref" href="#id35">ClangDiagsIndexName</a><a class="headerlink" href="#clangdiagsindexname" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostic name index.</p>
+</div>
+<div class="section" id="clangcommentnodes">
+<h3><a class="toc-backref" href="#id36">ClangCommentNodes</a><a class="headerlink" href="#clangcommentnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST comment nodes.</p>
+</div>
+<div class="section" id="clangdeclnodes">
+<h3><a class="toc-backref" href="#id37">ClangDeclNodes</a><a class="headerlink" href="#clangdeclnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST declaration nodes.</p>
+</div>
+<div class="section" id="clangstmtnodes">
+<h3><a class="toc-backref" href="#id38">ClangStmtNodes</a><a class="headerlink" href="#clangstmtnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST statement nodes.</p>
+</div>
+<div class="section" id="clangsacheckers">
+<h3><a class="toc-backref" href="#id39">ClangSACheckers</a><a class="headerlink" href="#clangsacheckers" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang Static Analyzer checkers.</p>
+</div>
+<div class="section" id="clangcommenthtmltags">
+<h3><a class="toc-backref" href="#id40">ClangCommentHTMLTags</a><a class="headerlink" href="#clangcommenthtmltags" title="Permalink to this headline">¶</a></h3>
+<p>Generate efficient matchers for HTML tag names that are used in documentation comments.</p>
+</div>
+<div class="section" id="clangcommenthtmltagsproperties">
+<h3><a class="toc-backref" href="#id41">ClangCommentHTMLTagsProperties</a><a class="headerlink" href="#clangcommenthtmltagsproperties" title="Permalink to this headline">¶</a></h3>
+<p>Generate efficient matchers for HTML tag properties.</p>
+</div>
+<div class="section" id="clangcommenthtmlnamedcharacterreferences">
+<h3><a class="toc-backref" href="#id42">ClangCommentHTMLNamedCharacterReferences</a><a class="headerlink" href="#clangcommenthtmlnamedcharacterreferences" title="Permalink to this headline">¶</a></h3>
+<p>Generate function to translate named character references to UTF-8 sequences.</p>
+</div>
+<div class="section" id="clangcommentcommandinfo">
+<h3><a class="toc-backref" href="#id43">ClangCommentCommandInfo</a><a class="headerlink" href="#clangcommentcommandinfo" title="Permalink to this headline">¶</a></h3>
+<p>Generate command properties for commands that are used in documentation comments.</p>
+</div>
+<div class="section" id="clangcommentcommandlist">
+<h3><a class="toc-backref" href="#id44">ClangCommentCommandList</a><a class="headerlink" href="#clangcommentcommandlist" title="Permalink to this headline">¶</a></h3>
+<p>Generate list of commands that are used in documentation comments.</p>
+</div>
+<div class="section" id="armneon">
+<h3><a class="toc-backref" href="#id45">ArmNeon</a><a class="headerlink" href="#armneon" title="Permalink to this headline">¶</a></h3>
+<p>Generate arm_neon.h for clang.</p>
+</div>
+<div class="section" id="armneonsema">
+<h3><a class="toc-backref" href="#id46">ArmNeonSema</a><a class="headerlink" href="#armneonsema" title="Permalink to this headline">¶</a></h3>
+<p>Generate ARM NEON sema support for clang.</p>
+</div>
+<div class="section" id="armneontest">
+<h3><a class="toc-backref" href="#id47">ArmNeonTest</a><a class="headerlink" href="#armneontest" title="Permalink to this headline">¶</a></h3>
+<p>Generate ARM NEON tests for clang.</p>
+</div>
+<div class="section" id="attrdocs">
+<h3><a class="toc-backref" href="#id48">AttrDocs</a><a class="headerlink" href="#attrdocs" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates <tt class="docutils literal"><span class="pre">AttributeReference.rst</span></tt> from <tt class="docutils literal"><span class="pre">AttrDocs.td</span></tt>, and is
+used for documenting user-facing attributes.</p>
+</div>
+</div>
+<div class="section" id="how-to-write-a-back-end">
+<h2><a class="toc-backref" href="#id49">How to write a back-end</a><a class="headerlink" href="#how-to-write-a-back-end" title="Permalink to this headline">¶</a></h2>
+<p>TODO.</p>
+<p>Until we get a step-by-step HowTo for writing TableGen backends, you can at
+least grab the boilerplate (build system, new files, etc.) from Clang’s
+r173931.</p>
+<p>TODO: How they work, how to write one. This section should not contain details
+about any particular backend, except maybe <tt class="docutils literal"><span class="pre">-print-enums</span></tt> as an example. This
+should highlight the APIs in <tt class="docutils literal"><span class="pre">TableGen/Record.h</span></tt>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LangRef.html" title="TableGen Language Reference"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="TableGen"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >TableGen</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TableGen/Deficiencies.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TableGen/Deficiencies.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TableGen/Deficiencies.html (added)
+++ www-releases/trunk/3.9.1/docs/TableGen/Deficiencies.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,128 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Deficiencies — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="../index.html" />
+ <link rel="up" title="TableGen" href="index.html" />
+ <link rel="next" title="Debugging JIT-ed Code With GDB" href="../DebuggingJITedCode.html" />
+ <link rel="prev" title="TableGen Language Introduction" href="LangIntro.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LangIntro.html" title="TableGen Language Introduction"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">TableGen</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-deficiencies">
+<h1>TableGen Deficiencies<a class="headerlink" href="#tablegen-deficiencies" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#known-problems" id="id2">Known Problems</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Despite being very generic, TableGen has some deficiencies that have been
+pointed out numerous times. The common theme is that, while TableGen allows
+you to build Domain-Specific-Languages, the final languages that you create
+lack the power of other DSLs, which in turn increase considerably the size
+and complexity of TableGen files.</p>
+<p>At the same time, TableGen allows you to create virtually any meaning of
+the basic concepts via custom-made back-ends, which can pervert the original
+design and make it very hard for newcomers to understand it.</p>
+<p>There are some in favour of extending the semantics even more, but making sure
+back-ends adhere to strict rules. Others suggesting we should move to more
+powerful DSLs designed with specific purposes, or even re-using existing
+DSLs.</p>
+</div>
+<div class="section" id="known-problems">
+<h2><a class="toc-backref" href="#id2">Known Problems</a><a class="headerlink" href="#known-problems" title="Permalink to this headline">¶</a></h2>
+<p>TODO: Add here frequently asked questions about why TableGen doesn’t do
+what you want, how it might, and how we could extend/restrict it to
+be more use friendly.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LangIntro.html" title="TableGen Language Introduction"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >TableGen</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TableGen/LangIntro.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TableGen/LangIntro.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TableGen/LangIntro.html (added)
+++ www-releases/trunk/3.9.1/docs/TableGen/LangIntro.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,647 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Language Introduction — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="../index.html" />
+ <link rel="up" title="TableGen" href="index.html" />
+ <link rel="next" title="TableGen Deficiencies" href="Deficiencies.html" />
+ <link rel="prev" title="TableGen Language Reference" href="LangRef.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Deficiencies.html" title="TableGen Deficiencies"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LangRef.html" title="TableGen Language Reference"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">TableGen</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-language-introduction">
+<h1>TableGen Language Introduction<a class="headerlink" href="#tablegen-language-introduction" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li>
+<li><a class="reference internal" href="#tablegen-syntax" id="id5">TableGen syntax</a><ul>
+<li><a class="reference internal" href="#tablegen-primitives" id="id6">TableGen primitives</a><ul>
+<li><a class="reference internal" href="#tablegen-comments" id="id7">TableGen comments</a></li>
+<li><a class="reference internal" href="#the-tablegen-type-system" id="id8">The TableGen type system</a></li>
+<li><a class="reference internal" href="#tablegen-values-and-expressions" id="id9">TableGen values and expressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#classes-and-definitions" id="id10">Classes and definitions</a><ul>
+<li><a class="reference internal" href="#value-definitions" id="id11">Value definitions</a></li>
+<li><a class="reference internal" href="#let-expressions-within-a-record" id="id12">‘let’ expressions</a></li>
+<li><a class="reference internal" href="#class-template-arguments" id="id13">Class template arguments</a></li>
+<li><a class="reference internal" href="#multiclass-definitions-and-instances" id="id14">Multiclass definitions and instances</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#file-scope-entities" id="id15">File scope entities</a><ul>
+<li><a class="reference internal" href="#file-inclusion" id="id16">File inclusion</a></li>
+<li><a class="reference internal" href="#id3" id="id17">‘let’ expressions</a></li>
+<li><a class="reference internal" href="#looping" id="id18">Looping</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#code-generator-backend-info" id="id19">Code Generator backend info</a></li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is extremely rough. If you find something lacking, please
+fix it, file a documentation bug, or ask about it on llvm-dev.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id4">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is not meant to be a normative spec about the TableGen language
+in and of itself (i.e. how to understand a given construct in terms of how
+it affects the final set of records represented by the TableGen file). For
+the formal language specification, see <a class="reference internal" href="LangRef.html"><em>TableGen Language Reference</em></a>.</p>
+</div>
+<div class="section" id="tablegen-syntax">
+<h2><a class="toc-backref" href="#id5">TableGen syntax</a><a class="headerlink" href="#tablegen-syntax" title="Permalink to this headline">¶</a></h2>
+<p>TableGen doesn’t care about the meaning of data (that is up to the backend to
+define), but it does care about syntax, and it enforces a simple type system.
+This section describes the syntax and the constructs allowed in a TableGen file.</p>
+<div class="section" id="tablegen-primitives">
+<h3><a class="toc-backref" href="#id6">TableGen primitives</a><a class="headerlink" href="#tablegen-primitives" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="tablegen-comments">
+<h4><a class="toc-backref" href="#id7">TableGen comments</a><a class="headerlink" href="#tablegen-comments" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports C++ style “<tt class="docutils literal"><span class="pre">//</span></tt>” comments, which run to the end of the
+line, and it also supports <strong>nestable</strong> “<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">*/</span></tt>” comments.</p>
+</div>
+<div class="section" id="the-tablegen-type-system">
+<span id="tablegen-type"></span><h4><a class="toc-backref" href="#id8">The TableGen type system</a><a class="headerlink" href="#the-tablegen-type-system" title="Permalink to this headline">¶</a></h4>
+<p>TableGen files are strongly typed, in a simple (but complete) type-system.
+These types are used to perform automatic conversions, check for errors, and to
+help interface designers constrain the input that they allow. Every <a class="reference internal" href="#value-definition">value
+definition</a> is required to have an associated type.</p>
+<p>TableGen supports a mixture of very low-level types (such as <tt class="docutils literal"><span class="pre">bit</span></tt>) and very
+high-level types (such as <tt class="docutils literal"><span class="pre">dag</span></tt>). This flexibility is what allows it to
+describe a wide range of information conveniently and compactly. The TableGen
+types are:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">bit</span></tt></dt>
+<dd>A ‘bit’ is a boolean value that can hold either 0 or 1.</dd>
+<dt><tt class="docutils literal"><span class="pre">int</span></tt></dt>
+<dd>The ‘int’ type represents a simple 32-bit integer value, such as 5.</dd>
+<dt><tt class="docutils literal"><span class="pre">string</span></tt></dt>
+<dd>The ‘string’ type represents an ordered sequence of characters of arbitrary
+length.</dd>
+<dt><tt class="docutils literal"><span class="pre">bits<n></span></tt></dt>
+<dd>A ‘bits’ type is an arbitrary, but fixed, size integer that is broken up
+into individual bits. This type is useful because it can handle some bits
+being defined while others are undefined.</dd>
+<dt><tt class="docutils literal"><span class="pre">list<ty></span></tt></dt>
+<dd>This type represents a list whose elements are some other type. The
+contained type is arbitrary: it can even be another list type.</dd>
+<dt>Class type</dt>
+<dd>Specifying a class name in a type context means that the defined value must
+be a subclass of the specified class. This is useful in conjunction with
+the <tt class="docutils literal"><span class="pre">list</span></tt> type, for example, to constrain the elements of the list to a
+common base class (e.g., a <tt class="docutils literal"><span class="pre">list<Register></span></tt> can only contain definitions
+derived from the “<tt class="docutils literal"><span class="pre">Register</span></tt>” class).</dd>
+<dt><tt class="docutils literal"><span class="pre">dag</span></tt></dt>
+<dd>This type represents a nestable directed graph of elements.</dd>
+</dl>
+<p>To date, these types have been sufficient for describing things that TableGen
+has been used for, but it is straight-forward to extend this list if needed.</p>
+</div>
+<div class="section" id="tablegen-values-and-expressions">
+<span id="tablegen-expressions"></span><h4><a class="toc-backref" href="#id9">TableGen values and expressions</a><a class="headerlink" href="#tablegen-values-and-expressions" title="Permalink to this headline">¶</a></h4>
+<p>TableGen allows for a pretty reasonable number of different expression forms
+when building up values. These forms allow the TableGen file to be written in a
+natural syntax and flavor for the application. The current expression forms
+supported include:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">?</span></tt></dt>
+<dd>uninitialized field</dd>
+<dt><tt class="docutils literal"><span class="pre">0b1001011</span></tt></dt>
+<dd>binary integer value.
+Note that this is sized by the number of bits given and will not be
+silently extended/truncated.</dd>
+<dt><tt class="docutils literal"><span class="pre">07654321</span></tt></dt>
+<dd>octal integer value (indicated by a leading 0)</dd>
+<dt><tt class="docutils literal"><span class="pre">7</span></tt></dt>
+<dd>decimal integer value</dd>
+<dt><tt class="docutils literal"><span class="pre">0x7F</span></tt></dt>
+<dd>hexadecimal integer value</dd>
+<dt><tt class="docutils literal"><span class="pre">"foo"</span></tt></dt>
+<dd>string value</dd>
+<dt><tt class="docutils literal"><span class="pre">[{</span> <span class="pre">...</span> <span class="pre">}]</span></tt></dt>
+<dd>usually called a “code fragment”, but is just a multiline string literal</dd>
+<dt><tt class="docutils literal"><span class="pre">[</span> <span class="pre">X,</span> <span class="pre">Y,</span> <span class="pre">Z</span> <span class="pre">]<type></span></tt></dt>
+<dd>list value. <type> is the type of the list element and is usually optional.
+In rare cases, TableGen is unable to deduce the element type in which case
+the user must specify it explicitly.</dd>
+<dt><tt class="docutils literal"><span class="pre">{</span> <span class="pre">a,</span> <span class="pre">b,</span> <span class="pre">0b10</span> <span class="pre">}</span></tt></dt>
+<dd>initializer for a “bits<4>” value.
+1-bit from “a”, 1-bit from “b”, 2-bits from 0b10.</dd>
+<dt><tt class="docutils literal"><span class="pre">value</span></tt></dt>
+<dd>value reference</dd>
+<dt><tt class="docutils literal"><span class="pre">value{17}</span></tt></dt>
+<dd>access to one bit of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">value{15-17}</span></tt></dt>
+<dd>access to multiple bits of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">DEF</span></tt></dt>
+<dd>reference to a record definition</dd>
+<dt><tt class="docutils literal"><span class="pre">CLASS<val</span> <span class="pre">list></span></tt></dt>
+<dd>reference to a new anonymous definition of CLASS with the specified template
+arguments.</dd>
+<dt><tt class="docutils literal"><span class="pre">X.Y</span></tt></dt>
+<dd>reference to the subfield of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">list[4-7,17,2-3]</span></tt></dt>
+<dd>A slice of the ‘list’ list, including elements 4,5,6,7,17,2, and 3 from it.
+Elements may be included multiple times.</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">[</span> <span class="pre"><list></span> <span class="pre">]</span> <span class="pre">in</span> <span class="pre">{</span> <span class="pre"><body></span> <span class="pre">}</span></tt></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">[</span> <span class="pre"><list></span> <span class="pre">]</span> <span class="pre">in</span> <span class="pre"><def></span></tt></dt>
+<dd>Replicate <body> or <def>, replacing instances of <var> with each value
+in <list>. <var> is scoped at the level of the <tt class="docutils literal"><span class="pre">foreach</span></tt> loop and must
+not conflict with any other object introduced in <body> or <def>. Currently
+only <tt class="docutils literal"><span class="pre">def</span></tt>s are expanded within <body>.</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">0-15</span> <span class="pre">in</span> <span class="pre">...</span></tt></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">{0-15,32-47}</span> <span class="pre">in</span> <span class="pre">...</span></tt></dt>
+<dd>Loop over ranges of integers. The braces are required for multiple ranges.</dd>
+<dt><tt class="docutils literal"><span class="pre">(DEF</span> <span class="pre">a,</span> <span class="pre">b)</span></tt></dt>
+<dd>a dag value. The first element is required to be a record definition, the
+remaining elements in the list may be arbitrary other values, including
+nested <tt class="docutils literal"><span class="pre">`dag</span></tt>‘ values.</dd>
+<dt><tt class="docutils literal"><span class="pre">!listconcat(a,</span> <span class="pre">b,</span> <span class="pre">...)</span></tt></dt>
+<dd>A list value that is the result of concatenating the ‘a’ and ‘b’ lists.
+The lists must have the same element type.
+More than two arguments are accepted with the result being the concatenation
+of all the lists given.</dd>
+<dt><tt class="docutils literal"><span class="pre">!strconcat(a,</span> <span class="pre">b,</span> <span class="pre">...)</span></tt></dt>
+<dd>A string value that is the result of concatenating the ‘a’ and ‘b’ strings.
+More than two arguments are accepted with the result being the concatenation
+of all the strings given.</dd>
+<dt><tt class="docutils literal"><span class="pre">str1#str2</span></tt></dt>
+<dd>“#” (paste) is a shorthand for !strconcat. It may concatenate things that
+are not quoted strings, in which case an implicit !cast<string> is done on
+the operand of the paste.</dd>
+<dt><tt class="docutils literal"><span class="pre">!cast<type>(a)</span></tt></dt>
+<dd>A symbol of type <em>type</em> obtained by looking up the string ‘a’ in the symbol
+table. If the type of ‘a’ does not match <em>type</em>, TableGen aborts with an
+error. !cast<string> is a special case in that the argument must be an
+object defined by a ‘def’ construct.</dd>
+<dt><tt class="docutils literal"><span class="pre">!subst(a,</span> <span class="pre">b,</span> <span class="pre">c)</span></tt></dt>
+<dd>If ‘a’ and ‘b’ are of string type or are symbol references, substitute ‘b’
+for ‘a’ in ‘c.’ This operation is analogous to $(subst) in GNU make.</dd>
+<dt><tt class="docutils literal"><span class="pre">!foreach(a,</span> <span class="pre">b,</span> <span class="pre">c)</span></tt></dt>
+<dd>For each member of dag or list ‘b’ apply operator ‘c.’ ‘a’ is a dummy
+variable that should be declared as a member variable of an instantiated
+class. This operation is analogous to $(foreach) in GNU make.</dd>
+<dt><tt class="docutils literal"><span class="pre">!head(a)</span></tt></dt>
+<dd>The first element of list ‘a.’</dd>
+<dt><tt class="docutils literal"><span class="pre">!tail(a)</span></tt></dt>
+<dd>The 2nd-N elements of list ‘a.’</dd>
+<dt><tt class="docutils literal"><span class="pre">!empty(a)</span></tt></dt>
+<dd>An integer {0,1} indicating whether list ‘a’ is empty.</dd>
+<dt><tt class="docutils literal"><span class="pre">!if(a,b,c)</span></tt></dt>
+<dd>‘b’ if the result of ‘int’ or ‘bit’ operator ‘a’ is nonzero, ‘c’ otherwise.</dd>
+<dt><tt class="docutils literal"><span class="pre">!eq(a,b)</span></tt></dt>
+<dd>‘bit 1’ if string a is equal to string b, 0 otherwise. This only operates
+on string, int and bit objects. Use !cast<string> to compare other types of
+objects.</dd>
+<dt><tt class="docutils literal"><span class="pre">!shl(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!srl(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!sra(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!add(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!and(a,b)</span></tt></dt>
+<dd>The usual binary and arithmetic operators.</dd>
+</dl>
+<p>Note that all of the values have rules specifying how they convert to values
+for different types. These rules allow you to assign a value like “<tt class="docutils literal"><span class="pre">7</span></tt>”
+to a “<tt class="docutils literal"><span class="pre">bits<4></span></tt>” value, for example.</p>
+</div>
+</div>
+<div class="section" id="classes-and-definitions">
+<h3><a class="toc-backref" href="#id10">Classes and definitions</a><a class="headerlink" href="#classes-and-definitions" title="Permalink to this headline">¶</a></h3>
+<p>As mentioned in the <a class="reference internal" href="index.html"><em>introduction</em></a>, classes and definitions (collectively known as
+‘records’) in TableGen are the main high-level unit of information that TableGen
+collects. Records are defined with a <tt class="docutils literal"><span class="pre">def</span></tt> or <tt class="docutils literal"><span class="pre">class</span></tt> keyword, the record
+name, and an optional list of “<a class="reference internal" href="#template-arguments">template arguments</a>”. If the record has
+superclasses, they are specified as a comma separated list that starts with a
+colon character (“<tt class="docutils literal"><span class="pre">:</span></tt>”). If <a class="reference internal" href="#value-definitions">value definitions</a> or <a class="reference internal" href="#let-expressions">let expressions</a> are
+needed for the class, they are enclosed in curly braces (“<tt class="docutils literal"><span class="pre">{}</span></tt>”); otherwise,
+the record ends with a semicolon.</p>
+<p>Here is a simple TableGen file:</p>
+<div class="highlight-text"><div class="highlight"><pre>class C { bit V = 1; }
+def X : C;
+def Y : C {
+ string Greeting = "hello";
+}
+</pre></div>
+</div>
+<p>This example defines two definitions, <tt class="docutils literal"><span class="pre">X</span></tt> and <tt class="docutils literal"><span class="pre">Y</span></tt>, both of which derive from
+the <tt class="docutils literal"><span class="pre">C</span></tt> class. Because of this, they both get the <tt class="docutils literal"><span class="pre">V</span></tt> bit value. The <tt class="docutils literal"><span class="pre">Y</span></tt>
+definition also gets the Greeting member as well.</p>
+<p>In general, classes are useful for collecting together the commonality between a
+group of records and isolating it in a single place. Also, classes permit the
+specification of default values for their subclasses, allowing the subclasses to
+override them as they wish.</p>
+<div class="section" id="value-definitions">
+<span id="value-definition"></span><span id="id1"></span><h4><a class="toc-backref" href="#id11">Value definitions</a><a class="headerlink" href="#value-definitions" title="Permalink to this headline">¶</a></h4>
+<p>Value definitions define named entries in records. A value must be defined
+before it can be referred to as the operand for another value definition or
+before the value is reset with a <a class="reference internal" href="#let-expression">let expression</a>. A value is defined by
+specifying a <a class="reference internal" href="#tablegen-type">TableGen type</a> and a name. If an initial value is available, it
+may be specified after the type with an equal sign. Value definitions require
+terminating semicolons.</p>
+</div>
+<div class="section" id="let-expressions-within-a-record">
+<span id="let-expressions"></span><span id="let-expression"></span><span id="id2"></span><h4><a class="toc-backref" href="#id12">‘let’ expressions</a><a class="headerlink" href="#let-expressions-within-a-record" title="Permalink to this headline">¶</a></h4>
+<p>A record-level let expression is used to change the value of a value definition
+in a record. This is primarily useful when a superclass defines a value that a
+derived class or definition wants to override. Let expressions consist of the
+‘<tt class="docutils literal"><span class="pre">let</span></tt>‘ keyword followed by a value name, an equal sign (“<tt class="docutils literal"><span class="pre">=</span></tt>”), and a new
+value. For example, a new class could be added to the example above, redefining
+the <tt class="docutils literal"><span class="pre">V</span></tt> field for all of its subclasses:</p>
+<div class="highlight-text"><div class="highlight"><pre>class D : C { let V = 0; }
+def Z : D;
+</pre></div>
+</div>
+<p>In this case, the <tt class="docutils literal"><span class="pre">Z</span></tt> definition will have a zero value for its <tt class="docutils literal"><span class="pre">V</span></tt> value,
+despite the fact that it derives (indirectly) from the <tt class="docutils literal"><span class="pre">C</span></tt> class, because the
+<tt class="docutils literal"><span class="pre">D</span></tt> class overrode its value.</p>
+</div>
+<div class="section" id="class-template-arguments">
+<span id="template-arguments"></span><h4><a class="toc-backref" href="#id13">Class template arguments</a><a class="headerlink" href="#class-template-arguments" title="Permalink to this headline">¶</a></h4>
+<p>TableGen permits the definition of parameterized classes as well as normal
+concrete classes. Parameterized TableGen classes specify a list of variable
+bindings (which may optionally have defaults) that are bound when used. Here is
+a simple example:</p>
+<div class="highlight-text"><div class="highlight"><pre>class FPFormat<bits<3> val> {
+ bits<3> Value = val;
+}
+def NotFP : FPFormat<0>;
+def ZeroArgFP : FPFormat<1>;
+def OneArgFP : FPFormat<2>;
+def OneArgFPRW : FPFormat<3>;
+def TwoArgFP : FPFormat<4>;
+def CompareFP : FPFormat<5>;
+def CondMovFP : FPFormat<6>;
+def SpecialFP : FPFormat<7>;
+</pre></div>
+</div>
+<p>In this case, template arguments are used as a space efficient way to specify a
+list of “enumeration values”, each with a “<tt class="docutils literal"><span class="pre">Value</span></tt>” field set to the specified
+integer.</p>
+<p>The more esoteric forms of <a class="reference internal" href="#tablegen-expressions">TableGen expressions</a> are useful in conjunction
+with template arguments. As an example:</p>
+<div class="highlight-text"><div class="highlight"><pre>class ModRefVal<bits<2> val> {
+ bits<2> Value = val;
+}
+
+def None : ModRefVal<0>;
+def Mod : ModRefVal<1>;
+def Ref : ModRefVal<2>;
+def ModRef : ModRefVal<3>;
+
+class Value<ModRefVal MR> {
+ // Decode some information into a more convenient format, while providing
+ // a nice interface to the user of the "Value" class.
+ bit isMod = MR.Value{0};
+ bit isRef = MR.Value{1};
+
+ // other stuff...
+}
+
+// Example uses
+def bork : Value<Mod>;
+def zork : Value<Ref>;
+def hork : Value<ModRef>;
+</pre></div>
+</div>
+<p>This is obviously a contrived example, but it shows how template arguments can
+be used to decouple the interface provided to the user of the class from the
+actual internal data representation expected by the class. In this case,
+running <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt> on the example prints the following definitions:</p>
+<div class="highlight-text"><div class="highlight"><pre>def bork { // Value
+ bit isMod = 1;
+ bit isRef = 0;
+}
+def hork { // Value
+ bit isMod = 1;
+ bit isRef = 1;
+}
+def zork { // Value
+ bit isMod = 0;
+ bit isRef = 1;
+}
+</pre></div>
+</div>
+<p>This shows that TableGen was able to dig into the argument and extract a piece
+of information that was requested by the designer of the “Value” class. For
+more realistic examples, please see existing users of TableGen, such as the X86
+backend.</p>
+</div>
+<div class="section" id="multiclass-definitions-and-instances">
+<h4><a class="toc-backref" href="#id14">Multiclass definitions and instances</a><a class="headerlink" href="#multiclass-definitions-and-instances" title="Permalink to this headline">¶</a></h4>
+<p>While classes with template arguments are a good way to factor commonality
+between two instances of a definition, multiclasses allow a convenient notation
+for defining multiple definitions at once (instances of implicitly constructed
+classes). For example, consider an 3-address instruction set whose instructions
+come in two forms: “<tt class="docutils literal"><span class="pre">reg</span> <span class="pre">=</span> <span class="pre">reg</span> <span class="pre">op</span> <span class="pre">reg</span></tt>” and “<tt class="docutils literal"><span class="pre">reg</span> <span class="pre">=</span> <span class="pre">reg</span> <span class="pre">op</span> <span class="pre">imm</span></tt>”
+(e.g. SPARC). In this case, you’d like to specify in one place that this
+commonality exists, then in a separate place indicate what all the ops are.</p>
+<p>Here is an example TableGen fragment that shows this idea:</p>
+<div class="highlight-text"><div class="highlight"><pre>def ops;
+def GPR;
+def Imm;
+class inst<int opc, string asmstr, dag operandlist>;
+
+multiclass ri_inst<int opc, string asmstr> {
+ def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+ def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+}
+
+// Instantiations of the ri_inst multiclass.
+defm ADD : ri_inst<0b111, "add">;
+defm SUB : ri_inst<0b101, "sub">;
+defm MUL : ri_inst<0b100, "mul">;
+...
+</pre></div>
+</div>
+<p>The name of the resultant definitions has the multidef fragment names appended
+to them, so this defines <tt class="docutils literal"><span class="pre">ADD_rr</span></tt>, <tt class="docutils literal"><span class="pre">ADD_ri</span></tt>, <tt class="docutils literal"><span class="pre">SUB_rr</span></tt>, etc. A defm may
+inherit from multiple multiclasses, instantiating definitions from each
+multiclass. Using a multiclass this way is exactly equivalent to instantiating
+the classes multiple times yourself, e.g. by writing:</p>
+<div class="highlight-text"><div class="highlight"><pre>def ops;
+def GPR;
+def Imm;
+class inst<int opc, string asmstr, dag operandlist>;
+
+class rrinst<int opc, string asmstr>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+
+class riinst<int opc, string asmstr>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+
+// Instantiations of the ri_inst multiclass.
+def ADD_rr : rrinst<0b111, "add">;
+def ADD_ri : riinst<0b111, "add">;
+def SUB_rr : rrinst<0b101, "sub">;
+def SUB_ri : riinst<0b101, "sub">;
+def MUL_rr : rrinst<0b100, "mul">;
+def MUL_ri : riinst<0b100, "mul">;
+...
+</pre></div>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">defm</span></tt> can also be used inside a multiclass providing several levels of
+multiclass instantiations.</p>
+<div class="highlight-text"><div class="highlight"><pre>class Instruction<bits<4> opc, string Name> {
+ bits<4> opcode = opc;
+ string name = Name;
+}
+
+multiclass basic_r<bits<4> opc> {
+ def rr : Instruction<opc, "rr">;
+ def rm : Instruction<opc, "rm">;
+}
+
+multiclass basic_s<bits<4> opc> {
+ defm SS : basic_r<opc>;
+ defm SD : basic_r<opc>;
+ def X : Instruction<opc, "x">;
+}
+
+multiclass basic_p<bits<4> opc> {
+ defm PS : basic_r<opc>;
+ defm PD : basic_r<opc>;
+ def Y : Instruction<opc, "y">;
+}
+
+defm ADD : basic_s<0xf>, basic_p<0xf>;
+...
+
+// Results
+def ADDPDrm { ...
+def ADDPDrr { ...
+def ADDPSrm { ...
+def ADDPSrr { ...
+def ADDSDrm { ...
+def ADDSDrr { ...
+def ADDY { ...
+def ADDX { ...
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">defm</span></tt> declarations can inherit from classes too, the rule to follow is that
+the class list must start after the last multiclass, and there must be at least
+one multiclass before them.</p>
+<div class="highlight-text"><div class="highlight"><pre>class XD { bits<4> Prefix = 11; }
+class XS { bits<4> Prefix = 12; }
+
+class I<bits<4> op> {
+ bits<4> opcode = op;
+}
+
+multiclass R {
+ def rr : I<4>;
+ def rm : I<2>;
+}
+
+multiclass Y {
+ defm SS : R, XD;
+ defm SD : R, XS;
+}
+
+defm Instr : Y;
+
+// Results
+def InstrSDrm {
+ bits<4> opcode = { 0, 0, 1, 0 };
+ bits<4> Prefix = { 1, 1, 0, 0 };
+}
+...
+def InstrSSrr {
+ bits<4> opcode = { 0, 1, 0, 0 };
+ bits<4> Prefix = { 1, 0, 1, 1 };
+}
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="file-scope-entities">
+<h3><a class="toc-backref" href="#id15">File scope entities</a><a class="headerlink" href="#file-scope-entities" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="file-inclusion">
+<h4><a class="toc-backref" href="#id16">File inclusion</a><a class="headerlink" href="#file-inclusion" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports the ‘<tt class="docutils literal"><span class="pre">include</span></tt>‘ token, which textually substitutes the
+specified file in place of the include directive. The filename should be
+specified as a double quoted string immediately after the ‘<tt class="docutils literal"><span class="pre">include</span></tt>‘ keyword.
+Example:</p>
+<div class="highlight-text"><div class="highlight"><pre>include "foo.td"
+</pre></div>
+</div>
+</div>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id17">‘let’ expressions</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>“Let” expressions at file scope are similar to <a class="reference internal" href="#let-expressions-within-a-record">“let” expressions within a
+record</a>, except they can specify a value binding for multiple records at a
+time, and may be useful in certain other cases. File-scope let expressions are
+really just another way that TableGen allows the end-user to factor out
+commonality from the records.</p>
+<p>File-scope “let” expressions take a comma-separated list of bindings to apply,
+and one or more records to bind the values in. Here are some examples:</p>
+<div class="highlight-text"><div class="highlight"><pre>let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
+ def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
+
+let isCall = 1 in
+ // All calls clobber the non-callee saved registers...
+ let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
+ MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
+ XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
+ def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
+ "call\t${dst:call}", []>;
+ def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
+ "call\t{*}$dst", [(X86call GR32:$dst)]>;
+ def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
+ "call\t{*}$dst", []>;
+ }
+</pre></div>
+</div>
+<p>File-scope “let” expressions are often useful when a couple of definitions need
+to be added to several records, and the records do not otherwise need to be
+opened, as in the case with the <tt class="docutils literal"><span class="pre">CALL*</span></tt> instructions above.</p>
+<p>It’s also possible to use “let” expressions inside multiclasses, providing more
+ways to factor out commonality from the records, specially if using several
+levels of multiclass instantiations. This also avoids the need of using “let”
+expressions within subsequent records inside a multiclass.</p>
+<div class="highlight-text"><div class="highlight"><pre>multiclass basic_r<bits<4> opc> {
+ let Predicates = [HasSSE2] in {
+ def rr : Instruction<opc, "rr">;
+ def rm : Instruction<opc, "rm">;
+ }
+ let Predicates = [HasSSE3] in
+ def rx : Instruction<opc, "rx">;
+}
+
+multiclass basic_ss<bits<4> opc> {
+ let IsDouble = 0 in
+ defm SS : basic_r<opc>;
+
+ let IsDouble = 1 in
+ defm SD : basic_r<opc>;
+}
+
+defm ADD : basic_ss<0xf>;
+</pre></div>
+</div>
+</div>
+<div class="section" id="looping">
+<h4><a class="toc-backref" href="#id18">Looping</a><a class="headerlink" href="#looping" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports the ‘<tt class="docutils literal"><span class="pre">foreach</span></tt>‘ block, which textually replicates the loop
+body, substituting iterator values for iterator references in the body.
+Example:</p>
+<div class="highlight-text"><div class="highlight"><pre>foreach i = [0, 1, 2, 3] in {
+ def R#i : Register<...>;
+ def F#i : Register<...>;
+}
+</pre></div>
+</div>
+<p>This will create objects <tt class="docutils literal"><span class="pre">R0</span></tt>, <tt class="docutils literal"><span class="pre">R1</span></tt>, <tt class="docutils literal"><span class="pre">R2</span></tt> and <tt class="docutils literal"><span class="pre">R3</span></tt>. <tt class="docutils literal"><span class="pre">foreach</span></tt> blocks
+may be nested. If there is only one item in the body the braces may be
+elided:</p>
+<div class="highlight-text"><div class="highlight"><pre>foreach i = [0, 1, 2, 3] in
+ def R#i : Register<...>;
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="code-generator-backend-info">
+<h2><a class="toc-backref" href="#id19">Code Generator backend info</a><a class="headerlink" href="#code-generator-backend-info" title="Permalink to this headline">¶</a></h2>
+<p>Expressions used by code generator to describe instructions and isel patterns:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">(implicit</span> <span class="pre">a)</span></tt></dt>
+<dd>an implicitly defined physical register. This tells the dag instruction
+selection emitter the input pattern’s extra definitions matches implicit
+physical register definitions.</dd>
+</dl>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Deficiencies.html" title="TableGen Deficiencies"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LangRef.html" title="TableGen Language Reference"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >TableGen</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TableGen/LangRef.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TableGen/LangRef.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TableGen/LangRef.html (added)
+++ www-releases/trunk/3.9.1/docs/TableGen/LangRef.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,447 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Language Reference — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="../index.html" />
+ <link rel="up" title="TableGen" href="index.html" />
+ <link rel="next" title="TableGen Language Introduction" href="LangIntro.html" />
+ <link rel="prev" title="TableGen BackEnds" href="BackEnds.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LangIntro.html" title="TableGen Language Introduction"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="BackEnds.html" title="TableGen BackEnds"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">TableGen</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-language-reference">
+<h1>TableGen Language Reference<a class="headerlink" href="#tablegen-language-reference" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id10">Introduction</a></li>
+<li><a class="reference internal" href="#notation" id="id11">Notation</a></li>
+<li><a class="reference internal" href="#lexical-analysis" id="id12">Lexical Analysis</a></li>
+<li><a class="reference internal" href="#syntax" id="id13">Syntax</a><ul>
+<li><a class="reference internal" href="#classes" id="id14"><tt class="docutils literal"><span class="pre">class</span></tt>es</a></li>
+<li><a class="reference internal" href="#declarations" id="id15">Declarations</a></li>
+<li><a class="reference internal" href="#types" id="id16">Types</a></li>
+<li><a class="reference internal" href="#values" id="id17">Values</a></li>
+<li><a class="reference internal" href="#bodies" id="id18">Bodies</a></li>
+<li><a class="reference internal" href="#def" id="id19"><tt class="docutils literal"><span class="pre">def</span></tt></a></li>
+<li><a class="reference internal" href="#defm" id="id20"><tt class="docutils literal"><span class="pre">defm</span></tt></a></li>
+<li><a class="reference internal" href="#foreach" id="id21"><tt class="docutils literal"><span class="pre">foreach</span></tt></a></li>
+<li><a class="reference internal" href="#top-level-let" id="id22">Top-Level <tt class="docutils literal"><span class="pre">let</span></tt></a></li>
+<li><a class="reference internal" href="#multiclass" id="id23"><tt class="docutils literal"><span class="pre">multiclass</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is extremely rough. If you find something lacking, please
+fix it, file a documentation bug, or ask about it on llvm-dev.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id10">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is meant to be a normative spec about the TableGen language
+in and of itself (i.e. how to understand a given construct in terms of how
+it affects the final set of records represented by the TableGen file). If
+you are unsure if this document is really what you are looking for, please
+read the <a class="reference internal" href="index.html"><em>introduction to TableGen</em></a> first.</p>
+</div>
+<div class="section" id="notation">
+<h2><a class="toc-backref" href="#id11">Notation</a><a class="headerlink" href="#notation" title="Permalink to this headline">¶</a></h2>
+<p>The lexical and syntax notation used here is intended to imitate
+<a class="reference external" href="http://docs.python.org/py3k/reference/introduction.html#notation">Python’s</a>. In particular, for lexical definitions, the productions
+operate at the character level and there is no implied whitespace between
+elements. The syntax definitions operate at the token level, so there is
+implied whitespace between tokens.</p>
+</div>
+<div class="section" id="lexical-analysis">
+<h2><a class="toc-backref" href="#id12">Lexical Analysis</a><a class="headerlink" href="#lexical-analysis" title="Permalink to this headline">¶</a></h2>
+<p>TableGen supports BCPL (<tt class="docutils literal"><span class="pre">//</span> <span class="pre">...</span></tt>) and nestable C-style (<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">...</span> <span class="pre">*/</span></tt>)
+comments.</p>
+<p>The following is a listing of the basic punctuation tokens:</p>
+<div class="highlight-python"><div class="highlight"><pre>- + [ ] { } ( ) < > : ; . = ? #
+</pre></div>
+</div>
+<p>Numeric literals take one of the following forms:</p>
+<pre>
+<strong id="grammar-token-TokInteger">TokInteger </strong> ::= <a class="reference internal" href="#grammar-token-DecimalInteger"><tt class="xref docutils literal"><span class="pre">DecimalInteger</span></tt></a> | <a class="reference internal" href="#grammar-token-HexInteger"><tt class="xref docutils literal"><span class="pre">HexInteger</span></tt></a> | <a class="reference internal" href="#grammar-token-BinInteger"><tt class="xref docutils literal"><span class="pre">BinInteger</span></tt></a>
+<strong id="grammar-token-DecimalInteger">DecimalInteger</strong> ::= ["+" | "-"] ("0"..."9")+
+<strong id="grammar-token-HexInteger">HexInteger </strong> ::= "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
+<strong id="grammar-token-BinInteger">BinInteger </strong> ::= "0b" ("0" | "1")+
+</pre>
+<p>One aspect to note is that the <a class="reference internal" href="#grammar-token-DecimalInteger"><tt class="xref std std-token docutils literal"><span class="pre">DecimalInteger</span></tt></a> token <em>includes</em> the
+<tt class="docutils literal"><span class="pre">+</span></tt> or <tt class="docutils literal"><span class="pre">-</span></tt>, as opposed to having <tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">-</span></tt> be unary operators as
+most languages do.</p>
+<p>Also note that <a class="reference internal" href="#grammar-token-BinInteger"><tt class="xref std std-token docutils literal"><span class="pre">BinInteger</span></tt></a> creates a value of type <tt class="docutils literal"><span class="pre">bits<n></span></tt>
+(where <tt class="docutils literal"><span class="pre">n</span></tt> is the number of bits). This will implicitly convert to
+integers when needed.</p>
+<p>TableGen has identifier-like tokens:</p>
+<pre>
+<strong id="grammar-token-ualpha">ualpha </strong> ::= "a"..."z" | "A"..."Z" | "_"
+<strong id="grammar-token-TokIdentifier">TokIdentifier</strong> ::= ("0"..."9")* <a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> (<a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> | "0"..."9")*
+<strong id="grammar-token-TokVarName">TokVarName </strong> ::= "$" <a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> (<a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> | "0"..."9")*
+</pre>
+<p>Note that unlike most languages, TableGen allows <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref std std-token docutils literal"><span class="pre">TokIdentifier</span></tt></a> to
+begin with a number. In case of ambiguity, a token will be interpreted as a
+numeric literal rather than an identifier.</p>
+<p>TableGen also has two string-like literals:</p>
+<pre>
+<strong id="grammar-token-TokString">TokString </strong> ::= '"' <non-'"' characters and C-like escapes> '"'
+<strong id="grammar-token-TokCodeFragment">TokCodeFragment</strong> ::= "[{" <shortest text not containing "}]"> "}]"
+</pre>
+<p><a class="reference internal" href="#grammar-token-TokCodeFragment"><tt class="xref std std-token docutils literal"><span class="pre">TokCodeFragment</span></tt></a> is essentially a multiline string literal
+delimited by <tt class="docutils literal"><span class="pre">[{</span></tt> and <tt class="docutils literal"><span class="pre">}]</span></tt>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>The current implementation accepts the following C-like escapes:</p>
+<div class="last highlight-python"><div class="highlight"><pre>\\ \' \" \t \n
+</pre></div>
+</div>
+</div>
+<p>TableGen also has the following keywords:</p>
+<div class="highlight-python"><div class="highlight"><pre>bit bits class code dag
+def foreach defm field in
+int let list multiclass string
+</pre></div>
+</div>
+<p>TableGen also has “bang operators” which have a
+wide variety of meanings:</p>
+<pre>
+<strong id="grammar-token-BangOperator">BangOperator</strong> ::= one of
+ !eq !if !head !tail !con
+ !add !shl !sra !srl !and
+ !cast !empty !subst !foreach !listconcat !strconcat
+</pre>
+</div>
+<div class="section" id="syntax">
+<h2><a class="toc-backref" href="#id13">Syntax</a><a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
+<p>TableGen has an <tt class="docutils literal"><span class="pre">include</span></tt> mechanism. It does not play a role in the
+syntax per se, since it is lexically replaced with the contents of the
+included file.</p>
+<pre>
+<strong id="grammar-token-IncludeDirective">IncludeDirective</strong> ::= "include" <a class="reference internal" href="#grammar-token-TokString"><tt class="xref docutils literal"><span class="pre">TokString</span></tt></a>
+</pre>
+<p>TableGen’s top-level production consists of “objects”.</p>
+<pre>
+<strong id="grammar-token-TableGenFile">TableGenFile</strong> ::= <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>*
+<strong id="grammar-token-Object">Object </strong> ::= <a class="reference internal" href="#grammar-token-Class"><tt class="xref docutils literal"><span class="pre">Class</span></tt></a> | <a class="reference internal" href="#grammar-token-Def"><tt class="xref docutils literal"><span class="pre">Def</span></tt></a> | <a class="reference internal" href="#grammar-token-Defm"><tt class="xref docutils literal"><span class="pre">Defm</span></tt></a> | <a class="reference internal" href="#grammar-token-Let"><tt class="xref docutils literal"><span class="pre">Let</span></tt></a> | <a class="reference internal" href="#grammar-token-MultiClass"><tt class="xref docutils literal"><span class="pre">MultiClass</span></tt></a> | <a class="reference internal" href="#grammar-token-Foreach"><tt class="xref docutils literal"><span class="pre">Foreach</span></tt></a>
+</pre>
+<div class="section" id="classes">
+<h3><a class="toc-backref" href="#id14"><tt class="docutils literal"><span class="pre">class</span></tt>es</a><a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Class">Class</strong> ::= "class" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref docutils literal"><span class="pre">TemplateArgList</span></tt></a>] <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref docutils literal"><span class="pre">ObjectBody</span></tt></a>
+</pre>
+<p>A <tt class="docutils literal"><span class="pre">class</span></tt> declaration creates a record which other records can inherit
+from. A class can be parametrized by a list of “template arguments”, whose
+values can be used in the class body.</p>
+<p>A given class can only be defined once. A <tt class="docutils literal"><span class="pre">class</span></tt> declaration is
+considered to define the class if any of the following is true:</p>
+<ol class="arabic simple">
+<li>The <a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref std std-token docutils literal"><span class="pre">TemplateArgList</span></tt></a> is present.</li>
+<li>The <a class="reference internal" href="#grammar-token-Body"><tt class="xref std std-token docutils literal"><span class="pre">Body</span></tt></a> in the <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a> is present and is not empty.</li>
+<li>The <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a> in the <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a> is present.</li>
+</ol>
+<p>You can declare an empty class by giving and empty <a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref std std-token docutils literal"><span class="pre">TemplateArgList</span></tt></a>
+and an empty <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a>. This can serve as a restricted form of
+forward declaration: note that records deriving from the forward-declared
+class will inherit no fields from it since the record expansion is done
+when the record is parsed.</p>
+<pre>
+<strong id="grammar-token-TemplateArgList">TemplateArgList</strong> ::= "<" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> ("," <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a>)* ">"
+</pre>
+</div>
+<div class="section" id="declarations">
+<h3><a class="toc-backref" href="#id15">Declarations</a><a class="headerlink" href="#declarations" title="Permalink to this headline">¶</a></h3>
+<p>The declaration syntax is pretty much what you would expect as a C++
+programmer.</p>
+<pre>
+<strong id="grammar-token-Declaration">Declaration</strong> ::= <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> ["=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>]
+</pre>
+<p>It assigns the value to the identifier.</p>
+</div>
+<div class="section" id="types">
+<h3><a class="toc-backref" href="#id16">Types</a><a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Type">Type </strong> ::= "string" | "code" | "bit" | "int" | "dag"
+ | "bits" "<" <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> ">"
+ | "list" "<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"
+ | <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a>
+<strong id="grammar-token-ClassID">ClassID</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>Both <tt class="docutils literal"><span class="pre">string</span></tt> and <tt class="docutils literal"><span class="pre">code</span></tt> correspond to the string type; the difference
+is purely to indicate programmer intention.</p>
+<p>The <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref std std-token docutils literal"><span class="pre">ClassID</span></tt></a> must identify a class that has been previously
+declared or defined.</p>
+</div>
+<div class="section" id="values">
+<h3><a class="toc-backref" href="#id17">Values</a><a class="headerlink" href="#values" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Value">Value </strong> ::= <a class="reference internal" href="#grammar-token-SimpleValue"><tt class="xref docutils literal"><span class="pre">SimpleValue</span></tt></a> <a class="reference internal" href="#grammar-token-ValueSuffix"><tt class="xref docutils literal"><span class="pre">ValueSuffix</span></tt></a>*
+<strong id="grammar-token-ValueSuffix">ValueSuffix</strong> ::= "{" <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a> "}"
+ | "[" <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a> "]"
+ | "." <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+<strong id="grammar-token-RangeList">RangeList </strong> ::= <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref docutils literal"><span class="pre">RangePiece</span></tt></a> ("," <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref docutils literal"><span class="pre">RangePiece</span></tt></a>)*
+<strong id="grammar-token-RangePiece">RangePiece </strong> ::= <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+ | <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> "-" <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+ | <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+</pre>
+<p>The peculiar last form of <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref std std-token docutils literal"><span class="pre">RangePiece</span></tt></a> is due to the fact that the
+“<tt class="docutils literal"><span class="pre">-</span></tt>” is included in the <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref std std-token docutils literal"><span class="pre">TokInteger</span></tt></a>, hence <tt class="docutils literal"><span class="pre">1-5</span></tt> gets lexed as
+two consecutive <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref std std-token docutils literal"><span class="pre">TokInteger</span></tt></a>‘s, with values <tt class="docutils literal"><span class="pre">1</span></tt> and <tt class="docutils literal"><span class="pre">-5</span></tt>,
+instead of “1”, “-”, and “5”.
+The <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref std std-token docutils literal"><span class="pre">RangeList</span></tt></a> can be thought of as specifying “list slice” in some
+contexts.</p>
+<p><a class="reference internal" href="#grammar-token-SimpleValue"><tt class="xref std std-token docutils literal"><span class="pre">SimpleValue</span></tt></a> has a number of forms:</p>
+<pre>
+<strong id="grammar-token-SimpleValue">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>The value will be the variable referenced by the identifier. It can be one
+of:</p>
+<ul>
+<li><p class="first">name of a <tt class="docutils literal"><span class="pre">def</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>def Bar : SomeClass {
+ int X = 5;
+}
+
+def Foo {
+ SomeClass Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+<li><p class="first">value local to a <tt class="docutils literal"><span class="pre">def</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>def Foo {
+ int Bar = 5;
+ int Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+<li><p class="first">a template arg of a <tt class="docutils literal"><span class="pre">class</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>class Foo<int Bar> {
+ int Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+<li><p class="first">value local to a <tt class="docutils literal"><span class="pre">multiclass</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>multiclass Foo {
+ int Bar = 5;
+ int Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+<li><p class="first">a template arg to a <tt class="docutils literal"><span class="pre">multiclass</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><div class="highlight"><pre>multiclass Foo<int Bar> {
+ int Baz = Bar;
+}
+</pre></div>
+</div>
+</li>
+</ul>
+<pre>
+<strong id="id1">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+</pre>
+<p>This represents the numeric value of the integer.</p>
+<pre>
+<strong id="id2">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokString"><tt class="xref docutils literal"><span class="pre">TokString</span></tt></a>+
+</pre>
+<p>Multiple adjacent string literals are concatenated like in C/C++. The value
+is the concatenation of the strings.</p>
+<pre>
+<strong id="id3">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokCodeFragment"><tt class="xref docutils literal"><span class="pre">TokCodeFragment</span></tt></a>
+</pre>
+<p>The value is the string value of the code fragment.</p>
+<pre>
+<strong id="id4">SimpleValue</strong> ::= "?"
+</pre>
+<p><tt class="docutils literal"><span class="pre">?</span></tt> represents an “unset” initializer.</p>
+<pre>
+<strong id="id5">SimpleValue</strong> ::= "{" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> "}"
+<strong id="grammar-token-ValueList">ValueList </strong> ::= [<a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a>]
+<strong id="grammar-token-ValueListNE">ValueListNE</strong> ::= <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> ("," <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>)*
+</pre>
+<p>This represents a sequence of bits, as would be used to initialize a
+<tt class="docutils literal"><span class="pre">bits<n></span></tt> field (where <tt class="docutils literal"><span class="pre">n</span></tt> is the number of bits).</p>
+<pre>
+<strong id="id6">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a> "<" <a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a> ">"
+</pre>
+<p>This generates a new anonymous record definition (as would be created by an
+unnamed <tt class="docutils literal"><span class="pre">def</span></tt> inheriting from the given class with the given template
+arguments) and the value is the value of that record definition.</p>
+<pre>
+<strong id="id7">SimpleValue</strong> ::= "[" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> "]" ["<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"]
+</pre>
+<p>A list initializer. The optional <a class="reference internal" href="#grammar-token-Type"><tt class="xref std std-token docutils literal"><span class="pre">Type</span></tt></a> can be used to indicate a
+specific element type, otherwise the element type will be deduced from the
+given values.</p>
+<pre>
+<strong id="id8">SimpleValue</strong> ::= "(" <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a> <a class="reference internal" href="#grammar-token-DagArgList"><tt class="xref docutils literal"><span class="pre">DagArgList</span></tt></a> ")"
+<strong id="grammar-token-DagArgList">DagArgList </strong> ::= <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a> ("," <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a>)*
+<strong id="grammar-token-DagArg">DagArg </strong> ::= <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> [":" <a class="reference internal" href="#grammar-token-TokVarName"><tt class="xref docutils literal"><span class="pre">TokVarName</span></tt></a>] | <a class="reference internal" href="#grammar-token-TokVarName"><tt class="xref docutils literal"><span class="pre">TokVarName</span></tt></a>
+</pre>
+<p>The initial <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref std std-token docutils literal"><span class="pre">DagArg</span></tt></a> is called the “operator” of the dag.</p>
+<pre>
+<strong id="id9">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-BangOperator"><tt class="xref docutils literal"><span class="pre">BangOperator</span></tt></a> ["<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"] "(" <a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a> ")"
+</pre>
+</div>
+<div class="section" id="bodies">
+<h3><a class="toc-backref" href="#id18">Bodies</a><a class="headerlink" href="#bodies" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-ObjectBody">ObjectBody </strong> ::= <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref docutils literal"><span class="pre">BaseClassList</span></tt></a> <a class="reference internal" href="#grammar-token-Body"><tt class="xref docutils literal"><span class="pre">Body</span></tt></a>
+<strong id="grammar-token-BaseClassList">BaseClassList </strong> ::= [":" <a class="reference internal" href="#grammar-token-BaseClassListNE"><tt class="xref docutils literal"><span class="pre">BaseClassListNE</span></tt></a>]
+<strong id="grammar-token-BaseClassListNE">BaseClassListNE</strong> ::= <a class="reference internal" href="#grammar-token-SubClassRef"><tt class="xref docutils literal"><span class="pre">SubClassRef</span></tt></a> ("," <a class="reference internal" href="#grammar-token-SubClassRef"><tt class="xref docutils literal"><span class="pre">SubClassRef</span></tt></a>)*
+<strong id="grammar-token-SubClassRef">SubClassRef </strong> ::= (<a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a> | <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a>) ["<" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> ">"]
+<strong id="grammar-token-DefmID">DefmID </strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>The version with the <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref std std-token docutils literal"><span class="pre">MultiClassID</span></tt></a> is only valid in the
+<a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a> of a <tt class="docutils literal"><span class="pre">defm</span></tt>.
+The <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref std std-token docutils literal"><span class="pre">MultiClassID</span></tt></a> should be the name of a <tt class="docutils literal"><span class="pre">multiclass</span></tt>.</p>
+<p>It is after parsing the base class list that the “let stack” is applied.</p>
+<pre>
+<strong id="grammar-token-Body">Body </strong> ::= ";" | "{" BodyList "}"
+<strong id="grammar-token-BodyList">BodyList</strong> ::= BodyItem*
+<strong id="grammar-token-BodyItem">BodyItem</strong> ::= <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> ";"
+ | "let" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a>] "=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> ";"
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">let</span></tt> form allows overriding the value of an inherited field.</p>
+</div>
+<div class="section" id="def">
+<h3><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">def</span></tt></a><a class="headerlink" href="#def" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Def">Def</strong> ::= "def" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref docutils literal"><span class="pre">ObjectBody</span></tt></a>
+</pre>
+<p>Defines a record whose name is given by the <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref std std-token docutils literal"><span class="pre">TokIdentifier</span></tt></a>. The
+fields of the record are inherited from the base classes and defined in the
+body.</p>
+<p>Special handling occurs if this <tt class="docutils literal"><span class="pre">def</span></tt> appears inside a <tt class="docutils literal"><span class="pre">multiclass</span></tt> or
+a <tt class="docutils literal"><span class="pre">foreach</span></tt>.</p>
+</div>
+<div class="section" id="defm">
+<h3><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">defm</span></tt></a><a class="headerlink" href="#defm" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Defm">Defm</strong> ::= "defm" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> ":" <a class="reference internal" href="#grammar-token-BaseClassListNE"><tt class="xref docutils literal"><span class="pre">BaseClassListNE</span></tt></a> ";"
+</pre>
+<p>Note that in the <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a>, all of the <tt class="docutils literal"><span class="pre">multiclass</span></tt>‘s must
+precede any <tt class="docutils literal"><span class="pre">class</span></tt>‘s that appear.</p>
+</div>
+<div class="section" id="foreach">
+<h3><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">foreach</span></tt></a><a class="headerlink" href="#foreach" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Foreach">Foreach</strong> ::= "foreach" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> "in" "{" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>* "}"
+ | "foreach" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> "in" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>
+</pre>
+<p>The value assigned to the variable in the declaration is iterated over and
+the object or object list is reevaluated with the variable set at each
+iterated value.</p>
+</div>
+<div class="section" id="top-level-let">
+<h3><a class="toc-backref" href="#id22">Top-Level <tt class="docutils literal"><span class="pre">let</span></tt></a><a class="headerlink" href="#top-level-let" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Let">Let </strong> ::= "let" <a class="reference internal" href="#grammar-token-LetList"><tt class="xref docutils literal"><span class="pre">LetList</span></tt></a> "in" "{" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>* "}"
+ | "let" <a class="reference internal" href="#grammar-token-LetList"><tt class="xref docutils literal"><span class="pre">LetList</span></tt></a> "in" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>
+<strong id="grammar-token-LetList">LetList</strong> ::= <a class="reference internal" href="#grammar-token-LetItem"><tt class="xref docutils literal"><span class="pre">LetItem</span></tt></a> ("," <a class="reference internal" href="#grammar-token-LetItem"><tt class="xref docutils literal"><span class="pre">LetItem</span></tt></a>)*
+<strong id="grammar-token-LetItem">LetItem</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a>] "=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>
+</pre>
+<p>This is effectively equivalent to <tt class="docutils literal"><span class="pre">let</span></tt> inside the body of a record
+except that it applies to multiple records at a time. The bindings are
+applied at the end of parsing the base classes of a record.</p>
+</div>
+<div class="section" id="multiclass">
+<h3><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">multiclass</span></tt></a><a class="headerlink" href="#multiclass" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-MultiClass">MultiClass </strong> ::= "multiclass" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref docutils literal"><span class="pre">TemplateArgList</span></tt></a>]
+ [":" <a class="reference internal" href="#grammar-token-BaseMultiClassList"><tt class="xref docutils literal"><span class="pre">BaseMultiClassList</span></tt></a>] "{" <a class="reference internal" href="#grammar-token-MultiClassObject"><tt class="xref docutils literal"><span class="pre">MultiClassObject</span></tt></a>+ "}"
+<strong id="grammar-token-BaseMultiClassList">BaseMultiClassList</strong> ::= <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a> ("," <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a>)*
+<strong id="grammar-token-MultiClassID">MultiClassID </strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+<strong id="grammar-token-MultiClassObject">MultiClassObject </strong> ::= <a class="reference internal" href="#grammar-token-Def"><tt class="xref docutils literal"><span class="pre">Def</span></tt></a> | <a class="reference internal" href="#grammar-token-Defm"><tt class="xref docutils literal"><span class="pre">Defm</span></tt></a> | <a class="reference internal" href="#grammar-token-Let"><tt class="xref docutils literal"><span class="pre">Let</span></tt></a> | <a class="reference internal" href="#grammar-token-Foreach"><tt class="xref docutils literal"><span class="pre">Foreach</span></tt></a>
+</pre>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LangIntro.html" title="TableGen Language Introduction"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="BackEnds.html" title="TableGen BackEnds"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >TableGen</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TableGen/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TableGen/index.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TableGen/index.html (added)
+++ www-releases/trunk/3.9.1/docs/TableGen/index.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,365 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="../index.html" />
+ <link rel="next" title="TableGen BackEnds" href="BackEnds.html" />
+ <link rel="prev" title="TableGen Fundamentals" href="../TableGenFundamentals.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="BackEnds.html" title="TableGen BackEnds"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../TableGenFundamentals.html" title="TableGen Fundamentals"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen">
+<h1>TableGen<a class="headerlink" href="#tablegen" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>
+<li><a class="reference internal" href="#the-tablegen-program" id="id4">The TableGen program</a><ul>
+<li><a class="reference internal" href="#running-tablegen" id="id5">Running TableGen</a></li>
+<li><a class="reference internal" href="#example" id="id6">Example</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#syntax" id="id7">Syntax</a><ul>
+<li><a class="reference internal" href="#basic-concepts" id="id8">Basic concepts</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tablegen-backends" id="id9">TableGen backends</a></li>
+<li><a class="reference internal" href="#tablegen-deficiencies" id="id10">TableGen Deficiencies</a></li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>TableGen’s purpose is to help a human develop and maintain records of
+domain-specific information. Because there may be a large number of these
+records, it is specifically designed to allow writing flexible descriptions and
+for common features of these records to be factored out. This reduces the
+amount of duplication in the description, reduces the chance of error, and makes
+it easier to structure domain specific information.</p>
+<p>The core part of TableGen parses a file, instantiates the declarations, and
+hands the result off to a domain-specific <a class="reference internal" href="#backend">backend</a> for processing.</p>
+<p>The current major users of TableGen are <a class="reference internal" href="../CodeGenerator.html"><em>The LLVM Target-Independent Code Generator</em></a>
+and the
+<a class="reference external" href="http://clang.llvm.org/docs/UsersManual.html#controlling-errors-and-warnings">Clang diagnostics and attributes</a>.</p>
+<p>Note that if you work on TableGen much, and use emacs or vim, that you can find
+an emacs “TableGen mode” and a vim language file in the <tt class="docutils literal"><span class="pre">llvm/utils/emacs</span></tt> and
+<tt class="docutils literal"><span class="pre">llvm/utils/vim</span></tt> directories of your LLVM distribution, respectively.</p>
+</div>
+<div class="section" id="the-tablegen-program">
+<span id="intro"></span><h2><a class="toc-backref" href="#id4">The TableGen program</a><a class="headerlink" href="#the-tablegen-program" title="Permalink to this headline">¶</a></h2>
+<p>TableGen files are interpreted by the TableGen program: <cite>llvm-tblgen</cite> available
+on your build directory under <cite>bin</cite>. It is not installed in the system (or where
+your sysroot is set to), since it has no use beyond LLVM’s build process.</p>
+<div class="section" id="running-tablegen">
+<h3><a class="toc-backref" href="#id5">Running TableGen</a><a class="headerlink" href="#running-tablegen" title="Permalink to this headline">¶</a></h3>
+<p>TableGen runs just like any other LLVM tool. The first (optional) argument
+specifies the file to read. If a filename is not specified, <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt>
+reads from standard input.</p>
+<p>To be useful, one of the <a class="reference internal" href="#backends">backends</a> must be used. These backends are
+selectable on the command line (type ‘<tt class="docutils literal"><span class="pre">llvm-tblgen</span> <span class="pre">-help</span></tt>‘ for a list). For
+example, to get a list of all of the definitions that subclass a particular type
+(which can be useful for building up an enum list of these records), use the
+<tt class="docutils literal"><span class="pre">-print-enums</span></tt> option:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>llvm-tblgen X86.td -print-enums -class<span class="o">=</span>Register
+AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
+ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
+MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
+R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
+R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
+RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
+XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
+XMM6, XMM7, XMM8, XMM9,
+
+<span class="nv">$ </span>llvm-tblgen X86.td -print-enums -class<span class="o">=</span>Instruction
+ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
+ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
+ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
+ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
+ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
+</pre></div>
+</div>
+<p>The default backend prints out all of the records.</p>
+<p>If you plan to use TableGen, you will most likely have to write a <a class="reference internal" href="#backend">backend</a>
+that extracts the information specific to what you need and formats it in the
+appropriate way.</p>
+</div>
+<div class="section" id="example">
+<h3><a class="toc-backref" href="#id6">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>With no other arguments, <cite>llvm-tblgen</cite> parses the specified file and prints out all
+of the classes, then all of the definitions. This is a good way to see what the
+various definitions expand to fully. Running this on the <tt class="docutils literal"><span class="pre">X86.td</span></tt> file prints
+this (at the time of this writing):</p>
+<div class="highlight-text"><div class="highlight"><pre>...
+def ADD32rr { // Instruction X86Inst I
+ string Namespace = "X86";
+ dag OutOperandList = (outs GR32:$dst);
+ dag InOperandList = (ins GR32:$src1, GR32:$src2);
+ string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
+ list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
+ list<Register> Uses = [];
+ list<Register> Defs = [EFLAGS];
+ list<Predicate> Predicates = [];
+ int CodeSize = 3;
+ int AddedComplexity = 0;
+ bit isReturn = 0;
+ bit isBranch = 0;
+ bit isIndirectBranch = 0;
+ bit isBarrier = 0;
+ bit isCall = 0;
+ bit canFoldAsLoad = 0;
+ bit mayLoad = 0;
+ bit mayStore = 0;
+ bit isImplicitDef = 0;
+ bit isConvertibleToThreeAddress = 1;
+ bit isCommutable = 1;
+ bit isTerminator = 0;
+ bit isReMaterializable = 0;
+ bit isPredicable = 0;
+ bit hasDelaySlot = 0;
+ bit usesCustomInserter = 0;
+ bit hasCtrlDep = 0;
+ bit isNotDuplicable = 0;
+ bit hasSideEffects = 0;
+ InstrItinClass Itinerary = NoItinerary;
+ string Constraints = "";
+ string DisableEncoding = "";
+ bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
+ Format Form = MRMDestReg;
+ bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
+ ImmType ImmT = NoImm;
+ bits<3> ImmTypeBits = { 0, 0, 0 };
+ bit hasOpSizePrefix = 0;
+ bit hasAdSizePrefix = 0;
+ bits<4> Prefix = { 0, 0, 0, 0 };
+ bit hasREX_WPrefix = 0;
+ FPFormat FPForm = ?;
+ bits<3> FPFormBits = { 0, 0, 0 };
+}
+...
+</pre></div>
+</div>
+<p>This definition corresponds to the 32-bit register-register <tt class="docutils literal"><span class="pre">add</span></tt> instruction
+of the x86 architecture. <tt class="docutils literal"><span class="pre">def</span> <span class="pre">ADD32rr</span></tt> defines a record named
+<tt class="docutils literal"><span class="pre">ADD32rr</span></tt>, and the comment at the end of the line indicates the superclasses
+of the definition. The body of the record contains all of the data that
+TableGen assembled for the record, indicating that the instruction is part of
+the “X86” namespace, the pattern indicating how the instruction is selected by
+the code generator, that it is a two-address instruction, has a particular
+encoding, etc. The contents and semantics of the information in the record are
+specific to the needs of the X86 backend, and are only shown as an example.</p>
+<p>As you can see, a lot of information is needed for every instruction supported
+by the code generator, and specifying it all manually would be unmaintainable,
+prone to bugs, and tiring to do in the first place. Because we are using
+TableGen, all of the information was derived from the following definition:</p>
+<div class="highlight-text"><div class="highlight"><pre>let Defs = [EFLAGS],
+ isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
+ isConvertibleToThreeAddress = 1 in // Can transform into LEA.
+def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
+ (ins GR32:$src1, GR32:$src2),
+ "add{l}\t{$src2, $dst|$dst, $src2}",
+ [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
+</pre></div>
+</div>
+<p>This definition makes use of the custom class <tt class="docutils literal"><span class="pre">I</span></tt> (extended from the custom
+class <tt class="docutils literal"><span class="pre">X86Inst</span></tt>), which is defined in the X86-specific TableGen file, to
+factor out the common features that instructions of its class share. A key
+feature of TableGen is that it allows the end-user to define the abstractions
+they prefer to use when describing their information.</p>
+<p>Each <tt class="docutils literal"><span class="pre">def</span></tt> record has a special entry called “NAME”. This is the name of the
+record (“<tt class="docutils literal"><span class="pre">ADD32rr</span></tt>” above). In the general case <tt class="docutils literal"><span class="pre">def</span></tt> names can be formed
+from various kinds of string processing expressions and <tt class="docutils literal"><span class="pre">NAME</span></tt> resolves to the
+final value obtained after resolving all of those expressions. The user may
+refer to <tt class="docutils literal"><span class="pre">NAME</span></tt> anywhere she desires to use the ultimate name of the <tt class="docutils literal"><span class="pre">def</span></tt>.
+<tt class="docutils literal"><span class="pre">NAME</span></tt> should not be defined anywhere else in user code to avoid conflicts.</p>
+</div>
+</div>
+<div class="section" id="syntax">
+<h2><a class="toc-backref" href="#id7">Syntax</a><a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
+<p>TableGen has a syntax that is loosely based on C++ templates, with built-in
+types and specification. In addition, TableGen’s syntax introduces some
+automation concepts like multiclass, foreach, let, etc.</p>
+<div class="section" id="basic-concepts">
+<h3><a class="toc-backref" href="#id8">Basic concepts</a><a class="headerlink" href="#basic-concepts" title="Permalink to this headline">¶</a></h3>
+<p>TableGen files consist of two key parts: ‘classes’ and ‘definitions’, both of
+which are considered ‘records’.</p>
+<p><strong>TableGen records</strong> have a unique name, a list of values, and a list of
+superclasses. The list of values is the main data that TableGen builds for each
+record; it is this that holds the domain specific information for the
+application. The interpretation of this data is left to a specific <a class="reference internal" href="#backend">backend</a>,
+but the structure and format rules are taken care of and are fixed by
+TableGen.</p>
+<p><strong>TableGen definitions</strong> are the concrete form of ‘records’. These generally do
+not have any undefined values, and are marked with the ‘<tt class="docutils literal"><span class="pre">def</span></tt>‘ keyword.</p>
+<div class="highlight-text"><div class="highlight"><pre>def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true",
+ "Enable ARMv8 FP">;
+</pre></div>
+</div>
+<p>In this example, FeatureFPARMv8 is <tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> record initialised
+with some values. The names of the classes are defined via the
+keyword <cite>class</cite> either on the same file or some other included. Most target
+TableGen files include the generic ones in <tt class="docutils literal"><span class="pre">include/llvm/Target</span></tt>.</p>
+<p><strong>TableGen classes</strong> are abstract records that are used to build and describe
+other records. These classes allow the end-user to build abstractions for
+either the domain they are targeting (such as “Register”, “RegisterClass”, and
+“Instruction” in the LLVM code generator) or for the implementor to help factor
+out common properties of records (such as “FPInst”, which is used to represent
+floating point instructions in the X86 backend). TableGen keeps track of all of
+the classes that are used to build up a definition, so the backend can find all
+definitions of a particular class, such as “Instruction”.</p>
+<div class="highlight-text"><div class="highlight"><pre>class ProcNoItin<string Name, list<SubtargetFeature> Features>
+ : Processor<Name, NoItineraries, Features>;
+</pre></div>
+</div>
+<p>Here, the class ProcNoItin, receiving parameters <cite>Name</cite> of type <cite>string</cite> and
+a list of target features is specializing the class Processor by passing the
+arguments down as well as hard-coding NoItineraries.</p>
+<p><strong>TableGen multiclasses</strong> are groups of abstract records that are instantiated
+all at once. Each instantiation can result in multiple TableGen definitions.
+If a multiclass inherits from another multiclass, the definitions in the
+sub-multiclass become part of the current multiclass, as if they were declared
+in the current multiclass.</p>
+<div class="highlight-text"><div class="highlight"><pre>multiclass ro_signed_pats<string T, string Rm, dag Base, dag Offset, dag Extend,
+ dag address, ValueType sty> {
+def : Pat<(i32 (!cast<SDNode>("sextload" # sty) address)),
+ (!cast<Instruction>("LDRS" # T # "w_" # Rm # "_RegOffset")
+ Base, Offset, Extend)>;
+
+def : Pat<(i64 (!cast<SDNode>("sextload" # sty) address)),
+ (!cast<Instruction>("LDRS" # T # "x_" # Rm # "_RegOffset")
+ Base, Offset, Extend)>;
+}
+
+defm : ro_signed_pats<"B", Rm, Base, Offset, Extend,
+ !foreach(decls.pattern, address,
+ !subst(SHIFT, imm_eq0, decls.pattern)),
+ i8>;
+</pre></div>
+</div>
+<p>See the <a class="reference internal" href="LangIntro.html"><em>TableGen Language Introduction</em></a> for more generic
+information on the usage of the language, and the
+<a class="reference internal" href="LangRef.html"><em>TableGen Language Reference</em></a> for more in-depth description
+of the formal language specification.</p>
+</div>
+</div>
+<div class="section" id="tablegen-backends">
+<span id="backends"></span><span id="backend"></span><h2><a class="toc-backref" href="#id9">TableGen backends</a><a class="headerlink" href="#tablegen-backends" title="Permalink to this headline">¶</a></h2>
+<p>TableGen files have no real meaning without a back-end. The default operation
+of running <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt> is to print the information in a textual format, but
+that’s only useful for debugging of the TableGen files themselves. The power
+in TableGen is, however, to interpret the source files into an internal
+representation that can be generated into anything you want.</p>
+<p>Current usage of TableGen is to create huge include files with tables that you
+can either include directly (if the output is in the language you’re coding),
+or be used in pre-processing via macros surrounding the include of the file.</p>
+<p>Direct output can be used if the back-end already prints a table in C format
+or if the output is just a list of strings (for error and warning messages).
+Pre-processed output should be used if the same information needs to be used
+in different contexts (like Instruction names), so your back-end should print
+a meta-information list that can be shaped into different compile-time formats.</p>
+<p>See the <a class="reference external" href="BackEnds.html">TableGen BackEnds</a> for more information.</p>
+</div>
+<div class="section" id="tablegen-deficiencies">
+<h2><a class="toc-backref" href="#id10">TableGen Deficiencies</a><a class="headerlink" href="#tablegen-deficiencies" title="Permalink to this headline">¶</a></h2>
+<p>Despite being very generic, TableGen has some deficiencies that have been
+pointed out numerous times. The common theme is that, while TableGen allows
+you to build Domain-Specific-Languages, the final languages that you create
+lack the power of other DSLs, which in turn increase considerably the size
+and complexity of TableGen files.</p>
+<p>At the same time, TableGen allows you to create virtually any meaning of
+the basic concepts via custom-made back-ends, which can pervert the original
+design and make it very hard for newcomers to understand the evil TableGen
+file.</p>
+<p>There are some in favour of extending the semantics even more, but making sure
+back-ends adhere to strict rules. Others are suggesting we should move to less,
+more powerful DSLs designed with specific purposes, or even re-using existing
+DSLs.</p>
+<p>Either way, this is a discussion that will likely span across several years,
+if not decades. You can read more in the <a class="reference external" href="Deficiencies.html">TableGen Deficiencies</a>
+document.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="BackEnds.html" title="TableGen BackEnds"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../TableGenFundamentals.html" title="TableGen Fundamentals"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TableGenFundamentals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TableGenFundamentals.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TableGenFundamentals.html (added)
+++ www-releases/trunk/3.9.1/docs/TableGenFundamentals.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,104 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Fundamentals — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="TableGen" href="TableGen/index.html" />
+ <link rel="prev" title="Segmented Stacks in LLVM" href="SegmentedStacks.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="TableGen/index.html" title="TableGen"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SegmentedStacks.html" title="Segmented Stacks in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-fundamentals">
+<h1>TableGen Fundamentals<a class="headerlink" href="#tablegen-fundamentals" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="moved">
+<h2>Moved<a class="headerlink" href="#moved" title="Permalink to this headline">¶</a></h2>
+<p>The TableGen fundamentals documentation has moved to a directory on its own
+and is now available at <a class="reference internal" href="TableGen/index.html"><em>TableGen</em></a>. Please, change your links to
+that page.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="TableGen/index.html" title="TableGen"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SegmentedStacks.html" title="Segmented Stacks in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TestSuiteMakefileGuide.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TestSuiteMakefileGuide.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TestSuiteMakefileGuide.html (added)
+++ www-releases/trunk/3.9.1/docs/TestSuiteMakefileGuide.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,414 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM test-suite Guide — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="up" title="LLVM Testing Infrastructure Guide" href="TestingGuide.html" />
+ <link rel="next" title="LLVM Tutorial: Table of Contents" href="tutorial/index.html" />
+ <link rel="prev" title="LLVM Testing Infrastructure Guide" href="TestingGuide.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="tutorial/index.html" title="LLVM Tutorial: Table of Contents"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TestingGuide.html" title="LLVM Testing Infrastructure Guide"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ <li><a href="TestingGuide.html" accesskey="U">LLVM Testing Infrastructure Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-test-suite-guide">
+<h1>LLVM test-suite Guide<a class="headerlink" href="#llvm-test-suite-guide" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
+<li><a class="reference internal" href="#test-suite-structure" id="id2">Test suite Structure</a></li>
+<li><a class="reference internal" href="#running-the-test-suite-via-cmake" id="id3">Running the test suite via CMake</a></li>
+<li><a class="reference internal" href="#running-the-test-suite-via-makefiles-deprecated" id="id4">Running the test suite via Makefiles (deprecated)</a><ul>
+<li><a class="reference internal" href="#configuring-external-tests" id="id5">Configuring External Tests</a></li>
+<li><a class="reference internal" href="#running-different-tests" id="id6">Running different tests</a></li>
+<li><a class="reference internal" href="#generating-test-output" id="id7">Generating test output</a></li>
+<li><a class="reference internal" href="#writing-custom-tests-for-the-test-suite" id="id8">Writing custom tests for the test suite</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id1">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the features of the Makefile-based LLVM
+test-suite as well as the cmake based replacement. This way of interacting
+with the test-suite is deprecated in favor of running the test-suite using LNT,
+but may continue to prove useful for some users. See the Testing
+Guide’s <a class="reference internal" href="TestingGuide.html#test-suite-quickstart"><em>test-suite Quickstart</em></a> section for more
+information.</p>
+</div>
+<div class="section" id="test-suite-structure">
+<h2><a class="toc-backref" href="#id2">Test suite Structure</a><a class="headerlink" href="#test-suite-structure" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">test-suite</span></tt> module contains a number of programs that can be
+compiled with LLVM and executed. These programs are compiled using the
+native compiler and various LLVM backends. The output from the program
+compiled with the native compiler is assumed correct; the results from
+the other programs are compared to the native program output and pass if
+they match.</p>
+<p>When executing tests, it is usually a good idea to start out with a
+subset of the available tests or programs. This makes test run times
+smaller at first and later on this is useful to investigate individual
+test failures. To run some test only on a subset of programs, simply
+change directory to the programs you want tested and run <tt class="docutils literal"><span class="pre">gmake</span></tt>
+there. Alternatively, you can run a different test using the <tt class="docutils literal"><span class="pre">TEST</span></tt>
+variable to change what tests or run on the selected programs (see below
+for more info).</p>
+<p>In addition for testing correctness, the <tt class="docutils literal"><span class="pre">test-suite</span></tt> directory also
+performs timing tests of various LLVM optimizations. It also records
+compilation times for the compilers and the JIT. This information can be
+used to compare the effectiveness of LLVM’s optimizations and code
+generation.</p>
+<p><tt class="docutils literal"><span class="pre">test-suite</span></tt> tests are divided into three types of tests: MultiSource,
+SingleSource, and External.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/SingleSource</span></tt></p>
+<p>The SingleSource directory contains test programs that are only a
+single source file in size. These are usually small benchmark
+programs or small programs that calculate a particular value. Several
+such programs are grouped together in each directory.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/MultiSource</span></tt></p>
+<p>The MultiSource directory contains subdirectories which contain
+entire programs with multiple source files. Large benchmarks and
+whole applications go here.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/External</span></tt></p>
+<p>The External directory contains Makefiles for building code that is
+external to (i.e., not distributed with) LLVM. The most prominent
+members of this directory are the SPEC 95 and SPEC 2000 benchmark
+suites. The <tt class="docutils literal"><span class="pre">External</span></tt> directory does not contain these actual
+tests, but only the Makefiles that know how to properly compile these
+programs from somewhere else. The presence and location of these
+external programs is configured by the test-suite <tt class="docutils literal"><span class="pre">configure</span></tt>
+script.</p>
+</li>
+</ul>
+<p>Each tree is then subdivided into several categories, including
+applications, benchmarks, regression tests, code that is strange
+grammatically, etc. These organizations should be relatively self
+explanatory.</p>
+<p>Some tests are known to fail. Some are bugs that we have not fixed yet;
+others are features that we haven’t added yet (or may never add). In the
+regression tests, the result for such tests will be XFAIL (eXpected
+FAILure). In this way, you can tell the difference between an expected
+and unexpected failure.</p>
+<p>The tests in the test suite have no such feature at this time. If the
+test passes, only warnings and other miscellaneous output will be
+generated. If a test fails, a large <program> FAILED message will be
+displayed. This will help you separate benign warnings from actual test
+failures.</p>
+</div>
+<div class="section" id="running-the-test-suite-via-cmake">
+<h2><a class="toc-backref" href="#id3">Running the test suite via CMake</a><a class="headerlink" href="#running-the-test-suite-via-cmake" title="Permalink to this headline">¶</a></h2>
+<p>To run the test suite, you need to use the following steps:</p>
+<ol class="arabic">
+<li><p class="first">The test suite uses the lit test runner to run the test-suite,
+you need to have lit installed first. Check out LLVM and install lit:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
+% <span class="nb">cd </span>llvm/utils/lit
+% sudo python setup.py install <span class="c"># Or without sudo, install in virtual-env.</span>
+running install
+running bdist_egg
+running egg_info
+writing lit.egg-info/PKG-INFO
+...
+% lit --version
+lit 0.5.0dev
+</pre></div>
+</div>
+</li>
+<li><p class="first">Check out the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module with:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% svn co http://llvm.org/svn/llvm-project/test-suite/trunk <span class="nb">test</span>-suite
+</pre></div>
+</div>
+</li>
+<li><p class="first">Use CMake to configure the test suite in a new directory. You cannot build
+the test suite in the source tree.</p>
+<div class="highlight-bash"><div class="highlight"><pre>% mkdir <span class="nb">test</span>-suite-build
+% <span class="nb">cd test</span>-suite-build
+% cmake ../test-suite
+</pre></div>
+</div>
+</li>
+<li><p class="first">Build the benchmarks, using the makefiles CMake generated.</p>
+</li>
+</ol>
+<div class="highlight-bash"><div class="highlight"><pre>% make
+Scanning dependencies of target timeit-target
+<span class="o">[</span> 0%<span class="o">]</span> Building C object tools/CMakeFiles/timeit-target.dir/timeit.c.o
+<span class="o">[</span> 0%<span class="o">]</span> Linking C executable timeit-target
+<span class="o">[</span> 0%<span class="o">]</span> Built target timeit-target
+Scanning dependencies of target fpcmp-host
+<span class="o">[</span> 0%<span class="o">]</span> <span class="o">[</span>TEST_SUITE_HOST_CC<span class="o">]</span> Building host executable fpcmp
+<span class="o">[</span> 0%<span class="o">]</span> Built target fpcmp-host
+Scanning dependencies of target timeit-host
+<span class="o">[</span> 0%<span class="o">]</span> <span class="o">[</span>TEST_SUITE_HOST_CC<span class="o">]</span> Building host executable timeit
+<span class="o">[</span> 0%<span class="o">]</span> Built target timeit-host
+</pre></div>
+</div>
+<ol class="arabic simple">
+<li>Run the tests with lit:</li>
+</ol>
+<div class="highlight-bash"><div class="highlight"><pre>% lit -v -j 1 . -o results.json
+-- Testing: 474 tests, 1 threads --
+PASS: <span class="nb">test</span>-suite :: MultiSource/Applications/ALAC/decode/alacconvert-decode.test <span class="o">(</span>1 of 474<span class="o">)</span>
+********** TEST <span class="s1">'test-suite :: MultiSource/Applications/ALAC/decode/alacconvert-decode.test'</span> RESULTS **********
+compile_time: 0.2192
+exec_time: 0.0462
+<span class="nb">hash</span>: <span class="s2">"59620e187c6ac38b36382685ccd2b63b"</span>
+size: 83348
+**********
+PASS: <span class="nb">test</span>-suite :: MultiSource/Applications/ALAC/encode/alacconvert-encode.test <span class="o">(</span>2 of 474<span class="o">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="running-the-test-suite-via-makefiles-deprecated">
+<h2><a class="toc-backref" href="#id4">Running the test suite via Makefiles (deprecated)</a><a class="headerlink" href="#running-the-test-suite-via-makefiles-deprecated" title="Permalink to this headline">¶</a></h2>
+<p>First, all tests are executed within the LLVM object directory tree.
+They <em>are not</em> executed inside of the LLVM source tree. This is because
+the test suite creates temporary files during execution.</p>
+<p>To run the test suite, you need to use the following steps:</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">cd</span></tt> into the <tt class="docutils literal"><span class="pre">llvm/projects</span></tt> directory in your source tree.</p>
+</li>
+<li><p class="first">Check out the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module with:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% svn co http://llvm.org/svn/llvm-project/test-suite/trunk <span class="nb">test</span>-suite
+</pre></div>
+</div>
+<p>This will get the test suite into <tt class="docutils literal"><span class="pre">llvm/projects/test-suite</span></tt>.</p>
+</li>
+<li><p class="first">Configure and build <tt class="docutils literal"><span class="pre">llvm</span></tt>.</p>
+</li>
+<li><p class="first">Configure and build <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>.</p>
+</li>
+<li><p class="first">Install <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> somewhere.</p>
+</li>
+<li><p class="first"><em>Re-configure</em> <tt class="docutils literal"><span class="pre">llvm</span></tt> from the top level of each build tree (LLVM
+object directory tree) in which you want to run the test suite, just
+as you do before building LLVM.</p>
+<p>During the <em>re-configuration</em>, you must either: (1) have <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>
+you just built in your path, or (2) specify the directory where your
+just-built <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> is installed using
+<tt class="docutils literal"><span class="pre">--with-llvmgccdir=$LLVM_GCC_DIR</span></tt>.</p>
+<p>You must also tell the configure machinery that the test suite is
+available so it can be configured for your build tree:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd</span> <span class="nv">$LLVM_OBJ_ROOT</span> ; <span class="nv">$LLVM_SRC_ROOT</span>/configure <span class="o">[</span>--with-llvmgccdir<span class="o">=</span><span class="nv">$LLVM_GCC_DIR</span><span class="o">]</span>
+</pre></div>
+</div>
+<p>[Remember that <tt class="docutils literal"><span class="pre">$LLVM_GCC_DIR</span></tt> is the directory where you
+<em>installed</em> llvm-gcc, not its src or obj directory.]</p>
+</li>
+<li><p class="first">You can now run the test suite from your build tree as follows:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd</span> <span class="nv">$LLVM_OBJ_ROOT</span>/projects/test-suite
+% make
+</pre></div>
+</div>
+</li>
+</ol>
+<p>Note that the second and third steps only need to be done once. After
+you have the suite checked out and configured, you don’t need to do it
+again (unless the test code or configure script changes).</p>
+<div class="section" id="configuring-external-tests">
+<h3><a class="toc-backref" href="#id5">Configuring External Tests</a><a class="headerlink" href="#configuring-external-tests" title="Permalink to this headline">¶</a></h3>
+<p>In order to run the External tests in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module, you
+must specify <em>–with-externals</em>. This must be done during the
+<em>re-configuration</em> step (see above), and the <tt class="docutils literal"><span class="pre">llvm</span></tt> re-configuration
+must recognize the previously-built <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>. If any of these is
+missing or neglected, the External tests won’t work.</p>
+<ul class="simple">
+<li><em>–with-externals</em></li>
+<li><em>–with-externals=<directory></em></li>
+</ul>
+<p>This tells LLVM where to find any external tests. They are expected to
+be in specifically named subdirectories of <<tt class="docutils literal"><span class="pre">directory</span></tt>>. If
+<tt class="docutils literal"><span class="pre">directory</span></tt> is left unspecified, <tt class="docutils literal"><span class="pre">configure</span></tt> uses the default value
+<tt class="docutils literal"><span class="pre">/home/vadve/shared/benchmarks/speccpu2000/benchspec</span></tt>. Subdirectory
+names known to LLVM include:</p>
+<ul class="simple">
+<li>spec95</li>
+<li>speccpu2000</li>
+<li>speccpu2006</li>
+<li>povray31</li>
+</ul>
+<p>Others are added from time to time, and can be determined from
+<tt class="docutils literal"><span class="pre">configure</span></tt>.</p>
+</div>
+<div class="section" id="running-different-tests">
+<h3><a class="toc-backref" href="#id6">Running different tests</a><a class="headerlink" href="#running-different-tests" title="Permalink to this headline">¶</a></h3>
+<p>In addition to the regular “whole program” tests, the <tt class="docutils literal"><span class="pre">test-suite</span></tt>
+module also provides a mechanism for compiling the programs in different
+ways. If the variable TEST is defined on the <tt class="docutils literal"><span class="pre">gmake</span></tt> command line, the
+test system will include a Makefile named
+<tt class="docutils literal"><span class="pre">TEST.<value</span> <span class="pre">of</span> <span class="pre">TEST</span> <span class="pre">variable>.Makefile</span></tt>. This Makefile can modify
+build rules to yield different results.</p>
+<p>For example, the LLVM nightly tester uses <tt class="docutils literal"><span class="pre">TEST.nightly.Makefile</span></tt> to
+create the nightly test reports. To run the nightly tests, run
+<tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=nightly</span></tt>.</p>
+<p>There are several TEST Makefiles available in the tree. Some of them are
+designed for internal LLVM research and will not work outside of the
+LLVM research group. They may still be valuable, however, as a guide to
+writing your own TEST Makefile for any optimization or analysis passes
+that you develop with LLVM.</p>
+</div>
+<div class="section" id="generating-test-output">
+<h3><a class="toc-backref" href="#id7">Generating test output</a><a class="headerlink" href="#generating-test-output" title="Permalink to this headline">¶</a></h3>
+<p>There are a number of ways to run the tests and generate output. The
+most simple one is simply running <tt class="docutils literal"><span class="pre">gmake</span></tt> with no arguments. This will
+compile and run all programs in the tree using a number of different
+methods and compare results. Any failures are reported in the output,
+but are likely drowned in the other output. Passes are not reported
+explicitly.</p>
+<p>Somewhat better is running <tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=sometest</span> <span class="pre">test</span></tt>, which runs the
+specified test and usually adds per-program summaries to the output
+(depending on which sometest you use). For example, the <tt class="docutils literal"><span class="pre">nightly</span></tt> test
+explicitly outputs TEST-PASS or TEST-FAIL for every test after each
+program. Though these lines are still drowned in the output, it’s easy
+to grep the output logs in the Output directories.</p>
+<p>Even better are the <tt class="docutils literal"><span class="pre">report</span></tt> and <tt class="docutils literal"><span class="pre">report.format</span></tt> targets (where
+<tt class="docutils literal"><span class="pre">format</span></tt> is one of <tt class="docutils literal"><span class="pre">html</span></tt>, <tt class="docutils literal"><span class="pre">csv</span></tt>, <tt class="docutils literal"><span class="pre">text</span></tt> or <tt class="docutils literal"><span class="pre">graphs</span></tt>). The
+exact contents of the report are dependent on which <tt class="docutils literal"><span class="pre">TEST</span></tt> you are
+running, but the text results are always shown at the end of the run and
+the results are always stored in the <tt class="docutils literal"><span class="pre">report.<type>.format</span></tt> file (when
+running with <tt class="docutils literal"><span class="pre">TEST=<type></span></tt>). The <tt class="docutils literal"><span class="pre">report</span></tt> also generate a file
+called <tt class="docutils literal"><span class="pre">report.<type>.raw.out</span></tt> containing the output of the entire
+test run.</p>
+</div>
+<div class="section" id="writing-custom-tests-for-the-test-suite">
+<h3><a class="toc-backref" href="#id8">Writing custom tests for the test suite</a><a class="headerlink" href="#writing-custom-tests-for-the-test-suite" title="Permalink to this headline">¶</a></h3>
+<p>Assuming you can run the test suite, (e.g.
+“<tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=nightly</span> <span class="pre">report</span></tt>” should work), it is really easy to run
+optimizations or code generator components against every program in the
+tree, collecting statistics or running custom checks for correctness. At
+base, this is how the nightly tester works, it’s just one example of a
+general framework.</p>
+<p>Lets say that you have an LLVM optimization pass, and you want to see
+how many times it triggers. First thing you should do is add an LLVM
+<a class="reference external" href="ProgrammersManual.html#Statistic">statistic</a> to your pass, which will
+tally counts of things you care about.</p>
+<p>Following this, you can set up a test and a report that collects these
+and formats them for easy viewing. This consists of two files, a
+“<tt class="docutils literal"><span class="pre">test-suite/TEST.XXX.Makefile</span></tt>” fragment (where XXX is the name of
+your test) and a “<tt class="docutils literal"><span class="pre">test-suite/TEST.XXX.report</span></tt>” file that indicates
+how to format the output into a table. There are many example reports of
+various levels of sophistication included with the test suite, and the
+framework is very general.</p>
+<p>If you are interested in testing an optimization pass, check out the
+“libcalls” test as an example. It can be run like this:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>llvm/projects/test-suite/MultiSource/Benchmarks <span class="c"># or some other level</span>
+% make <span class="nv">TEST</span><span class="o">=</span>libcalls report
+</pre></div>
+</div>
+<p>This will do a bunch of stuff, then eventually print a table like this:</p>
+<div class="highlight-python"><div class="highlight"><pre>Name | total | #exit |
+...
+FreeBench/analyzer/analyzer | 51 | 6 |
+FreeBench/fourinarow/fourinarow | 1 | 1 |
+FreeBench/neural/neural | 19 | 9 |
+FreeBench/pifft/pifft | 5 | 3 |
+MallocBench/cfrac/cfrac | 1 | * |
+MallocBench/espresso/espresso | 52 | 12 |
+MallocBench/gs/gs | 4 | * |
+Prolangs-C/TimberWolfMC/timberwolfmc | 302 | * |
+Prolangs-C/agrep/agrep | 33 | 12 |
+Prolangs-C/allroots/allroots | * | * |
+Prolangs-C/assembler/assembler | 47 | * |
+Prolangs-C/bison/mybison | 74 | * |
+...
+</pre></div>
+</div>
+<p>This basically is grepping the -stats output and displaying it in a
+table. You can also use the “TEST=libcalls report.html” target to get
+the table in HTML form, similarly for report.csv and report.tex.</p>
+<p>The source for this is in <tt class="docutils literal"><span class="pre">test-suite/TEST.libcalls.*</span></tt>. The format is
+pretty simple: the Makefile indicates how to run the test (in this case,
+“<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-simplify-libcalls</span> <span class="pre">-stats</span></tt>”), and the report contains one line
+for each column of the output. The first value is the header for the
+column and the second is the regex to grep the output of the command
+for. There are lots of example reports that can do fancy stuff.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="tutorial/index.html" title="LLVM Tutorial: Table of Contents"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TestingGuide.html" title="LLVM Testing Infrastructure Guide"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ <li><a href="TestingGuide.html" >LLVM Testing Infrastructure Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TestingGuide.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TestingGuide.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TestingGuide.html (added)
+++ www-releases/trunk/3.9.1/docs/TestingGuide.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,640 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Testing Infrastructure Guide — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="LLVM test-suite Guide" href="TestSuiteMakefileGuide.html" />
+ <link rel="prev" title="Code Reviews with Phabricator" href="Phabricator.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="TestSuiteMakefileGuide.html" title="LLVM test-suite Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Phabricator.html" title="Code Reviews with Phabricator"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-testing-infrastructure-guide">
+<h1>LLVM Testing Infrastructure Guide<a class="headerlink" href="#llvm-testing-infrastructure-guide" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id5">Overview</a></li>
+<li><a class="reference internal" href="#requirements" id="id6">Requirements</a></li>
+<li><a class="reference internal" href="#llvm-testing-infrastructure-organization" id="id7">LLVM testing infrastructure organization</a><ul>
+<li><a class="reference internal" href="#regression-tests" id="id8">Regression tests</a></li>
+<li><a class="reference internal" href="#test-suite" id="id9"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a></li>
+<li><a class="reference internal" href="#debugging-information-tests" id="id10">Debugging Information tests</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#quick-start" id="id11">Quick start</a><ul>
+<li><a class="reference internal" href="#id1" id="id12">Regression tests</a></li>
+<li><a class="reference internal" href="#id2" id="id13">Debugging Information tests</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#regression-test-structure" id="id14">Regression test structure</a><ul>
+<li><a class="reference internal" href="#writing-new-regression-tests" id="id15">Writing new regression tests</a></li>
+<li><a class="reference internal" href="#extra-files" id="id16">Extra files</a></li>
+<li><a class="reference internal" href="#fragile-tests" id="id17">Fragile tests</a></li>
+<li><a class="reference internal" href="#platform-specific-tests" id="id18">Platform-Specific Tests</a><ul>
+<li><a class="reference internal" href="#requires-and-requires-any-directive" id="id19">REQUIRES and REQUIRES-ANY directive</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#substitutions" id="id20">Substitutions</a></li>
+<li><a class="reference internal" href="#options" id="id21">Options</a></li>
+<li><a class="reference internal" href="#other-features" id="id22">Other Features</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#test-suite-overview" id="id23"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Overview</a><ul>
+<li><a class="reference internal" href="#test-suite-quickstart" id="id24"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Quickstart</a></li>
+<li><a class="reference internal" href="#test-suite-makefiles" id="id25"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefiles</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id5">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>This document is the reference manual for the LLVM testing
+infrastructure. It documents the structure of the LLVM testing
+infrastructure, the tools needed to use it, and how to add and run
+tests.</p>
+</div>
+<div class="section" id="requirements">
+<h2><a class="toc-backref" href="#id6">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
+<p>In order to use the LLVM testing infrastructure, you will need all of the
+software required to build LLVM, as well as <a class="reference external" href="http://python.org">Python</a> 2.7 or
+later.</p>
+<p>If you intend to run the <a class="reference internal" href="#test-suite-overview"><em>test-suite</em></a>, you will also
+need a development version of zlib (zlib1g-dev is known to work on several Linux
+distributions).</p>
+</div>
+<div class="section" id="llvm-testing-infrastructure-organization">
+<h2><a class="toc-backref" href="#id7">LLVM testing infrastructure organization</a><a class="headerlink" href="#llvm-testing-infrastructure-organization" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM testing infrastructure contains two major categories of tests:
+regression tests and whole programs. The regression tests are contained
+inside the LLVM repository itself under <tt class="docutils literal"><span class="pre">llvm/test</span></tt> and are expected
+to always pass – they should be run before every commit.</p>
+<p>The whole programs tests are referred to as the “LLVM test suite” (or
+“test-suite”) and are in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module in subversion. For
+historical reasons, these tests are also referred to as the “nightly
+tests” in places, which is less ambiguous than “test-suite” and remains
+in use although we run them much more often than nightly.</p>
+<div class="section" id="regression-tests">
+<h3><a class="toc-backref" href="#id8">Regression tests</a><a class="headerlink" href="#regression-tests" title="Permalink to this headline">¶</a></h3>
+<p>The regression tests are small pieces of code that test a specific
+feature of LLVM or trigger a specific bug in LLVM. The language they are
+written in depends on the part of LLVM being tested. These tests are driven by
+the <a class="reference internal" href="CommandGuide/lit.html"><em>Lit</em></a> testing tool (which is part of LLVM), and
+are located in the <tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory.</p>
+<p>Typically when a bug is found in LLVM, a regression test containing just
+enough code to reproduce the problem should be written and placed
+somewhere underneath this directory. For example, it can be a small
+piece of LLVM IR distilled from an actual application or benchmark.</p>
+</div>
+<div class="section" id="test-suite">
+<h3><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a><a class="headerlink" href="#test-suite" title="Permalink to this headline">¶</a></h3>
+<p>The test suite contains whole programs, which are pieces of code which
+can be compiled and linked into a stand-alone program that can be
+executed. These programs are generally written in high level languages
+such as C or C++.</p>
+<p>These programs are compiled using a user specified compiler and set of
+flags, and then executed to capture the program output and timing
+information. The output of these programs is compared to a reference
+output to ensure that the program is being compiled correctly.</p>
+<p>In addition to compiling and executing programs, whole program tests
+serve as a way of benchmarking LLVM performance, both in terms of the
+efficiency of the programs generated as well as the speed with which
+LLVM compiles, optimizes, and generates code.</p>
+<p>The test-suite is located in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> Subversion module.</p>
+</div>
+<div class="section" id="debugging-information-tests">
+<h3><a class="toc-backref" href="#id10">Debugging Information tests</a><a class="headerlink" href="#debugging-information-tests" title="Permalink to this headline">¶</a></h3>
+<p>The test suite contains tests to check quality of debugging information.
+The test are written in C based languages or in LLVM assembly language.</p>
+<p>These tests are compiled and run under a debugger. The debugger output
+is checked to validate of debugging information. See README.txt in the
+test suite for more information . This test suite is located in the
+<tt class="docutils literal"><span class="pre">debuginfo-tests</span></tt> Subversion module.</p>
+</div>
+</div>
+<div class="section" id="quick-start">
+<h2><a class="toc-backref" href="#id11">Quick start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
+<p>The tests are located in two separate Subversion modules. The
+regressions tests are in the main “llvm” module under the directory
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> (so you get these tests for free with the main LLVM tree).
+Use <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt> to run the regression tests after building LLVM.</p>
+<p>The more comprehensive test suite that includes whole programs in C and C++
+is in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module. See <a class="reference internal" href="#test-suite-quickstart"><em>test-suite Quickstart</em></a> for more information on running these tests.</p>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id12">Regression tests</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>To run all of the LLVM regression tests use the check-llvm target:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check-llvm
+</pre></div>
+</div>
+<p>If you have <a class="reference external" href="http://clang.llvm.org/">Clang</a> checked out and built, you
+can run the LLVM and Clang tests simultaneously using:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check-all
+</pre></div>
+</div>
+<p>To run the tests with Valgrind (Memcheck by default), use the <tt class="docutils literal"><span class="pre">LIT_ARGS</span></tt> make
+variable to pass the required options to lit. For example, you can use:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check <span class="nv">LIT_ARGS</span><span class="o">=</span><span class="s2">"-v --vg --vg-leak"</span>
+</pre></div>
+</div>
+<p>to enable testing with valgrind and with leak checking enabled.</p>
+<p>To run individual tests or subsets of tests, you can use the <tt class="docutils literal"><span class="pre">llvm-lit</span></tt>
+script which is built as part of LLVM. For example, to run the
+<tt class="docutils literal"><span class="pre">Integer/BitPacked.ll</span></tt> test by itself you can run:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% llvm-lit ~/llvm/test/Integer/BitPacked.ll
+</pre></div>
+</div>
+<p>or to run all of the ARM CodeGen tests:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% llvm-lit ~/llvm/test/CodeGen/ARM
+</pre></div>
+</div>
+<p>For more information on using the <strong class="program">lit</strong> tool, see <tt class="docutils literal"><span class="pre">llvm-lit</span> <span class="pre">--help</span></tt>
+or the <a class="reference internal" href="CommandGuide/lit.html"><em>lit man page</em></a>.</p>
+</div>
+<div class="section" id="id2">
+<h3><a class="toc-backref" href="#id13">Debugging Information tests</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<p>To run debugging information tests simply checkout the tests inside
+clang/test directory.</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>clang/test
+% svn co http://llvm.org/svn/llvm-project/debuginfo-tests/trunk debuginfo-tests
+</pre></div>
+</div>
+<p>These tests are already set up to run as part of clang regression tests.</p>
+</div>
+</div>
+<div class="section" id="regression-test-structure">
+<h2><a class="toc-backref" href="#id14">Regression test structure</a><a class="headerlink" href="#regression-test-structure" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM regression tests are driven by <strong class="program">lit</strong> and are located in the
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory.</p>
+<p>This directory contains a large array of small tests that exercise
+various features of LLVM and to ensure that regressions do not occur.
+The directory is broken into several sub-directories, each focused on a
+particular area of LLVM.</p>
+<div class="section" id="writing-new-regression-tests">
+<h3><a class="toc-backref" href="#id15">Writing new regression tests</a><a class="headerlink" href="#writing-new-regression-tests" title="Permalink to this headline">¶</a></h3>
+<p>The regression test structure is very simple, but does require some
+information to be set. This information is gathered via <tt class="docutils literal"><span class="pre">configure</span></tt>
+and is written to a file, <tt class="docutils literal"><span class="pre">test/lit.site.cfg</span></tt> in the build directory.
+The <tt class="docutils literal"><span class="pre">llvm/test</span></tt> Makefile does this work for you.</p>
+<p>In order for the regression tests to work, each directory of tests must
+have a <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> file. <strong class="program">lit</strong> looks for this file to determine
+how to run the tests. This file is just Python code and thus is very
+flexible, but we’ve standardized it for the LLVM regression tests. If
+you’re adding a directory of tests, just copy <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> from
+another directory to get running. The standard <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> simply
+specifies which files to look in for tests. Any directory that contains
+only directories does not need the <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> file. Read the <a class="reference internal" href="CommandGuide/lit.html"><em>Lit
+documentation</em></a> for more information.</p>
+<p>Each test file must contain lines starting with “RUN:” that tell <strong class="program">lit</strong>
+how to run it. If there are no RUN lines, <strong class="program">lit</strong> will issue an error
+while running a test.</p>
+<p>RUN lines are specified in the comments of the test program using the
+keyword <tt class="docutils literal"><span class="pre">RUN</span></tt> followed by a colon, and lastly the command (pipeline)
+to execute. Together, these lines form the “script” that <strong class="program">lit</strong>
+executes to run the test case. The syntax of the RUN lines is similar to a
+shell’s syntax for pipelines including I/O redirection and variable
+substitution. However, even though these lines may <em>look</em> like a shell
+script, they are not. RUN lines are interpreted by <strong class="program">lit</strong>.
+Consequently, the syntax differs from shell in a few ways. You can specify
+as many RUN lines as needed.</p>
+<p><strong class="program">lit</strong> performs substitution on each RUN line to replace LLVM tool names
+with the full paths to the executable built for each tool (in
+<tt class="docutils literal"><span class="pre">$(LLVM_OBJ_ROOT)/$(BuildMode)/bin)</span></tt>. This ensures that <strong class="program">lit</strong> does
+not invoke any stray LLVM tools in the user’s path during testing.</p>
+<p>Each RUN line is executed on its own, distinct from other lines unless
+its last character is <tt class="docutils literal"><span class="pre">\</span></tt>. This continuation character causes the RUN
+line to be concatenated with the next one. In this way you can build up
+long pipelines of commands without making huge line lengths. The lines
+ending in <tt class="docutils literal"><span class="pre">\</span></tt> are concatenated until a RUN line that doesn’t end in
+<tt class="docutils literal"><span class="pre">\</span></tt> is found. This concatenated set of RUN lines then constitutes one
+execution. <strong class="program">lit</strong> will substitute variables and arrange for the pipeline
+to be executed. If any process in the pipeline fails, the entire line (and
+test case) fails too.</p>
+<p>Below is an example of legal RUN lines in a <tt class="docutils literal"><span class="pre">.ll</span></tt> file:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: llvm-as < %s | llvm-dis > %t1</span>
+<span class="c">; RUN: llvm-dis < %s.bc-13 > %t2</span>
+<span class="c">; RUN: diff %t1 %t2</span>
+</pre></div>
+</div>
+<p>As with a Unix shell, the RUN lines permit pipelines and I/O
+redirection to be used.</p>
+<p>There are some quoting rules that you must pay attention to when writing
+your RUN lines. In general nothing needs to be quoted. <strong class="program">lit</strong> won’t
+strip off any quote characters so they will get passed to the invoked program.
+To avoid this use curly braces to tell <strong class="program">lit</strong> that it should treat
+everything enclosed as one value.</p>
+<p>In general, you should strive to keep your RUN lines as simple as possible,
+using them only to run tools that generate textual output you can then examine.
+The recommended way to examine output to figure out if the test passes is using
+the <a class="reference internal" href="CommandGuide/FileCheck.html"><em>FileCheck tool</em></a>. <em>[The usage of grep in RUN
+lines is deprecated - please do not send or commit patches that use it.]</em></p>
+<p>Put related tests into a single file rather than having a separate file per
+test. Check if there are files already covering your feature and consider
+adding your code there instead of creating a new file.</p>
+</div>
+<div class="section" id="extra-files">
+<h3><a class="toc-backref" href="#id16">Extra files</a><a class="headerlink" href="#extra-files" title="Permalink to this headline">¶</a></h3>
+<p>If your test requires extra files besides the file containing the <tt class="docutils literal"><span class="pre">RUN:</span></tt>
+lines, the idiomatic place to put them is in a subdirectory <tt class="docutils literal"><span class="pre">Inputs</span></tt>.
+You can then refer to the extra files as <tt class="docutils literal"><span class="pre">%S/Inputs/foo.bar</span></tt>.</p>
+<p>For example, consider <tt class="docutils literal"><span class="pre">test/Linker/ident.ll</span></tt>. The directory structure is
+as follows:</p>
+<div class="highlight-python"><div class="highlight"><pre>test/
+ Linker/
+ ident.ll
+ Inputs/
+ ident.a.ll
+ ident.b.ll
+</pre></div>
+</div>
+<p>For convenience, these are the contents:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">;;;;; ident.ll:</span>
+
+<span class="c">; RUN: llvm-link %S/Inputs/ident.a.ll %S/Inputs/ident.b.ll -S | FileCheck %s</span>
+
+<span class="c">; Verify that multiple input llvm.ident metadata are linked together.</span>
+
+<span class="c">; CHECK-DAG: !llvm.ident = !{!0, !1, !2}</span>
+<span class="c">; CHECK-DAG: "Compiler V1"</span>
+<span class="c">; CHECK-DAG: "Compiler V2"</span>
+<span class="c">; CHECK-DAG: "Compiler V3"</span>
+
+<span class="c">;;;;; Inputs/ident.a.ll:</span>
+
+<span class="nv">!llvm.ident</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">,</span> <span class="nv-Anonymous">!1</span><span class="p">}</span>
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv">!"Compiler V1"</span><span class="p">}</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv">!"Compiler V2"</span><span class="p">}</span>
+
+<span class="c">;;;;; Inputs/ident.b.ll:</span>
+
+<span class="nv">!llvm.ident</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv">!"Compiler V3"</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>For symmetry reasons, <tt class="docutils literal"><span class="pre">ident.ll</span></tt> is just a dummy file that doesn’t
+actually participate in the test besides holding the <tt class="docutils literal"><span class="pre">RUN:</span></tt> lines.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Some existing tests use <tt class="docutils literal"><span class="pre">RUN:</span> <span class="pre">true</span></tt> in extra files instead of just
+putting the extra files in an <tt class="docutils literal"><span class="pre">Inputs/</span></tt> directory. This pattern is
+deprecated.</p>
+</div>
+</div>
+<div class="section" id="fragile-tests">
+<h3><a class="toc-backref" href="#id17">Fragile tests</a><a class="headerlink" href="#fragile-tests" title="Permalink to this headline">¶</a></h3>
+<p>It is easy to write a fragile test that would fail spuriously if the tool being
+tested outputs a full path to the input file. For example, <strong class="program">opt</strong> by
+default outputs a <tt class="docutils literal"><span class="pre">ModuleID</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat example.ll
+<span class="go">define i32 @main() nounwind {</span>
+<span class="go"> ret i32 0</span>
+<span class="go">}</span>
+
+<span class="gp">$</span> opt -S /path/to/example.ll
+<span class="go">; ModuleID = '/path/to/example.ll'</span>
+
+<span class="go">define i32 @main() nounwind {</span>
+<span class="go"> ret i32 0</span>
+<span class="go">}</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">ModuleID</span></tt> can unexpetedly match against <tt class="docutils literal"><span class="pre">CHECK</span></tt> lines. For example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: opt -S %s | FileCheck</span>
+
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="k">nounwind</span> <span class="p">{</span>
+ <span class="c">; CHECK-NOT: load</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This test will fail if placed into a <tt class="docutils literal"><span class="pre">download</span></tt> directory.</p>
+<p>To make your tests robust, always use <tt class="docutils literal"><span class="pre">opt</span> <span class="pre">...</span> <span class="pre"><</span> <span class="pre">%s</span></tt> in the RUN line.
+<strong class="program">opt</strong> does not output a <tt class="docutils literal"><span class="pre">ModuleID</span></tt> when input comes from stdin.</p>
+</div>
+<div class="section" id="platform-specific-tests">
+<h3><a class="toc-backref" href="#id18">Platform-Specific Tests</a><a class="headerlink" href="#platform-specific-tests" title="Permalink to this headline">¶</a></h3>
+<p>Whenever adding tests that require the knowledge of a specific platform,
+either related to code generated, specific output or back-end features,
+you must make sure to isolate the features, so that buildbots that
+run on different architectures (and don’t even compile all back-ends),
+don’t fail.</p>
+<p>The first problem is to check for target-specific output, for example sizes
+of structures, paths and architecture names, for example:</p>
+<ul class="simple">
+<li>Tests containing Windows paths will fail on Linux and vice-versa.</li>
+<li>Tests that check for <tt class="docutils literal"><span class="pre">x86_64</span></tt> somewhere in the text will fail anywhere else.</li>
+<li>Tests where the debug information calculates the size of types and structures.</li>
+</ul>
+<p>Also, if the test rely on any behaviour that is coded in any back-end, it must
+go in its own directory. So, for instance, code generator tests for ARM go
+into <tt class="docutils literal"><span class="pre">test/CodeGen/ARM</span></tt> and so on. Those directories contain a special
+<tt class="docutils literal"><span class="pre">lit</span></tt> configuration file that ensure all tests in that directory will
+only run if a specific back-end is compiled and available.</p>
+<p>For instance, on <tt class="docutils literal"><span class="pre">test/CodeGen/ARM</span></tt>, the <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> is:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">config</span><span class="o">.</span><span class="n">suffixes</span> <span class="o">=</span> <span class="p">[</span><span class="s">'.ll'</span><span class="p">,</span> <span class="s">'.c'</span><span class="p">,</span> <span class="s">'.cpp'</span><span class="p">,</span> <span class="s">'.test'</span><span class="p">]</span>
+<span class="k">if</span> <span class="ow">not</span> <span class="s">'ARM'</span> <span class="ow">in</span> <span class="n">config</span><span class="o">.</span><span class="n">root</span><span class="o">.</span><span class="n">targets</span><span class="p">:</span>
+ <span class="n">config</span><span class="o">.</span><span class="n">unsupported</span> <span class="o">=</span> <span class="bp">True</span>
+</pre></div>
+</div>
+<p>Other platform-specific tests are those that depend on a specific feature
+of a specific sub-architecture, for example only to Intel chips that support <tt class="docutils literal"><span class="pre">AVX2</span></tt>.</p>
+<p>For instance, <tt class="docutils literal"><span class="pre">test/CodeGen/X86/psubus.ll</span></tt> tests three sub-architecture
+variants:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: llc -mcpu=core2 < %s | FileCheck %s -check-prefix=SSE2</span>
+<span class="c">; RUN: llc -mcpu=corei7-avx < %s | FileCheck %s -check-prefix=AVX1</span>
+<span class="c">; RUN: llc -mcpu=core-avx2 < %s | FileCheck %s -check-prefix=AVX2</span>
+</pre></div>
+</div>
+<p>And the checks are different:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; SSE2: @test1</span>
+<span class="c">; SSE2: psubusw LCPI0_0(%rip), %xmm0</span>
+<span class="c">; AVX1: @test1</span>
+<span class="c">; AVX1: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0</span>
+<span class="c">; AVX2: @test1</span>
+<span class="c">; AVX2: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0</span>
+</pre></div>
+</div>
+<p>So, if you’re testing for a behaviour that you know is platform-specific or
+depends on special features of sub-architectures, you must add the specific
+triple, test with the specific FileCheck and put it into the specific
+directory that will filter out all other architectures.</p>
+<div class="section" id="requires-and-requires-any-directive">
+<h4><a class="toc-backref" href="#id19">REQUIRES and REQUIRES-ANY directive</a><a class="headerlink" href="#requires-and-requires-any-directive" title="Permalink to this headline">¶</a></h4>
+<p>Some tests can be enabled only in specific situation - like having
+debug build. Use <tt class="docutils literal"><span class="pre">REQUIRES</span></tt> directive to specify those requirements.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; This test will be only enabled in the build with asserts</span>
+<span class="c">; REQUIRES: asserts</span>
+</pre></div>
+</div>
+<p>You can separate requirements by a comma.
+<tt class="docutils literal"><span class="pre">REQUIRES</span></tt> means all listed requirements must be satisfied.
+<tt class="docutils literal"><span class="pre">REQUIRES-ANY</span></tt> means at least one must be satisfied.</p>
+<p>List of features that can be used in <tt class="docutils literal"><span class="pre">REQUIRES</span></tt> and <tt class="docutils literal"><span class="pre">REQUIRES-ANY</span></tt> can be
+found in lit.cfg files.</p>
+</div>
+</div>
+<div class="section" id="substitutions">
+<h3><a class="toc-backref" href="#id20">Substitutions</a><a class="headerlink" href="#substitutions" title="Permalink to this headline">¶</a></h3>
+<p>Besides replacing LLVM tool names the following substitutions are performed in
+RUN lines:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">%%</span></tt></dt>
+<dd>Replaced by a single <tt class="docutils literal"><span class="pre">%</span></tt>. This allows escaping other substitutions.</dd>
+<dt><tt class="docutils literal"><span class="pre">%s</span></tt></dt>
+<dd><p class="first">File path to the test case’s source. This is suitable for passing on the
+command line as the input to an LLVM tool.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">/home/user/llvm/test/MC/ELF/foo_test.s</span></tt></p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%S</span></tt></dt>
+<dd><p class="first">Directory path to the test case’s source.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">/home/user/llvm/test/MC/ELF</span></tt></p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%t</span></tt></dt>
+<dd><p class="first">File path to a temporary file name that could be used for this test case.
+The file name won’t conflict with other test cases. You can append to it
+if you need multiple temporaries. This is useful as the destination of
+some redirected output.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">/home/user/llvm.build/test/MC/ELF/Output/foo_test.s.tmp</span></tt></p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%T</span></tt></dt>
+<dd><p class="first">Directory of <tt class="docutils literal"><span class="pre">%t</span></tt>.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">/home/user/llvm.build/test/MC/ELF/Output</span></tt></p>
+</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">%{pathsep}</span></tt></p>
+<blockquote>
+<div>Expands to the path separator, i.e. <tt class="docutils literal"><span class="pre">:</span></tt> (or <tt class="docutils literal"><span class="pre">;</span></tt> on Windows).</div></blockquote>
+<p><strong>LLVM-specific substitutions:</strong></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">%shlibext</span></tt></dt>
+<dd><p class="first">The suffix for the host platforms shared library files. This includes the
+period as the first character.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">.so</span></tt> (Linux), <tt class="docutils literal"><span class="pre">.dylib</span></tt> (OS X), <tt class="docutils literal"><span class="pre">.dll</span></tt> (Windows)</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%exeext</span></tt></dt>
+<dd><p class="first">The suffix for the host platforms executable files. This includes the
+period as the first character.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">.exe</span></tt> (Windows), empty on Linux.</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">%(line)</span></tt>, <tt class="docutils literal"><span class="pre">%(line+<number>)</span></tt>, <tt class="docutils literal"><span class="pre">%(line-<number>)</span></tt></dt>
+<dd>The number of the line where this substitution is used, with an optional
+integer offset. This can be used in tests with multiple RUN lines, which
+reference test file’s line numbers.</dd>
+</dl>
+<p><strong>Clang-specific substitutions:</strong></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">%clang</span></tt></dt>
+<dd>Invokes the Clang driver.</dd>
+<dt><tt class="docutils literal"><span class="pre">%clang_cpp</span></tt></dt>
+<dd>Invokes the Clang driver for C++.</dd>
+<dt><tt class="docutils literal"><span class="pre">%clang_cl</span></tt></dt>
+<dd>Invokes the CL-compatible Clang driver.</dd>
+<dt><tt class="docutils literal"><span class="pre">%clangxx</span></tt></dt>
+<dd>Invokes the G++-compatible Clang driver.</dd>
+<dt><tt class="docutils literal"><span class="pre">%clang_cc1</span></tt></dt>
+<dd>Invokes the Clang frontend.</dd>
+<dt><tt class="docutils literal"><span class="pre">%itanium_abi_triple</span></tt>, <tt class="docutils literal"><span class="pre">%ms_abi_triple</span></tt></dt>
+<dd>These substitutions can be used to get the current target triple adjusted to
+the desired ABI. For example, if the test suite is running with the
+<tt class="docutils literal"><span class="pre">i686-pc-win32</span></tt> target, <tt class="docutils literal"><span class="pre">%itanium_abi_triple</span></tt> will expand to
+<tt class="docutils literal"><span class="pre">i686-pc-mingw32</span></tt>. This allows a test to run with a specific ABI without
+constraining it to a specific triple.</dd>
+</dl>
+<p>To add more substituations, look at <tt class="docutils literal"><span class="pre">test/lit.cfg</span></tt> or <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt>.</p>
+</div>
+<div class="section" id="options">
+<h3><a class="toc-backref" href="#id21">Options</a><a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
+<p>The llvm lit configuration allows to customize some things with user options:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">llc</span></tt>, <tt class="docutils literal"><span class="pre">opt</span></tt>, ...</dt>
+<dd><p class="first">Substitute the respective llvm tool name with a custom command line. This
+allows to specify custom paths and default arguments for these tools.
+Example:</p>
+<p class="last">% llvm-lit “-Dllc=llc -verify-machineinstrs”</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">run_long_tests</span></tt></dt>
+<dd>Enable the execution of long running tests.</dd>
+<dt><tt class="docutils literal"><span class="pre">llvm_site_config</span></tt></dt>
+<dd>Load the specified lit configuration instead of the default one.</dd>
+</dl>
+</div>
+<div class="section" id="other-features">
+<h3><a class="toc-backref" href="#id22">Other Features</a><a class="headerlink" href="#other-features" title="Permalink to this headline">¶</a></h3>
+<p>To make RUN line writing easier, there are several helper programs. These
+helpers are in the PATH when running tests, so you can just call them using
+their name. For example:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">not</span></tt></dt>
+<dd>This program runs its arguments and then inverts the result code from it.
+Zero result codes become 1. Non-zero result codes become 0.</dd>
+</dl>
+<p>Sometimes it is necessary to mark a test case as “expected fail” or
+XFAIL. You can easily mark a test as XFAIL just by including <tt class="docutils literal"><span class="pre">XFAIL:</span></tt>
+on a line near the top of the file. This signals that the test case
+should succeed if the test fails. Such test cases are counted separately
+by the testing tool. To specify an expected fail, use the XFAIL keyword
+in the comments of the test program followed by a colon and one or more
+failure patterns. Each failure pattern can be either <tt class="docutils literal"><span class="pre">*</span></tt> (to specify
+fail everywhere), or a part of a target triple (indicating the test
+should fail on that platform), or the name of a configurable feature
+(for example, <tt class="docutils literal"><span class="pre">loadable_module</span></tt>). If there is a match, the test is
+expected to fail. If not, the test is expected to succeed. To XFAIL
+everywhere just specify <tt class="docutils literal"><span class="pre">XFAIL:</span> <span class="pre">*</span></tt>. Here is an example of an <tt class="docutils literal"><span class="pre">XFAIL</span></tt>
+line:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; XFAIL: darwin,sun</span>
+</pre></div>
+</div>
+<p>To make the output more useful, <strong class="program">lit</strong> will scan
+the lines of the test case for ones that contain a pattern that matches
+<tt class="docutils literal"><span class="pre">PR[0-9]+</span></tt>. This is the syntax for specifying a PR (Problem Report) number
+that is related to the test case. The number after “PR” specifies the
+LLVM bugzilla number. When a PR number is specified, it will be used in
+the pass/fail reporting. This is useful to quickly get some context when
+a test fails.</p>
+<p>Finally, any line that contains “END.” will cause the special
+interpretation of lines to terminate. This is generally done right after
+the last RUN: line. This has two side effects:</p>
+<ol class="loweralpha simple">
+<li>it prevents special interpretation of lines that are part of the test
+program, not the instructions to the test case, and</li>
+<li>it speeds things up for really big test cases by avoiding
+interpretation of the remainder of the file.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="test-suite-overview">
+<span id="id3"></span><h2><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Overview</a><a class="headerlink" href="#test-suite-overview" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">test-suite</span></tt> module contains a number of programs that can be
+compiled and executed. The <tt class="docutils literal"><span class="pre">test-suite</span></tt> includes reference outputs for
+all of the programs, so that the output of the executed program can be
+checked for correctness.</p>
+<p><tt class="docutils literal"><span class="pre">test-suite</span></tt> tests are divided into three types of tests: MultiSource,
+SingleSource, and External.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/SingleSource</span></tt></p>
+<p>The SingleSource directory contains test programs that are only a
+single source file in size. These are usually small benchmark
+programs or small programs that calculate a particular value. Several
+such programs are grouped together in each directory.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/MultiSource</span></tt></p>
+<p>The MultiSource directory contains subdirectories which contain
+entire programs with multiple source files. Large benchmarks and
+whole applications go here.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/External</span></tt></p>
+<p>The External directory contains Makefiles for building code that is
+external to (i.e., not distributed with) LLVM. The most prominent
+members of this directory are the SPEC 95 and SPEC 2000 benchmark
+suites. The <tt class="docutils literal"><span class="pre">External</span></tt> directory does not contain these actual
+tests, but only the Makefiles that know how to properly compile these
+programs from somewhere else. When using <tt class="docutils literal"><span class="pre">LNT</span></tt>, use the
+<tt class="docutils literal"><span class="pre">--test-externals</span></tt> option to include these tests in the results.</p>
+</li>
+</ul>
+<div class="section" id="test-suite-quickstart">
+<span id="id4"></span><h3><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Quickstart</a><a class="headerlink" href="#test-suite-quickstart" title="Permalink to this headline">¶</a></h3>
+<p>The modern way of running the <tt class="docutils literal"><span class="pre">test-suite</span></tt> is focused on testing and
+benchmarking complete compilers using the
+<a class="reference external" href="http://llvm.org/docs/lnt">LNT</a> testing infrastructure.</p>
+<p>For more information on using LNT to execute the <tt class="docutils literal"><span class="pre">test-suite</span></tt>, please
+see the <a class="reference external" href="http://llvm.org/docs/lnt/quickstart.html">LNT Quickstart</a>
+documentation.</p>
+</div>
+<div class="section" id="test-suite-makefiles">
+<h3><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefiles</a><a class="headerlink" href="#test-suite-makefiles" title="Permalink to this headline">¶</a></h3>
+<p>Historically, the <tt class="docutils literal"><span class="pre">test-suite</span></tt> was executed using a complicated setup
+of Makefiles. The LNT based approach above is recommended for most
+users, but there are some testing scenarios which are not supported by
+the LNT approach. In addition, LNT currently uses the Makefile setup
+under the covers and so developers who are interested in how LNT works
+under the hood may want to understand the Makefile based setup.</p>
+<p>For more information on the <tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefile setup, please see
+the <a class="reference internal" href="TestSuiteMakefileGuide.html"><em>Test Suite Makefile Guide</em></a>.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="TestSuiteMakefileGuide.html" title="LLVM test-suite Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Phabricator.html" title="Code Reviews with Phabricator"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/TypeMetadata.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/TypeMetadata.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/TypeMetadata.html (added)
+++ www-releases/trunk/3.9.1/docs/TypeMetadata.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,387 @@
+
+<!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>Type Metadata — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="FaultMaps and implicit checks" href="FaultMaps.html" />
+ <link rel="prev" title="MergeFunctions pass, how it works" href="MergeFunctions.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="FaultMaps.html" title="FaultMaps and implicit checks"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="MergeFunctions.html" title="MergeFunctions pass, how it works"
+ 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="type-metadata">
+<h1>Type Metadata<a class="headerlink" href="#type-metadata" title="Permalink to this headline">¶</a></h1>
+<p>Type metadata is a mechanism that allows IR modules to co-operatively build
+pointer sets corresponding to addresses within a given set of globals. LLVM’s
+<a class="reference external" href="http://clang.llvm.org/docs/ControlFlowIntegrity.html">control flow integrity</a> implementation uses this metadata to efficiently
+check (at each call site) that a given address corresponds to either a
+valid vtable or function pointer for a given class or function type, and its
+whole-program devirtualization pass uses the metadata to identify potential
+callees for a given virtual call.</p>
+<p>To use the mechanism, a client creates metadata nodes with two elements:</p>
+<ol class="arabic simple">
+<li>a byte offset into the global (generally zero for functions)</li>
+<li>a metadata object representing an identifier for the type</li>
+</ol>
+<p>These metadata nodes are associated with globals by using global object
+metadata attachments with the <tt class="docutils literal"><span class="pre">!type</span></tt> metadata kind.</p>
+<p>Each type identifier must exclusively identify either global variables
+or functions.</p>
+<div class="admonition-limitation admonition">
+<p class="first admonition-title">Limitation</p>
+<p class="last">The current implementation only supports attaching metadata to functions on
+the x86-32 and x86-64 architectures.</p>
+</div>
+<p>An intrinsic, <a class="reference internal" href="LangRef.html#type-test"><em>llvm.type.test</em></a>, is used to test whether a
+given pointer is associated with a type identifier.</p>
+<div class="section" id="representing-type-information-using-type-metadata">
+<h2>Representing Type Information using Type Metadata<a class="headerlink" href="#representing-type-information-using-type-metadata" title="Permalink to this headline">¶</a></h2>
+<p>This section describes how Clang represents C++ type information associated with
+virtual tables using type metadata.</p>
+<p>Consider the following inheritance hierarchy:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">A</span> <span class="p">{</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">B</span> <span class="o">:</span> <span class="n">A</span> <span class="p">{</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f</span><span class="p">();</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">g</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">C</span> <span class="p">{</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">h</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">D</span> <span class="o">:</span> <span class="n">A</span><span class="p">,</span> <span class="n">C</span> <span class="p">{</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f</span><span class="p">();</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">h</span><span class="p">();</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The virtual table objects for A, B, C and D look like this (under the Itanium ABI):</p>
+<table border="1" class="docutils">
+<caption>Virtual Table Layout for A, B, C, D</caption>
+<colgroup>
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Class</th>
+<th class="head">0</th>
+<th class="head">1</th>
+<th class="head">2</th>
+<th class="head">3</th>
+<th class="head">4</th>
+<th class="head">5</th>
+<th class="head">6</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>A</td>
+<td>A::offset-to-top</td>
+<td>&A::rtti</td>
+<td>&A::f</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-odd"><td>B</td>
+<td>B::offset-to-top</td>
+<td>&B::rtti</td>
+<td>&B::f</td>
+<td>&B::g</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td>C</td>
+<td>C::offset-to-top</td>
+<td>&C::rtti</td>
+<td>&C::h</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-odd"><td>D</td>
+<td>D::offset-to-top</td>
+<td>&D::rtti</td>
+<td>&D::f</td>
+<td>&D::h</td>
+<td>D::offset-to-top</td>
+<td>&D::rtti</td>
+<td>thunk for &D::h</td>
+</tr>
+</tbody>
+</table>
+<p>When an object of type A is constructed, the address of <tt class="docutils literal"><span class="pre">&A::f</span></tt> in A’s
+virtual table object is stored in the object’s vtable pointer. In ABI parlance
+this address is known as an <a class="reference external" href="https://mentorembedded.github.io/cxx-abi/abi.html#vtable-general">address point</a>. Similarly, when an object of type
+B is constructed, the address of <tt class="docutils literal"><span class="pre">&B::f</span></tt> is stored in the vtable pointer. In
+this way, the vtable in B’s virtual table object is compatible with A’s vtable.</p>
+<p>D is a little more complicated, due to the use of multiple inheritance. Its
+virtual table object contains two vtables, one compatible with A’s vtable and
+the other compatible with C’s vtable. Objects of type D contain two virtual
+pointers, one belonging to the A subobject and containing the address of
+the vtable compatible with A’s vtable, and the other belonging to the C
+subobject and containing the address of the vtable compatible with C’s vtable.</p>
+<p>The full set of compatibility information for the above class hierarchy is
+shown below. The following table shows the name of a class, the offset of an
+address point within that class’s vtable and the name of one of the classes
+with which that address point is compatible.</p>
+<table border="1" class="docutils">
+<caption>Type Offsets for A, B, C, D</caption>
+<colgroup>
+<col width="33%" />
+<col width="33%" />
+<col width="33%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">VTable for</th>
+<th class="head">Offset</th>
+<th class="head">Compatible Class</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>A</td>
+<td>16</td>
+<td>A</td>
+</tr>
+<tr class="row-odd"><td>B</td>
+<td>16</td>
+<td>A</td>
+</tr>
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>B</td>
+</tr>
+<tr class="row-odd"><td>C</td>
+<td>16</td>
+<td>C</td>
+</tr>
+<tr class="row-even"><td>D</td>
+<td>16</td>
+<td>A</td>
+</tr>
+<tr class="row-odd"><td> </td>
+<td> </td>
+<td>D</td>
+</tr>
+<tr class="row-even"><td> </td>
+<td>48</td>
+<td>C</td>
+</tr>
+</tbody>
+</table>
+<p>The next step is to encode this compatibility information into the IR. The way
+this is done is to create type metadata named after each of the compatible
+classes, with which we associate each of the compatible address points in
+each vtable. For example, these type metadata entries encode the compatibility
+information for the above hierarchy:</p>
+<div class="highlight-python"><div class="highlight"><pre>@_ZTV1A = constant [...], !type !0
+ at _ZTV1B = constant [...], !type !0, !type !1
+ at _ZTV1C = constant [...], !type !2
+ at _ZTV1D = constant [...], !type !0, !type !3, !type !4
+
+!0 = !{i64 16, !"_ZTS1A"}
+!1 = !{i64 16, !"_ZTS1B"}
+!2 = !{i64 16, !"_ZTS1C"}
+!3 = !{i64 16, !"_ZTS1D"}
+!4 = !{i64 48, !"_ZTS1C"}
+</pre></div>
+</div>
+<p>With this type metadata, we can now use the <tt class="docutils literal"><span class="pre">llvm.type.test</span></tt> intrinsic to
+test whether a given pointer is compatible with a type identifier. Working
+backwards, if <tt class="docutils literal"><span class="pre">llvm.type.test</span></tt> returns true for a particular pointer,
+we can also statically determine the identities of the virtual functions
+that a particular virtual call may call. For example, if a program assumes
+a pointer to be a member of <tt class="docutils literal"><span class="pre">!"_ZST1A"</span></tt>, we know that the address can
+be only be one of <tt class="docutils literal"><span class="pre">_ZTV1A+16</span></tt>, <tt class="docutils literal"><span class="pre">_ZTV1B+16</span></tt> or <tt class="docutils literal"><span class="pre">_ZTV1D+16</span></tt> (i.e. the
+address points of the vtables of A, B and D respectively). If we then load
+an address from that pointer, we know that the address can only be one of
+<tt class="docutils literal"><span class="pre">&A::f</span></tt>, <tt class="docutils literal"><span class="pre">&B::f</span></tt> or <tt class="docutils literal"><span class="pre">&D::f</span></tt>.</p>
+</div>
+<div class="section" id="testing-addresses-for-type-membership">
+<h2>Testing Addresses For Type Membership<a class="headerlink" href="#testing-addresses-for-type-membership" title="Permalink to this headline">¶</a></h2>
+<p>If a program tests an address using <tt class="docutils literal"><span class="pre">llvm.type.test</span></tt>, this will cause
+a link-time optimization pass, <tt class="docutils literal"><span class="pre">LowerTypeTests</span></tt>, to replace calls to this
+intrinsic with efficient code to perform type member tests. At a high level,
+the pass will lay out referenced globals in a consecutive memory region in
+the object file, construct bit vectors that map onto that memory region,
+and generate code at each of the <tt class="docutils literal"><span class="pre">llvm.type.test</span></tt> call sites to test
+pointers against those bit vectors. Because of the layout manipulation, the
+globals’ definitions must be available at LTO time. For more information,
+see the <a class="reference external" href="http://clang.llvm.org/docs/ControlFlowIntegrityDesign.html">control flow integrity design document</a>.</p>
+<p>A type identifier that identifies functions is transformed into a jump table,
+which is a block of code consisting of one branch instruction for each
+of the functions associated with the type identifier that branches to the
+target function. The pass will redirect any taken function addresses to the
+corresponding jump table entry. In the object file’s symbol table, the jump
+table entries take the identities of the original functions, so that addresses
+taken outside the module will pass any verification done inside the module.</p>
+<p>Jump tables may call external functions, so their definitions need not
+be available at LTO time. Note that if an externally defined function is
+associated with a type identifier, there is no guarantee that its identity
+within the module will be the same as its identity outside of the module,
+as the former will be the jump table entry if a jump table is necessary.</p>
+<p>The <a class="reference external" href="http://llvm.org/klaus/llvm/blob/master/include/llvm/Transforms/IPO/LowerTypeTests.h">GlobalLayoutBuilder</a> class is responsible for laying out the globals
+efficiently to minimize the sizes of the underlying bitsets.</p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"></td>
+</tr>
+</tbody>
+</table>
+<div class="highlight-python"><div class="highlight"><pre>target datalayout = "e-p:32:32"
+
+ at a = internal global i32 0, !type !0
+ at b = internal global i32 0, !type !0, !type !1
+ at c = internal global i32 0, !type !1
+ at d = internal global [2 x i32] [i32 0, i32 0], !type !2
+
+define void @e() !type !3 {
+ ret void
+}
+
+define void @f() {
+ ret void
+}
+
+declare void @g() !type !3
+
+!0 = !{i32 0, !"typeid1"}
+!1 = !{i32 0, !"typeid2"}
+!2 = !{i32 4, !"typeid2"}
+!3 = !{i32 0, !"typeid3"}
+
+declare i1 @llvm.type.test(i8* %ptr, metadata %typeid) nounwind readnone
+
+define i1 @foo(i32* %p) {
+ %pi8 = bitcast i32* %p to i8*
+ %x = call i1 @llvm.type.test(i8* %pi8, metadata !"typeid1")
+ ret i1 %x
+}
+
+define i1 @bar(i32* %p) {
+ %pi8 = bitcast i32* %p to i8*
+ %x = call i1 @llvm.type.test(i8* %pi8, metadata !"typeid2")
+ ret i1 %x
+}
+
+define i1 @baz(void ()* %p) {
+ %pi8 = bitcast void ()* %p to i8*
+ %x = call i1 @llvm.type.test(i8* %pi8, metadata !"typeid3")
+ ret i1 %x
+}
+
+define void @main() {
+ %a1 = call i1 @foo(i32* @a) ; returns 1
+ %b1 = call i1 @foo(i32* @b) ; returns 1
+ %c1 = call i1 @foo(i32* @c) ; returns 0
+ %a2 = call i1 @bar(i32* @a) ; returns 0
+ %b2 = call i1 @bar(i32* @b) ; returns 1
+ %c2 = call i1 @bar(i32* @c) ; returns 1
+ %d02 = call i1 @bar(i32* getelementptr ([2 x i32]* @d, i32 0, i32 0)) ; returns 0
+ %d12 = call i1 @bar(i32* getelementptr ([2 x i32]* @d, i32 0, i32 1)) ; returns 1
+ %e = call i1 @baz(void ()* @e) ; returns 1
+ %f = call i1 @baz(void ()* @f) ; returns 0
+ %g = call i1 @baz(void ()* @g) ; returns 1
+ ret void
+}
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="FaultMaps.html" title="FaultMaps and implicit checks"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="MergeFunctions.html" title="MergeFunctions pass, how it works"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/Vectorizers.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/Vectorizers.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/Vectorizers.html (added)
+++ www-releases/trunk/3.9.1/docs/Vectorizers.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,491 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Auto-Vectorization in LLVM — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="Writing an LLVM Backend" href="WritingAnLLVMBackend.html" />
+ <link rel="prev" title="Source Level Debugging with LLVM" href="SourceLevelDebugging.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="auto-vectorization-in-llvm">
+<h1>Auto-Vectorization in LLVM<a class="headerlink" href="#auto-vectorization-in-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#the-loop-vectorizer" id="id2">The Loop Vectorizer</a><ul>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a><ul>
+<li><a class="reference internal" href="#command-line-flags" id="id4">Command line flags</a></li>
+<li><a class="reference internal" href="#pragma-loop-hint-directives" id="id5">Pragma loop hint directives</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#diagnostics" id="id6">Diagnostics</a></li>
+<li><a class="reference internal" href="#features" id="id7">Features</a><ul>
+<li><a class="reference internal" href="#loops-with-unknown-trip-count" id="id8">Loops with unknown trip count</a></li>
+<li><a class="reference internal" href="#runtime-checks-of-pointers" id="id9">Runtime Checks of Pointers</a></li>
+<li><a class="reference internal" href="#reductions" id="id10">Reductions</a></li>
+<li><a class="reference internal" href="#inductions" id="id11">Inductions</a></li>
+<li><a class="reference internal" href="#if-conversion" id="id12">If Conversion</a></li>
+<li><a class="reference internal" href="#pointer-induction-variables" id="id13">Pointer Induction Variables</a></li>
+<li><a class="reference internal" href="#reverse-iterators" id="id14">Reverse Iterators</a></li>
+<li><a class="reference internal" href="#scatter-gather" id="id15">Scatter / Gather</a></li>
+<li><a class="reference internal" href="#vectorization-of-mixed-types" id="id16">Vectorization of Mixed Types</a></li>
+<li><a class="reference internal" href="#global-structures-alias-analysis" id="id17">Global Structures Alias Analysis</a></li>
+<li><a class="reference internal" href="#vectorization-of-function-calls" id="id18">Vectorization of function calls</a></li>
+<li><a class="reference internal" href="#partial-unrolling-during-vectorization" id="id19">Partial unrolling during vectorization</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#performance" id="id20">Performance</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-slp-vectorizer" id="id21">The SLP Vectorizer</a><ul>
+<li><a class="reference internal" href="#details" id="id22">Details</a></li>
+<li><a class="reference internal" href="#id1" id="id23">Usage</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<p>LLVM has two vectorizers: The <a class="reference internal" href="#loop-vectorizer"><em>Loop Vectorizer</em></a>,
+which operates on Loops, and the <a class="reference internal" href="#slp-vectorizer"><em>SLP Vectorizer</em></a>. These vectorizers
+focus on different optimization opportunities and use different techniques.
+The SLP vectorizer merges multiple scalars that are found in the code into
+vectors while the Loop Vectorizer widens instructions in loops
+to operate on multiple consecutive iterations.</p>
+<p>Both the Loop Vectorizer and the SLP Vectorizer are enabled by default.</p>
+<div class="section" id="the-loop-vectorizer">
+<span id="loop-vectorizer"></span><h2><a class="toc-backref" href="#id2">The Loop Vectorizer</a><a class="headerlink" href="#the-loop-vectorizer" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="usage">
+<h3><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h3>
+<p>The Loop Vectorizer is enabled by default, but it can be disabled
+through clang using the command line flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang ... -fno-vectorize file.c
+</pre></div>
+</div>
+<div class="section" id="command-line-flags">
+<h4><a class="toc-backref" href="#id4">Command line flags</a><a class="headerlink" href="#command-line-flags" title="Permalink to this headline">¶</a></h4>
+<p>The loop vectorizer uses a cost model to decide on the optimal vectorization factor
+and unroll factor. However, users of the vectorizer can force the vectorizer to use
+specific values. Both ‘clang’ and ‘opt’ support the flags below.</p>
+<p>Users can control the vectorization SIMD width using the command line flag “-force-vector-width”.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -mllvm -force-vector-width<span class="o">=</span>8 ...
+<span class="gp">$</span> opt -loop-vectorize -force-vector-width<span class="o">=</span>8 ...
+</pre></div>
+</div>
+<p>Users can control the unroll factor using the command line flag “-force-vector-unroll”</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -mllvm -force-vector-unroll<span class="o">=</span>2 ...
+<span class="gp">$</span> opt -loop-vectorize -force-vector-unroll<span class="o">=</span>2 ...
+</pre></div>
+</div>
+</div>
+<div class="section" id="pragma-loop-hint-directives">
+<h4><a class="toc-backref" href="#id5">Pragma loop hint directives</a><a class="headerlink" href="#pragma-loop-hint-directives" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span></tt> directive allows loop vectorization hints to be
+specified for the subsequent for, while, do-while, or c++11 range-based for
+loop. The directive allows vectorization and interleaving to be enabled or
+disabled. Vector width as well as interleave count can also be manually
+specified. The following example explicitly enables vectorization and
+interleaving:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma clang loop vectorize(enable) interleave(enable)</span>
+<span class="k">while</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The following example implicitly enables vectorization and interleaving by
+specifying a vector width and interleaving count:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma clang loop vectorize_width(2) interleave_count(2)</span>
+<span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>See the Clang
+<a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations">language extensions</a>
+for details.</p>
+</div>
+</div>
+<div class="section" id="diagnostics">
+<h3><a class="toc-backref" href="#id6">Diagnostics</a><a class="headerlink" href="#diagnostics" title="Permalink to this headline">¶</a></h3>
+<p>Many loops cannot be vectorized including loops with complicated control flow,
+unvectorizable types, and unvectorizable calls. The loop vectorizer generates
+optimization remarks which can be queried using command line options to identify
+and diagnose loops that are skipped by the loop-vectorizer.</p>
+<p>Optimization remarks are enabled using:</p>
+<p><tt class="docutils literal"><span class="pre">-Rpass=loop-vectorize</span></tt> identifies loops that were successfully vectorized.</p>
+<p><tt class="docutils literal"><span class="pre">-Rpass-missed=loop-vectorize</span></tt> identifies loops that failed vectorization and
+indicates if vectorization was specified.</p>
+<p><tt class="docutils literal"><span class="pre">-Rpass-analysis=loop-vectorize</span></tt> identifies the statements that caused
+vectorization to fail.</p>
+<p>Consider the following loop:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma clang loop vectorize(enable)</span>
+<span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">Length</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">switch</span><span class="p">(</span><span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">])</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="mi">0</span>: <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="o">*</span><span class="mi">2</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="mi">1</span>: <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="nl">default:</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The command line <tt class="docutils literal"><span class="pre">-Rpass-missed=loop-vectorized</span></tt> prints the remark:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">no_switch.cpp:4:5: remark: loop not vectorized: vectorization is explicitly enabled [-Rpass-missed=loop-vectorize]</span>
+</pre></div>
+</div>
+<p>And the command line <tt class="docutils literal"><span class="pre">-Rpass-analysis=loop-vectorize</span></tt> indicates that the
+switch statement cannot be vectorized.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">no_switch.cpp:4:5: remark: loop not vectorized: loop contains a switch statement [-Rpass-analysis=loop-vectorize]</span>
+<span class="go"> switch(A[i]) {</span>
+<span class="go"> ^</span>
+</pre></div>
+</div>
+<p>To ensure line and column numbers are produced include the command line options
+<tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> and <tt class="docutils literal"><span class="pre">-gcolumn-info</span></tt>. See the Clang <a class="reference external" href="http://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports">user manual</a>
+for details</p>
+</div>
+<div class="section" id="features">
+<h3><a class="toc-backref" href="#id7">Features</a><a class="headerlink" href="#features" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM Loop Vectorizer has a number of features that allow it to vectorize
+complex loops.</p>
+<div class="section" id="loops-with-unknown-trip-count">
+<h4><a class="toc-backref" href="#id8">Loops with unknown trip count</a><a class="headerlink" href="#loops-with-unknown-trip-count" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer supports loops with an unknown trip count.
+In the loop below, the iteration <tt class="docutils literal"><span class="pre">start</span></tt> and <tt class="docutils literal"><span class="pre">finish</span></tt> points are unknown,
+and the Loop Vectorizer has a mechanism to vectorize loops that do not start
+at zero. In this example, ‘n’ may not be a multiple of the vector width, and
+the vectorizer has to execute the last few iterations as scalar code. Keeping
+a scalar copy of the loop increases the code size.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</span><span class="p">,</span> <span class="kt">int</span> <span class="n">start</span><span class="p">,</span> <span class="kt">int</span> <span class="n">end</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">start</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">end</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="n">K</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="runtime-checks-of-pointers">
+<h4><a class="toc-backref" href="#id9">Runtime Checks of Pointers</a><a class="headerlink" href="#runtime-checks-of-pointers" title="Permalink to this headline">¶</a></h4>
+<p>In the example below, if the pointers A and B point to consecutive addresses,
+then it is illegal to vectorize the code because some elements of A will be
+written before they are read from array B.</p>
+<p>Some programmers use the ‘restrict’ keyword to notify the compiler that the
+pointers are disjointed, but in our example, the Loop Vectorizer has no way of
+knowing that the pointers A and B are unique. The Loop Vectorizer handles this
+loop by placing code that checks, at runtime, if the arrays A and B point to
+disjointed memory locations. If arrays A and B overlap, then the scalar version
+of the loop is executed.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="n">K</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="reductions">
+<h4><a class="toc-backref" href="#id10">Reductions</a><a class="headerlink" href="#reductions" title="Permalink to this headline">¶</a></h4>
+<p>In this example the <tt class="docutils literal"><span class="pre">sum</span></tt> variable is used by consecutive iterations of
+the loop. Normally, this would prevent vectorization, but the vectorizer can
+detect that ‘sum’ is a reduction variable. The variable ‘sum’ becomes a vector
+of integers, and at the end of the loop the elements of the array are added
+together to create the correct result. We support a number of different
+reduction operations, such as addition, multiplication, XOR, AND and OR.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">5</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>We support floating point reduction operations when <cite>-ffast-math</cite> is used.</p>
+</div>
+<div class="section" id="inductions">
+<h4><a class="toc-backref" href="#id11">Inductions</a><a class="headerlink" href="#inductions" title="Permalink to this headline">¶</a></h4>
+<p>In this example the value of the induction variable <tt class="docutils literal"><span class="pre">i</span></tt> is saved into an
+array. The Loop Vectorizer knows to vectorize induction variables.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="if-conversion">
+<h4><a class="toc-backref" href="#id12">If Conversion</a><a class="headerlink" href="#if-conversion" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer is able to “flatten” the IF statement in the code and
+generate a single stream of instructions. The Loop Vectorizer supports any
+control flow in the innermost loop. The innermost loop may contain complex
+nesting of IFs, ELSEs and even GOTOs.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">></span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
+ <span class="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">5</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pointer-induction-variables">
+<h4><a class="toc-backref" href="#id13">Pointer Induction Variables</a><a class="headerlink" href="#pointer-induction-variables" title="Permalink to this headline">¶</a></h4>
+<p>This example uses the “accumulate” function of the standard c++ library. This
+loop uses C++ iterators, which are pointers, and not integer indices.
+The Loop Vectorizer detects pointer induction variables and can vectorize
+this loop. This feature is important because many C++ programs use iterators.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">baz</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">accumulate</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">A</span> <span class="o">+</span> <span class="n">n</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="reverse-iterators">
+<h4><a class="toc-backref" href="#id14">Reverse Iterators</a><a class="headerlink" href="#reverse-iterators" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize loops that count backwards.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">n</span><span class="p">;</span> <span class="n">i</span> <span class="o">></span> <span class="mi">0</span><span class="p">;</span> <span class="o">--</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span><span class="mi">1</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="scatter-gather">
+<h4><a class="toc-backref" href="#id15">Scatter / Gather</a><a class="headerlink" href="#scatter-gather" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize code that becomes a sequence of scalar instructions
+that scatter/gathers memory.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">intptr_t</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span> <span class="o">*</span> <span class="mi">4</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In many situations the cost model will inform LLVM that this is not beneficial
+and LLVM will only vectorize such code if forced with “-mllvm -force-vector-width=#”.</p>
+</div>
+<div class="section" id="vectorization-of-mixed-types">
+<h4><a class="toc-backref" href="#id16">Vectorization of Mixed Types</a><a class="headerlink" href="#vectorization-of-mixed-types" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize programs with mixed types. The Vectorizer
+cost model can estimate the cost of the type conversion and decide if
+vectorization is profitable.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">,</span> <span class="kt">int</span> <span class="n">k</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span> <span class="mi">4</span> <span class="o">*</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="global-structures-alias-analysis">
+<h4><a class="toc-backref" href="#id17">Global Structures Alias Analysis</a><a class="headerlink" href="#global-structures-alias-analysis" title="Permalink to this headline">¶</a></h4>
+<p>Access to global structures can also be vectorized, with alias analysis being
+used to make sure accesses don’t alias. Run-time checks can also be added on
+pointer access to structure members.</p>
+<p>Many variations are supported, but some that rely on undefined behaviour being
+ignored (as other compilers do) are still being left un-vectorized.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">A</span><span class="p">[</span><span class="mi">100</span><span class="p">],</span> <span class="n">K</span><span class="p">,</span> <span class="n">B</span><span class="p">[</span><span class="mi">100</span><span class="p">];</span> <span class="p">}</span> <span class="n">Foo</span><span class="p">;</span>
+
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="mi">100</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Foo</span><span class="p">.</span><span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">Foo</span><span class="p">.</span><span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">100</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="vectorization-of-function-calls">
+<h4><a class="toc-backref" href="#id18">Vectorization of function calls</a><a class="headerlink" href="#vectorization-of-function-calls" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorize can vectorize intrinsic math functions.
+See the table below for a list of these functions.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="26%" />
+<col width="26%" />
+<col width="47%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>pow</td>
+<td>exp</td>
+<td>exp2</td>
+</tr>
+<tr class="row-even"><td>sin</td>
+<td>cos</td>
+<td>sqrt</td>
+</tr>
+<tr class="row-odd"><td>log</td>
+<td>log2</td>
+<td>log10</td>
+</tr>
+<tr class="row-even"><td>fabs</td>
+<td>floor</td>
+<td>ceil</td>
+</tr>
+<tr class="row-odd"><td>fma</td>
+<td>trunc</td>
+<td>nearbyint</td>
+</tr>
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>fmuladd</td>
+</tr>
+</tbody>
+</table>
+<p>The loop vectorizer knows about special instructions on the target and will
+vectorize a loop containing a function call that maps to the instructions. For
+example, the loop below will be vectorized on Intel x86 if the SSE4.1 roundps
+instruction is available.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">f</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="mi">1024</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">f</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">floorf</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="partial-unrolling-during-vectorization">
+<h4><a class="toc-backref" href="#id19">Partial unrolling during vectorization</a><a class="headerlink" href="#partial-unrolling-during-vectorization" title="Permalink to this headline">¶</a></h4>
+<p>Modern processors feature multiple execution units, and only programs that contain a
+high degree of parallelism can fully utilize the entire width of the machine.
+The Loop Vectorizer increases the instruction level parallelism (ILP) by
+performing partial-unrolling of loops.</p>
+<p>In the example below the entire array is accumulated into the variable ‘sum’.
+This is inefficient because only a single execution port can be used by the processor.
+By unrolling the code the Loop Vectorizer allows two or more execution ports
+to be used simultaneously.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The Loop Vectorizer uses a cost model to decide when it is profitable to unroll loops.
+The decision to unroll the loop depends on the register pressure and the generated code size.</p>
+</div>
+</div>
+<div class="section" id="performance">
+<h3><a class="toc-backref" href="#id20">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h3>
+<p>This section shows the execution time of Clang on a simple benchmark:
+<a class="reference external" href="http://llvm.org/viewvc/llvm-project/test-suite/trunk/SingleSource/UnitTests/Vectorizer/">gcc-loops</a>.
+This benchmarks is a collection of loops from the GCC autovectorization
+<a class="reference external" href="http://gcc.gnu.org/projects/tree-ssa/vectorization.html">page</a> by Dorit Nuzman.</p>
+<p>The chart below compares GCC-4.7, ICC-13, and Clang-SVN with and without loop vectorization at -O3, tuned for “corei7-avx”, running on a Sandybridge iMac.
+The Y-axis shows the time in msec. Lower is better. The last column shows the geomean of all the kernels.</p>
+<img alt="_images/gcc-loops.png" src="_images/gcc-loops.png" />
+<p>And Linpack-pc with the same configuration. Result is Mflops, higher is better.</p>
+<img alt="_images/linpack-pc.png" src="_images/linpack-pc.png" />
+</div>
+</div>
+<div class="section" id="the-slp-vectorizer">
+<span id="slp-vectorizer"></span><h2><a class="toc-backref" href="#id21">The SLP Vectorizer</a><a class="headerlink" href="#the-slp-vectorizer" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="details">
+<h3><a class="toc-backref" href="#id22">Details</a><a class="headerlink" href="#details" title="Permalink to this headline">¶</a></h3>
+<p>The goal of SLP vectorization (a.k.a. superword-level parallelism) is
+to combine similar independent instructions
+into vector instructions. Memory accesses, arithmetic operations, comparison
+operations, PHI-nodes, can all be vectorized using this technique.</p>
+<p>For example, the following function performs very similar operations on its
+inputs (a1, b1) and (a2, b2). The basic-block vectorizer may combine these
+into vector operations.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">a1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">a2</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b2</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">A</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">a1</span><span class="o">*</span><span class="p">(</span><span class="n">a1</span> <span class="o">+</span> <span class="n">b1</span><span class="p">)</span><span class="o">/</span><span class="n">b1</span> <span class="o">+</span> <span class="mi">50</span><span class="o">*</span><span class="n">b1</span><span class="o">/</span><span class="n">a1</span><span class="p">;</span>
+ <span class="n">A</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">a2</span><span class="o">*</span><span class="p">(</span><span class="n">a2</span> <span class="o">+</span> <span class="n">b2</span><span class="p">)</span><span class="o">/</span><span class="n">b2</span> <span class="o">+</span> <span class="mi">50</span><span class="o">*</span><span class="n">b2</span><span class="o">/</span><span class="n">a2</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The SLP-vectorizer processes the code bottom-up, across basic blocks, in search of scalars to combine.</p>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id23">Usage</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>The SLP Vectorizer is enabled by default, but it can be disabled
+through clang using the command line flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -fno-slp-vectorize file.c
+</pre></div>
+</div>
+<p>LLVM has a second basic block vectorization phase
+which is more compile-time intensive (The BB vectorizer). This optimization
+can be enabled through clang using the command line flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -fslp-vectorize-aggressive file.c
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/WritingAnLLVMBackend.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/WritingAnLLVMBackend.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/WritingAnLLVMBackend.html (added)
+++ www-releases/trunk/3.9.1/docs/WritingAnLLVMBackend.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,1822 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Writing an LLVM Backend — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="How To Use Instruction Mappings" href="HowToUseInstrMappings.html" />
+ <link rel="prev" title="Auto-Vectorization in LLVM" href="Vectorizers.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="writing-an-llvm-backend">
+<h1>Writing an LLVM Backend<a class="headerlink" href="#writing-an-llvm-backend" title="Permalink to this headline">¶</a></h1>
+<div class="toctree-wrapper compound">
+</div>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a><ul>
+<li><a class="reference internal" href="#audience" id="id4">Audience</a></li>
+<li><a class="reference internal" href="#prerequisite-reading" id="id5">Prerequisite Reading</a></li>
+<li><a class="reference internal" href="#basic-steps" id="id6">Basic Steps</a></li>
+<li><a class="reference internal" href="#preliminaries" id="id7">Preliminaries</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-machine" id="id8">Target Machine</a></li>
+<li><a class="reference internal" href="#target-registration" id="id9">Target Registration</a></li>
+<li><a class="reference internal" href="#register-set-and-register-classes" id="id10">Register Set and Register Classes</a><ul>
+<li><a class="reference internal" href="#defining-a-register" id="id11">Defining a Register</a></li>
+<li><a class="reference internal" href="#defining-a-register-class" id="id12">Defining a Register Class</a></li>
+<li><a class="reference internal" href="#implement-a-subclass-of-targetregisterinfo" id="id13">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instruction-set" id="id14">Instruction Set</a><ul>
+<li><a class="reference internal" href="#instruction-operand-mapping" id="id15">Instruction Operand Mapping</a><ul>
+<li><a class="reference internal" href="#instruction-operand-name-mapping" id="id16">Instruction Operand Name Mapping</a></li>
+<li><a class="reference internal" href="#instruction-operand-types" id="id17">Instruction Operand Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instruction-scheduling" id="id18">Instruction Scheduling</a></li>
+<li><a class="reference internal" href="#instruction-relation-mapping" id="id19">Instruction Relation Mapping</a></li>
+<li><a class="reference internal" href="#implement-a-subclass-of-targetinstrinfo" id="id20">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt></a></li>
+<li><a class="reference internal" href="#branch-folding-and-if-conversion" id="id21">Branch Folding and If Conversion</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instruction-selector" id="id22">Instruction Selector</a><ul>
+<li><a class="reference internal" href="#the-selectiondag-legalize-phase" id="id23">The SelectionDAG Legalize Phase</a><ul>
+<li><a class="reference internal" href="#promote" id="id24">Promote</a></li>
+<li><a class="reference internal" href="#expand" id="id25">Expand</a></li>
+<li><a class="reference internal" href="#custom" id="id26">Custom</a></li>
+<li><a class="reference internal" href="#legal" id="id27">Legal</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#calling-conventions" id="id28">Calling Conventions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#assembly-printer" id="id29">Assembly Printer</a></li>
+<li><a class="reference internal" href="#subtarget-support" id="id30">Subtarget Support</a></li>
+<li><a class="reference internal" href="#jit-support" id="id31">JIT Support</a><ul>
+<li><a class="reference internal" href="#machine-code-emitter" id="id32">Machine Code Emitter</a></li>
+<li><a class="reference internal" href="#target-jit-info" id="id33">Target JIT Info</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes techniques for writing compiler backends that convert
+the LLVM Intermediate Representation (IR) to code for a specified machine or
+other languages. Code intended for a specific machine can take the form of
+either assembly code or binary code (usable for a JIT compiler).</p>
+<p>The backend of LLVM features a target-independent code generator that may
+create output for several types of target CPUs — including X86, PowerPC,
+ARM, and SPARC. The backend may also be used to generate code targeted at SPUs
+of the Cell processor or GPUs to support the execution of compute kernels.</p>
+<p>The document focuses on existing examples found in subdirectories of
+<tt class="docutils literal"><span class="pre">llvm/lib/Target</span></tt> in a downloaded LLVM release. In particular, this document
+focuses on the example of creating a static compiler (one that emits text
+assembly) for a SPARC target, because SPARC has fairly standard
+characteristics, such as a RISC instruction set and straightforward calling
+conventions.</p>
+<div class="section" id="audience">
+<h3><a class="toc-backref" href="#id4">Audience</a><a class="headerlink" href="#audience" title="Permalink to this headline">¶</a></h3>
+<p>The audience for this document is anyone who needs to write an LLVM backend to
+generate code for a specific hardware or software target.</p>
+</div>
+<div class="section" id="prerequisite-reading">
+<h3><a class="toc-backref" href="#id5">Prerequisite Reading</a><a class="headerlink" href="#prerequisite-reading" title="Permalink to this headline">¶</a></h3>
+<p>These essential documents must be read before reading this document:</p>
+<ul class="simple">
+<li><a class="reference external" href="LangRef.html">LLVM Language Reference Manual</a> — a reference manual for
+the LLVM assembly language.</li>
+<li><a class="reference internal" href="CodeGenerator.html"><em>The LLVM Target-Independent Code Generator</em></a> — a guide to the components (classes and code
+generation algorithms) for translating the LLVM internal representation into
+machine code for a specified target. Pay particular attention to the
+descriptions of code generation stages: Instruction Selection, Scheduling and
+Formation, SSA-based Optimization, Register Allocation, Prolog/Epilog Code
+Insertion, Late Machine Code Optimizations, and Code Emission.</li>
+<li><a class="reference internal" href="TableGen/index.html"><em>TableGen</em></a> — a document that describes the TableGen
+(<tt class="docutils literal"><span class="pre">tblgen</span></tt>) application that manages domain-specific information to support
+LLVM code generation. TableGen processes input from a target description
+file (<tt class="docutils literal"><span class="pre">.td</span></tt> suffix) and generates C++ code that can be used for code
+generation.</li>
+<li><a class="reference internal" href="WritingAnLLVMPass.html"><em>Writing an LLVM Pass</em></a> — The assembly printer is a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, as
+are several <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> processing steps.</li>
+</ul>
+<p>To follow the SPARC examples in this document, have a copy of <a class="reference external" href="http://www.sparc.org/standards/V8.pdf">The SPARC
+Architecture Manual, Version 8</a> for
+reference. For details about the ARM instruction set, refer to the <a class="reference external" href="http://infocenter.arm.com/">ARM
+Architecture Reference Manual</a>. For more about
+the GNU Assembler format (<tt class="docutils literal"><span class="pre">GAS</span></tt>), see <a class="reference external" href="http://sourceware.org/binutils/docs/as/index.html">Using As</a>, especially for the
+assembly printer. “Using As” contains a list of target machine dependent
+features.</p>
+</div>
+<div class="section" id="basic-steps">
+<h3><a class="toc-backref" href="#id6">Basic Steps</a><a class="headerlink" href="#basic-steps" title="Permalink to this headline">¶</a></h3>
+<p>To write a compiler backend for LLVM that converts the LLVM IR to code for a
+specified target (machine or other language), follow these steps:</p>
+<ul class="simple">
+<li>Create a subclass of the <tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class that describes
+characteristics of your target machine. Copy existing examples of specific
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class and header files; for example, start with
+<tt class="docutils literal"><span class="pre">SparcTargetMachine.cpp</span></tt> and <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt>, but change the file
+names for your target. Similarly, change code that references “<tt class="docutils literal"><span class="pre">Sparc</span></tt>” to
+reference your target.</li>
+<li>Describe the register set of the target. Use TableGen to generate code for
+register definition, register aliases, and register classes from a
+target-specific <tt class="docutils literal"><span class="pre">RegisterInfo.td</span></tt> input file. You should also write
+additional code for a subclass of the <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt> class that
+represents the class register file data used for register allocation and also
+describes the interactions between registers.</li>
+<li>Describe the instruction set of the target. Use TableGen to generate code
+for target-specific instructions from target-specific versions of
+<tt class="docutils literal"><span class="pre">TargetInstrFormats.td</span></tt> and <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. You should write
+additional code for a subclass of the <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt> class to represent
+machine instructions supported by the target machine.</li>
+<li>Describe the selection and conversion of the LLVM IR from a Directed Acyclic
+Graph (DAG) representation of instructions to native target-specific
+instructions. Use TableGen to generate code that matches patterns and
+selects instructions based on additional information in a target-specific
+version of <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. Write code for <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt>,
+where <tt class="docutils literal"><span class="pre">XXX</span></tt> identifies the specific target, to perform pattern matching and
+DAG-to-DAG instruction selection. Also write code in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>
+to replace or remove operations and data types that are not supported
+natively in a SelectionDAG.</li>
+<li>Write code for an assembly printer that converts LLVM IR to a GAS format for
+your target machine. You should add assembly strings to the instructions
+defined in your target-specific version of <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. You
+should also write code for a subclass of <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> that performs the
+LLVM-to-assembly conversion and a trivial subclass of <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt>.</li>
+<li>Optionally, add support for subtargets (i.e., variants with different
+capabilities). You should also write code for a subclass of the
+<tt class="docutils literal"><span class="pre">TargetSubtarget</span></tt> class, which allows you to use the <tt class="docutils literal"><span class="pre">-mcpu=</span></tt> and
+<tt class="docutils literal"><span class="pre">-mattr=</span></tt> command-line options.</li>
+<li>Optionally, add JIT support and create a machine code emitter (subclass of
+<tt class="docutils literal"><span class="pre">TargetJITInfo</span></tt>) that is used to emit binary code directly into memory.</li>
+</ul>
+<p>In the <tt class="docutils literal"><span class="pre">.cpp</span></tt> and <tt class="docutils literal"><span class="pre">.h</span></tt>. files, initially stub up these methods and then
+implement them later. Initially, you may not know which private members that
+the class will need and which components will need to be subclassed.</p>
+</div>
+<div class="section" id="preliminaries">
+<h3><a class="toc-backref" href="#id7">Preliminaries</a><a class="headerlink" href="#preliminaries" title="Permalink to this headline">¶</a></h3>
+<p>To actually create your compiler backend, you need to create and modify a few
+files. The absolute minimum is discussed here. But to actually use the LLVM
+target-independent code generator, you must perform the steps described in the
+<a class="reference internal" href="CodeGenerator.html"><em>LLVM Target-Independent Code Generator</em></a> document.</p>
+<p>First, you should create a subdirectory under <tt class="docutils literal"><span class="pre">lib/Target</span></tt> to hold all the
+files related to your target. If your target is called “Dummy”, create the
+directory <tt class="docutils literal"><span class="pre">lib/Target/Dummy</span></tt>.</p>
+<p>In this new directory, create a <tt class="docutils literal"><span class="pre">CMakeLists.txt</span></tt>. It is easiest to copy a
+<tt class="docutils literal"><span class="pre">CMakeLists.txt</span></tt> of another target and modify it. It should at least contain
+the <tt class="docutils literal"><span class="pre">LLVM_TARGET_DEFINITIONS</span></tt> variable. The library can be named <tt class="docutils literal"><span class="pre">LLVMDummy</span></tt>
+(for example, see the MIPS target). Alternatively, you can split the library
+into <tt class="docutils literal"><span class="pre">LLVMDummyCodeGen</span></tt> and <tt class="docutils literal"><span class="pre">LLVMDummyAsmPrinter</span></tt>, the latter of which
+should be implemented in a subdirectory below <tt class="docutils literal"><span class="pre">lib/Target/Dummy</span></tt> (for example,
+see the PowerPC target).</p>
+<p>Note that these two naming schemes are hardcoded into <tt class="docutils literal"><span class="pre">llvm-config</span></tt>. Using
+any other naming scheme will confuse <tt class="docutils literal"><span class="pre">llvm-config</span></tt> and produce a lot of
+(seemingly unrelated) linker errors when linking <tt class="docutils literal"><span class="pre">llc</span></tt>.</p>
+<p>To make your target actually do something, you need to implement a subclass of
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt>. This implementation should typically be in the file
+<tt class="docutils literal"><span class="pre">lib/Target/DummyTargetMachine.cpp</span></tt>, but any file in the <tt class="docutils literal"><span class="pre">lib/Target</span></tt>
+directory will be built and should work. To use LLVM’s target independent code
+generator, you should do what all current machine backends do: create a
+subclass of <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt>. (To create a target from scratch, create a
+subclass of <tt class="docutils literal"><span class="pre">TargetMachine</span></tt>.)</p>
+<p>To get LLVM to actually build and link your target, you need to run <tt class="docutils literal"><span class="pre">cmake</span></tt>
+with <tt class="docutils literal"><span class="pre">-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=Dummy</span></tt>. This will build your
+target without needing to add it to the list of all the targets.</p>
+<p>Once your target is stable, you can add it to the <tt class="docutils literal"><span class="pre">LLVM_ALL_TARGETS</span></tt> variable
+located in the main <tt class="docutils literal"><span class="pre">CMakeLists.txt</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="target-machine">
+<h2><a class="toc-backref" href="#id8">Target Machine</a><a class="headerlink" href="#target-machine" title="Permalink to this headline">¶</a></h2>
+<p><tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> is designed as a base class for targets implemented with
+the LLVM target-independent code generator. The <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> class
+should be specialized by a concrete target class that implements the various
+virtual methods. <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> is defined as a subclass of
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> in <tt class="docutils literal"><span class="pre">include/llvm/Target/TargetMachine.h</span></tt>. The
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class implementation (<tt class="docutils literal"><span class="pre">TargetMachine.cpp</span></tt>) also processes
+numerous command-line options.</p>
+<p>To create a concrete target-specific subclass of <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt>, start
+by copying an existing <tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class and header. You should name the
+files that you create to reflect your specific target. For instance, for the
+SPARC target, name the files <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt> and
+<tt class="docutils literal"><span class="pre">SparcTargetMachine.cpp</span></tt>.</p>
+<p>For a target machine <tt class="docutils literal"><span class="pre">XXX</span></tt>, the implementation of <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> must
+have access methods to obtain objects that represent target components. These
+methods are named <tt class="docutils literal"><span class="pre">get*Info</span></tt>, and are intended to obtain the instruction set
+(<tt class="docutils literal"><span class="pre">getInstrInfo</span></tt>), register set (<tt class="docutils literal"><span class="pre">getRegisterInfo</span></tt>), stack frame layout
+(<tt class="docutils literal"><span class="pre">getFrameInfo</span></tt>), and similar information. <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> must also
+implement the <tt class="docutils literal"><span class="pre">getDataLayout</span></tt> method to access an object with target-specific
+data characteristics, such as data type size and alignment requirements.</p>
+<p>For instance, for the SPARC target, the header file <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt>
+declares prototypes for several <tt class="docutils literal"><span class="pre">get*Info</span></tt> and <tt class="docutils literal"><span class="pre">getDataLayout</span></tt> methods that
+simply return a class member.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
+
+<span class="k">class</span> <span class="nc">Module</span><span class="p">;</span>
+
+<span class="k">class</span> <span class="nc">SparcTargetMachine</span> <span class="o">:</span> <span class="k">public</span> <span class="n">LLVMTargetMachine</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="n">DataLayout</span> <span class="n">DataLayout</span><span class="p">;</span> <span class="c1">// Calculates type size & alignment</span>
+ <span class="n">SparcSubtarget</span> <span class="n">Subtarget</span><span class="p">;</span>
+ <span class="n">SparcInstrInfo</span> <span class="n">InstrInfo</span><span class="p">;</span>
+ <span class="n">TargetFrameInfo</span> <span class="n">FrameInfo</span><span class="p">;</span>
+
+<span class="nl">protected:</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetAsmInfo</span> <span class="o">*</span><span class="n">createTargetAsmInfo</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+ <span class="n">SparcTargetMachine</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">,</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">FS</span><span class="p">);</span>
+
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">SparcInstrInfo</span> <span class="o">*</span><span class="n">getInstrInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">InstrInfo</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetFrameInfo</span> <span class="o">*</span><span class="n">getFrameInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">FrameInfo</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetSubtarget</span> <span class="o">*</span><span class="n">getSubtargetImpl</span><span class="p">()</span> <span class="k">const</span><span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">Subtarget</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetRegisterInfo</span> <span class="o">*</span><span class="n">getRegisterInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="o">&</span><span class="n">InstrInfo</span><span class="p">.</span><span class="n">getRegisterInfo</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">DataLayout</span> <span class="o">*</span><span class="n">getDataLayout</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&</span><span class="n">DataLayout</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="kt">unsigned</span> <span class="n">getModuleMatchQuality</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+
+ <span class="c1">// Pass Pipeline Configuration</span>
+ <span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">addInstSelector</span><span class="p">(</span><span class="n">PassManagerBase</span> <span class="o">&</span><span class="n">PM</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">Fast</span><span class="p">);</span>
+ <span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">addPreEmitPass</span><span class="p">(</span><span class="n">PassManagerBase</span> <span class="o">&</span><span class="n">PM</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">Fast</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="p">}</span> <span class="c1">// end namespace llvm</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getInstrInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getRegisterInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getFrameInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getDataLayout()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getSubtargetImpl()</span></tt></li>
+</ul>
+<p>For some targets, you also need to support the following methods:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getTargetLowering()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getJITInfo()</span></tt></li>
+</ul>
+<p>Some architectures, such as GPUs, do not support jumping to an arbitrary
+program location and implement branching using masked execution and loop using
+special instructions around the loop body. In order to avoid CFG modifications
+that introduce irreducible control flow not handled by such hardware, a target
+must call <cite>setRequiresStructuredCFG(true)</cite> when being initialized.</p>
+<p>In addition, the <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> constructor should specify a
+<tt class="docutils literal"><span class="pre">TargetDescription</span></tt> string that determines the data layout for the target
+machine, including characteristics such as pointer size, alignment, and
+endianness. For example, the constructor for <tt class="docutils literal"><span class="pre">SparcTargetMachine</span></tt> contains
+the following:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SparcTargetMachine</span><span class="o">::</span><span class="n">SparcTargetMachine</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">,</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">FS</span><span class="p">)</span>
+ <span class="o">:</span> <span class="n">DataLayout</span><span class="p">(</span><span class="s">"E-p:32:32-f128:128:128"</span><span class="p">),</span>
+ <span class="n">Subtarget</span><span class="p">(</span><span class="n">M</span><span class="p">,</span> <span class="n">FS</span><span class="p">),</span> <span class="n">InstrInfo</span><span class="p">(</span><span class="n">Subtarget</span><span class="p">),</span>
+ <span class="n">FrameInfo</span><span class="p">(</span><span class="n">TargetFrameInfo</span><span class="o">::</span><span class="n">StackGrowsDown</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Hyphens separate portions of the <tt class="docutils literal"><span class="pre">TargetDescription</span></tt> string.</p>
+<ul class="simple">
+<li>An upper-case “<tt class="docutils literal"><span class="pre">E</span></tt>” in the string indicates a big-endian target data model.
+A lower-case “<tt class="docutils literal"><span class="pre">e</span></tt>” indicates little-endian.</li>
+<li>“<tt class="docutils literal"><span class="pre">p:</span></tt>” is followed by pointer information: size, ABI alignment, and
+preferred alignment. If only two figures follow “<tt class="docutils literal"><span class="pre">p:</span></tt>”, then the first
+value is pointer size, and the second value is both ABI and preferred
+alignment.</li>
+<li>Then a letter for numeric type alignment: “<tt class="docutils literal"><span class="pre">i</span></tt>”, “<tt class="docutils literal"><span class="pre">f</span></tt>”, “<tt class="docutils literal"><span class="pre">v</span></tt>”, or
+“<tt class="docutils literal"><span class="pre">a</span></tt>” (corresponding to integer, floating point, vector, or aggregate).
+“<tt class="docutils literal"><span class="pre">i</span></tt>”, “<tt class="docutils literal"><span class="pre">v</span></tt>”, or “<tt class="docutils literal"><span class="pre">a</span></tt>” are followed by ABI alignment and preferred
+alignment. “<tt class="docutils literal"><span class="pre">f</span></tt>” is followed by three values: the first indicates the size
+of a long double, then ABI alignment, and then ABI preferred alignment.</li>
+</ul>
+</div>
+<div class="section" id="target-registration">
+<h2><a class="toc-backref" href="#id9">Target Registration</a><a class="headerlink" href="#target-registration" title="Permalink to this headline">¶</a></h2>
+<p>You must also register your target with the <tt class="docutils literal"><span class="pre">TargetRegistry</span></tt>, which is what
+other LLVM tools use to be able to lookup and use your target at runtime. The
+<tt class="docutils literal"><span class="pre">TargetRegistry</span></tt> can be used directly, but for most targets there are helper
+templates which should take care of the work for you.</p>
+<p>All targets should declare a global <tt class="docutils literal"><span class="pre">Target</span></tt> object which is used to
+represent the target during registration. Then, in the target’s <tt class="docutils literal"><span class="pre">TargetInfo</span></tt>
+library, the target should define that object and use the <tt class="docutils literal"><span class="pre">RegisterTarget</span></tt>
+template to register the target. For example, the Sparc registration code
+looks like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Target</span> <span class="n">llvm</span><span class="o">::</span><span class="n">TheSparcTarget</span><span class="p">;</span>
+
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">LLVMInitializeSparcTargetInfo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">RegisterTarget</span><span class="o"><</span><span class="n">Triple</span><span class="o">::</span><span class="n">sparc</span><span class="p">,</span> <span class="cm">/*HasJIT=*/</span><span class="nb">false</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="n">TheSparcTarget</span><span class="p">,</span> <span class="s">"sparc"</span><span class="p">,</span> <span class="s">"Sparc"</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This allows the <tt class="docutils literal"><span class="pre">TargetRegistry</span></tt> to look up the target by name or by target
+triple. In addition, most targets will also register additional features which
+are available in separate libraries. These registration steps are separate,
+because some clients may wish to only link in some parts of the target — the
+JIT code generator does not require the use of the assembler printer, for
+example. Here is an example of registering the Sparc assembly printer:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">LLVMInitializeSparcAsmPrinter</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">RegisterAsmPrinter</span><span class="o"><</span><span class="n">SparcAsmPrinter</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="n">TheSparcTarget</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For more information, see “<a class="reference external" href="/doxygen/TargetRegistry_8h-source.html">llvm/Target/TargetRegistry.h</a>”.</p>
+</div>
+<div class="section" id="register-set-and-register-classes">
+<h2><a class="toc-backref" href="#id10">Register Set and Register Classes</a><a class="headerlink" href="#register-set-and-register-classes" title="Permalink to this headline">¶</a></h2>
+<p>You should describe a concrete target-specific class that represents the
+register file of a target machine. This class is called <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt>
+(where <tt class="docutils literal"><span class="pre">XXX</span></tt> identifies the target) and represents the class register file
+data that is used for register allocation. It also describes the interactions
+between registers.</p>
+<p>You also need to define register classes to categorize related registers. A
+register class should be added for groups of registers that are all treated the
+same way for some instruction. Typical examples are register classes for
+integer, floating-point, or vector registers. A register allocator allows an
+instruction to use any register in a specified register class to perform the
+instruction in a similar manner. Register classes allocate virtual registers
+to instructions from these sets, and register classes let the
+target-independent register allocator automatically choose the actual
+registers.</p>
+<p>Much of the code for registers, including register definition, register
+aliases, and register classes, is generated by TableGen from
+<tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> input files and placed in <tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.h.inc</span></tt>
+and <tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.inc</span></tt> output files. Some of the code in the
+implementation of <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt> requires hand-coding.</p>
+<div class="section" id="defining-a-register">
+<h3><a class="toc-backref" href="#id11">Defining a Register</a><a class="headerlink" href="#defining-a-register" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> file typically starts with register definitions for
+a target machine. The <tt class="docutils literal"><span class="pre">Register</span></tt> class (specified in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is used
+to define an object for each register. The specified string <tt class="docutils literal"><span class="pre">n</span></tt> becomes the
+<tt class="docutils literal"><span class="pre">Name</span></tt> of the register. The basic <tt class="docutils literal"><span class="pre">Register</span></tt> object does not have any
+subregisters and does not specify any aliases.</p>
+<div class="highlight-text"><div class="highlight"><pre>class Register<string n> {
+ string Namespace = "";
+ string AsmName = n;
+ string Name = n;
+ int SpillSize = 0;
+ int SpillAlignment = 0;
+ list<Register> Aliases = [];
+ list<Register> SubRegs = [];
+ list<int> DwarfNumbers = [];
+}
+</pre></div>
+</div>
+<p>For example, in the <tt class="docutils literal"><span class="pre">X86RegisterInfo.td</span></tt> file, there are register definitions
+that utilize the <tt class="docutils literal"><span class="pre">Register</span></tt> class, such as:</p>
+<div class="highlight-text"><div class="highlight"><pre>def AL : Register<"AL">, DwarfRegNum<[0, 0, 0]>;
+</pre></div>
+</div>
+<p>This defines the register <tt class="docutils literal"><span class="pre">AL</span></tt> and assigns it values (with <tt class="docutils literal"><span class="pre">DwarfRegNum</span></tt>)
+that are used by <tt class="docutils literal"><span class="pre">gcc</span></tt>, <tt class="docutils literal"><span class="pre">gdb</span></tt>, or a debug information writer to identify a
+register. For register <tt class="docutils literal"><span class="pre">AL</span></tt>, <tt class="docutils literal"><span class="pre">DwarfRegNum</span></tt> takes an array of 3 values
+representing 3 different modes: the first element is for X86-64, the second for
+exception handling (EH) on X86-32, and the third is generic. -1 is a special
+Dwarf number that indicates the gcc number is undefined, and -2 indicates the
+register number is invalid for this mode.</p>
+<p>From the previously described line in the <tt class="docutils literal"><span class="pre">X86RegisterInfo.td</span></tt> file, TableGen
+generates this code in the <tt class="docutils literal"><span class="pre">X86GenRegisterInfo.inc</span></tt> file:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="k">const</span> <span class="kt">unsigned</span> <span class="n">GR8</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="n">X86</span><span class="o">::</span><span class="n">AL</span><span class="p">,</span> <span class="p">...</span> <span class="p">};</span>
+
+<span class="k">const</span> <span class="kt">unsigned</span> <span class="n">AL_AliasSet</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="n">X86</span><span class="o">::</span><span class="n">AX</span><span class="p">,</span> <span class="n">X86</span><span class="o">::</span><span class="n">EAX</span><span class="p">,</span> <span class="n">X86</span><span class="o">::</span><span class="n">RAX</span><span class="p">,</span> <span class="mi">0</span> <span class="p">};</span>
+
+<span class="k">const</span> <span class="n">TargetRegisterDesc</span> <span class="n">RegisterDescriptors</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">{</span> <span class="s">"AL"</span><span class="p">,</span> <span class="s">"AL"</span><span class="p">,</span> <span class="n">AL_AliasSet</span><span class="p">,</span> <span class="n">Empty_SubRegsSet</span><span class="p">,</span> <span class="n">Empty_SubRegsSet</span><span class="p">,</span> <span class="n">AL_SuperRegsSet</span> <span class="p">},</span> <span class="p">...</span>
+</pre></div>
+</div>
+<p>From the register info file, TableGen generates a <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> object
+for each register. <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> is defined in
+<tt class="docutils literal"><span class="pre">include/llvm/Target/TargetRegisterInfo.h</span></tt> with the following fields:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">TargetRegisterDesc</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">AsmName</span><span class="p">;</span> <span class="c1">// Assembly language name for the register</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">Name</span><span class="p">;</span> <span class="c1">// Printable name for the reg (for debugging)</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">AliasSet</span><span class="p">;</span> <span class="c1">// Register Alias Set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">SubRegs</span><span class="p">;</span> <span class="c1">// Sub-register set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">ImmSubRegs</span><span class="p">;</span> <span class="c1">// Immediate sub-register set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">SuperRegs</span><span class="p">;</span> <span class="c1">// Super-register set</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>TableGen uses the entire target description file (<tt class="docutils literal"><span class="pre">.td</span></tt>) to determine text
+names for the register (in the <tt class="docutils literal"><span class="pre">AsmName</span></tt> and <tt class="docutils literal"><span class="pre">Name</span></tt> fields of
+<tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt>) and the relationships of other registers to the defined
+register (in the other <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> fields). In this example, other
+definitions establish the registers “<tt class="docutils literal"><span class="pre">AX</span></tt>”, “<tt class="docutils literal"><span class="pre">EAX</span></tt>”, and “<tt class="docutils literal"><span class="pre">RAX</span></tt>” as
+aliases for one another, so TableGen generates a null-terminated array
+(<tt class="docutils literal"><span class="pre">AL_AliasSet</span></tt>) for this register alias set.</p>
+<p>The <tt class="docutils literal"><span class="pre">Register</span></tt> class is commonly used as a base class for more complex
+classes. In <tt class="docutils literal"><span class="pre">Target.td</span></tt>, the <tt class="docutils literal"><span class="pre">Register</span></tt> class is the base for the
+<tt class="docutils literal"><span class="pre">RegisterWithSubRegs</span></tt> class that is used to define registers that need to
+specify subregisters in the <tt class="docutils literal"><span class="pre">SubRegs</span></tt> list, as shown here:</p>
+<div class="highlight-text"><div class="highlight"><pre>class RegisterWithSubRegs<string n, list<Register> subregs> : Register<n> {
+ let SubRegs = subregs;
+}
+</pre></div>
+</div>
+<p>In <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt>, additional register classes are defined for SPARC:
+a <tt class="docutils literal"><span class="pre">Register</span></tt> subclass, <tt class="docutils literal"><span class="pre">SparcReg</span></tt>, and further subclasses: <tt class="docutils literal"><span class="pre">Ri</span></tt>, <tt class="docutils literal"><span class="pre">Rf</span></tt>,
+and <tt class="docutils literal"><span class="pre">Rd</span></tt>. SPARC registers are identified by 5-bit ID numbers, which is a
+feature common to these subclasses. Note the use of “<tt class="docutils literal"><span class="pre">let</span></tt>” expressions to
+override values that are initially defined in a superclass (such as <tt class="docutils literal"><span class="pre">SubRegs</span></tt>
+field in the <tt class="docutils literal"><span class="pre">Rd</span></tt> class).</p>
+<div class="highlight-text"><div class="highlight"><pre>class SparcReg<string n> : Register<n> {
+ field bits<5> Num;
+ let Namespace = "SP";
+}
+// Ri - 32-bit integer registers
+class Ri<bits<5> num, string n> :
+SparcReg<n> {
+ let Num = num;
+}
+// Rf - 32-bit floating-point registers
+class Rf<bits<5> num, string n> :
+SparcReg<n> {
+ let Num = num;
+}
+// Rd - Slots in the FP register file for 64-bit floating-point values.
+class Rd<bits<5> num, string n, list<Register> subregs> : SparcReg<n> {
+ let Num = num;
+ let SubRegs = subregs;
+}
+</pre></div>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> file, there are register definitions that
+utilize these subclasses of <tt class="docutils literal"><span class="pre">Register</span></tt>, such as:</p>
+<div class="highlight-text"><div class="highlight"><pre>def G0 : Ri< 0, "G0">, DwarfRegNum<[0]>;
+def G1 : Ri< 1, "G1">, DwarfRegNum<[1]>;
+...
+def F0 : Rf< 0, "F0">, DwarfRegNum<[32]>;
+def F1 : Rf< 1, "F1">, DwarfRegNum<[33]>;
+...
+def D0 : Rd< 0, "F0", [F0, F1]>, DwarfRegNum<[32]>;
+def D1 : Rd< 2, "F2", [F2, F3]>, DwarfRegNum<[34]>;
+</pre></div>
+</div>
+<p>The last two registers shown above (<tt class="docutils literal"><span class="pre">D0</span></tt> and <tt class="docutils literal"><span class="pre">D1</span></tt>) are double-precision
+floating-point registers that are aliases for pairs of single-precision
+floating-point sub-registers. In addition to aliases, the sub-register and
+super-register relationships of the defined register are in fields of a
+register’s <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt>.</p>
+</div>
+<div class="section" id="defining-a-register-class">
+<h3><a class="toc-backref" href="#id12">Defining a Register Class</a><a class="headerlink" href="#defining-a-register-class" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> class (specified in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is used to define an
+object that represents a group of related registers and also defines the
+default allocation order of the registers. A target description file
+<tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> that uses <tt class="docutils literal"><span class="pre">Target.td</span></tt> can construct register classes
+using the following class:</p>
+<div class="highlight-text"><div class="highlight"><pre>class RegisterClass<string namespace,
+list<ValueType> regTypes, int alignment, dag regList> {
+ string Namespace = namespace;
+ list<ValueType> RegTypes = regTypes;
+ int Size = 0; // spill size, in bits; zero lets tblgen pick the size
+ int Alignment = alignment;
+
+ // CopyCost is the cost of copying a value between two registers
+ // default value 1 means a single instruction
+ // A negative value means copying is extremely expensive or impossible
+ int CopyCost = 1;
+ dag MemberList = regList;
+
+ // for register classes that are subregisters of this class
+ list<RegisterClass> SubRegClassList = [];
+
+ code MethodProtos = [{}]; // to insert arbitrary code
+ code MethodBodies = [{}];
+}
+</pre></div>
+</div>
+<p>To define a <tt class="docutils literal"><span class="pre">RegisterClass</span></tt>, use the following 4 arguments:</p>
+<ul class="simple">
+<li>The first argument of the definition is the name of the namespace.</li>
+<li>The second argument is a list of <tt class="docutils literal"><span class="pre">ValueType</span></tt> register type values that are
+defined in <tt class="docutils literal"><span class="pre">include/llvm/CodeGen/ValueTypes.td</span></tt>. Defined values include
+integer types (such as <tt class="docutils literal"><span class="pre">i16</span></tt>, <tt class="docutils literal"><span class="pre">i32</span></tt>, and <tt class="docutils literal"><span class="pre">i1</span></tt> for Boolean),
+floating-point types (<tt class="docutils literal"><span class="pre">f32</span></tt>, <tt class="docutils literal"><span class="pre">f64</span></tt>), and vector types (for example,
+<tt class="docutils literal"><span class="pre">v8i16</span></tt> for an <tt class="docutils literal"><span class="pre">8</span> <span class="pre">x</span> <span class="pre">i16</span></tt> vector). All registers in a <tt class="docutils literal"><span class="pre">RegisterClass</span></tt>
+must have the same <tt class="docutils literal"><span class="pre">ValueType</span></tt>, but some registers may store vector data in
+different configurations. For example a register that can process a 128-bit
+vector may be able to handle 16 8-bit integer elements, 8 16-bit integers, 4
+32-bit integers, and so on.</li>
+<li>The third argument of the <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> definition specifies the
+alignment required of the registers when they are stored or loaded to
+memory.</li>
+<li>The final argument, <tt class="docutils literal"><span class="pre">regList</span></tt>, specifies which registers are in this class.
+If an alternative allocation order method is not specified, then <tt class="docutils literal"><span class="pre">regList</span></tt>
+also defines the order of allocation used by the register allocator. Besides
+simply listing registers with <tt class="docutils literal"><span class="pre">(add</span> <span class="pre">R0,</span> <span class="pre">R1,</span> <span class="pre">...)</span></tt>, more advanced set
+operators are available. See <tt class="docutils literal"><span class="pre">include/llvm/Target/Target.td</span></tt> for more
+information.</li>
+</ul>
+<p>In <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt>, three <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> objects are defined:
+<tt class="docutils literal"><span class="pre">FPRegs</span></tt>, <tt class="docutils literal"><span class="pre">DFPRegs</span></tt>, and <tt class="docutils literal"><span class="pre">IntRegs</span></tt>. For all three register classes, the
+first argument defines the namespace with the string “<tt class="docutils literal"><span class="pre">SP</span></tt>”. <tt class="docutils literal"><span class="pre">FPRegs</span></tt>
+defines a group of 32 single-precision floating-point registers (<tt class="docutils literal"><span class="pre">F0</span></tt> to
+<tt class="docutils literal"><span class="pre">F31</span></tt>); <tt class="docutils literal"><span class="pre">DFPRegs</span></tt> defines a group of 16 double-precision registers
+(<tt class="docutils literal"><span class="pre">D0-D15</span></tt>).</p>
+<div class="highlight-text"><div class="highlight"><pre>// F0, F1, F2, ..., F31
+def FPRegs : RegisterClass<"SP", [f32], 32, (sequence "F%u", 0, 31)>;
+
+def DFPRegs : RegisterClass<"SP", [f64], 64,
+ (add D0, D1, D2, D3, D4, D5, D6, D7, D8,
+ D9, D10, D11, D12, D13, D14, D15)>;
+
+def IntRegs : RegisterClass<"SP", [i32], 32,
+ (add L0, L1, L2, L3, L4, L5, L6, L7,
+ I0, I1, I2, I3, I4, I5,
+ O0, O1, O2, O3, O4, O5, O7,
+ G1,
+ // Non-allocatable regs:
+ G2, G3, G4,
+ O6, // stack ptr
+ I6, // frame ptr
+ I7, // return address
+ G0, // constant zero
+ G5, G6, G7 // reserved for kernel
+ )>;
+</pre></div>
+</div>
+<p>Using <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> with TableGen generates several output files
+that are intended for inclusion in other source code that you write.
+<tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> generates <tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.h.inc</span></tt>, which should
+be included in the header file for the implementation of the SPARC register
+implementation that you write (<tt class="docutils literal"><span class="pre">SparcRegisterInfo.h</span></tt>). In
+<tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.h.inc</span></tt> a new structure is defined called
+<tt class="docutils literal"><span class="pre">SparcGenRegisterInfo</span></tt> that uses <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt> as its base. It also
+specifies types, based upon the defined register classes: <tt class="docutils literal"><span class="pre">DFPRegsClass</span></tt>,
+<tt class="docutils literal"><span class="pre">FPRegsClass</span></tt>, and <tt class="docutils literal"><span class="pre">IntRegsClass</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> also generates <tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.inc</span></tt>, which is
+included at the bottom of <tt class="docutils literal"><span class="pre">SparcRegisterInfo.cpp</span></tt>, the SPARC register
+implementation. The code below shows only the generated integer registers and
+associated register classes. The order of registers in <tt class="docutils literal"><span class="pre">IntRegs</span></tt> reflects
+the order in the definition of <tt class="docutils literal"><span class="pre">IntRegs</span></tt> in the target description file.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// IntRegs Register Class...</span>
+<span class="k">static</span> <span class="k">const</span> <span class="kt">unsigned</span> <span class="n">IntRegs</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">L0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L3</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L5</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">L6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">I4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I5</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">O4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O5</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">G4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G5</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">G6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G7</span><span class="p">,</span>
+<span class="p">};</span>
+
+<span class="c1">// IntRegsVTs Register Class Value Types...</span>
+<span class="k">static</span> <span class="k">const</span> <span class="n">MVT</span><span class="o">::</span><span class="n">ValueType</span> <span class="n">IntRegsVTs</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">Other</span>
+<span class="p">};</span>
+
+<span class="k">namespace</span> <span class="n">SP</span> <span class="p">{</span> <span class="c1">// Register class instances</span>
+ <span class="n">DFPRegsClass</span> <span class="n">DFPRegsRegClass</span><span class="p">;</span>
+ <span class="n">FPRegsClass</span> <span class="n">FPRegsRegClass</span><span class="p">;</span>
+ <span class="n">IntRegsClass</span> <span class="n">IntRegsRegClass</span><span class="p">;</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Sub-register Classess...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSubRegClasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Super-register Classess...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSuperRegClasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Register Class sub-classes...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSubclasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Register Class super-classes...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSuperclasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+
+ <span class="n">IntRegsClass</span><span class="o">::</span><span class="n">IntRegsClass</span><span class="p">()</span> <span class="o">:</span> <span class="n">TargetRegisterClass</span><span class="p">(</span><span class="n">IntRegsRegClassID</span><span class="p">,</span>
+ <span class="n">IntRegsVTs</span><span class="p">,</span> <span class="n">IntRegsSubclasses</span><span class="p">,</span> <span class="n">IntRegsSuperclasses</span><span class="p">,</span> <span class="n">IntRegsSubRegClasses</span><span class="p">,</span>
+ <span class="n">IntRegsSuperRegClasses</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">IntRegs</span><span class="p">,</span> <span class="n">IntRegs</span> <span class="o">+</span> <span class="mi">32</span><span class="p">)</span> <span class="p">{}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The register allocators will avoid using reserved registers, and callee saved
+registers are not used until all the volatile registers have been used. That
+is usually good enough, but in some cases it may be necessary to provide custom
+allocation orders.</p>
+</div>
+<div class="section" id="implement-a-subclass-of-targetregisterinfo">
+<h3><a class="toc-backref" href="#id13">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt></a><a class="headerlink" href="#implement-a-subclass-of-targetregisterinfo" title="Permalink to this headline">¶</a></h3>
+<p>The final step is to hand code portions of <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt>, which
+implements the interface described in <tt class="docutils literal"><span class="pre">TargetRegisterInfo.h</span></tt> (see
+<a class="reference internal" href="CodeGenerator.html#targetregisterinfo"><em>The TargetRegisterInfo class</em></a>). These functions return <tt class="docutils literal"><span class="pre">0</span></tt>, <tt class="docutils literal"><span class="pre">NULL</span></tt>, or
+<tt class="docutils literal"><span class="pre">false</span></tt>, unless overridden. Here is a list of functions that are overridden
+for the SPARC implementation in <tt class="docutils literal"><span class="pre">SparcRegisterInfo.cpp</span></tt>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getCalleeSavedRegs</span></tt> — Returns a list of callee-saved registers in the
+order of the desired callee-save stack frame offset.</li>
+<li><tt class="docutils literal"><span class="pre">getReservedRegs</span></tt> — Returns a bitset indexed by physical register
+numbers, indicating if a particular register is unavailable.</li>
+<li><tt class="docutils literal"><span class="pre">hasFP</span></tt> — Return a Boolean indicating if a function should have a
+dedicated frame pointer register.</li>
+<li><tt class="docutils literal"><span class="pre">eliminateCallFramePseudoInstr</span></tt> — If call frame setup or destroy pseudo
+instructions are used, this can be called to eliminate them.</li>
+<li><tt class="docutils literal"><span class="pre">eliminateFrameIndex</span></tt> — Eliminate abstract frame indices from
+instructions that may use them.</li>
+<li><tt class="docutils literal"><span class="pre">emitPrologue</span></tt> — Insert prologue code into the function.</li>
+<li><tt class="docutils literal"><span class="pre">emitEpilogue</span></tt> — Insert epilogue code into the function.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="instruction-set">
+<span id="id1"></span><h2><a class="toc-backref" href="#id14">Instruction Set</a><a class="headerlink" href="#instruction-set" title="Permalink to this headline">¶</a></h2>
+<p>During the early stages of code generation, the LLVM IR code is converted to a
+<tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> with nodes that are instances of the <tt class="docutils literal"><span class="pre">SDNode</span></tt> class
+containing target instructions. An <tt class="docutils literal"><span class="pre">SDNode</span></tt> has an opcode, operands, type
+requirements, and operation properties. For example, is an operation
+commutative, does an operation load from memory. The various operation node
+types are described in the <tt class="docutils literal"><span class="pre">include/llvm/CodeGen/SelectionDAGNodes.h</span></tt> file
+(values of the <tt class="docutils literal"><span class="pre">NodeType</span></tt> enum in the <tt class="docutils literal"><span class="pre">ISD</span></tt> namespace).</p>
+<p>TableGen uses the following target description (<tt class="docutils literal"><span class="pre">.td</span></tt>) input files to
+generate much of the code for instruction definition:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">Target.td</span></tt> — Where the <tt class="docutils literal"><span class="pre">Instruction</span></tt>, <tt class="docutils literal"><span class="pre">Operand</span></tt>, <tt class="docutils literal"><span class="pre">InstrInfo</span></tt>, and
+other fundamental classes are defined.</li>
+<li><tt class="docutils literal"><span class="pre">TargetSelectionDAG.td</span></tt> — Used by <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> instruction selection
+generators, contains <tt class="docutils literal"><span class="pre">SDTC*</span></tt> classes (selection DAG type constraint),
+definitions of <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> nodes (such as <tt class="docutils literal"><span class="pre">imm</span></tt>, <tt class="docutils literal"><span class="pre">cond</span></tt>, <tt class="docutils literal"><span class="pre">bb</span></tt>,
+<tt class="docutils literal"><span class="pre">add</span></tt>, <tt class="docutils literal"><span class="pre">fadd</span></tt>, <tt class="docutils literal"><span class="pre">sub</span></tt>), and pattern support (<tt class="docutils literal"><span class="pre">Pattern</span></tt>, <tt class="docutils literal"><span class="pre">Pat</span></tt>,
+<tt class="docutils literal"><span class="pre">PatFrag</span></tt>, <tt class="docutils literal"><span class="pre">PatLeaf</span></tt>, <tt class="docutils literal"><span class="pre">ComplexPattern</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">XXXInstrFormats.td</span></tt> — Patterns for definitions of target-specific
+instructions.</li>
+<li><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> — Target-specific definitions of instruction templates,
+condition codes, and instructions of an instruction set. For architecture
+modifications, a different file name may be used. For example, for Pentium
+with SSE instruction, this file is <tt class="docutils literal"><span class="pre">X86InstrSSE.td</span></tt>, and for Pentium with
+MMX, this file is <tt class="docutils literal"><span class="pre">X86InstrMMX.td</span></tt>.</li>
+</ul>
+<p>There is also a target-specific <tt class="docutils literal"><span class="pre">XXX.td</span></tt> file, where <tt class="docutils literal"><span class="pre">XXX</span></tt> is the name of
+the target. The <tt class="docutils literal"><span class="pre">XXX.td</span></tt> file includes the other <tt class="docutils literal"><span class="pre">.td</span></tt> input files, but
+its contents are only directly important for subtargets.</p>
+<p>You should describe a concrete target-specific class <tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> that
+represents machine instructions supported by a target machine.
+<tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> contains an array of <tt class="docutils literal"><span class="pre">XXXInstrDescriptor</span></tt> objects, each of
+which describes one instruction. An instruction descriptor defines:</p>
+<ul class="simple">
+<li>Opcode mnemonic</li>
+<li>Number of operands</li>
+<li>List of implicit register definitions and uses</li>
+<li>Target-independent properties (such as memory access, is commutable)</li>
+<li>Target-specific flags</li>
+</ul>
+<p>The Instruction class (defined in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is mostly used as a base for
+more complex instruction classes.</p>
+<div class="highlight-text"><div class="highlight"><pre>class Instruction {
+ string Namespace = "";
+ dag OutOperandList; // A dag containing the MI def operand list.
+ dag InOperandList; // A dag containing the MI use operand list.
+ string AsmString = ""; // The .s format to print the instruction with.
+ list<dag> Pattern; // Set to the DAG pattern for this instruction.
+ list<Register> Uses = [];
+ list<Register> Defs = [];
+ list<Predicate> Predicates = []; // predicates turned into isel match code
+ ... remainder not shown for space ...
+}
+</pre></div>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> node (<tt class="docutils literal"><span class="pre">SDNode</span></tt>) should contain an object representing a
+target-specific instruction that is defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt>. The
+instruction objects should represent instructions from the architecture manual
+of the target machine (such as the SPARC Architecture Manual for the SPARC
+target).</p>
+<p>A single instruction from the architecture manual is often modeled as multiple
+target instructions, depending upon its operands. For example, a manual might
+describe an add instruction that takes a register or an immediate operand. An
+LLVM target could model this with two instructions named <tt class="docutils literal"><span class="pre">ADDri</span></tt> and
+<tt class="docutils literal"><span class="pre">ADDrr</span></tt>.</p>
+<p>You should define a class for each instruction category and define each opcode
+as a subclass of the category with appropriate parameters such as the fixed
+binary encoding of opcodes and extended opcodes. You should map the register
+bits to the bits of the instruction in which they are encoded (for the JIT).
+Also you should specify how the instruction should be printed when the
+automatic assembly printer is used.</p>
+<p>As is described in the SPARC Architecture Manual, Version 8, there are three
+major 32-bit formats for instructions. Format 1 is only for the <tt class="docutils literal"><span class="pre">CALL</span></tt>
+instruction. Format 2 is for branch on condition codes and <tt class="docutils literal"><span class="pre">SETHI</span></tt> (set high
+bits of a register) instructions. Format 3 is for other instructions.</p>
+<p>Each of these formats has corresponding classes in <tt class="docutils literal"><span class="pre">SparcInstrFormat.td</span></tt>.
+<tt class="docutils literal"><span class="pre">InstSP</span></tt> is a base class for other instruction classes. Additional base
+classes are specified for more precise formats: for example in
+<tt class="docutils literal"><span class="pre">SparcInstrFormat.td</span></tt>, <tt class="docutils literal"><span class="pre">F2_1</span></tt> is for <tt class="docutils literal"><span class="pre">SETHI</span></tt>, and <tt class="docutils literal"><span class="pre">F2_2</span></tt> is for
+branches. There are three other base classes: <tt class="docutils literal"><span class="pre">F3_1</span></tt> for register/register
+operations, <tt class="docutils literal"><span class="pre">F3_2</span></tt> for register/immediate operations, and <tt class="docutils literal"><span class="pre">F3_3</span></tt> for
+floating-point operations. <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> also adds the base class
+<tt class="docutils literal"><span class="pre">Pseudo</span></tt> for synthetic SPARC instructions.</p>
+<p><tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> largely consists of operand and instruction definitions
+for the SPARC target. In <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>, the following target
+description file entry, <tt class="docutils literal"><span class="pre">LDrr</span></tt>, defines the Load Integer instruction for a
+Word (the <tt class="docutils literal"><span class="pre">LD</span></tt> SPARC opcode) from a memory address to a register. The first
+parameter, the value 3 (<tt class="docutils literal"><span class="pre">11</span></tt><sub>2</sub>), is the operation value for this
+category of operation. The second parameter (<tt class="docutils literal"><span class="pre">000000</span></tt><sub>2</sub>) is the
+specific operation value for <tt class="docutils literal"><span class="pre">LD</span></tt>/Load Word. The third parameter is the
+output destination, which is a register operand and defined in the <tt class="docutils literal"><span class="pre">Register</span></tt>
+target description file (<tt class="docutils literal"><span class="pre">IntRegs</span></tt>).</p>
+<div class="highlight-text"><div class="highlight"><pre>def LDrr : F3_1 <3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr),
+ "ld [$addr], $dst",
+ [(set i32:$dst, (load ADDRrr:$addr))]>;
+</pre></div>
+</div>
+<p>The fourth parameter is the input source, which uses the address operand
+<tt class="docutils literal"><span class="pre">MEMrr</span></tt> that is defined earlier in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>:</p>
+<div class="highlight-text"><div class="highlight"><pre>def MEMrr : Operand<i32> {
+ let PrintMethod = "printMemOperand";
+ let MIOperandInfo = (ops IntRegs, IntRegs);
+}
+</pre></div>
+</div>
+<p>The fifth parameter is a string that is used by the assembly printer and can be
+left as an empty string until the assembly printer interface is implemented.
+The sixth and final parameter is the pattern used to match the instruction
+during the SelectionDAG Select Phase described in <a class="reference internal" href="CodeGenerator.html"><em>The LLVM Target-Independent Code Generator</em></a>.
+This parameter is detailed in the next section, <a class="reference internal" href="#instruction-selector"><em>Instruction Selector</em></a>.</p>
+<p>Instruction class definitions are not overloaded for different operand types,
+so separate versions of instructions are needed for register, memory, or
+immediate value operands. For example, to perform a Load Integer instruction
+for a Word from an immediate operand to a register, the following instruction
+class is defined:</p>
+<div class="highlight-text"><div class="highlight"><pre>def LDri : F3_2 <3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr),
+ "ld [$addr], $dst",
+ [(set i32:$dst, (load ADDRri:$addr))]>;
+</pre></div>
+</div>
+<p>Writing these definitions for so many similar instructions can involve a lot of
+cut and paste. In <tt class="docutils literal"><span class="pre">.td</span></tt> files, the <tt class="docutils literal"><span class="pre">multiclass</span></tt> directive enables the
+creation of templates to define several instruction classes at once (using the
+<tt class="docutils literal"><span class="pre">defm</span></tt> directive). For example in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>, the <tt class="docutils literal"><span class="pre">multiclass</span></tt>
+pattern <tt class="docutils literal"><span class="pre">F3_12</span></tt> is defined to create 2 instruction classes each time
+<tt class="docutils literal"><span class="pre">F3_12</span></tt> is invoked:</p>
+<div class="highlight-text"><div class="highlight"><pre>multiclass F3_12 <string OpcStr, bits<6> Op3Val, SDNode OpNode> {
+ def rr : F3_1 <2, Op3Val,
+ (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
+ !strconcat(OpcStr, " $b, $c, $dst"),
+ [(set i32:$dst, (OpNode i32:$b, i32:$c))]>;
+ def ri : F3_2 <2, Op3Val,
+ (outs IntRegs:$dst), (ins IntRegs:$b, i32imm:$c),
+ !strconcat(OpcStr, " $b, $c, $dst"),
+ [(set i32:$dst, (OpNode i32:$b, simm13:$c))]>;
+}
+</pre></div>
+</div>
+<p>So when the <tt class="docutils literal"><span class="pre">defm</span></tt> directive is used for the <tt class="docutils literal"><span class="pre">XOR</span></tt> and <tt class="docutils literal"><span class="pre">ADD</span></tt>
+instructions, as seen below, it creates four instruction objects: <tt class="docutils literal"><span class="pre">XORrr</span></tt>,
+<tt class="docutils literal"><span class="pre">XORri</span></tt>, <tt class="docutils literal"><span class="pre">ADDrr</span></tt>, and <tt class="docutils literal"><span class="pre">ADDri</span></tt>.</p>
+<div class="highlight-text"><div class="highlight"><pre>defm XOR : F3_12<"xor", 0b000011, xor>;
+defm ADD : F3_12<"add", 0b000000, add>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> also includes definitions for condition codes that are
+referenced by branch instructions. The following definitions in
+<tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> indicate the bit location of the SPARC condition code.
+For example, the 10<sup>th</sup> bit represents the “greater than” condition for
+integers, and the 22<sup>nd</sup> bit represents the “greater than” condition for
+floats.</p>
+<div class="highlight-text"><div class="highlight"><pre>def ICC_NE : ICC_VAL< 9>; // Not Equal
+def ICC_E : ICC_VAL< 1>; // Equal
+def ICC_G : ICC_VAL<10>; // Greater
+...
+def FCC_U : FCC_VAL<23>; // Unordered
+def FCC_G : FCC_VAL<22>; // Greater
+def FCC_UG : FCC_VAL<21>; // Unordered or Greater
+...
+</pre></div>
+</div>
+<p>(Note that <tt class="docutils literal"><span class="pre">Sparc.h</span></tt> also defines enums that correspond to the same SPARC
+condition codes. Care must be taken to ensure the values in <tt class="docutils literal"><span class="pre">Sparc.h</span></tt>
+correspond to the values in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>. I.e., <tt class="docutils literal"><span class="pre">SPCC::ICC_NE</span> <span class="pre">=</span> <span class="pre">9</span></tt>,
+<tt class="docutils literal"><span class="pre">SPCC::FCC_U</span> <span class="pre">=</span> <span class="pre">23</span></tt> and so on.)</p>
+<div class="section" id="instruction-operand-mapping">
+<h3><a class="toc-backref" href="#id15">Instruction Operand Mapping</a><a class="headerlink" href="#instruction-operand-mapping" title="Permalink to this headline">¶</a></h3>
+<p>The code generator backend maps instruction operands to fields in the
+instruction. Operands are assigned to unbound fields in the instruction in the
+order they are defined. Fields are bound when they are assigned a value. For
+example, the Sparc target defines the <tt class="docutils literal"><span class="pre">XNORrr</span></tt> instruction as a <tt class="docutils literal"><span class="pre">F3_1</span></tt>
+format instruction having three operands.</p>
+<div class="highlight-text"><div class="highlight"><pre>def XNORrr : F3_1<2, 0b000111,
+ (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
+ "xnor $b, $c, $dst",
+ [(set i32:$dst, (not (xor i32:$b, i32:$c)))]>;
+</pre></div>
+</div>
+<p>The instruction templates in <tt class="docutils literal"><span class="pre">SparcInstrFormats.td</span></tt> show the base class for
+<tt class="docutils literal"><span class="pre">F3_1</span></tt> is <tt class="docutils literal"><span class="pre">InstSP</span></tt>.</p>
+<div class="highlight-text"><div class="highlight"><pre>class InstSP<dag outs, dag ins, string asmstr, list<dag> pattern> : Instruction {
+ field bits<32> Inst;
+ let Namespace = "SP";
+ bits<2> op;
+ let Inst{31-30} = op;
+ dag OutOperandList = outs;
+ dag InOperandList = ins;
+ let AsmString = asmstr;
+ let Pattern = pattern;
+}
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">InstSP</span></tt> leaves the <tt class="docutils literal"><span class="pre">op</span></tt> field unbound.</p>
+<div class="highlight-text"><div class="highlight"><pre>class F3<dag outs, dag ins, string asmstr, list<dag> pattern>
+ : InstSP<outs, ins, asmstr, pattern> {
+ bits<5> rd;
+ bits<6> op3;
+ bits<5> rs1;
+ let op{1} = 1; // Op = 2 or 3
+ let Inst{29-25} = rd;
+ let Inst{24-19} = op3;
+ let Inst{18-14} = rs1;
+}
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">F3</span></tt> binds the <tt class="docutils literal"><span class="pre">op</span></tt> field and defines the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">op3</span></tt>, and <tt class="docutils literal"><span class="pre">rs1</span></tt>
+fields. <tt class="docutils literal"><span class="pre">F3</span></tt> format instructions will bind the operands <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">op3</span></tt>, and
+<tt class="docutils literal"><span class="pre">rs1</span></tt> fields.</p>
+<div class="highlight-text"><div class="highlight"><pre>class F3_1<bits<2> opVal, bits<6> op3val, dag outs, dag ins,
+ string asmstr, list<dag> pattern> : F3<outs, ins, asmstr, pattern> {
+ bits<8> asi = 0; // asi not currently used
+ bits<5> rs2;
+ let op = opVal;
+ let op3 = op3val;
+ let Inst{13} = 0; // i field = 0
+ let Inst{12-5} = asi; // address space identifier
+ let Inst{4-0} = rs2;
+}
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">F3_1</span></tt> binds the <tt class="docutils literal"><span class="pre">op3</span></tt> field and defines the <tt class="docutils literal"><span class="pre">rs2</span></tt> fields. <tt class="docutils literal"><span class="pre">F3_1</span></tt>
+format instructions will bind the operands to the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">rs1</span></tt>, and <tt class="docutils literal"><span class="pre">rs2</span></tt>
+fields. This results in the <tt class="docutils literal"><span class="pre">XNORrr</span></tt> instruction binding <tt class="docutils literal"><span class="pre">$dst</span></tt>, <tt class="docutils literal"><span class="pre">$b</span></tt>,
+and <tt class="docutils literal"><span class="pre">$c</span></tt> operands to the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">rs1</span></tt>, and <tt class="docutils literal"><span class="pre">rs2</span></tt> fields respectively.</p>
+<div class="section" id="instruction-operand-name-mapping">
+<h4><a class="toc-backref" href="#id16">Instruction Operand Name Mapping</a><a class="headerlink" href="#instruction-operand-name-mapping" title="Permalink to this headline">¶</a></h4>
+<p>TableGen will also generate a function called getNamedOperandIdx() which
+can be used to look up an operand’s index in a MachineInstr based on its
+TableGen name. Setting the UseNamedOperandTable bit in an instruction’s
+TableGen definition will add all of its operands to an enumeration in the
+llvm::XXX:OpName namespace and also add an entry for it into the OperandMap
+table, which can be queried using getNamedOperandIdx()</p>
+<div class="highlight-text"><div class="highlight"><pre>int DstIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::dst); // => 0
+int BIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::b); // => 1
+int CIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::c); // => 2
+int DIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::d); // => -1
+
+...
+</pre></div>
+</div>
+<p>The entries in the OpName enum are taken verbatim from the TableGen definitions,
+so operands with lowercase names will have lower case entries in the enum.</p>
+<p>To include the getNamedOperandIdx() function in your backend, you will need
+to define a few preprocessor macros in XXXInstrInfo.cpp and XXXInstrInfo.h.
+For example:</p>
+<p>XXXInstrInfo.cpp:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_INSTRINFO_NAMED_OPS </span><span class="c1">// For getNamedOperandIdx() function</span>
+<span class="cp">#include "XXXGenInstrInfo.inc"</span>
+</pre></div>
+</div>
+<p>XXXInstrInfo.h:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_INSTRINFO_OPERAND_ENUM </span><span class="c1">// For OpName enum</span>
+<span class="cp">#include "XXXGenInstrInfo.inc"</span>
+
+<span class="k">namespace</span> <span class="n">XXX</span> <span class="p">{</span>
+ <span class="kt">int16_t</span> <span class="n">getNamedOperandIdx</span><span class="p">(</span><span class="kt">uint16_t</span> <span class="n">Opcode</span><span class="p">,</span> <span class="kt">uint16_t</span> <span class="n">NamedIndex</span><span class="p">);</span>
+<span class="p">}</span> <span class="c1">// End namespace XXX</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="instruction-operand-types">
+<h4><a class="toc-backref" href="#id17">Instruction Operand Types</a><a class="headerlink" href="#instruction-operand-types" title="Permalink to this headline">¶</a></h4>
+<p>TableGen will also generate an enumeration consisting of all named Operand
+types defined in the backend, in the llvm::XXX::OpTypes namespace.
+Some common immediate Operand types (for instance i8, i32, i64, f32, f64)
+are defined for all targets in <tt class="docutils literal"><span class="pre">include/llvm/Target/Target.td</span></tt>, and are
+available in each Target’s OpTypes enum. Also, only named Operand types appear
+in the enumeration: anonymous types are ignored.
+For example, the X86 backend defines <tt class="docutils literal"><span class="pre">brtarget</span></tt> and <tt class="docutils literal"><span class="pre">brtarget8</span></tt>, both
+instances of the TableGen <tt class="docutils literal"><span class="pre">Operand</span></tt> class, which represent branch target
+operands:</p>
+<div class="highlight-text"><div class="highlight"><pre>def brtarget : Operand<OtherVT>;
+def brtarget8 : Operand<OtherVT>;
+</pre></div>
+</div>
+<p>This results in:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">X86</span> <span class="p">{</span>
+<span class="k">namespace</span> <span class="n">OpTypes</span> <span class="p">{</span>
+<span class="k">enum</span> <span class="n">OperandType</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="n">brtarget</span><span class="p">,</span>
+ <span class="n">brtarget8</span><span class="p">,</span>
+ <span class="p">...</span>
+ <span class="n">i32imm</span><span class="p">,</span>
+ <span class="n">i64imm</span><span class="p">,</span>
+ <span class="p">...</span>
+ <span class="n">OPERAND_TYPE_LIST_END</span>
+<span class="p">}</span> <span class="c1">// End namespace OpTypes</span>
+<span class="p">}</span> <span class="c1">// End namespace X86</span>
+</pre></div>
+</div>
+<p>In typical TableGen fashion, to use the enum, you will need to define a
+preprocessor macro:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_INSTRINFO_OPERAND_TYPES_ENUM </span><span class="c1">// For OpTypes enum</span>
+<span class="cp">#include "XXXGenInstrInfo.inc"</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="instruction-scheduling">
+<h3><a class="toc-backref" href="#id18">Instruction Scheduling</a><a class="headerlink" href="#instruction-scheduling" title="Permalink to this headline">¶</a></h3>
+<p>Instruction itineraries can be queried using MCDesc::getSchedClass(). The
+value can be named by an enumemation in llvm::XXX::Sched namespace generated
+by TableGen in XXXGenInstrInfo.inc. The name of the schedule classes are
+the same as provided in XXXSchedule.td plus a default NoItinerary class.</p>
+</div>
+<div class="section" id="instruction-relation-mapping">
+<h3><a class="toc-backref" href="#id19">Instruction Relation Mapping</a><a class="headerlink" href="#instruction-relation-mapping" title="Permalink to this headline">¶</a></h3>
+<p>This TableGen feature is used to relate instructions with each other. It is
+particularly useful when you have multiple instruction formats and need to
+switch between them after instruction selection. This entire feature is driven
+by relation models which can be defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> files
+according to the target-specific instruction set. Relation models are defined
+using <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> class as a base. TableGen parses all the models
+and generates instruction relation maps using the specified information.
+Relation maps are emitted as tables in the <tt class="docutils literal"><span class="pre">XXXGenInstrInfo.inc</span></tt> file
+along with the functions to query them. For the detailed information on how to
+use this feature, please refer to <a class="reference internal" href="HowToUseInstrMappings.html"><em>How To Use Instruction Mappings</em></a>.</p>
+</div>
+<div class="section" id="implement-a-subclass-of-targetinstrinfo">
+<h3><a class="toc-backref" href="#id20">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt></a><a class="headerlink" href="#implement-a-subclass-of-targetinstrinfo" title="Permalink to this headline">¶</a></h3>
+<p>The final step is to hand code portions of <tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt>, which implements
+the interface described in <tt class="docutils literal"><span class="pre">TargetInstrInfo.h</span></tt> (see <a class="reference internal" href="CodeGenerator.html#targetinstrinfo"><em>The TargetInstrInfo class</em></a>).
+These functions return <tt class="docutils literal"><span class="pre">0</span></tt> or a Boolean or they assert, unless overridden.
+Here’s a list of functions that are overridden for the SPARC implementation in
+<tt class="docutils literal"><span class="pre">SparcInstrInfo.cpp</span></tt>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">isLoadFromStackSlot</span></tt> — If the specified machine instruction is a direct
+load from a stack slot, return the register number of the destination and the
+<tt class="docutils literal"><span class="pre">FrameIndex</span></tt> of the stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">isStoreToStackSlot</span></tt> — If the specified machine instruction is a direct
+store to a stack slot, return the register number of the destination and the
+<tt class="docutils literal"><span class="pre">FrameIndex</span></tt> of the stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">copyPhysReg</span></tt> — Copy values between a pair of physical registers.</li>
+<li><tt class="docutils literal"><span class="pre">storeRegToStackSlot</span></tt> — Store a register value to a stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">loadRegFromStackSlot</span></tt> — Load a register value from a stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">storeRegToAddr</span></tt> — Store a register value to memory.</li>
+<li><tt class="docutils literal"><span class="pre">loadRegFromAddr</span></tt> — Load a register value from memory.</li>
+<li><tt class="docutils literal"><span class="pre">foldMemoryOperand</span></tt> — Attempt to combine instructions of any load or
+store instruction for the specified operand(s).</li>
+</ul>
+</div>
+<div class="section" id="branch-folding-and-if-conversion">
+<h3><a class="toc-backref" href="#id21">Branch Folding and If Conversion</a><a class="headerlink" href="#branch-folding-and-if-conversion" title="Permalink to this headline">¶</a></h3>
+<p>Performance can be improved by combining instructions or by eliminating
+instructions that are never reached. The <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> method in
+<tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> may be implemented to examine conditional instructions and
+remove unnecessary instructions. <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> looks at the end of a
+machine basic block (MBB) for opportunities for improvement, such as branch
+folding and if conversion. The <tt class="docutils literal"><span class="pre">BranchFolder</span></tt> and <tt class="docutils literal"><span class="pre">IfConverter</span></tt> machine
+function passes (see the source files <tt class="docutils literal"><span class="pre">BranchFolding.cpp</span></tt> and
+<tt class="docutils literal"><span class="pre">IfConversion.cpp</span></tt> in the <tt class="docutils literal"><span class="pre">lib/CodeGen</span></tt> directory) call <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>
+to improve the control flow graph that represents the instructions.</p>
+<p>Several implementations of <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (for ARM, Alpha, and X86) can be
+examined as models for your own <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> implementation. Since SPARC
+does not implement a useful <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>, the ARM target implementation is
+shown below.</p>
+<p><tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> returns a Boolean value and takes four parameters:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">&MBB</span></tt> — The incoming block to be examined.</li>
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">*&TBB</span></tt> — A destination block that is returned. For a
+conditional branch that evaluates to true, <tt class="docutils literal"><span class="pre">TBB</span></tt> is the destination.</li>
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">*&FBB</span></tt> — For a conditional branch that evaluates to
+false, <tt class="docutils literal"><span class="pre">FBB</span></tt> is returned as the destination.</li>
+<li><tt class="docutils literal"><span class="pre">std::vector<MachineOperand></span> <span class="pre">&Cond</span></tt> — List of operands to evaluate a
+condition for a conditional branch.</li>
+</ul>
+<p>In the simplest case, if a block ends without a branch, then it falls through
+to the successor block. No destination blocks are specified for either <tt class="docutils literal"><span class="pre">TBB</span></tt>
+or <tt class="docutils literal"><span class="pre">FBB</span></tt>, so both parameters return <tt class="docutils literal"><span class="pre">NULL</span></tt>. The start of the
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (see code below for the ARM target) shows the function
+parameters and the code for the simplest case.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">ARMInstrInfo</span><span class="o">::</span><span class="n">AnalyzeBranch</span><span class="p">(</span><span class="n">MachineBasicBlock</span> <span class="o">&</span><span class="n">MBB</span><span class="p">,</span>
+ <span class="n">MachineBasicBlock</span> <span class="o">*&</span><span class="n">TBB</span><span class="p">,</span>
+ <span class="n">MachineBasicBlock</span> <span class="o">*&</span><span class="n">FBB</span><span class="p">,</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">MachineOperand</span><span class="o">></span> <span class="o">&</span><span class="n">Cond</span><span class="p">)</span> <span class="k">const</span>
+<span class="p">{</span>
+ <span class="n">MachineBasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">MBB</span><span class="p">.</span><span class="n">end</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">I</span> <span class="o">==</span> <span class="n">MBB</span><span class="p">.</span><span class="n">begin</span><span class="p">()</span> <span class="o">||</span> <span class="o">!</span><span class="n">isUnpredicatedTerminator</span><span class="p">(</span><span class="o">--</span><span class="n">I</span><span class="p">))</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>If a block ends with a single unconditional branch instruction, then
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the destination of that branch in
+the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If a block ends with two unconditional branches, then the second branch is
+never reached. In that situation, as shown below, remove the last branch
+instruction and return the penultimate branch in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">((</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">I</span> <span class="o">=</span> <span class="n">LastInst</span><span class="p">;</span>
+ <span class="n">I</span><span class="o">-></span><span class="n">eraseFromParent</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A block may end with a single conditional branch instruction that falls through
+to successor block if the condition evaluates to false. In that case,
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the destination of that
+conditional branch in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter and a list of operands in the
+<tt class="docutils literal"><span class="pre">Cond</span></tt> parameter to evaluate the condition.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">Bcc</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tBcc</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Block ends with fall-through condbranch.</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If a block ends with both a conditional branch and an ensuing unconditional
+branch, then <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the conditional
+branch destination (assuming it corresponds to a conditional evaluation of
+“<tt class="docutils literal"><span class="pre">true</span></tt>”) in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter and the unconditional branch destination
+in the <tt class="docutils literal"><span class="pre">FBB</span></tt> (corresponding to a conditional evaluation of “<tt class="docutils literal"><span class="pre">false</span></tt>”). A
+list of operands to evaluate the condition should be returned in the <tt class="docutils literal"><span class="pre">Cond</span></tt>
+parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">unsigned</span> <span class="n">SecondLastOpc</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOpcode</span><span class="p">();</span>
+
+<span class="k">if</span> <span class="p">((</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">Bcc</span> <span class="o">&&</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span><span class="p">)</span> <span class="o">||</span>
+ <span class="p">(</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tBcc</span> <span class="o">&&</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
+ <span class="n">FBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For the last two cases (ending with a single conditional branch or ending with
+one conditional and one unconditional branch), the operands returned in the
+<tt class="docutils literal"><span class="pre">Cond</span></tt> parameter can be passed to methods of other instructions to create new
+branches or perform other operations. An implementation of <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>
+requires the helper methods <tt class="docutils literal"><span class="pre">RemoveBranch</span></tt> and <tt class="docutils literal"><span class="pre">InsertBranch</span></tt> to manage
+subsequent operations.</p>
+<p><tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> should return false indicating success in most circumstances.
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> should only return true when the method is stumped about what
+to do, for example, if a block has three terminating branches.
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> may return true if it encounters a terminator it cannot
+handle, such as an indirect branch.</p>
+</div>
+</div>
+<div class="section" id="instruction-selector">
+<span id="id2"></span><h2><a class="toc-backref" href="#id22">Instruction Selector</a><a class="headerlink" href="#instruction-selector" title="Permalink to this headline">¶</a></h2>
+<p>LLVM uses a <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> to represent LLVM IR instructions, and nodes of
+the <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> ideally represent native target instructions. During code
+generation, instruction selection passes are performed to convert non-native
+DAG instructions into native target-specific instructions. The pass described
+in <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt> is used to match patterns and perform DAG-to-DAG
+instruction selection. Optionally, a pass may be defined (in
+<tt class="docutils literal"><span class="pre">XXXBranchSelector.cpp</span></tt>) to perform similar DAG-to-DAG operations for branch
+instructions. Later, the code in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt> replaces or removes
+operations and data types not supported natively (legalizes) in a
+<tt class="docutils literal"><span class="pre">SelectionDAG</span></tt>.</p>
+<p>TableGen generates code for instruction selection using the following target
+description input files:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> — Contains definitions of instructions in a
+target-specific instruction set, generates <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>, which is
+included in <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">XXXCallingConv.td</span></tt> — Contains the calling and return value conventions
+for the target architecture, and it generates <tt class="docutils literal"><span class="pre">XXXGenCallingConv.inc</span></tt>,
+which is included in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>.</li>
+</ul>
+<p>The implementation of an instruction selection pass must include a header that
+declares the <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> class or a subclass of <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>. In
+<tt class="docutils literal"><span class="pre">XXXTargetMachine.cpp</span></tt>, a Pass Manager (PM) should add each instruction
+selection pass into the queue of passes to run.</p>
+<p>The LLVM static compiler (<tt class="docutils literal"><span class="pre">llc</span></tt>) is an excellent tool for visualizing the
+contents of DAGs. To display the <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> before or after specific
+processing phases, use the command line options for <tt class="docutils literal"><span class="pre">llc</span></tt>, described at
+<a class="reference internal" href="CodeGenerator.html#selectiondag-process"><em>SelectionDAG Instruction Selection Process</em></a>.</p>
+<p>To describe instruction selector behavior, you should add patterns for lowering
+LLVM code into a <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> as the last parameter of the instruction
+definitions in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt>. For example, in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>,
+this entry defines a register store operation, and the last parameter describes
+a pattern with the store DAG operator.</p>
+<div class="highlight-text"><div class="highlight"><pre>def STrr : F3_1< 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src),
+ "st $src, [$addr]", [(store i32:$src, ADDRrr:$addr)]>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">ADDRrr</span></tt> is a memory mode that is also defined in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>:</p>
+<div class="highlight-text"><div class="highlight"><pre>def ADDRrr : ComplexPattern<i32, 2, "SelectADDRrr", [], []>;
+</pre></div>
+</div>
+<p>The definition of <tt class="docutils literal"><span class="pre">ADDRrr</span></tt> refers to <tt class="docutils literal"><span class="pre">SelectADDRrr</span></tt>, which is a function
+defined in an implementation of the Instructor Selector (such as
+<tt class="docutils literal"><span class="pre">SparcISelDAGToDAG.cpp</span></tt>).</p>
+<p>In <tt class="docutils literal"><span class="pre">lib/Target/TargetSelectionDAG.td</span></tt>, the DAG operator for store is defined
+below:</p>
+<div class="highlight-text"><div class="highlight"><pre>def store : PatFrag<(ops node:$val, node:$ptr),
+ (st node:$val, node:$ptr), [{
+ if (StoreSDNode *ST = dyn_cast<StoreSDNode>(N))
+ return !ST->isTruncatingStore() &&
+ ST->getAddressingMode() == ISD::UNINDEXED;
+ return false;
+}]>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> also generates (in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>) the
+<tt class="docutils literal"><span class="pre">SelectCode</span></tt> method that is used to call the appropriate processing method
+for an instruction. In this example, <tt class="docutils literal"><span class="pre">SelectCode</span></tt> calls <tt class="docutils literal"><span class="pre">Select_ISD_STORE</span></tt>
+for the <tt class="docutils literal"><span class="pre">ISD::STORE</span></tt> opcode.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDNode</span> <span class="o">*</span><span class="nf">SelectCode</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">N</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="n">MVT</span><span class="o">::</span><span class="n">ValueType</span> <span class="n">NVT</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">N</span><span class="p">.</span><span class="n">getOpcode</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">ISD</span>:<span class="o">:</span><span class="n">STORE</span><span class="o">:</span> <span class="p">{</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">NVT</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nl">default:</span>
+ <span class="k">return</span> <span class="n">Select_ISD_STORE</span><span class="p">(</span><span class="n">N</span><span class="p">);</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+<p>The pattern for <tt class="docutils literal"><span class="pre">STrr</span></tt> is matched, so elsewhere in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>,
+code for <tt class="docutils literal"><span class="pre">STrr</span></tt> is created for <tt class="docutils literal"><span class="pre">Select_ISD_STORE</span></tt>. The <tt class="docutils literal"><span class="pre">Emit_22</span></tt> method
+is also generated in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt> to complete the processing of this
+instruction.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDNode</span> <span class="o">*</span><span class="nf">Select_ISD_STORE</span><span class="p">(</span><span class="k">const</span> <span class="n">SDValue</span> <span class="o">&</span><span class="n">N</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">SDValue</span> <span class="n">Chain</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Predicate_store</span><span class="p">(</span><span class="n">N</span><span class="p">.</span><span class="n">getNode</span><span class="p">()))</span> <span class="p">{</span>
+ <span class="n">SDValue</span> <span class="n">N1</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+ <span class="n">SDValue</span> <span class="n">N2</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span>
+ <span class="n">SDValue</span> <span class="n">CPTmp0</span><span class="p">;</span>
+ <span class="n">SDValue</span> <span class="n">CPTmp1</span><span class="p">;</span>
+
+ <span class="c1">// Pattern: (st:void i32:i32:$src,</span>
+ <span class="c1">// ADDRrr:i32:$addr)<<P:Predicate_store>></span>
+ <span class="c1">// Emits: (STrr:void ADDRrr:i32:$addr, IntRegs:i32:$src)</span>
+ <span class="c1">// Pattern complexity = 13 cost = 1 size = 0</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">SelectADDRrr</span><span class="p">(</span><span class="n">N</span><span class="p">,</span> <span class="n">N2</span><span class="p">,</span> <span class="n">CPTmp0</span><span class="p">,</span> <span class="n">CPTmp1</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="n">N1</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span> <span class="o">&&</span>
+ <span class="n">N2</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">Emit_22</span><span class="p">(</span><span class="n">N</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">STrr</span><span class="p">,</span> <span class="n">CPTmp0</span><span class="p">,</span> <span class="n">CPTmp1</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<div class="section" id="the-selectiondag-legalize-phase">
+<h3><a class="toc-backref" href="#id23">The SelectionDAG Legalize Phase</a><a class="headerlink" href="#the-selectiondag-legalize-phase" title="Permalink to this headline">¶</a></h3>
+<p>The Legalize phase converts a DAG to use types and operations that are natively
+supported by the target. For natively unsupported types and operations, you
+need to add code to the target-specific <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> implementation to
+convert unsupported types and operations to supported ones.</p>
+<p>In the constructor for the <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> class, first use the
+<tt class="docutils literal"><span class="pre">addRegisterClass</span></tt> method to specify which types are supported and which
+register classes are associated with them. The code for the register classes
+are generated by TableGen from <tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> and placed in
+<tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.h.inc</span></tt>. For example, the implementation of the
+constructor for the SparcTargetLowering class (in <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt>)
+starts with the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">IntRegsRegisterClass</span><span class="p">);</span>
+<span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">FPRegsRegisterClass</span><span class="p">);</span>
+<span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">f64</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">DFPRegsRegisterClass</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>You should examine the node types in the <tt class="docutils literal"><span class="pre">ISD</span></tt> namespace
+(<tt class="docutils literal"><span class="pre">include/llvm/CodeGen/SelectionDAGNodes.h</span></tt>) and determine which operations
+the target natively supports. For operations that do <strong>not</strong> have native
+support, add a callback to the constructor for the <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> class,
+so the instruction selection process knows what to do. The <tt class="docutils literal"><span class="pre">TargetLowering</span></tt>
+class callback methods (declared in <tt class="docutils literal"><span class="pre">llvm/Target/TargetLowering.h</span></tt>) are:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">setOperationAction</span></tt> — General operation.</li>
+<li><tt class="docutils literal"><span class="pre">setLoadExtAction</span></tt> — Load with extension.</li>
+<li><tt class="docutils literal"><span class="pre">setTruncStoreAction</span></tt> — Truncating store.</li>
+<li><tt class="docutils literal"><span class="pre">setIndexedLoadAction</span></tt> — Indexed load.</li>
+<li><tt class="docutils literal"><span class="pre">setIndexedStoreAction</span></tt> — Indexed store.</li>
+<li><tt class="docutils literal"><span class="pre">setConvertAction</span></tt> — Type conversion.</li>
+<li><tt class="docutils literal"><span class="pre">setCondCodeAction</span></tt> — Support for a given condition code.</li>
+</ul>
+<p>Note: on older releases, <tt class="docutils literal"><span class="pre">setLoadXAction</span></tt> is used instead of
+<tt class="docutils literal"><span class="pre">setLoadExtAction</span></tt>. Also, on older releases, <tt class="docutils literal"><span class="pre">setCondCodeAction</span></tt> may not
+be supported. Examine your release to see what methods are specifically
+supported.</p>
+<p>These callbacks are used to determine that an operation does or does not work
+with a specified type (or types). And in all cases, the third parameter is a
+<tt class="docutils literal"><span class="pre">LegalAction</span></tt> type enum value: <tt class="docutils literal"><span class="pre">Promote</span></tt>, <tt class="docutils literal"><span class="pre">Expand</span></tt>, <tt class="docutils literal"><span class="pre">Custom</span></tt>, or
+<tt class="docutils literal"><span class="pre">Legal</span></tt>. <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> contains examples of all four
+<tt class="docutils literal"><span class="pre">LegalAction</span></tt> values.</p>
+<div class="section" id="promote">
+<h4><a class="toc-backref" href="#id24">Promote</a><a class="headerlink" href="#promote" title="Permalink to this headline">¶</a></h4>
+<p>For an operation without native support for a given type, the specified type
+may be promoted to a larger type that is supported. For example, SPARC does
+not support a sign-extending load for Boolean values (<tt class="docutils literal"><span class="pre">i1</span></tt> type), so in
+<tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> the third parameter below, <tt class="docutils literal"><span class="pre">Promote</span></tt>, changes
+<tt class="docutils literal"><span class="pre">i1</span></tt> type values to a large type before loading.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setLoadExtAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">SEXTLOAD</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i1</span><span class="p">,</span> <span class="n">Promote</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="expand">
+<h4><a class="toc-backref" href="#id25">Expand</a><a class="headerlink" href="#expand" title="Permalink to this headline">¶</a></h4>
+<p>For a type without native support, a value may need to be broken down further,
+rather than promoted. For an operation without native support, a combination
+of other operations may be used to similar effect. In SPARC, the
+floating-point sine and cosine trig operations are supported by expansion to
+other operations, as indicated by the third parameter, <tt class="docutils literal"><span class="pre">Expand</span></tt>, to
+<tt class="docutils literal"><span class="pre">setOperationAction</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FSIN</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+<span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FCOS</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="custom">
+<h4><a class="toc-backref" href="#id26">Custom</a><a class="headerlink" href="#custom" title="Permalink to this headline">¶</a></h4>
+<p>For some operations, simple type promotion or operation expansion may be
+insufficient. In some cases, a special intrinsic function must be implemented.</p>
+<p>For example, a constant value may require special treatment, or an operation
+may require spilling and restoring registers in the stack and working with
+register allocators.</p>
+<p>As seen in <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> code below, to perform a type conversion
+from a floating point value to a signed integer, first the
+<tt class="docutils literal"><span class="pre">setOperationAction</span></tt> should be called with <tt class="docutils literal"><span class="pre">Custom</span></tt> as the third parameter:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FP_TO_SINT</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Custom</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">LowerOperation</span></tt> method, for each <tt class="docutils literal"><span class="pre">Custom</span></tt> operation, a case
+statement should be added to indicate what function to call. In the following
+code, an <tt class="docutils literal"><span class="pre">FP_TO_SINT</span></tt> opcode will call the <tt class="docutils literal"><span class="pre">LowerFP_TO_SINT</span></tt> method:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDValue</span> <span class="n">SparcTargetLowering</span><span class="o">::</span><span class="n">LowerOperation</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">Op</span><span class="p">,</span> <span class="n">SelectionDAG</span> <span class="o">&</span><span class="n">DAG</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">Op</span><span class="p">.</span><span class="n">getOpcode</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">ISD</span>:<span class="o">:</span><span class="n">FP_TO_SINT</span><span class="o">:</span> <span class="k">return</span> <span class="n">LowerFP_TO_SINT</span><span class="p">(</span><span class="n">Op</span><span class="p">,</span> <span class="n">DAG</span><span class="p">);</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Finally, the <tt class="docutils literal"><span class="pre">LowerFP_TO_SINT</span></tt> method is implemented, using an FP register to
+convert the floating-point value to an integer.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">SDValue</span> <span class="nf">LowerFP_TO_SINT</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">Op</span><span class="p">,</span> <span class="n">SelectionDAG</span> <span class="o">&</span><span class="n">DAG</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Op</span><span class="p">.</span><span class="n">getValueType</span><span class="p">()</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">);</span>
+ <span class="n">Op</span> <span class="o">=</span> <span class="n">DAG</span><span class="p">.</span><span class="n">getNode</span><span class="p">(</span><span class="n">SPISD</span><span class="o">::</span><span class="n">FTOI</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Op</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span>
+ <span class="k">return</span> <span class="n">DAG</span><span class="p">.</span><span class="n">getNode</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">BITCAST</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Op</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="legal">
+<h4><a class="toc-backref" href="#id27">Legal</a><a class="headerlink" href="#legal" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">Legal</span></tt> <tt class="docutils literal"><span class="pre">LegalizeAction</span></tt> enum value simply indicates that an operation
+<strong>is</strong> natively supported. <tt class="docutils literal"><span class="pre">Legal</span></tt> represents the default condition, so it
+is rarely used. In <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt>, the action for <tt class="docutils literal"><span class="pre">CTPOP</span></tt> (an
+operation to count the bits set in an integer) is natively supported only for
+SPARC v9. The following code enables the <tt class="docutils literal"><span class="pre">Expand</span></tt> conversion technique for
+non-v9 SPARC implementations.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">CTPOP</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+<span class="p">...</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">TM</span><span class="p">.</span><span class="n">getSubtarget</span><span class="o"><</span><span class="n">SparcSubtarget</span><span class="o">></span><span class="p">().</span><span class="n">isV9</span><span class="p">())</span>
+ <span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">CTPOP</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Legal</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="calling-conventions">
+<h3><a class="toc-backref" href="#id28">Calling Conventions</a><a class="headerlink" href="#calling-conventions" title="Permalink to this headline">¶</a></h3>
+<p>To support target-specific calling conventions, <tt class="docutils literal"><span class="pre">XXXGenCallingConv.td</span></tt> uses
+interfaces (such as <tt class="docutils literal"><span class="pre">CCIfType</span></tt> and <tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt>) that are defined in
+<tt class="docutils literal"><span class="pre">lib/Target/TargetCallingConv.td</span></tt>. TableGen can take the target descriptor
+file <tt class="docutils literal"><span class="pre">XXXGenCallingConv.td</span></tt> and generate the header file
+<tt class="docutils literal"><span class="pre">XXXGenCallingConv.inc</span></tt>, which is typically included in
+<tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>. You can use the interfaces in
+<tt class="docutils literal"><span class="pre">TargetCallingConv.td</span></tt> to specify:</p>
+<ul class="simple">
+<li>The order of parameter allocation.</li>
+<li>Where parameters and return values are placed (that is, on the stack or in
+registers).</li>
+<li>Which registers may be used.</li>
+<li>Whether the caller or callee unwinds the stack.</li>
+</ul>
+<p>The following example demonstrates the use of the <tt class="docutils literal"><span class="pre">CCIfType</span></tt> and
+<tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt> interfaces. If the <tt class="docutils literal"><span class="pre">CCIfType</span></tt> predicate is true (that is,
+if the current argument is of type <tt class="docutils literal"><span class="pre">f32</span></tt> or <tt class="docutils literal"><span class="pre">f64</span></tt>), then the action is
+performed. In this case, the <tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt> action assigns the argument
+value to the first available register: either <tt class="docutils literal"><span class="pre">R0</span></tt> or <tt class="docutils literal"><span class="pre">R1</span></tt>.</p>
+<div class="highlight-text"><div class="highlight"><pre>CCIfType<[f32,f64], CCAssignToReg<[R0, R1]>>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">SparcCallingConv.td</span></tt> contains definitions for a target-specific return-value
+calling convention (<tt class="docutils literal"><span class="pre">RetCC_Sparc32</span></tt>) and a basic 32-bit C calling convention
+(<tt class="docutils literal"><span class="pre">CC_Sparc32</span></tt>). The definition of <tt class="docutils literal"><span class="pre">RetCC_Sparc32</span></tt> (shown below) indicates
+which registers are used for specified scalar return types. A single-precision
+float is returned to register <tt class="docutils literal"><span class="pre">F0</span></tt>, and a double-precision float goes to
+register <tt class="docutils literal"><span class="pre">D0</span></tt>. A 32-bit integer is returned in register <tt class="docutils literal"><span class="pre">I0</span></tt> or <tt class="docutils literal"><span class="pre">I1</span></tt>.</p>
+<div class="highlight-text"><div class="highlight"><pre>def RetCC_Sparc32 : CallingConv<[
+ CCIfType<[i32], CCAssignToReg<[I0, I1]>>,
+ CCIfType<[f32], CCAssignToReg<[F0]>>,
+ CCIfType<[f64], CCAssignToReg<[D0]>>
+]>;
+</pre></div>
+</div>
+<p>The definition of <tt class="docutils literal"><span class="pre">CC_Sparc32</span></tt> in <tt class="docutils literal"><span class="pre">SparcCallingConv.td</span></tt> introduces
+<tt class="docutils literal"><span class="pre">CCAssignToStack</span></tt>, which assigns the value to a stack slot with the specified
+size and alignment. In the example below, the first parameter, 4, indicates
+the size of the slot, and the second parameter, also 4, indicates the stack
+alignment along 4-byte units. (Special cases: if size is zero, then the ABI
+size is used; if alignment is zero, then the ABI alignment is used.)</p>
+<div class="highlight-text"><div class="highlight"><pre>def CC_Sparc32 : CallingConv<[
+ // All arguments get passed in integer registers if there is space.
+ CCIfType<[i32, f32, f64], CCAssignToReg<[I0, I1, I2, I3, I4, I5]>>,
+ CCAssignToStack<4, 4>
+]>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">CCDelegateTo</span></tt> is another commonly used interface, which tries to find a
+specified sub-calling convention, and, if a match is found, it is invoked. In
+the following example (in <tt class="docutils literal"><span class="pre">X86CallingConv.td</span></tt>), the definition of
+<tt class="docutils literal"><span class="pre">RetCC_X86_32_C</span></tt> ends with <tt class="docutils literal"><span class="pre">CCDelegateTo</span></tt>. After the current value is
+assigned to the register <tt class="docutils literal"><span class="pre">ST0</span></tt> or <tt class="docutils literal"><span class="pre">ST1</span></tt>, the <tt class="docutils literal"><span class="pre">RetCC_X86Common</span></tt> is
+invoked.</p>
+<div class="highlight-text"><div class="highlight"><pre>def RetCC_X86_32_C : CallingConv<[
+ CCIfType<[f32], CCAssignToReg<[ST0, ST1]>>,
+ CCIfType<[f64], CCAssignToReg<[ST0, ST1]>>,
+ CCDelegateTo<RetCC_X86Common>
+]>;
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">CCIfCC</span></tt> is an interface that attempts to match the given name to the current
+calling convention. If the name identifies the current calling convention,
+then a specified action is invoked. In the following example (in
+<tt class="docutils literal"><span class="pre">X86CallingConv.td</span></tt>), if the <tt class="docutils literal"><span class="pre">Fast</span></tt> calling convention is in use, then
+<tt class="docutils literal"><span class="pre">RetCC_X86_32_Fast</span></tt> is invoked. If the <tt class="docutils literal"><span class="pre">SSECall</span></tt> calling convention is in
+use, then <tt class="docutils literal"><span class="pre">RetCC_X86_32_SSE</span></tt> is invoked.</p>
+<div class="highlight-text"><div class="highlight"><pre>def RetCC_X86_32 : CallingConv<[
+ CCIfCC<"CallingConv::Fast", CCDelegateTo<RetCC_X86_32_Fast>>,
+ CCIfCC<"CallingConv::X86_SSECall", CCDelegateTo<RetCC_X86_32_SSE>>,
+ CCDelegateTo<RetCC_X86_32_C>
+]>;
+</pre></div>
+</div>
+<p>Other calling convention interfaces include:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">CCIf</span> <span class="pre"><predicate,</span> <span class="pre">action></span></tt> — If the predicate matches, apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfInReg</span> <span class="pre"><action></span></tt> — If the argument is marked with the “<tt class="docutils literal"><span class="pre">inreg</span></tt>”
+attribute, then apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfNest</span> <span class="pre"><action></span></tt> — If the argument is marked with the “<tt class="docutils literal"><span class="pre">nest</span></tt>”
+attribute, then apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfNotVarArg</span> <span class="pre"><action></span></tt> — If the current function does not take a
+variable number of arguments, apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCAssignToRegWithShadow</span> <span class="pre"><registerList,</span> <span class="pre">shadowList></span></tt> — similar to
+<tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt>, but with a shadow list of registers.</li>
+<li><tt class="docutils literal"><span class="pre">CCPassByVal</span> <span class="pre"><size,</span> <span class="pre">align></span></tt> — Assign value to a stack slot with the
+minimum specified size and alignment.</li>
+<li><tt class="docutils literal"><span class="pre">CCPromoteToType</span> <span class="pre"><type></span></tt> — Promote the current value to the specified
+type.</li>
+<li><tt class="docutils literal"><span class="pre">CallingConv</span> <span class="pre"><[actions]></span></tt> — Define each calling convention that is
+supported.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="assembly-printer">
+<h2><a class="toc-backref" href="#id29">Assembly Printer</a><a class="headerlink" href="#assembly-printer" title="Permalink to this headline">¶</a></h2>
+<p>During the code emission stage, the code generator may utilize an LLVM pass to
+produce assembly output. To do this, you want to implement the code for a
+printer that converts LLVM IR to a GAS-format assembly language for your target
+machine, using the following steps:</p>
+<ul class="simple">
+<li>Define all the assembly strings for your target, adding them to the
+instructions defined in the <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> file. (See
+<a class="reference internal" href="#instruction-set"><em>Instruction Set</em></a>.) TableGen will produce an output file
+(<tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt>) with an implementation of the <tt class="docutils literal"><span class="pre">printInstruction</span></tt>
+method for the <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt> class.</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.h</span></tt>, which contains the bare-bones declaration of
+the <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt> class (a subclass of <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt>).</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt>, which contains target-specific values for
+<tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt> properties and sometimes new implementations for methods.</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, which implements the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> class that
+performs the LLVM-to-assembly conversion.</li>
+</ul>
+<p>The code in <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.h</span></tt> is usually a trivial declaration of the
+<tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt> class for use in <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt>. Similarly,
+<tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt> usually has a few declarations of <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt>
+replacement values that override the default values in <tt class="docutils literal"><span class="pre">TargetAsmInfo.cpp</span></tt>.
+For example in <tt class="docutils literal"><span class="pre">SparcTargetAsmInfo.cpp</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SparcTargetAsmInfo</span><span class="o">::</span><span class="n">SparcTargetAsmInfo</span><span class="p">(</span><span class="k">const</span> <span class="n">SparcTargetMachine</span> <span class="o">&</span><span class="n">TM</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Data16bitsDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.half</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">Data32bitsDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.word</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">Data64bitsDirective</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// .xword is only supported by V9.</span>
+ <span class="n">ZeroDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.skip</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">CommentString</span> <span class="o">=</span> <span class="s">"!"</span><span class="p">;</span>
+ <span class="n">ConstantPoolSection</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.section </span><span class="se">\"</span><span class="s">.rodata</span><span class="se">\"</span><span class="s">,#alloc</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The X86 assembly printer implementation (<tt class="docutils literal"><span class="pre">X86TargetAsmInfo</span></tt>) is an example
+where the target specific <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt> class uses an overridden methods:
+<tt class="docutils literal"><span class="pre">ExpandInlineAsm</span></tt>.</p>
+<p>A target-specific implementation of <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> is written in
+<tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, which implements the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> class that converts
+the LLVM to printable assembly. The implementation must include the following
+headers that have declarations for the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> and
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> classes. The <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> is a subclass of
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/CodeGen/AsmPrinter.h"</span>
+<span class="cp">#include "llvm/CodeGen/MachineFunctionPass.h"</span>
+</pre></div>
+</div>
+<p>As a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> first calls <tt class="docutils literal"><span class="pre">doInitialization</span></tt> to set
+up the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt>. In <tt class="docutils literal"><span class="pre">SparcAsmPrinter</span></tt>, a <tt class="docutils literal"><span class="pre">Mangler</span></tt> object is
+instantiated to process variable names.</p>
+<p>In <tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, the <tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> method (declared in
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>) must be implemented for <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt>. In
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>, the <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method invokes
+<tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt>. Target-specific implementations of
+<tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> differ, but generally do the following to process each
+machine function:</p>
+<ul class="simple">
+<li>Call <tt class="docutils literal"><span class="pre">SetupMachineFunction</span></tt> to perform initialization.</li>
+<li>Call <tt class="docutils literal"><span class="pre">EmitConstantPool</span></tt> to print out (to the output stream) constants which
+have been spilled to memory.</li>
+<li>Call <tt class="docutils literal"><span class="pre">EmitJumpTableInfo</span></tt> to print out jump tables used by the current
+function.</li>
+<li>Print out the label for the current function.</li>
+<li>Print out the code for the function, including basic block labels and the
+assembly for the instruction (using <tt class="docutils literal"><span class="pre">printInstruction</span></tt>)</li>
+</ul>
+<p>The <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt> implementation must also include the code generated by
+TableGen that is output in the <tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt> file. The code in
+<tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt> contains an implementation of the <tt class="docutils literal"><span class="pre">printInstruction</span></tt>
+method that may call these methods:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">printOperand</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printMemOperand</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printCCOperand</span></tt> (for conditional statements)</li>
+<li><tt class="docutils literal"><span class="pre">printDataDirective</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printDeclare</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printImplicitDef</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printInlineAsm</span></tt></li>
+</ul>
+<p>The implementations of <tt class="docutils literal"><span class="pre">printDeclare</span></tt>, <tt class="docutils literal"><span class="pre">printImplicitDef</span></tt>,
+<tt class="docutils literal"><span class="pre">printInlineAsm</span></tt>, and <tt class="docutils literal"><span class="pre">printLabel</span></tt> in <tt class="docutils literal"><span class="pre">AsmPrinter.cpp</span></tt> are generally
+adequate for printing assembly and do not need to be overridden.</p>
+<p>The <tt class="docutils literal"><span class="pre">printOperand</span></tt> method is implemented with a long <tt class="docutils literal"><span class="pre">switch</span></tt>/<tt class="docutils literal"><span class="pre">case</span></tt>
+statement for the type of operand: register, immediate, basic block, external
+symbol, global address, constant pool index, or jump table index. For an
+instruction with a memory address operand, the <tt class="docutils literal"><span class="pre">printMemOperand</span></tt> method
+should be implemented to generate the proper output. Similarly,
+<tt class="docutils literal"><span class="pre">printCCOperand</span></tt> should be used to print a conditional operand.</p>
+<p><tt class="docutils literal"><span class="pre">doFinalization</span></tt> should be overridden in <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt>, and it should be
+called to shut down the assembly printer. During <tt class="docutils literal"><span class="pre">doFinalization</span></tt>, global
+variables and constants are printed to output.</p>
+</div>
+<div class="section" id="subtarget-support">
+<h2><a class="toc-backref" href="#id30">Subtarget Support</a><a class="headerlink" href="#subtarget-support" title="Permalink to this headline">¶</a></h2>
+<p>Subtarget support is used to inform the code generation process of instruction
+set variations for a given chip set. For example, the LLVM SPARC
+implementation provided covers three major versions of the SPARC microprocessor
+architecture: Version 8 (V8, which is a 32-bit architecture), Version 9 (V9, a
+64-bit architecture), and the UltraSPARC architecture. V8 has 16
+double-precision floating-point registers that are also usable as either 32
+single-precision or 8 quad-precision registers. V8 is also purely big-endian.
+V9 has 32 double-precision floating-point registers that are also usable as 16
+quad-precision registers, but cannot be used as single-precision registers.
+The UltraSPARC architecture combines V9 with UltraSPARC Visual Instruction Set
+extensions.</p>
+<p>If subtarget support is needed, you should implement a target-specific
+<tt class="docutils literal"><span class="pre">XXXSubtarget</span></tt> class for your architecture. This class should process the
+command-line options <tt class="docutils literal"><span class="pre">-mcpu=</span></tt> and <tt class="docutils literal"><span class="pre">-mattr=</span></tt>.</p>
+<p>TableGen uses definitions in the <tt class="docutils literal"><span class="pre">Target.td</span></tt> and <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> files to
+generate code in <tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt>. In <tt class="docutils literal"><span class="pre">Target.td</span></tt>, shown below, the
+<tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> interface is defined. The first 4 string parameters of
+the <tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> interface are a feature name, an attribute set by the
+feature, the value of the attribute, and a description of the feature. (The
+fifth parameter is a list of features whose presence is implied, and its
+default value is an empty array.)</p>
+<div class="highlight-text"><div class="highlight"><pre>class SubtargetFeature<string n, string a, string v, string d,
+ list<SubtargetFeature> i = []> {
+ string Name = n;
+ string Attribute = a;
+ string Value = v;
+ string Desc = d;
+ list<SubtargetFeature> Implies = i;
+}
+</pre></div>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> file, the <tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> is used to define the
+following features.</p>
+<div class="highlight-text"><div class="highlight"><pre>def FeatureV9 : SubtargetFeature<"v9", "IsV9", "true",
+ "Enable SPARC-V9 instructions">;
+def FeatureV8Deprecated : SubtargetFeature<"deprecated-v8",
+ "V8DeprecatedInsts", "true",
+ "Enable deprecated V8 instructions in V9 mode">;
+def FeatureVIS : SubtargetFeature<"vis", "IsVIS", "true",
+ "Enable UltraSPARC Visual Instruction Set extensions">;
+</pre></div>
+</div>
+<p>Elsewhere in <tt class="docutils literal"><span class="pre">Sparc.td</span></tt>, the <tt class="docutils literal"><span class="pre">Proc</span></tt> class is defined and then is used to
+define particular SPARC processor subtypes that may have the previously
+described features.</p>
+<div class="highlight-text"><div class="highlight"><pre>class Proc<string Name, list<SubtargetFeature> Features>
+ : Processor<Name, NoItineraries, Features>;
+
+def : Proc<"generic", []>;
+def : Proc<"v8", []>;
+def : Proc<"supersparc", []>;
+def : Proc<"sparclite", []>;
+def : Proc<"f934", []>;
+def : Proc<"hypersparc", []>;
+def : Proc<"sparclite86x", []>;
+def : Proc<"sparclet", []>;
+def : Proc<"tsc701", []>;
+def : Proc<"v9", [FeatureV9]>;
+def : Proc<"ultrasparc", [FeatureV9, FeatureV8Deprecated]>;
+def : Proc<"ultrasparc3", [FeatureV9, FeatureV8Deprecated]>;
+def : Proc<"ultrasparc3-vis", [FeatureV9, FeatureV8Deprecated, FeatureVIS]>;
+</pre></div>
+</div>
+<p>From <tt class="docutils literal"><span class="pre">Target.td</span></tt> and <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> files, the resulting
+<tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt> specifies enum values to identify the features,
+arrays of constants to represent the CPU features and CPU subtypes, and the
+<tt class="docutils literal"><span class="pre">ParseSubtargetFeatures</span></tt> method that parses the features string that sets
+specified subtarget options. The generated <tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt> file
+should be included in the <tt class="docutils literal"><span class="pre">SparcSubtarget.cpp</span></tt>. The target-specific
+implementation of the <tt class="docutils literal"><span class="pre">XXXSubtarget</span></tt> method should follow this pseudocode:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">XXXSubtarget</span><span class="o">::</span><span class="n">XXXSubtarget</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">,</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">FS</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Set the default features</span>
+ <span class="c1">// Determine default and user specified characteristics of the CPU</span>
+ <span class="c1">// Call ParseSubtargetFeatures(FS, CPU) to parse the features string</span>
+ <span class="c1">// Perform any additional operations</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="jit-support">
+<h2><a class="toc-backref" href="#id31">JIT Support</a><a class="headerlink" href="#jit-support" title="Permalink to this headline">¶</a></h2>
+<p>The implementation of a target machine optionally includes a Just-In-Time (JIT)
+code generator that emits machine code and auxiliary structures as binary
+output that can be written directly to memory. To do this, implement JIT code
+generation by performing the following steps:</p>
+<ul class="simple">
+<li>Write an <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> file that contains a machine function pass
+that transforms target-machine instructions into relocatable machine
+code.</li>
+<li>Write an <tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> file that implements the JIT interfaces for
+target-specific code-generation activities, such as emitting machine code and
+stubs.</li>
+<li>Modify <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> so that it provides a <tt class="docutils literal"><span class="pre">TargetJITInfo</span></tt> object
+through its <tt class="docutils literal"><span class="pre">getJITInfo</span></tt> method.</li>
+</ul>
+<p>There are several different approaches to writing the JIT support code. For
+instance, TableGen and target descriptor files may be used for creating a JIT
+code generator, but are not mandatory. For the Alpha and PowerPC target
+machines, TableGen is used to generate <tt class="docutils literal"><span class="pre">XXXGenCodeEmitter.inc</span></tt>, which
+contains the binary coding of machine instructions and the
+<tt class="docutils literal"><span class="pre">getBinaryCodeForInstr</span></tt> method to access those codes. Other JIT
+implementations do not.</p>
+<p>Both <tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> and <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> must include the
+<tt class="docutils literal"><span class="pre">llvm/CodeGen/MachineCodeEmitter.h</span></tt> header file that defines the
+<tt class="docutils literal"><span class="pre">MachineCodeEmitter</span></tt> class containing code for several callback functions
+that write data (in bytes, words, strings, etc.) to the output stream.</p>
+<div class="section" id="machine-code-emitter">
+<h3><a class="toc-backref" href="#id32">Machine Code Emitter</a><a class="headerlink" href="#machine-code-emitter" title="Permalink to this headline">¶</a></h3>
+<p>In <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt>, a target-specific of the <tt class="docutils literal"><span class="pre">Emitter</span></tt> class is
+implemented as a function pass (subclass of <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>). The
+target-specific implementation of <tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> (invoked by
+<tt class="docutils literal"><span class="pre">runOnFunction</span></tt> in <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>) iterates through the
+<tt class="docutils literal"><span class="pre">MachineBasicBlock</span></tt> calls <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> to process each instruction and
+emit binary code. <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> is largely implemented with case
+statements on the instruction types defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.h</span></tt>. For
+example, in <tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt>, the <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> method is built
+around the following <tt class="docutils literal"><span class="pre">switch</span></tt>/<tt class="docutils literal"><span class="pre">case</span></tt> statements:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">switch</span> <span class="p">(</span><span class="n">Desc</span><span class="o">-></span><span class="n">TSFlags</span> <span class="o">&</span> <span class="n">X86</span><span class="o">::</span><span class="n">FormMask</span><span class="p">)</span> <span class="p">{</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">Pseudo</span><span class="o">:</span> <span class="c1">// for not yet implemented instructions</span>
+ <span class="p">...</span> <span class="c1">// or pseudo-instructions</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">RawFrm</span><span class="o">:</span> <span class="c1">// for instructions with a fixed opcode value</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">AddRegFrm</span><span class="o">:</span> <span class="c1">// for instructions that have one register operand</span>
+ <span class="p">...</span> <span class="c1">// added to their opcode</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMDestReg</span><span class="o">:</span><span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a destination (register)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMDestMem</span><span class="o">:</span><span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a destination (memory)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMSrcReg</span><span class="o">:</span> <span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a source (register)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMSrcMem</span><span class="o">:</span> <span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a source (memory)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM0r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM1r</span><span class="o">:</span> <span class="c1">// for instructions that operate on</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM2r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM3r</span><span class="o">:</span> <span class="c1">// a REGISTER r/m operand and</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM4r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM5r</span><span class="o">:</span> <span class="c1">// use the Mod/RM byte and a field</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM6r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM7r</span><span class="o">:</span> <span class="c1">// to hold extended opcode data</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM0m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM1m</span><span class="o">:</span> <span class="c1">// for instructions that operate on</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM2m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM3m</span><span class="o">:</span> <span class="c1">// a MEMORY r/m operand and</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM4m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM5m</span><span class="o">:</span> <span class="c1">// use the Mod/RM byte and a field</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM6m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM7m</span><span class="o">:</span> <span class="c1">// to hold extended opcode data</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMInitReg</span><span class="o">:</span> <span class="c1">// for instructions whose source and</span>
+ <span class="p">...</span> <span class="c1">// destination are the same register</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The implementations of these case statements often first emit the opcode and
+then get the operand(s). Then depending upon the operand, helper methods may
+be called to process the operand(s). For example, in <tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt>,
+for the <tt class="docutils literal"><span class="pre">X86II::AddRegFrm</span></tt> case, the first data emitted (by <tt class="docutils literal"><span class="pre">emitByte</span></tt>) is
+the opcode added to the register operand. Then an object representing the
+machine operand, <tt class="docutils literal"><span class="pre">MO1</span></tt>, is extracted. The helper methods such as
+<tt class="docutils literal"><span class="pre">isImmediate</span></tt>, <tt class="docutils literal"><span class="pre">isGlobalAddress</span></tt>, <tt class="docutils literal"><span class="pre">isExternalSymbol</span></tt>,
+<tt class="docutils literal"><span class="pre">isConstantPoolIndex</span></tt>, and <tt class="docutils literal"><span class="pre">isJumpTableIndex</span></tt> determine the operand type.
+(<tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt> also has private methods such as <tt class="docutils literal"><span class="pre">emitConstant</span></tt>,
+<tt class="docutils literal"><span class="pre">emitGlobalAddress</span></tt>, <tt class="docutils literal"><span class="pre">emitExternalSymbolAddress</span></tt>, <tt class="docutils literal"><span class="pre">emitConstPoolAddress</span></tt>,
+and <tt class="docutils literal"><span class="pre">emitJumpTableAddress</span></tt> that emit the data into the output stream.)</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">AddRegFrm</span><span class="o">:</span>
+ <span class="n">MCE</span><span class="p">.</span><span class="n">emitByte</span><span class="p">(</span><span class="n">BaseOpcode</span> <span class="o">+</span> <span class="n">getX86RegNum</span><span class="p">(</span><span class="n">MI</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="n">CurOp</span><span class="o">++</span><span class="p">).</span><span class="n">getReg</span><span class="p">()));</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">CurOp</span> <span class="o">!=</span> <span class="n">NumOps</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="n">MachineOperand</span> <span class="o">&</span><span class="n">MO1</span> <span class="o">=</span> <span class="n">MI</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="n">CurOp</span><span class="o">++</span><span class="p">);</span>
+ <span class="kt">unsigned</span> <span class="n">Size</span> <span class="o">=</span> <span class="n">X86InstrInfo</span><span class="o">::</span><span class="n">sizeOfImm</span><span class="p">(</span><span class="n">Desc</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isImmediate</span><span class="p">())</span>
+ <span class="n">emitConstant</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getImm</span><span class="p">(),</span> <span class="n">Size</span><span class="p">);</span>
+ <span class="k">else</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">rt</span> <span class="o">=</span> <span class="n">Is64BitMode</span> <span class="o">?</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_pcrel_word</span>
+ <span class="o">:</span> <span class="p">(</span><span class="n">IsPIC</span> <span class="o">?</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_picrel_word</span> <span class="o">:</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_absolute_word</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Opcode</span> <span class="o">==</span> <span class="n">X86</span><span class="o">::</span><span class="n">MOV64ri</span><span class="p">)</span>
+ <span class="n">rt</span> <span class="o">=</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_absolute_dword</span><span class="p">;</span> <span class="c1">// FIXME: add X86II flag?</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isGlobalAddress</span><span class="p">())</span> <span class="p">{</span>
+ <span class="kt">bool</span> <span class="n">NeedStub</span> <span class="o">=</span> <span class="n">isa</span><span class="o"><</span><span class="n">Function</span><span class="o">></span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">());</span>
+ <span class="kt">bool</span> <span class="n">isLazy</span> <span class="o">=</span> <span class="n">gvNeedsLazyPtr</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">());</span>
+ <span class="n">emitGlobalAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">(),</span> <span class="n">rt</span><span class="p">,</span> <span class="n">MO1</span><span class="p">.</span><span class="n">getOffset</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span>
+ <span class="n">NeedStub</span><span class="p">,</span> <span class="n">isLazy</span><span class="p">);</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isExternalSymbol</span><span class="p">())</span>
+ <span class="n">emitExternalSymbolAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getSymbolName</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="k">else</span> <span class="nf">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isConstantPoolIndex</span><span class="p">())</span>
+ <span class="n">emitConstPoolAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getIndex</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="k">else</span> <span class="nf">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isJumpTableIndex</span><span class="p">())</span>
+ <span class="n">emitJumpTableAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getIndex</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="k">break</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>In the previous example, <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> uses the variable <tt class="docutils literal"><span class="pre">rt</span></tt>, which
+is a <tt class="docutils literal"><span class="pre">RelocationType</span></tt> enum that may be used to relocate addresses (for
+example, a global address with a PIC base offset). The <tt class="docutils literal"><span class="pre">RelocationType</span></tt> enum
+for that target is defined in the short target-specific <tt class="docutils literal"><span class="pre">XXXRelocations.h</span></tt>
+file. The <tt class="docutils literal"><span class="pre">RelocationType</span></tt> is used by the <tt class="docutils literal"><span class="pre">relocate</span></tt> method defined in
+<tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> to rewrite addresses for referenced global symbols.</p>
+<p>For example, <tt class="docutils literal"><span class="pre">X86Relocations.h</span></tt> specifies the following relocation types for
+the X86 addresses. In all four cases, the relocated value is added to the
+value already in memory. For <tt class="docutils literal"><span class="pre">reloc_pcrel_word</span></tt> and <tt class="docutils literal"><span class="pre">reloc_picrel_word</span></tt>,
+there is an additional initial adjustment.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">RelocationType</span> <span class="p">{</span>
+ <span class="n">reloc_pcrel_word</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// add reloc value after adjusting for the PC loc</span>
+ <span class="n">reloc_picrel_word</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// add reloc value after adjusting for the PIC base</span>
+ <span class="n">reloc_absolute_word</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> <span class="c1">// absolute relocation; no additional adjustment</span>
+ <span class="n">reloc_absolute_dword</span> <span class="o">=</span> <span class="mi">3</span> <span class="c1">// absolute relocation; no additional adjustment</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="target-jit-info">
+<h3><a class="toc-backref" href="#id33">Target JIT Info</a><a class="headerlink" href="#target-jit-info" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> implements the JIT interfaces for target-specific
+code-generation activities, such as emitting machine code and stubs. At
+minimum, a target-specific version of <tt class="docutils literal"><span class="pre">XXXJITInfo</span></tt> implements the following:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> — Initializes the JIT, gives the target a
+function that is used for compilation.</li>
+<li><tt class="docutils literal"><span class="pre">emitFunctionStub</span></tt> — Returns a native function with a specified address
+for a callback function.</li>
+<li><tt class="docutils literal"><span class="pre">relocate</span></tt> — Changes the addresses of referenced globals, based on
+relocation types.</li>
+<li>Callback function that are wrappers to a function stub that is used when the
+real target is not initially known.</li>
+</ul>
+<p><tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> is generally trivial to implement. It makes the
+incoming parameter as the global <tt class="docutils literal"><span class="pre">JITCompilerFunction</span></tt> and returns the
+callback function that will be used a function wrapper. For the Alpha target
+(in <tt class="docutils literal"><span class="pre">AlphaJITInfo.cpp</span></tt>), the <tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> implementation is
+simply:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">TargetJITInfo</span><span class="o">::</span><span class="n">LazyResolverFn</span> <span class="n">AlphaJITInfo</span><span class="o">::</span><span class="n">getLazyResolverFunction</span><span class="p">(</span>
+ <span class="n">JITCompilerFn</span> <span class="n">F</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">JITCompilerFunction</span> <span class="o">=</span> <span class="n">F</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">AlphaCompilationCallback</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For the X86 target, the <tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> implementation is a little
+more complicated, because it returns a different callback function for
+processors with SSE instructions and XMM registers.</p>
+<p>The callback function initially saves and later restores the callee register
+values, incoming arguments, and frame and return address. The callback
+function needs low-level access to the registers or stack, so it is typically
+implemented with assembler.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/WritingAnLLVMPass.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/WritingAnLLVMPass.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/WritingAnLLVMPass.html (added)
+++ www-releases/trunk/3.9.1/docs/WritingAnLLVMPass.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,1333 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Writing an LLVM Pass — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="How To Use Attributes" href="HowToUseAttributes.html" />
+ <link rel="prev" title="Garbage Collection with LLVM" href="GarbageCollection.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToUseAttributes.html" title="How To Use Attributes"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GarbageCollection.html" title="Garbage Collection with LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="writing-an-llvm-pass">
+<h1>Writing an LLVM Pass<a class="headerlink" href="#writing-an-llvm-pass" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction-what-is-a-pass" id="id5">Introduction — What is a pass?</a></li>
+<li><a class="reference internal" href="#quick-start-writing-hello-world" id="id6">Quick Start — Writing hello world</a><ul>
+<li><a class="reference internal" href="#setting-up-the-build-environment" id="id7">Setting up the build environment</a></li>
+<li><a class="reference internal" href="#basic-code-required" id="id8">Basic code required</a></li>
+<li><a class="reference internal" href="#running-a-pass-with-opt" id="id9">Running a pass with <tt class="docutils literal"><span class="pre">opt</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#pass-classes-and-requirements" id="id10">Pass classes and requirements</a><ul>
+<li><a class="reference internal" href="#the-immutablepass-class" id="id11">The <tt class="docutils literal"><span class="pre">ImmutablePass</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-modulepass-class" id="id12">The <tt class="docutils literal"><span class="pre">ModulePass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-runonmodule-method" id="id13">The <tt class="docutils literal"><span class="pre">runOnModule</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-callgraphsccpass-class" id="id14">The <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-callgraph-method" id="id15">The <tt class="docutils literal"><span class="pre">doInitialization(CallGraph</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonscc-method" id="id16">The <tt class="docutils literal"><span class="pre">runOnSCC</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-dofinalization-callgraph-method" id="id17">The <tt class="docutils literal"><span class="pre">doFinalization(CallGraph</span> <span class="pre">&)</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-functionpass-class" id="id18">The <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-module-method" id="id19">The <tt class="docutils literal"><span class="pre">doInitialization(Module</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonfunction-method" id="id20">The <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-dofinalization-module-method" id="id21">The <tt class="docutils literal"><span class="pre">doFinalization(Module</span> <span class="pre">&)</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-looppass-class" id="id22">The <tt class="docutils literal"><span class="pre">LoopPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-loop-lppassmanager-method" id="id23">The <tt class="docutils literal"><span class="pre">doInitialization(Loop</span> <span class="pre">*,</span> <span class="pre">LPPassManager</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonloop-method" id="id24">The <tt class="docutils literal"><span class="pre">runOnLoop</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-dofinalization-method" id="id25">The <tt class="docutils literal"><span class="pre">doFinalization()</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-regionpass-class" id="id26">The <tt class="docutils literal"><span class="pre">RegionPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-region-rgpassmanager-method" id="id27">The <tt class="docutils literal"><span class="pre">doInitialization(Region</span> <span class="pre">*,</span> <span class="pre">RGPassManager</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonregion-method" id="id28">The <tt class="docutils literal"><span class="pre">runOnRegion</span></tt> method</a></li>
+<li><a class="reference internal" href="#id2" id="id29">The <tt class="docutils literal"><span class="pre">doFinalization()</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-basicblockpass-class" id="id30">The <tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-doinitialization-function-method" id="id31">The <tt class="docutils literal"><span class="pre">doInitialization(Function</span> <span class="pre">&)</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-runonbasicblock-method" id="id32">The <tt class="docutils literal"><span class="pre">runOnBasicBlock</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-dofinalization-function-method" id="id33">The <tt class="docutils literal"><span class="pre">doFinalization(Function</span> <span class="pre">&)</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-machinefunctionpass-class" id="id34">The <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> class</a><ul>
+<li><a class="reference internal" href="#the-runonmachinefunction-machinefunction-mf-method" id="id35">The <tt class="docutils literal"><span class="pre">runOnMachineFunction(MachineFunction</span> <span class="pre">&MF)</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#pass-registration" id="id36">Pass registration</a><ul>
+<li><a class="reference internal" href="#the-print-method" id="id37">The <tt class="docutils literal"><span class="pre">print</span></tt> method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#specifying-interactions-between-passes" id="id38">Specifying interactions between passes</a><ul>
+<li><a class="reference internal" href="#the-getanalysisusage-method" id="id39">The <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt> method</a></li>
+<li><a class="reference internal" href="#the-analysisusage-addrequired-and-analysisusage-addrequiredtransitive-methods" id="id40">The <tt class="docutils literal"><span class="pre">AnalysisUsage::addRequired<></span></tt> and <tt class="docutils literal"><span class="pre">AnalysisUsage::addRequiredTransitive<></span></tt> methods</a></li>
+<li><a class="reference internal" href="#the-analysisusage-addpreserved-method" id="id41">The <tt class="docutils literal"><span class="pre">AnalysisUsage::addPreserved<></span></tt> method</a></li>
+<li><a class="reference internal" href="#example-implementations-of-getanalysisusage" id="id42">Example implementations of <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt></a></li>
+<li><a class="reference internal" href="#the-getanalysis-and-getanalysisifavailable-methods" id="id43">The <tt class="docutils literal"><span class="pre">getAnalysis<></span></tt> and <tt class="docutils literal"><span class="pre">getAnalysisIfAvailable<></span></tt> methods</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#implementing-analysis-groups" id="id44">Implementing Analysis Groups</a><ul>
+<li><a class="reference internal" href="#analysis-group-concepts" id="id45">Analysis Group Concepts</a></li>
+<li><a class="reference internal" href="#using-registeranalysisgroup" id="id46">Using <tt class="docutils literal"><span class="pre">RegisterAnalysisGroup</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#pass-statistics" id="id47">Pass Statistics</a><ul>
+<li><a class="reference internal" href="#what-passmanager-does" id="id48">What PassManager does</a><ul>
+<li><a class="reference internal" href="#the-releasememory-method" id="id49">The <tt class="docutils literal"><span class="pre">releaseMemory</span></tt> method</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#registering-dynamically-loaded-passes" id="id50">Registering dynamically loaded passes</a><ul>
+<li><a class="reference internal" href="#using-existing-registries" id="id51">Using existing registries</a></li>
+<li><a class="reference internal" href="#creating-new-registries" id="id52">Creating new registries</a></li>
+<li><a class="reference internal" href="#using-gdb-with-dynamically-loaded-passes" id="id53">Using GDB with dynamically loaded passes</a><ul>
+<li><a class="reference internal" href="#setting-a-breakpoint-in-your-pass" id="id54">Setting a breakpoint in your pass</a></li>
+<li><a class="reference internal" href="#miscellaneous-problems" id="id55">Miscellaneous Problems</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#future-extensions-planned" id="id56">Future extensions planned</a><ul>
+<li><a class="reference internal" href="#multithreaded-llvm" id="id57">Multithreaded LLVM</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction-what-is-a-pass">
+<h2><a class="toc-backref" href="#id5">Introduction — What is a pass?</a><a class="headerlink" href="#introduction-what-is-a-pass" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM Pass Framework is an important part of the LLVM system, because LLVM
+passes are where most of the interesting parts of the compiler exist. Passes
+perform the transformations and optimizations that make up the compiler, they
+build the analysis results that are used by these transformations, and they
+are, above all, a structuring technique for compiler code.</p>
+<p>All LLVM passes are subclasses of the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a> class, which implement
+functionality by overriding virtual methods inherited from <tt class="docutils literal"><span class="pre">Pass</span></tt>. Depending
+on how your pass works, you should inherit from the <a class="reference internal" href="#writing-an-llvm-pass-modulepass"><em>ModulePass</em></a> , <a class="reference internal" href="#writing-an-llvm-pass-callgraphsccpass"><em>CallGraphSCCPass</em></a>, <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a> , or <a class="reference internal" href="#writing-an-llvm-pass-looppass"><em>LoopPass</em></a>, or <a class="reference internal" href="#writing-an-llvm-pass-regionpass"><em>RegionPass</em></a>, or <a class="reference internal" href="#writing-an-llvm-pass-basicblockpass"><em>BasicBlockPass</em></a> classes, which gives the system more
+information about what your pass does, and how it can be combined with other
+passes. One of the main features of the LLVM Pass Framework is that it
+schedules passes to run in an efficient way based on the constraints that your
+pass meets (which are indicated by which class they derive from).</p>
+<p>We start by showing you how to construct a pass, everything from setting up the
+code, to compiling, loading, and executing it. After the basics are down, more
+advanced features are discussed.</p>
+</div>
+<div class="section" id="quick-start-writing-hello-world">
+<h2><a class="toc-backref" href="#id6">Quick Start — Writing hello world</a><a class="headerlink" href="#quick-start-writing-hello-world" title="Permalink to this headline">¶</a></h2>
+<p>Here we describe how to write the “hello world” of passes. The “Hello” pass is
+designed to simply print out the name of non-external functions that exist in
+the program being compiled. It does not modify the program at all, it just
+inspects it. The source code and files for this pass are available in the LLVM
+source tree in the <tt class="docutils literal"><span class="pre">lib/Transforms/Hello</span></tt> directory.</p>
+<div class="section" id="setting-up-the-build-environment">
+<span id="writing-an-llvm-pass-makefile"></span><h3><a class="toc-backref" href="#id7">Setting up the build environment</a><a class="headerlink" href="#setting-up-the-build-environment" title="Permalink to this headline">¶</a></h3>
+<p>First, configure and build LLVM. Next, you need to create a new directory
+somewhere in the LLVM source base. For this example, we’ll assume that you
+made <tt class="docutils literal"><span class="pre">lib/Transforms/Hello</span></tt>. Finally, you must set up a build script
+(<tt class="docutils literal"><span class="pre">Makefile</span></tt>) that will compile the source code for the new pass. To do this,
+copy the following into <tt class="docutils literal"><span class="pre">Makefile</span></tt>:</p>
+<div class="highlight-make"><div class="highlight"><pre><span class="c"># Makefile for hello pass</span>
+
+<span class="c"># Path to top level of LLVM hierarchy</span>
+<span class="nv">LEVEL</span> <span class="o">=</span> ../../..
+
+<span class="c"># Name of the library to build</span>
+<span class="nv">LIBRARYNAME</span> <span class="o">=</span> Hello
+
+<span class="c"># Make the shared library become a loadable module so the tools can</span>
+<span class="c"># dlopen/dlsym on the resulting library.</span>
+<span class="nv">LOADABLE_MODULE</span> <span class="o">=</span> 1
+
+<span class="c"># Include the makefile implementation stuff</span>
+<span class="cp">include $(LEVEL)/Makefile.common</span>
+</pre></div>
+</div>
+<p>This makefile specifies that all of the <tt class="docutils literal"><span class="pre">.cpp</span></tt> files in the current directory
+are to be compiled and linked together into a shared object
+<tt class="docutils literal"><span class="pre">$(LEVEL)/Debug+Asserts/lib/Hello.so</span></tt> that can be dynamically loaded by the
+<strong class="program">opt</strong> or <strong class="program">bugpoint</strong> tools via their <a class="reference internal" href="CommandGuide/opt.html#cmdoption-load"><em class="xref std std-option">-load</em></a> options.
+If your operating system uses a suffix other than <tt class="docutils literal"><span class="pre">.so</span></tt> (such as Windows or Mac
+OS X), the appropriate extension will be used.</p>
+<p>If you are used CMake to build LLVM, see <a class="reference internal" href="CMake.html#cmake-out-of-source-pass"><em>Developing LLVM passes out of source</em></a>.</p>
+<p>Now that we have the build scripts set up, we just need to write the code for
+the pass itself.</p>
+</div>
+<div class="section" id="basic-code-required">
+<span id="writing-an-llvm-pass-basiccode"></span><h3><a class="toc-backref" href="#id8">Basic code required</a><a class="headerlink" href="#basic-code-required" title="Permalink to this headline">¶</a></h3>
+<p>Now that we have a way to compile our new pass, we just have to write it.
+Start out with:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Pass.h"</span>
+<span class="cp">#include "llvm/IR/Function.h"</span>
+<span class="cp">#include "llvm/Support/raw_ostream.h"</span>
+</pre></div>
+</div>
+<p>Which are needed because we are writing a <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a>, we are operating on
+<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Function.html">Function</a>s, and we will
+be doing some printing.</p>
+<p>Next we have:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>... which is required because the functions from the include files live in the
+llvm namespace.</p>
+<p>Next we have:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="p">{</span>
+</pre></div>
+</div>
+<p>... which starts out an anonymous namespace. Anonymous namespaces are to C++
+what the “<tt class="docutils literal"><span class="pre">static</span></tt>” keyword is to C (at global scope). It makes the things
+declared inside of the anonymous namespace visible only to the current file.
+If you’re not familiar with them, consult a decent C++ book for more
+information.</p>
+<p>Next, we declare our pass itself:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Hello</span> <span class="o">:</span> <span class="k">public</span> <span class="n">FunctionPass</span> <span class="p">{</span>
+</pre></div>
+</div>
+<p>This declares a “<tt class="docutils literal"><span class="pre">Hello</span></tt>” class that is a subclass of <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a>. The different builtin pass subclasses
+are described in detail <a class="reference internal" href="#writing-an-llvm-pass-pass-classes"><em>later</em></a>, but
+for now, know that <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> operates on a function at a time.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="kt">char</span> <span class="n">ID</span><span class="p">;</span>
+<span class="n">Hello</span><span class="p">()</span> <span class="o">:</span> <span class="n">FunctionPass</span><span class="p">(</span><span class="n">ID</span><span class="p">)</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>This declares pass identifier used by LLVM to identify pass. This allows LLVM
+to avoid using expensive C++ runtime information.</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="kt">bool</span> <span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="n">override</span> <span class="p">{</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"Hello: "</span><span class="p">;</span>
+ <span class="n">errs</span><span class="p">().</span><span class="n">write_escaped</span><span class="p">(</span><span class="n">F</span><span class="p">.</span><span class="n">getName</span><span class="p">())</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">};</span> <span class="c1">// end of struct Hello</span>
+<span class="p">}</span> <span class="c1">// end of anonymous namespace</span>
+</pre></div>
+</div>
+<p>We declare a <a class="reference internal" href="#writing-an-llvm-pass-runonfunction"><em>runOnFunction</em></a> method,
+which overrides an abstract virtual method inherited from <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a>. This is where we are supposed to do our
+thing, so we just print out our message with the name of each function.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">char</span> <span class="n">Hello</span><span class="o">::</span><span class="n">ID</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>We initialize pass ID here. LLVM uses ID’s address to identify a pass, so
+initialization value is not important.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">RegisterPass</span><span class="o"><</span><span class="n">Hello</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="s">"hello"</span><span class="p">,</span> <span class="s">"Hello World Pass"</span><span class="p">,</span>
+ <span class="nb">false</span> <span class="cm">/* Only looks at CFG */</span><span class="p">,</span>
+ <span class="nb">false</span> <span class="cm">/* Analysis Pass */</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Lastly, we <a class="reference internal" href="#writing-an-llvm-pass-registration"><em>register our class</em></a>
+<tt class="docutils literal"><span class="pre">Hello</span></tt>, giving it a command line argument “<tt class="docutils literal"><span class="pre">hello</span></tt>”, and a name “Hello
+World Pass”. The last two arguments describe its behavior: if a pass walks CFG
+without modifying it then the third argument is set to <tt class="docutils literal"><span class="pre">true</span></tt>; if a pass is
+an analysis pass, for example dominator tree pass, then <tt class="docutils literal"><span class="pre">true</span></tt> is supplied as
+the fourth argument.</p>
+<p>As a whole, the <tt class="docutils literal"><span class="pre">.cpp</span></tt> file looks like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Pass.h"</span>
+<span class="cp">#include "llvm/IR/Function.h"</span>
+<span class="cp">#include "llvm/Support/raw_ostream.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">struct</span> <span class="n">Hello</span> <span class="o">:</span> <span class="k">public</span> <span class="n">FunctionPass</span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">char</span> <span class="n">ID</span><span class="p">;</span>
+ <span class="n">Hello</span><span class="p">()</span> <span class="o">:</span> <span class="n">FunctionPass</span><span class="p">(</span><span class="n">ID</span><span class="p">)</span> <span class="p">{}</span>
+
+ <span class="kt">bool</span> <span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="n">override</span> <span class="p">{</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"Hello: "</span><span class="p">;</span>
+ <span class="n">errs</span><span class="p">().</span><span class="n">write_escaped</span><span class="p">(</span><span class="n">F</span><span class="p">.</span><span class="n">getName</span><span class="p">())</span> <span class="o"><<</span> <span class="sc">'\n'</span><span class="p">;</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">};</span>
+<span class="p">}</span>
+
+<span class="kt">char</span> <span class="n">Hello</span><span class="o">::</span><span class="n">ID</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="k">static</span> <span class="n">RegisterPass</span><span class="o"><</span><span class="n">Hello</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="s">"hello"</span><span class="p">,</span> <span class="s">"Hello World Pass"</span><span class="p">,</span> <span class="nb">false</span><span class="p">,</span> <span class="nb">false</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Now that it’s all together, compile the file with a simple “<tt class="docutils literal"><span class="pre">gmake</span></tt>” command
+from the top level of your build directory and you should get a new file
+“<tt class="docutils literal"><span class="pre">Debug+Asserts/lib/Hello.so</span></tt>”. Note that everything in this file is
+contained in an anonymous namespace — this reflects the fact that passes
+are self contained units that do not need external interfaces (although they
+can have them) to be useful.</p>
+</div>
+<div class="section" id="running-a-pass-with-opt">
+<h3><a class="toc-backref" href="#id9">Running a pass with <tt class="docutils literal"><span class="pre">opt</span></tt></a><a class="headerlink" href="#running-a-pass-with-opt" title="Permalink to this headline">¶</a></h3>
+<p>Now that you have a brand new shiny shared object file, we can use the
+<strong class="program">opt</strong> command to run an LLVM program through your pass. Because you
+registered your pass with <tt class="docutils literal"><span class="pre">RegisterPass</span></tt>, you will be able to use the
+<strong class="program">opt</strong> tool to access it, once loaded.</p>
+<p>To test it, follow the example at the end of the <a class="reference internal" href="GettingStarted.html"><em>Getting Started with the LLVM System</em></a> to
+compile “Hello World” to LLVM. We can now run the bitcode file (hello.bc) for
+the program through our transformation like this (or course, any bitcode file
+will work):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../Debug+Asserts/lib/Hello.so -hello < hello.bc > /dev/null
+<span class="go">Hello: __main</span>
+<span class="go">Hello: puts</span>
+<span class="go">Hello: main</span>
+</pre></div>
+</div>
+<p>The <a class="reference internal" href="CommandGuide/opt.html#cmdoption-load"><em class="xref std std-option">-load</em></a> option specifies that <strong class="program">opt</strong> should load your pass
+as a shared object, which makes “<tt class="docutils literal"><span class="pre">-hello</span></tt>” a valid command line argument
+(which is one reason you need to <a class="reference internal" href="#writing-an-llvm-pass-registration"><em>register your pass</em></a>). Because the Hello pass does not modify
+the program in any interesting way, we just throw away the result of
+<strong class="program">opt</strong> (sending it to <tt class="docutils literal"><span class="pre">/dev/null</span></tt>).</p>
+<p>To see what happened to the other string you registered, try running
+<strong class="program">opt</strong> with the <a class="reference internal" href="CommandGuide/opt.html#cmdoption-help"><em class="xref std std-option">-help</em></a> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../Debug+Asserts/lib/Hello.so -help
+<span class="go">OVERVIEW: llvm .bc -> .bc modular optimizer</span>
+
+<span class="go">USAGE: opt [options] <input bitcode></span>
+
+<span class="go">OPTIONS:</span>
+<span class="go"> Optimizations available:</span>
+<span class="go">...</span>
+<span class="go"> -globalopt - Global Variable Optimizer</span>
+<span class="go"> -globalsmodref-aa - Simple mod/ref analysis for globals</span>
+<span class="go"> -gvn - Global Value Numbering</span>
+<span class="go"> -hello - Hello World Pass</span>
+<span class="go"> -indvars - Induction Variable Simplification</span>
+<span class="go"> -inline - Function Integration/Inlining</span>
+<span class="go">...</span>
+</pre></div>
+</div>
+<p>The pass name gets added as the information string for your pass, giving some
+documentation to users of <strong class="program">opt</strong>. Now that you have a working pass,
+you would go ahead and make it do the cool transformations you want. Once you
+get it all working and tested, it may become useful to find out how fast your
+pass is. The <a class="reference internal" href="#writing-an-llvm-pass-passmanager"><em>PassManager</em></a> provides a
+nice command line option (<a class="reference internal" href="CommandGuide/llc.html#cmdoption--time-passes"><em class="xref std std-option">--time-passes</em></a>) that allows you to get
+information about the execution time of your pass along with the other passes
+you queue up. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../Debug+Asserts/lib/Hello.so -hello -time-passes < hello.bc > /dev/null
+<span class="go">Hello: __main</span>
+<span class="go">Hello: puts</span>
+<span class="go">Hello: main</span>
+<span class="go">===============================================================================</span>
+<span class="go"> ... Pass execution timing report ...</span>
+<span class="go">===============================================================================</span>
+<span class="go"> Total Execution Time: 0.02 seconds (0.0479059 wall clock)</span>
+
+<span class="go"> ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Pass Name ---</span>
+<span class="go"> 0.0100 (100.0%) 0.0000 ( 0.0%) 0.0100 ( 50.0%) 0.0402 ( 84.0%) Bitcode Writer</span>
+<span class="go"> 0.0000 ( 0.0%) 0.0100 (100.0%) 0.0100 ( 50.0%) 0.0031 ( 6.4%) Dominator Set Construction</span>
+<span class="go"> 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0013 ( 2.7%) Module Verifier</span>
+<span class="go"> 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0033 ( 6.9%) Hello World Pass</span>
+<span class="go"> 0.0100 (100.0%) 0.0100 (100.0%) 0.0200 (100.0%) 0.0479 (100.0%) TOTAL</span>
+</pre></div>
+</div>
+<p>As you can see, our implementation above is pretty fast. The additional
+passes listed are automatically inserted by the <strong class="program">opt</strong> tool to verify
+that the LLVM emitted by your pass is still valid and well formed LLVM, which
+hasn’t been broken somehow.</p>
+<p>Now that you have seen the basics of the mechanics behind passes, we can talk
+about some more details of how they work and how to use them.</p>
+</div>
+</div>
+<div class="section" id="pass-classes-and-requirements">
+<span id="writing-an-llvm-pass-pass-classes"></span><h2><a class="toc-backref" href="#id10">Pass classes and requirements</a><a class="headerlink" href="#pass-classes-and-requirements" title="Permalink to this headline">¶</a></h2>
+<p>One of the first things that you should do when designing a new pass is to
+decide what class you should subclass for your pass. The <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> example uses the <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a> class for its implementation, but we did
+not discuss why or when this should occur. Here we talk about the classes
+available, from the most general to the most specific.</p>
+<p>When choosing a superclass for your <tt class="docutils literal"><span class="pre">Pass</span></tt>, you should choose the <strong>most
+specific</strong> class possible, while still being able to meet the requirements
+listed. This gives the LLVM Pass Infrastructure information necessary to
+optimize how passes are run, so that the resultant compiler isn’t unnecessarily
+slow.</p>
+<div class="section" id="the-immutablepass-class">
+<h3><a class="toc-backref" href="#id11">The <tt class="docutils literal"><span class="pre">ImmutablePass</span></tt> class</a><a class="headerlink" href="#the-immutablepass-class" title="Permalink to this headline">¶</a></h3>
+<p>The most plain and boring type of pass is the “<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1ImmutablePass.html">ImmutablePass</a>” class. This pass
+type is used for passes that do not have to be run, do not change state, and
+never need to be updated. This is not a normal type of transformation or
+analysis, but can provide information about the current compiler configuration.</p>
+<p>Although this pass class is very infrequently used, it is important for
+providing information about the current target machine being compiled for, and
+other static information that can affect the various transformations.</p>
+<p><tt class="docutils literal"><span class="pre">ImmutablePass</span></tt>es never invalidate other transformations, are never
+invalidated, and are never “run”.</p>
+</div>
+<div class="section" id="the-modulepass-class">
+<span id="writing-an-llvm-pass-modulepass"></span><h3><a class="toc-backref" href="#id12">The <tt class="docutils literal"><span class="pre">ModulePass</span></tt> class</a><a class="headerlink" href="#the-modulepass-class" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1ModulePass.html">ModulePass</a> class
+is the most general of all superclasses that you can use. Deriving from
+<tt class="docutils literal"><span class="pre">ModulePass</span></tt> indicates that your pass uses the entire program as a unit,
+referring to function bodies in no predictable order, or adding and removing
+functions. Because nothing is known about the behavior of <tt class="docutils literal"><span class="pre">ModulePass</span></tt>
+subclasses, no optimization can be done for their execution.</p>
+<p>A module pass can use function level passes (e.g. dominators) using the
+<tt class="docutils literal"><span class="pre">getAnalysis</span></tt> interface <tt class="docutils literal"><span class="pre">getAnalysis<DominatorTree>(llvm::Function</span> <span class="pre">*)</span></tt> to
+provide the function to retrieve analysis result for, if the function pass does
+not require any module or immutable passes. Note that this can only be done
+for functions for which the analysis ran, e.g. in the case of dominators you
+should only ask for the <tt class="docutils literal"><span class="pre">DominatorTree</span></tt> for function definitions, not
+declarations.</p>
+<p>To write a correct <tt class="docutils literal"><span class="pre">ModulePass</span></tt> subclass, derive from <tt class="docutils literal"><span class="pre">ModulePass</span></tt> and
+overload the <tt class="docutils literal"><span class="pre">runOnModule</span></tt> method with the following signature:</p>
+<div class="section" id="the-runonmodule-method">
+<h4><a class="toc-backref" href="#id13">The <tt class="docutils literal"><span class="pre">runOnModule</span></tt> method</a><a class="headerlink" href="#the-runonmodule-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnModule</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnModule</span></tt> method performs the interesting work of the pass. It
+should return <tt class="docutils literal"><span class="pre">true</span></tt> if the module was modified by the transformation and
+<tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</p>
+</div>
+</div>
+<div class="section" id="the-callgraphsccpass-class">
+<span id="writing-an-llvm-pass-callgraphsccpass"></span><h3><a class="toc-backref" href="#id14">The <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt> class</a><a class="headerlink" href="#the-callgraphsccpass-class" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1CallGraphSCCPass.html">CallGraphSCCPass</a> is used by
+passes that need to traverse the program bottom-up on the call graph (callees
+before callers). Deriving from <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt> provides some mechanics
+for building and traversing the <tt class="docutils literal"><span class="pre">CallGraph</span></tt>, but also allows the system to
+optimize execution of <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt>es. If your pass meets the
+requirements outlined below, and doesn’t meet the requirements of a
+<a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a> or <a class="reference internal" href="#writing-an-llvm-pass-basicblockpass"><em>BasicBlockPass</em></a>, you should derive from
+<tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">TODO</span></tt>: explain briefly what SCC, Tarjan’s algo, and B-U mean.</p>
+<p>To be explicit, CallGraphSCCPass subclasses are:</p>
+<ol class="arabic simple">
+<li>... <em>not allowed</em> to inspect or modify any <tt class="docutils literal"><span class="pre">Function</span></tt>s other than those
+in the current SCC and the direct callers and direct callees of the SCC.</li>
+<li>... <em>required</em> to preserve the current <tt class="docutils literal"><span class="pre">CallGraph</span></tt> object, updating it to
+reflect any changes made to the program.</li>
+<li>... <em>not allowed</em> to add or remove SCC’s from the current Module, though
+they may change the contents of an SCC.</li>
+<li>... <em>allowed</em> to add or remove global variables from the current Module.</li>
+<li>... <em>allowed</em> to maintain state across invocations of <a class="reference internal" href="#writing-an-llvm-pass-runonscc"><em>runOnSCC</em></a> (including global data).</li>
+</ol>
+<p>Implementing a <tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt> is slightly tricky in some cases because it
+has to handle SCCs with more than one node in it. All of the virtual methods
+described below should return <tt class="docutils literal"><span class="pre">true</span></tt> if they modified the program, or
+<tt class="docutils literal"><span class="pre">false</span></tt> if they didn’t.</p>
+<div class="section" id="the-doinitialization-callgraph-method">
+<h4><a class="toc-backref" href="#id15">The <tt class="docutils literal"><span class="pre">doInitialization(CallGraph</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-callgraph-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">CallGraph</span> <span class="o">&</span><span class="n">CG</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is allowed to do most of the things that
+<tt class="docutils literal"><span class="pre">CallGraphSCCPass</span></tt>es are not allowed to do. They can add and remove
+functions, get pointers to functions, etc. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is
+designed to do simple initialization type of stuff that does not depend on the
+SCCs being processed. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to
+overlap with any other pass executions (thus it should be very fast).</p>
+</div>
+<div class="section" id="the-runonscc-method">
+<span id="writing-an-llvm-pass-runonscc"></span><h4><a class="toc-backref" href="#id16">The <tt class="docutils literal"><span class="pre">runOnSCC</span></tt> method</a><a class="headerlink" href="#the-runonscc-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnSCC</span><span class="p">(</span><span class="n">CallGraphSCC</span> <span class="o">&</span><span class="n">SCC</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnSCC</span></tt> method performs the interesting work of the pass, and should
+return <tt class="docutils literal"><span class="pre">true</span></tt> if the module was modified by the transformation, <tt class="docutils literal"><span class="pre">false</span></tt>
+otherwise.</p>
+</div>
+<div class="section" id="the-dofinalization-callgraph-method">
+<h4><a class="toc-backref" href="#id17">The <tt class="docutils literal"><span class="pre">doFinalization(CallGraph</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-dofinalization-callgraph-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">(</span><span class="n">CallGraph</span> <span class="o">&</span><span class="n">CG</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonscc"><em>runOnSCC</em></a> for every SCC in the program being compiled.</p>
+</div>
+</div>
+<div class="section" id="the-functionpass-class">
+<span id="writing-an-llvm-pass-functionpass"></span><h3><a class="toc-backref" href="#id18">The <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> class</a><a class="headerlink" href="#the-functionpass-class" title="Permalink to this headline">¶</a></h3>
+<p>In contrast to <tt class="docutils literal"><span class="pre">ModulePass</span></tt> subclasses, <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Pass.html">FunctionPass</a> subclasses do have a
+predictable, local behavior that can be expected by the system. All
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt> execute on each function in the program independent of all of
+the other functions in the program. <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es do not require that
+they are executed in a particular order, and <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es do not modify
+external functions.</p>
+<p>To be explicit, <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> subclasses are not allowed to:</p>
+<ol class="arabic simple">
+<li>Inspect or modify a <tt class="docutils literal"><span class="pre">Function</span></tt> other than the one currently being processed.</li>
+<li>Add or remove <tt class="docutils literal"><span class="pre">Function</span></tt>s from the current <tt class="docutils literal"><span class="pre">Module</span></tt>.</li>
+<li>Add or remove global variables from the current <tt class="docutils literal"><span class="pre">Module</span></tt>.</li>
+<li>Maintain state across invocations of <a class="reference internal" href="#writing-an-llvm-pass-runonfunction"><em>runOnFunction</em></a> (including global data).</li>
+</ol>
+<p>Implementing a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> is usually straightforward (See the <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello
+World</em></a> pass for example).
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es may overload three virtual methods to do their work. All
+of these methods should return <tt class="docutils literal"><span class="pre">true</span></tt> if they modified the program, or
+<tt class="docutils literal"><span class="pre">false</span></tt> if they didn’t.</p>
+<div class="section" id="the-doinitialization-module-method">
+<span id="writing-an-llvm-pass-doinitialization-mod"></span><h4><a class="toc-backref" href="#id19">The <tt class="docutils literal"><span class="pre">doInitialization(Module</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-module-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is allowed to do most of the things that
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es are not allowed to do. They can add and remove functions,
+get pointers to functions, etc. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is designed to
+do simple initialization type of stuff that does not depend on the functions
+being processed. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to
+overlap with any other pass executions (thus it should be very fast).</p>
+<p>A good example of how this method should be used is the <a class="reference external" href="http://llvm.org/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations</a> pass. This pass
+converts <tt class="docutils literal"><span class="pre">malloc</span></tt> and <tt class="docutils literal"><span class="pre">free</span></tt> instructions into platform dependent
+<tt class="docutils literal"><span class="pre">malloc()</span></tt> and <tt class="docutils literal"><span class="pre">free()</span></tt> function calls. It uses the <tt class="docutils literal"><span class="pre">doInitialization</span></tt>
+method to get a reference to the <tt class="docutils literal"><span class="pre">malloc</span></tt> and <tt class="docutils literal"><span class="pre">free</span></tt> functions that it
+needs, adding prototypes to the module if necessary.</p>
+</div>
+<div class="section" id="the-runonfunction-method">
+<span id="writing-an-llvm-pass-runonfunction"></span><h4><a class="toc-backref" href="#id20">The <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method</a><a class="headerlink" href="#the-runonfunction-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method must be implemented by your subclass to do the
+transformation or analysis work of your pass. As usual, a <tt class="docutils literal"><span class="pre">true</span></tt> value
+should be returned if the function is modified.</p>
+</div>
+<div class="section" id="the-dofinalization-module-method">
+<span id="writing-an-llvm-pass-dofinalization-mod"></span><h4><a class="toc-backref" href="#id21">The <tt class="docutils literal"><span class="pre">doFinalization(Module</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-dofinalization-module-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonfunction"><em>runOnFunction</em></a> for every function in the program being
+compiled.</p>
+</div>
+</div>
+<div class="section" id="the-looppass-class">
+<span id="writing-an-llvm-pass-looppass"></span><h3><a class="toc-backref" href="#id22">The <tt class="docutils literal"><span class="pre">LoopPass</span></tt> class</a><a class="headerlink" href="#the-looppass-class" title="Permalink to this headline">¶</a></h3>
+<p>All <tt class="docutils literal"><span class="pre">LoopPass</span></tt> execute on each loop in the function independent of all of the
+other loops in the function. <tt class="docutils literal"><span class="pre">LoopPass</span></tt> processes loops in loop nest order
+such that outer most loop is processed last.</p>
+<p><tt class="docutils literal"><span class="pre">LoopPass</span></tt> subclasses are allowed to update loop nest using <tt class="docutils literal"><span class="pre">LPPassManager</span></tt>
+interface. Implementing a loop pass is usually straightforward.
+<tt class="docutils literal"><span class="pre">LoopPass</span></tt>es may overload three virtual methods to do their work. All
+these methods should return <tt class="docutils literal"><span class="pre">true</span></tt> if they modified the program, or <tt class="docutils literal"><span class="pre">false</span></tt>
+if they didn’t.</p>
+<p>A <tt class="docutils literal"><span class="pre">LoopPass</span></tt> subclass which is intended to run as part of the main loop pass
+pipeline needs to preserve all of the same <em>function</em> analyses that the other
+loop passes in its pipeline require. To make that easier,
+a <tt class="docutils literal"><span class="pre">getLoopAnalysisUsage</span></tt> function is provided by <tt class="docutils literal"><span class="pre">LoopUtils.h</span></tt>. It can be
+called within the subclass’s <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt> override to get consistent
+and correct behavior. Analogously, <tt class="docutils literal"><span class="pre">INITIALIZE_PASS_DEPENDENCY(LoopPass)</span></tt>
+will initialize this set of function analyses.</p>
+<div class="section" id="the-doinitialization-loop-lppassmanager-method">
+<h4><a class="toc-backref" href="#id23">The <tt class="docutils literal"><span class="pre">doInitialization(Loop</span> <span class="pre">*,</span> <span class="pre">LPPassManager</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-loop-lppassmanager-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">Loop</span> <span class="o">*</span><span class="p">,</span> <span class="n">LPPassManager</span> <span class="o">&</span><span class="n">LPM</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is designed to do simple initialization type of
+stuff that does not depend on the functions being processed. The
+<tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to overlap with any other
+pass executions (thus it should be very fast). <tt class="docutils literal"><span class="pre">LPPassManager</span></tt> interface
+should be used to access <tt class="docutils literal"><span class="pre">Function</span></tt> or <tt class="docutils literal"><span class="pre">Module</span></tt> level analysis information.</p>
+</div>
+<div class="section" id="the-runonloop-method">
+<span id="writing-an-llvm-pass-runonloop"></span><h4><a class="toc-backref" href="#id24">The <tt class="docutils literal"><span class="pre">runOnLoop</span></tt> method</a><a class="headerlink" href="#the-runonloop-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnLoop</span><span class="p">(</span><span class="n">Loop</span> <span class="o">*</span><span class="p">,</span> <span class="n">LPPassManager</span> <span class="o">&</span><span class="n">LPM</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnLoop</span></tt> method must be implemented by your subclass to do the
+transformation or analysis work of your pass. As usual, a <tt class="docutils literal"><span class="pre">true</span></tt> value
+should be returned if the function is modified. <tt class="docutils literal"><span class="pre">LPPassManager</span></tt> interface
+should be used to update loop nest.</p>
+</div>
+<div class="section" id="the-dofinalization-method">
+<h4><a class="toc-backref" href="#id25">The <tt class="docutils literal"><span class="pre">doFinalization()</span></tt> method</a><a class="headerlink" href="#the-dofinalization-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonloop"><em>runOnLoop</em></a> for every loop in the program being compiled.</p>
+</div>
+</div>
+<div class="section" id="the-regionpass-class">
+<span id="writing-an-llvm-pass-regionpass"></span><h3><a class="toc-backref" href="#id26">The <tt class="docutils literal"><span class="pre">RegionPass</span></tt> class</a><a class="headerlink" href="#the-regionpass-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">RegionPass</span></tt> is similar to <a class="reference internal" href="#writing-an-llvm-pass-looppass"><em>LoopPass</em></a>,
+but executes on each single entry single exit region in the function.
+<tt class="docutils literal"><span class="pre">RegionPass</span></tt> processes regions in nested order such that the outer most
+region is processed last.</p>
+<p><tt class="docutils literal"><span class="pre">RegionPass</span></tt> subclasses are allowed to update the region tree by using the
+<tt class="docutils literal"><span class="pre">RGPassManager</span></tt> interface. You may overload three virtual methods of
+<tt class="docutils literal"><span class="pre">RegionPass</span></tt> to implement your own region pass. All these methods should
+return <tt class="docutils literal"><span class="pre">true</span></tt> if they modified the program, or <tt class="docutils literal"><span class="pre">false</span></tt> if they did not.</p>
+<div class="section" id="the-doinitialization-region-rgpassmanager-method">
+<h4><a class="toc-backref" href="#id27">The <tt class="docutils literal"><span class="pre">doInitialization(Region</span> <span class="pre">*,</span> <span class="pre">RGPassManager</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-region-rgpassmanager-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">Region</span> <span class="o">*</span><span class="p">,</span> <span class="n">RGPassManager</span> <span class="o">&</span><span class="n">RGM</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is designed to do simple initialization type of
+stuff that does not depend on the functions being processed. The
+<tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to overlap with any other
+pass executions (thus it should be very fast). <tt class="docutils literal"><span class="pre">RPPassManager</span></tt> interface
+should be used to access <tt class="docutils literal"><span class="pre">Function</span></tt> or <tt class="docutils literal"><span class="pre">Module</span></tt> level analysis information.</p>
+</div>
+<div class="section" id="the-runonregion-method">
+<span id="writing-an-llvm-pass-runonregion"></span><h4><a class="toc-backref" href="#id28">The <tt class="docutils literal"><span class="pre">runOnRegion</span></tt> method</a><a class="headerlink" href="#the-runonregion-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnRegion</span><span class="p">(</span><span class="n">Region</span> <span class="o">*</span><span class="p">,</span> <span class="n">RGPassManager</span> <span class="o">&</span><span class="n">RGM</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">runOnRegion</span></tt> method must be implemented by your subclass to do the
+transformation or analysis work of your pass. As usual, a true value should be
+returned if the region is modified. <tt class="docutils literal"><span class="pre">RGPassManager</span></tt> interface should be used to
+update region tree.</p>
+</div>
+<div class="section" id="id2">
+<h4><a class="toc-backref" href="#id29">The <tt class="docutils literal"><span class="pre">doFinalization()</span></tt> method</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonregion"><em>runOnRegion</em></a> for every region in the program being
+compiled.</p>
+</div>
+</div>
+<div class="section" id="the-basicblockpass-class">
+<span id="writing-an-llvm-pass-basicblockpass"></span><h3><a class="toc-backref" href="#id30">The <tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt> class</a><a class="headerlink" href="#the-basicblockpass-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt>es are just like <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass’s</em></a> , except that they must limit their scope
+of inspection and modification to a single basic block at a time. As such,
+they are <strong>not</strong> allowed to do any of the following:</p>
+<ol class="arabic simple">
+<li>Modify or inspect any basic blocks outside of the current one.</li>
+<li>Maintain state across invocations of <a class="reference internal" href="#writing-an-llvm-pass-runonbasicblock"><em>runOnBasicBlock</em></a>.</li>
+<li>Modify the control flow graph (by altering terminator instructions)</li>
+<li>Any of the things forbidden for <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPasses</em></a>.</li>
+</ol>
+<p><tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt>es are useful for traditional local and “peephole”
+optimizations. They may override the same <a class="reference internal" href="#writing-an-llvm-pass-doinitialization-mod"><em>doInitialization(Module &)</em></a> and <a class="reference internal" href="#writing-an-llvm-pass-dofinalization-mod"><em>doFinalization(Module &)</em></a> methods that <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass’s</em></a> have, but also have the following virtual
+methods that may also be implemented:</p>
+<div class="section" id="the-doinitialization-function-method">
+<h4><a class="toc-backref" href="#id31">The <tt class="docutils literal"><span class="pre">doInitialization(Function</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-doinitialization-function-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doInitialization</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is allowed to do most of the things that
+<tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt>es are not allowed to do, but that <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>es
+can. The <tt class="docutils literal"><span class="pre">doInitialization</span></tt> method is designed to do simple initialization
+that does not depend on the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s being processed. The
+<tt class="docutils literal"><span class="pre">doInitialization</span></tt> method call is not scheduled to overlap with any other
+pass executions (thus it should be very fast).</p>
+</div>
+<div class="section" id="the-runonbasicblock-method">
+<span id="writing-an-llvm-pass-runonbasicblock"></span><h4><a class="toc-backref" href="#id32">The <tt class="docutils literal"><span class="pre">runOnBasicBlock</span></tt> method</a><a class="headerlink" href="#the-runonbasicblock-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnBasicBlock</span><span class="p">(</span><span class="n">BasicBlock</span> <span class="o">&</span><span class="n">BB</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Override this function to do the work of the <tt class="docutils literal"><span class="pre">BasicBlockPass</span></tt>. This function
+is not allowed to inspect or modify basic blocks other than the parameter, and
+are not allowed to modify the CFG. A <tt class="docutils literal"><span class="pre">true</span></tt> value must be returned if the
+basic block is modified.</p>
+</div>
+<div class="section" id="the-dofinalization-function-method">
+<h4><a class="toc-backref" href="#id33">The <tt class="docutils literal"><span class="pre">doFinalization(Function</span> <span class="pre">&)</span></tt> method</a><a class="headerlink" href="#the-dofinalization-function-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">doFinalization</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">doFinalization</span></tt> method is an infrequently used method that is called
+when the pass framework has finished calling <a class="reference internal" href="#writing-an-llvm-pass-runonbasicblock"><em>runOnBasicBlock</em></a> for every <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> in the program
+being compiled. This can be used to perform per-function finalization.</p>
+</div>
+</div>
+<div class="section" id="the-machinefunctionpass-class">
+<h3><a class="toc-backref" href="#id34">The <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> class</a><a class="headerlink" href="#the-machinefunctionpass-class" title="Permalink to this headline">¶</a></h3>
+<p>A <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> is a part of the LLVM code generator that executes on
+the machine-dependent representation of each LLVM function in the program.</p>
+<p>Code generator passes are registered and initialized specially by
+<tt class="docutils literal"><span class="pre">TargetMachine::addPassesToEmitFile</span></tt> and similar routines, so they cannot
+generally be run from the <strong class="program">opt</strong> or <strong class="program">bugpoint</strong> commands.</p>
+<p>A <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> is also a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, so all the restrictions
+that apply to a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> also apply to it. <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>es
+also have additional restrictions. In particular, <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>es
+are not allowed to do any of the following:</p>
+<ol class="arabic simple">
+<li>Modify or create any LLVM IR <tt class="docutils literal"><span class="pre">Instruction</span></tt>s, <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s,
+<tt class="docutils literal"><span class="pre">Argument</span></tt>s, <tt class="docutils literal"><span class="pre">Function</span></tt>s, <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt>s,
+<tt class="docutils literal"><span class="pre">GlobalAlias</span></tt>es, or <tt class="docutils literal"><span class="pre">Module</span></tt>s.</li>
+<li>Modify a <tt class="docutils literal"><span class="pre">MachineFunction</span></tt> other than the one currently being processed.</li>
+<li>Maintain state across invocations of <a class="reference internal" href="#writing-an-llvm-pass-runonmachinefunction"><em>runOnMachineFunction</em></a> (including global data).</li>
+</ol>
+<div class="section" id="the-runonmachinefunction-machinefunction-mf-method">
+<span id="writing-an-llvm-pass-runonmachinefunction"></span><h4><a class="toc-backref" href="#id35">The <tt class="docutils literal"><span class="pre">runOnMachineFunction(MachineFunction</span> <span class="pre">&MF)</span></tt> method</a><a class="headerlink" href="#the-runonmachinefunction-machinefunction-mf-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">bool</span> <span class="n">runOnMachineFunction</span><span class="p">(</span><span class="n">MachineFunction</span> <span class="o">&</span><span class="n">MF</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> can be considered the main entry point of a
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>; that is, you should override this method to do the
+work of your <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>.</p>
+<p>The <tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> method is called on every <tt class="docutils literal"><span class="pre">MachineFunction</span></tt> in a
+<tt class="docutils literal"><span class="pre">Module</span></tt>, so that the <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> may perform optimizations on
+the machine-dependent representation of the function. If you want to get at
+the LLVM <tt class="docutils literal"><span class="pre">Function</span></tt> for the <tt class="docutils literal"><span class="pre">MachineFunction</span></tt> you’re working on, use
+<tt class="docutils literal"><span class="pre">MachineFunction</span></tt>‘s <tt class="docutils literal"><span class="pre">getFunction()</span></tt> accessor method — but remember, you
+may not modify the LLVM <tt class="docutils literal"><span class="pre">Function</span></tt> or its contents from a
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="pass-registration">
+<span id="writing-an-llvm-pass-registration"></span><h3><a class="toc-backref" href="#id36">Pass registration</a><a class="headerlink" href="#pass-registration" title="Permalink to this headline">¶</a></h3>
+<p>In the <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> example pass we
+illustrated how pass registration works, and discussed some of the reasons that
+it is used and what it does. Here we discuss how and why passes are
+registered.</p>
+<p>As we saw above, passes are registered with the <tt class="docutils literal"><span class="pre">RegisterPass</span></tt> template. The
+template parameter is the name of the pass that is to be used on the command
+line to specify that the pass should be added to a program (for example, with
+<strong class="program">opt</strong> or <strong class="program">bugpoint</strong>). The first argument is the name of the
+pass, which is to be used for the <a class="reference internal" href="CommandGuide/opt.html#cmdoption-help"><em class="xref std std-option">-help</em></a> output of programs, as well
+as for debug output generated by the <cite>–debug-pass</cite> option.</p>
+<p>If you want your pass to be easily dumpable, you should implement the virtual
+print method:</p>
+<div class="section" id="the-print-method">
+<h4><a class="toc-backref" href="#id37">The <tt class="docutils literal"><span class="pre">print</span></tt> method</a><a class="headerlink" href="#the-print-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">print</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="n">O</span><span class="p">,</span> <span class="k">const</span> <span class="n">Module</span> <span class="o">*</span><span class="n">M</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">print</span></tt> method must be implemented by “analyses” in order to print a
+human readable version of the analysis results. This is useful for debugging
+an analysis itself, as well as for other people to figure out how an analysis
+works. Use the opt <tt class="docutils literal"><span class="pre">-analyze</span></tt> argument to invoke this method.</p>
+<p>The <tt class="docutils literal"><span class="pre">llvm::raw_ostream</span></tt> parameter specifies the stream to write the results
+on, and the <tt class="docutils literal"><span class="pre">Module</span></tt> parameter gives a pointer to the top level module of the
+program that has been analyzed. Note however that this pointer may be <tt class="docutils literal"><span class="pre">NULL</span></tt>
+in certain circumstances (such as calling the <tt class="docutils literal"><span class="pre">Pass::dump()</span></tt> from a
+debugger), so it should only be used to enhance debug output, it should not be
+depended on.</p>
+</div>
+</div>
+<div class="section" id="specifying-interactions-between-passes">
+<span id="writing-an-llvm-pass-interaction"></span><h3><a class="toc-backref" href="#id38">Specifying interactions between passes</a><a class="headerlink" href="#specifying-interactions-between-passes" title="Permalink to this headline">¶</a></h3>
+<p>One of the main responsibilities of the <tt class="docutils literal"><span class="pre">PassManager</span></tt> is to make sure that
+passes interact with each other correctly. Because <tt class="docutils literal"><span class="pre">PassManager</span></tt> tries to
+<a class="reference internal" href="#writing-an-llvm-pass-passmanager"><em>optimize the execution of passes</em></a> it
+must know how the passes interact with each other and what dependencies exist
+between the various passes. To track this, each pass can declare the set of
+passes that are required to be executed before the current pass, and the passes
+which are invalidated by the current pass.</p>
+<p>Typically this functionality is used to require that analysis results are
+computed before your pass is run. Running arbitrary transformation passes can
+invalidate the computed analysis results, which is what the invalidation set
+specifies. If a pass does not implement the <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a> method, it defaults to not having any
+prerequisite passes, and invalidating <strong>all</strong> other passes.</p>
+<div class="section" id="the-getanalysisusage-method">
+<span id="writing-an-llvm-pass-getanalysisusage"></span><h4><a class="toc-backref" href="#id39">The <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt> method</a><a class="headerlink" href="#the-getanalysisusage-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">getAnalysisUsage</span><span class="p">(</span><span class="n">AnalysisUsage</span> <span class="o">&</span><span class="n">Info</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>By implementing the <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt> method, the required and invalidated
+sets may be specified for your transformation. The implementation should fill
+in the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1AnalysisUsage.html">AnalysisUsage</a> object with
+information about which passes are required and not invalidated. To do this, a
+pass may call any of the following methods on the <tt class="docutils literal"><span class="pre">AnalysisUsage</span></tt> object:</p>
+</div>
+<div class="section" id="the-analysisusage-addrequired-and-analysisusage-addrequiredtransitive-methods">
+<h4><a class="toc-backref" href="#id40">The <tt class="docutils literal"><span class="pre">AnalysisUsage::addRequired<></span></tt> and <tt class="docutils literal"><span class="pre">AnalysisUsage::addRequiredTransitive<></span></tt> methods</a><a class="headerlink" href="#the-analysisusage-addrequired-and-analysisusage-addrequiredtransitive-methods" title="Permalink to this headline">¶</a></h4>
+<p>If your pass requires a previous pass to be executed (an analysis for example),
+it can use one of these methods to arrange for it to be run before your pass.
+LLVM has many different types of analyses and passes that can be required,
+spanning the range from <tt class="docutils literal"><span class="pre">DominatorSet</span></tt> to <tt class="docutils literal"><span class="pre">BreakCriticalEdges</span></tt>. Requiring
+<tt class="docutils literal"><span class="pre">BreakCriticalEdges</span></tt>, for example, guarantees that there will be no critical
+edges in the CFG when your pass has been run.</p>
+<p>Some analyses chain to other analyses to do their job. For example, an
+<cite>AliasAnalysis <AliasAnalysis></cite> implementation is required to <a class="reference internal" href="AliasAnalysis.html#aliasanalysis-chaining"><em>chain</em></a> to other alias analysis passes. In cases where
+analyses chain, the <tt class="docutils literal"><span class="pre">addRequiredTransitive</span></tt> method should be used instead of
+the <tt class="docutils literal"><span class="pre">addRequired</span></tt> method. This informs the <tt class="docutils literal"><span class="pre">PassManager</span></tt> that the
+transitively required pass should be alive as long as the requiring pass is.</p>
+</div>
+<div class="section" id="the-analysisusage-addpreserved-method">
+<h4><a class="toc-backref" href="#id41">The <tt class="docutils literal"><span class="pre">AnalysisUsage::addPreserved<></span></tt> method</a><a class="headerlink" href="#the-analysisusage-addpreserved-method" title="Permalink to this headline">¶</a></h4>
+<p>One of the jobs of the <tt class="docutils literal"><span class="pre">PassManager</span></tt> is to optimize how and when analyses are
+run. In particular, it attempts to avoid recomputing data unless it needs to.
+For this reason, passes are allowed to declare that they preserve (i.e., they
+don’t invalidate) an existing analysis if it’s available. For example, a
+simple constant folding pass would not modify the CFG, so it can’t possibly
+affect the results of dominator analysis. By default, all passes are assumed
+to invalidate all others.</p>
+<p>The <tt class="docutils literal"><span class="pre">AnalysisUsage</span></tt> class provides several methods which are useful in
+certain circumstances that are related to <tt class="docutils literal"><span class="pre">addPreserved</span></tt>. In particular, the
+<tt class="docutils literal"><span class="pre">setPreservesAll</span></tt> method can be called to indicate that the pass does not
+modify the LLVM program at all (which is true for analyses), and the
+<tt class="docutils literal"><span class="pre">setPreservesCFG</span></tt> method can be used by transformations that change
+instructions in the program but do not modify the CFG or terminator
+instructions (note that this property is implicitly set for
+<a class="reference internal" href="#writing-an-llvm-pass-basicblockpass"><em>BasicBlockPass</em></a>es).</p>
+<p><tt class="docutils literal"><span class="pre">addPreserved</span></tt> is particularly useful for transformations like
+<tt class="docutils literal"><span class="pre">BreakCriticalEdges</span></tt>. This pass knows how to update a small set of loop and
+dominator related analyses if they exist, so it can preserve them, despite the
+fact that it hacks on the CFG.</p>
+</div>
+<div class="section" id="example-implementations-of-getanalysisusage">
+<h4><a class="toc-backref" href="#id42">Example implementations of <tt class="docutils literal"><span class="pre">getAnalysisUsage</span></tt></a><a class="headerlink" href="#example-implementations-of-getanalysisusage" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// This example modifies the program, but does not modify the CFG</span>
+<span class="kt">void</span> <span class="n">LICM</span><span class="o">::</span><span class="n">getAnalysisUsage</span><span class="p">(</span><span class="n">AnalysisUsage</span> <span class="o">&</span><span class="n">AU</span><span class="p">)</span> <span class="k">const</span> <span class="p">{</span>
+ <span class="n">AU</span><span class="p">.</span><span class="n">setPreservesCFG</span><span class="p">();</span>
+ <span class="n">AU</span><span class="p">.</span><span class="n">addRequired</span><span class="o"><</span><span class="n">LoopInfoWrapperPass</span><span class="o">></span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-getanalysis-and-getanalysisifavailable-methods">
+<span id="writing-an-llvm-pass-getanalysis"></span><h4><a class="toc-backref" href="#id43">The <tt class="docutils literal"><span class="pre">getAnalysis<></span></tt> and <tt class="docutils literal"><span class="pre">getAnalysisIfAvailable<></span></tt> methods</a><a class="headerlink" href="#the-getanalysis-and-getanalysisifavailable-methods" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">Pass::getAnalysis<></span></tt> method is automatically inherited by your class,
+providing you with access to the passes that you declared that you required
+with the <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a>
+method. It takes a single template argument that specifies which pass class
+you want, and returns a reference to that pass. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">LICM</span><span class="o">::</span><span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">LoopInfo</span> <span class="o">&</span><span class="n">LI</span> <span class="o">=</span> <span class="n">getAnalysis</span><span class="o"><</span><span class="n">LoopInfoWrapperPass</span><span class="o">></span><span class="p">().</span><span class="n">getLoopInfo</span><span class="p">();</span>
+ <span class="c1">//...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This method call returns a reference to the pass desired. You may get a
+runtime assertion failure if you attempt to get an analysis that you did not
+declare as required in your <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a> implementation. This method can be
+called by your <tt class="docutils literal"><span class="pre">run*</span></tt> method implementation, or by any other local method
+invoked by your <tt class="docutils literal"><span class="pre">run*</span></tt> method.</p>
+<p>A module level pass can use function level analysis info using this interface.
+For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">ModuleLevelPass</span><span class="o">::</span><span class="n">runOnModule</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//...</span>
+ <span class="n">DominatorTree</span> <span class="o">&</span><span class="n">DT</span> <span class="o">=</span> <span class="n">getAnalysis</span><span class="o"><</span><span class="n">DominatorTree</span><span class="o">></span><span class="p">(</span><span class="n">Func</span><span class="p">);</span>
+ <span class="c1">//...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In above example, <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> for <tt class="docutils literal"><span class="pre">DominatorTree</span></tt> is called by pass
+manager before returning a reference to the desired pass.</p>
+<p>If your pass is capable of updating analyses if they exist (e.g.,
+<tt class="docutils literal"><span class="pre">BreakCriticalEdges</span></tt>, as described above), you can use the
+<tt class="docutils literal"><span class="pre">getAnalysisIfAvailable</span></tt> method, which returns a pointer to the analysis if
+it is active. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">DominatorSet</span> <span class="o">*</span><span class="n">DS</span> <span class="o">=</span> <span class="n">getAnalysisIfAvailable</span><span class="o"><</span><span class="n">DominatorSet</span><span class="o">></span><span class="p">())</span> <span class="p">{</span>
+ <span class="c1">// A DominatorSet is active. This code will update it.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="implementing-analysis-groups">
+<h3><a class="toc-backref" href="#id44">Implementing Analysis Groups</a><a class="headerlink" href="#implementing-analysis-groups" title="Permalink to this headline">¶</a></h3>
+<p>Now that we understand the basics of how passes are defined, how they are used,
+and how they are required from other passes, it’s time to get a little bit
+fancier. All of the pass relationships that we have seen so far are very
+simple: one pass depends on one other specific pass to be run before it can
+run. For many applications, this is great, for others, more flexibility is
+required.</p>
+<p>In particular, some analyses are defined such that there is a single simple
+interface to the analysis results, but multiple ways of calculating them.
+Consider alias analysis for example. The most trivial alias analysis returns
+“may alias” for any alias query. The most sophisticated analysis a
+flow-sensitive, context-sensitive interprocedural analysis that can take a
+significant amount of time to execute (and obviously, there is a lot of room
+between these two extremes for other implementations). To cleanly support
+situations like this, the LLVM Pass Infrastructure supports the notion of
+Analysis Groups.</p>
+<div class="section" id="analysis-group-concepts">
+<h4><a class="toc-backref" href="#id45">Analysis Group Concepts</a><a class="headerlink" href="#analysis-group-concepts" title="Permalink to this headline">¶</a></h4>
+<p>An Analysis Group is a single simple interface that may be implemented by
+multiple different passes. Analysis Groups can be given human readable names
+just like passes, but unlike passes, they need not derive from the <tt class="docutils literal"><span class="pre">Pass</span></tt>
+class. An analysis group may have one or more implementations, one of which is
+the “default” implementation.</p>
+<p>Analysis groups are used by client passes just like other passes are: the
+<tt class="docutils literal"><span class="pre">AnalysisUsage::addRequired()</span></tt> and <tt class="docutils literal"><span class="pre">Pass::getAnalysis()</span></tt> methods. In order
+to resolve this requirement, the <a class="reference internal" href="#writing-an-llvm-pass-passmanager"><em>PassManager</em></a> scans the available passes to see if any
+implementations of the analysis group are available. If none is available, the
+default implementation is created for the pass to use. All standard rules for
+<a class="reference internal" href="#writing-an-llvm-pass-interaction"><em>interaction between passes</em></a> still
+apply.</p>
+<p>Although <a class="reference internal" href="#writing-an-llvm-pass-registration"><em>Pass Registration</em></a> is
+optional for normal passes, all analysis group implementations must be
+registered, and must use the <a class="reference internal" href="#writing-an-llvm-pass-registeranalysisgroup"><em>INITIALIZE_AG_PASS</em></a> template to join the
+implementation pool. Also, a default implementation of the interface <strong>must</strong>
+be registered with <a class="reference internal" href="#writing-an-llvm-pass-registeranalysisgroup"><em>RegisterAnalysisGroup</em></a>.</p>
+<p>As a concrete example of an Analysis Group in action, consider the
+<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>
+analysis group. The default implementation of the alias analysis interface
+(the <a class="reference external" href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">basicaa</a> pass)
+just does a few simple checks that don’t require significant analysis to
+compute (such as: two different globals can never alias each other, etc).
+Passes that use the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a> interface (for
+example the <a class="reference external" href="http://llvm.org/doxygen/structGCSE.html">gcse</a> pass), do not
+care which implementation of alias analysis is actually provided, they just use
+the designated interface.</p>
+<p>From the user’s perspective, commands work just like normal. Issuing the
+command <tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-gcse</span> <span class="pre">...</span></tt> will cause the <tt class="docutils literal"><span class="pre">basicaa</span></tt> class to be instantiated
+and added to the pass sequence. Issuing the command <tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-somefancyaa</span> <span class="pre">-gcse</span>
+<span class="pre">...</span></tt> will cause the <tt class="docutils literal"><span class="pre">gcse</span></tt> pass to use the <tt class="docutils literal"><span class="pre">somefancyaa</span></tt> alias analysis
+(which doesn’t actually exist, it’s just a hypothetical example) instead.</p>
+</div>
+<div class="section" id="using-registeranalysisgroup">
+<span id="writing-an-llvm-pass-registeranalysisgroup"></span><h4><a class="toc-backref" href="#id46">Using <tt class="docutils literal"><span class="pre">RegisterAnalysisGroup</span></tt></a><a class="headerlink" href="#using-registeranalysisgroup" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">RegisterAnalysisGroup</span></tt> template is used to register the analysis group
+itself, while the <tt class="docutils literal"><span class="pre">INITIALIZE_AG_PASS</span></tt> is used to add pass implementations to
+the analysis group. First, an analysis group should be registered, with a
+human readable name provided for it. Unlike registration of passes, there is
+no command line argument to be specified for the Analysis Group Interface
+itself, because it is “abstract”:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">RegisterAnalysisGroup</span><span class="o"><</span><span class="n">AliasAnalysis</span><span class="o">></span> <span class="n">A</span><span class="p">(</span><span class="s">"Alias Analysis"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Once the analysis is registered, passes can declare that they are valid
+implementations of the interface by using the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="p">{</span>
+ <span class="c1">// Declare that we implement the AliasAnalysis interface</span>
+ <span class="n">INITIALIZE_AG_PASS</span><span class="p">(</span><span class="n">FancyAA</span><span class="p">,</span> <span class="n">AliasAnalysis</span> <span class="p">,</span> <span class="s">"somefancyaa"</span><span class="p">,</span>
+ <span class="s">"A more complex alias analysis implementation"</span><span class="p">,</span>
+ <span class="nb">false</span><span class="p">,</span> <span class="c1">// Is CFG Only?</span>
+ <span class="nb">true</span><span class="p">,</span> <span class="c1">// Is Analysis?</span>
+ <span class="nb">false</span><span class="p">);</span> <span class="c1">// Is default Analysis Group implementation?</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This just shows a class <tt class="docutils literal"><span class="pre">FancyAA</span></tt> that uses the <tt class="docutils literal"><span class="pre">INITIALIZE_AG_PASS</span></tt> macro
+both to register and to “join” the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a> analysis group.
+Every implementation of an analysis group should join using this macro.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="p">{</span>
+ <span class="c1">// Declare that we implement the AliasAnalysis interface</span>
+ <span class="n">INITIALIZE_AG_PASS</span><span class="p">(</span><span class="n">BasicAA</span><span class="p">,</span> <span class="n">AliasAnalysis</span><span class="p">,</span> <span class="s">"basicaa"</span><span class="p">,</span>
+ <span class="s">"Basic Alias Analysis (default AA impl)"</span><span class="p">,</span>
+ <span class="nb">false</span><span class="p">,</span> <span class="c1">// Is CFG Only?</span>
+ <span class="nb">true</span><span class="p">,</span> <span class="c1">// Is Analysis?</span>
+ <span class="nb">true</span><span class="p">);</span> <span class="c1">// Is default Analysis Group implementation?</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here we show how the default implementation is specified (using the final
+argument to the <tt class="docutils literal"><span class="pre">INITIALIZE_AG_PASS</span></tt> template). There must be exactly one
+default implementation available at all times for an Analysis Group to be used.
+Only default implementation can derive from <tt class="docutils literal"><span class="pre">ImmutablePass</span></tt>. Here we declare
+that the <a class="reference external" href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">BasicAliasAnalysis</a> pass is the default
+implementation for the interface.</p>
+</div>
+</div>
+</div>
+<div class="section" id="pass-statistics">
+<h2><a class="toc-backref" href="#id47">Pass Statistics</a><a class="headerlink" href="#pass-statistics" title="Permalink to this headline">¶</a></h2>
+<p>The <a class="reference external" href="http://llvm.org/doxygen/Statistic_8h-source.html">Statistic</a> class is
+designed to be an easy way to expose various success metrics from passes.
+These statistics are printed at the end of a run, when the <a class="reference internal" href="CommandGuide/opt.html#cmdoption-stats"><em class="xref std std-option">-stats</em></a>
+command line option is enabled on the command line. See the <a class="reference internal" href="ProgrammersManual.html#statistic"><em>Statistics
+section</em></a> in the Programmer’s Manual for details.</p>
+<div class="section" id="what-passmanager-does">
+<span id="writing-an-llvm-pass-passmanager"></span><h3><a class="toc-backref" href="#id48">What PassManager does</a><a class="headerlink" href="#what-passmanager-does" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://llvm.org/doxygen/PassManager_8h-source.html">PassManager</a> <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1PassManager.html">class</a> takes a list of
+passes, ensures their <a class="reference internal" href="#writing-an-llvm-pass-interaction"><em>prerequisites</em></a>
+are set up correctly, and then schedules passes to run efficiently. All of the
+LLVM tools that run passes use the PassManager for execution of these passes.</p>
+<p>The PassManager does two main things to try to reduce the execution time of a
+series of passes:</p>
+<ol class="arabic">
+<li><p class="first"><strong>Share analysis results.</strong> The <tt class="docutils literal"><span class="pre">PassManager</span></tt> attempts to avoid
+recomputing analysis results as much as possible. This means keeping track
+of which analyses are available already, which analyses get invalidated, and
+which analyses are needed to be run for a pass. An important part of work
+is that the <tt class="docutils literal"><span class="pre">PassManager</span></tt> tracks the exact lifetime of all analysis
+results, allowing it to <a class="reference internal" href="#writing-an-llvm-pass-releasememory"><em>free memory</em></a> allocated to holding analysis results
+as soon as they are no longer needed.</p>
+</li>
+<li><p class="first"><strong>Pipeline the execution of passes on the program.</strong> The <tt class="docutils literal"><span class="pre">PassManager</span></tt>
+attempts to get better cache and memory usage behavior out of a series of
+passes by pipelining the passes together. This means that, given a series
+of consecutive <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a>, it
+will execute all of the <a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPass</em></a> on the first function, then all of the
+<a class="reference internal" href="#writing-an-llvm-pass-functionpass"><em>FunctionPasses</em></a> on the second
+function, etc... until the entire program has been run through the passes.</p>
+<p>This improves the cache behavior of the compiler, because it is only
+touching the LLVM program representation for a single function at a time,
+instead of traversing the entire program. It reduces the memory consumption
+of compiler, because, for example, only one <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1DominatorSet.html">DominatorSet</a> needs to be
+calculated at a time. This also makes it possible to implement some
+<a class="reference internal" href="#writing-an-llvm-pass-smp"><em>interesting enhancements</em></a> in the future.</p>
+</li>
+</ol>
+<p>The effectiveness of the <tt class="docutils literal"><span class="pre">PassManager</span></tt> is influenced directly by how much
+information it has about the behaviors of the passes it is scheduling. For
+example, the “preserved” set is intentionally conservative in the face of an
+unimplemented <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a>
+method. Not implementing when it should be implemented will have the effect of
+not allowing any analysis results to live across the execution of your pass.</p>
+<p>The <tt class="docutils literal"><span class="pre">PassManager</span></tt> class exposes a <tt class="docutils literal"><span class="pre">--debug-pass</span></tt> command line options that
+is useful for debugging pass execution, seeing how things work, and diagnosing
+when you should be preserving more analyses than you currently are. (To get
+information about all of the variants of the <tt class="docutils literal"><span class="pre">--debug-pass</span></tt> option, just type
+“<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-help-hidden</span></tt>”).</p>
+<p>By using the –debug-pass=Structure option, for example, we can see how our
+<a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> pass interacts with other
+passes. Lets try it out with the gcse and licm passes:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../Debug+Asserts/lib/Hello.so -gcse -licm --debug-pass<span class="o">=</span>Structure < hello.bc > /dev/null
+<span class="go">Module Pass Manager</span>
+<span class="go"> Function Pass Manager</span>
+<span class="go"> Dominator Set Construction</span>
+<span class="go"> Immediate Dominators Construction</span>
+<span class="go"> Global Common Subexpression Elimination</span>
+<span class="go">-- Immediate Dominators Construction</span>
+<span class="go">-- Global Common Subexpression Elimination</span>
+<span class="go"> Natural Loop Construction</span>
+<span class="go"> Loop Invariant Code Motion</span>
+<span class="go">-- Natural Loop Construction</span>
+<span class="go">-- Loop Invariant Code Motion</span>
+<span class="go"> Module Verifier</span>
+<span class="go">-- Dominator Set Construction</span>
+<span class="go">-- Module Verifier</span>
+<span class="go"> Bitcode Writer</span>
+<span class="go">--Bitcode Writer</span>
+</pre></div>
+</div>
+<p>This output shows us when passes are constructed and when the analysis results
+are known to be dead (prefixed with “<tt class="docutils literal"><span class="pre">--</span></tt>”). Here we see that GCSE uses
+dominator and immediate dominator information to do its job. The LICM pass
+uses natural loop information, which uses dominator sets, but not immediate
+dominators. Because immediate dominators are no longer useful after the GCSE
+pass, it is immediately destroyed. The dominator sets are then reused to
+compute natural loop information, which is then used by the LICM pass.</p>
+<p>After the LICM pass, the module verifier runs (which is automatically added by
+the <strong class="program">opt</strong> tool), which uses the dominator set to check that the
+resultant LLVM code is well formed. After it finishes, the dominator set
+information is destroyed, after being computed once, and shared by three
+passes.</p>
+<p>Lets see how this changes when we run the <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> pass in between the two passes:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass<span class="o">=</span>Structure < hello.bc > /dev/null
+<span class="go">Module Pass Manager</span>
+<span class="go"> Function Pass Manager</span>
+<span class="go"> Dominator Set Construction</span>
+<span class="go"> Immediate Dominators Construction</span>
+<span class="go"> Global Common Subexpression Elimination</span>
+<span class="go">-- Dominator Set Construction</span>
+<span class="go">-- Immediate Dominators Construction</span>
+<span class="go">-- Global Common Subexpression Elimination</span>
+<span class="go"> Hello World Pass</span>
+<span class="go">-- Hello World Pass</span>
+<span class="go"> Dominator Set Construction</span>
+<span class="go"> Natural Loop Construction</span>
+<span class="go"> Loop Invariant Code Motion</span>
+<span class="go">-- Natural Loop Construction</span>
+<span class="go">-- Loop Invariant Code Motion</span>
+<span class="go"> Module Verifier</span>
+<span class="go">-- Dominator Set Construction</span>
+<span class="go">-- Module Verifier</span>
+<span class="go"> Bitcode Writer</span>
+<span class="go">--Bitcode Writer</span>
+<span class="go">Hello: __main</span>
+<span class="go">Hello: puts</span>
+<span class="go">Hello: main</span>
+</pre></div>
+</div>
+<p>Here we see that the <a class="reference internal" href="#writing-an-llvm-pass-basiccode"><em>Hello World</em></a> pass
+has killed the Dominator Set pass, even though it doesn’t modify the code at
+all! To fix this, we need to add the following <a class="reference internal" href="#writing-an-llvm-pass-getanalysisusage"><em>getAnalysisUsage</em></a> method to our pass:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// We don't modify the program, so we preserve all analyses</span>
+<span class="kt">void</span> <span class="nf">getAnalysisUsage</span><span class="p">(</span><span class="n">AnalysisUsage</span> <span class="o">&</span><span class="n">AU</span><span class="p">)</span> <span class="k">const</span> <span class="n">override</span> <span class="p">{</span>
+ <span class="n">AU</span><span class="p">.</span><span class="n">setPreservesAll</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Now when we run our pass, we get this output:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> opt -load ../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass<span class="o">=</span>Structure < hello.bc > /dev/null
+<span class="go">Pass Arguments: -gcse -hello -licm</span>
+<span class="go">Module Pass Manager</span>
+<span class="go"> Function Pass Manager</span>
+<span class="go"> Dominator Set Construction</span>
+<span class="go"> Immediate Dominators Construction</span>
+<span class="go"> Global Common Subexpression Elimination</span>
+<span class="go">-- Immediate Dominators Construction</span>
+<span class="go">-- Global Common Subexpression Elimination</span>
+<span class="go"> Hello World Pass</span>
+<span class="go">-- Hello World Pass</span>
+<span class="go"> Natural Loop Construction</span>
+<span class="go"> Loop Invariant Code Motion</span>
+<span class="go">-- Loop Invariant Code Motion</span>
+<span class="go">-- Natural Loop Construction</span>
+<span class="go"> Module Verifier</span>
+<span class="go">-- Dominator Set Construction</span>
+<span class="go">-- Module Verifier</span>
+<span class="go"> Bitcode Writer</span>
+<span class="go">--Bitcode Writer</span>
+<span class="go">Hello: __main</span>
+<span class="go">Hello: puts</span>
+<span class="go">Hello: main</span>
+</pre></div>
+</div>
+<p>Which shows that we don’t accidentally invalidate dominator information
+anymore, and therefore do not have to compute it twice.</p>
+<div class="section" id="the-releasememory-method">
+<span id="writing-an-llvm-pass-releasememory"></span><h4><a class="toc-backref" href="#id49">The <tt class="docutils literal"><span class="pre">releaseMemory</span></tt> method</a><a class="headerlink" href="#the-releasememory-method" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="nf">releaseMemory</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">PassManager</span></tt> automatically determines when to compute analysis results,
+and how long to keep them around for. Because the lifetime of the pass object
+itself is effectively the entire duration of the compilation process, we need
+some way to free analysis results when they are no longer useful. The
+<tt class="docutils literal"><span class="pre">releaseMemory</span></tt> virtual method is the way to do this.</p>
+<p>If you are writing an analysis or any other pass that retains a significant
+amount of state (for use by another pass which “requires” your pass and uses
+the <a class="reference internal" href="#writing-an-llvm-pass-getanalysis"><em>getAnalysis</em></a> method) you should
+implement <tt class="docutils literal"><span class="pre">releaseMemory</span></tt> to, well, release the memory allocated to maintain
+this internal state. This method is called after the <tt class="docutils literal"><span class="pre">run*</span></tt> method for the
+class, before the next call of <tt class="docutils literal"><span class="pre">run*</span></tt> in your pass.</p>
+</div>
+</div>
+</div>
+<div class="section" id="registering-dynamically-loaded-passes">
+<h2><a class="toc-backref" href="#id50">Registering dynamically loaded passes</a><a class="headerlink" href="#registering-dynamically-loaded-passes" title="Permalink to this headline">¶</a></h2>
+<p><em>Size matters</em> when constructing production quality tools using LLVM, both for
+the purposes of distribution, and for regulating the resident code size when
+running on the target system. Therefore, it becomes desirable to selectively
+use some passes, while omitting others and maintain the flexibility to change
+configurations later on. You want to be able to do all this, and, provide
+feedback to the user. This is where pass registration comes into play.</p>
+<p>The fundamental mechanisms for pass registration are the
+<tt class="docutils literal"><span class="pre">MachinePassRegistry</span></tt> class and subclasses of <tt class="docutils literal"><span class="pre">MachinePassRegistryNode</span></tt>.</p>
+<p>An instance of <tt class="docutils literal"><span class="pre">MachinePassRegistry</span></tt> is used to maintain a list of
+<tt class="docutils literal"><span class="pre">MachinePassRegistryNode</span></tt> objects. This instance maintains the list and
+communicates additions and deletions to the command line interface.</p>
+<p>An instance of <tt class="docutils literal"><span class="pre">MachinePassRegistryNode</span></tt> subclass is used to maintain
+information provided about a particular pass. This information includes the
+command line name, the command help string and the address of the function used
+to create an instance of the pass. A global static constructor of one of these
+instances <em>registers</em> with a corresponding <tt class="docutils literal"><span class="pre">MachinePassRegistry</span></tt>, the static
+destructor <em>unregisters</em>. Thus a pass that is statically linked in the tool
+will be registered at start up. A dynamically loaded pass will register on
+load and unregister at unload.</p>
+<div class="section" id="using-existing-registries">
+<h3><a class="toc-backref" href="#id51">Using existing registries</a><a class="headerlink" href="#using-existing-registries" title="Permalink to this headline">¶</a></h3>
+<p>There are predefined registries to track instruction scheduling
+(<tt class="docutils literal"><span class="pre">RegisterScheduler</span></tt>) and register allocation (<tt class="docutils literal"><span class="pre">RegisterRegAlloc</span></tt>) machine
+passes. Here we will describe how to <em>register</em> a register allocator machine
+pass.</p>
+<p>Implement your register allocator machine pass. In your register allocator
+<tt class="docutils literal"><span class="pre">.cpp</span></tt> file add the following include:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/CodeGen/RegAllocRegistry.h"</span>
+</pre></div>
+</div>
+<p>Also in your register allocator <tt class="docutils literal"><span class="pre">.cpp</span></tt> file, define a creator function in the
+form:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FunctionPass</span> <span class="o">*</span><span class="nf">createMyRegisterAllocator</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="n">MyRegisterAllocator</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that the signature of this function should match the type of
+<tt class="docutils literal"><span class="pre">RegisterRegAlloc::FunctionPassCtor</span></tt>. In the same file add the “installing”
+declaration, in the form:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">RegisterRegAlloc</span> <span class="nf">myRegAlloc</span><span class="p">(</span><span class="s">"myregalloc"</span><span class="p">,</span>
+ <span class="s">"my register allocator help string"</span><span class="p">,</span>
+ <span class="n">createMyRegisterAllocator</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Note the two spaces prior to the help string produces a tidy result on the
+<a class="reference internal" href="CommandGuide/opt.html#cmdoption-help"><em class="xref std std-option">-help</em></a> query.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> llc -help
+<span class="go"> ...</span>
+<span class="go"> -regalloc - Register allocator to use (default=linearscan)</span>
+<span class="go"> =linearscan - linear scan register allocator</span>
+<span class="go"> =local - local register allocator</span>
+<span class="go"> =simple - simple register allocator</span>
+<span class="go"> =myregalloc - my register allocator help string</span>
+<span class="go"> ...</span>
+</pre></div>
+</div>
+<p>And that’s it. The user is now free to use <tt class="docutils literal"><span class="pre">-regalloc=myregalloc</span></tt> as an
+option. Registering instruction schedulers is similar except use the
+<tt class="docutils literal"><span class="pre">RegisterScheduler</span></tt> class. Note that the
+<tt class="docutils literal"><span class="pre">RegisterScheduler::FunctionPassCtor</span></tt> is significantly different from
+<tt class="docutils literal"><span class="pre">RegisterRegAlloc::FunctionPassCtor</span></tt>.</p>
+<p>To force the load/linking of your register allocator into the
+<strong class="program">llc</strong>/<strong class="program">lli</strong> tools, add your creator function’s global
+declaration to <tt class="docutils literal"><span class="pre">Passes.h</span></tt> and add a “pseudo” call line to
+<tt class="docutils literal"><span class="pre">llvm/Codegen/LinkAllCodegenComponents.h</span></tt>.</p>
+</div>
+<div class="section" id="creating-new-registries">
+<h3><a class="toc-backref" href="#id52">Creating new registries</a><a class="headerlink" href="#creating-new-registries" title="Permalink to this headline">¶</a></h3>
+<p>The easiest way to get started is to clone one of the existing registries; we
+recommend <tt class="docutils literal"><span class="pre">llvm/CodeGen/RegAllocRegistry.h</span></tt>. The key things to modify are
+the class name and the <tt class="docutils literal"><span class="pre">FunctionPassCtor</span></tt> type.</p>
+<p>Then you need to declare the registry. Example: if your pass registry is
+<tt class="docutils literal"><span class="pre">RegisterMyPasses</span></tt> then define:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MachinePassRegistry</span> <span class="n">RegisterMyPasses</span><span class="o">::</span><span class="n">Registry</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>And finally, declare the command line option for your passes. Example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">RegisterMyPasses</span><span class="o">::</span><span class="n">FunctionPassCtor</span><span class="p">,</span> <span class="nb">false</span><span class="p">,</span>
+ <span class="n">RegisterPassParser</span><span class="o"><</span><span class="n">RegisterMyPasses</span><span class="o">></span> <span class="o">></span>
+<span class="n">MyPassOpt</span><span class="p">(</span><span class="s">"mypass"</span><span class="p">,</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">init</span><span class="p">(</span><span class="o">&</span><span class="n">createDefaultMyPass</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"my pass option help"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>Here the command option is “<tt class="docutils literal"><span class="pre">mypass</span></tt>”, with <tt class="docutils literal"><span class="pre">createDefaultMyPass</span></tt> as the
+default creator.</p>
+</div>
+<div class="section" id="using-gdb-with-dynamically-loaded-passes">
+<h3><a class="toc-backref" href="#id53">Using GDB with dynamically loaded passes</a><a class="headerlink" href="#using-gdb-with-dynamically-loaded-passes" title="Permalink to this headline">¶</a></h3>
+<p>Unfortunately, using GDB with dynamically loaded passes is not as easy as it
+should be. First of all, you can’t set a breakpoint in a shared object that
+has not been loaded yet, and second of all there are problems with inlined
+functions in shared objects. Here are some suggestions to debugging your pass
+with GDB.</p>
+<p>For sake of discussion, I’m going to assume that you are debugging a
+transformation invoked by <strong class="program">opt</strong>, although nothing described here
+depends on that.</p>
+<div class="section" id="setting-a-breakpoint-in-your-pass">
+<h4><a class="toc-backref" href="#id54">Setting a breakpoint in your pass</a><a class="headerlink" href="#setting-a-breakpoint-in-your-pass" title="Permalink to this headline">¶</a></h4>
+<p>First thing you do is start gdb on the opt process:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> gdb opt
+<span class="go">GNU gdb 5.0</span>
+<span class="go">Copyright 2000 Free Software Foundation, Inc.</span>
+<span class="go">GDB is free software, covered by the GNU General Public License, and you are</span>
+<span class="go">welcome to change it and/or distribute copies of it under certain conditions.</span>
+<span class="go">Type "show copying" to see the conditions.</span>
+<span class="go">There is absolutely no warranty for GDB. Type "show warranty" for details.</span>
+<span class="go">This GDB was configured as "sparc-sun-solaris2.6"...</span>
+<span class="go">(gdb)</span>
+</pre></div>
+</div>
+<p>Note that <strong class="program">opt</strong> has a lot of debugging information in it, so it takes
+time to load. Be patient. Since we cannot set a breakpoint in our pass yet
+(the shared object isn’t loaded until runtime), we must execute the process,
+and have it stop before it invokes our pass, but after it has loaded the shared
+object. The most foolproof way of doing this is to set a breakpoint in
+<tt class="docutils literal"><span class="pre">PassManager::run</span></tt> and then run the process with the arguments you want:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="o">(</span>gdb<span class="o">)</span> <span class="nb">break </span>llvm::PassManager::run
+<span class="go">Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.</span>
+<span class="go">(gdb) run test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]</span>
+<span class="go">Starting program: opt test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]</span>
+<span class="go">Breakpoint 1, PassManager::run (this=0xffbef174, M=@0x70b298) at Pass.cpp:70</span>
+<span class="go">70 bool PassManager::run(Module &M) { return PM->run(M); }</span>
+<span class="go">(gdb)</span>
+</pre></div>
+</div>
+<p>Once the <strong class="program">opt</strong> stops in the <tt class="docutils literal"><span class="pre">PassManager::run</span></tt> method you are now
+free to set breakpoints in your pass so that you can trace through execution or
+do other standard debugging stuff.</p>
+</div>
+<div class="section" id="miscellaneous-problems">
+<h4><a class="toc-backref" href="#id55">Miscellaneous Problems</a><a class="headerlink" href="#miscellaneous-problems" title="Permalink to this headline">¶</a></h4>
+<p>Once you have the basics down, there are a couple of problems that GDB has,
+some with solutions, some without.</p>
+<ul class="simple">
+<li>Inline functions have bogus stack information. In general, GDB does a pretty
+good job getting stack traces and stepping through inline functions. When a
+pass is dynamically loaded however, it somehow completely loses this
+capability. The only solution I know of is to de-inline a function (move it
+from the body of a class to a <tt class="docutils literal"><span class="pre">.cpp</span></tt> file).</li>
+<li>Restarting the program breaks breakpoints. After following the information
+above, you have succeeded in getting some breakpoints planted in your pass.
+Next thing you know, you restart the program (i.e., you type “<tt class="docutils literal"><span class="pre">run</span></tt>” again),
+and you start getting errors about breakpoints being unsettable. The only
+way I have found to “fix” this problem is to delete the breakpoints that are
+already set in your pass, run the program, and re-set the breakpoints once
+execution stops in <tt class="docutils literal"><span class="pre">PassManager::run</span></tt>.</li>
+</ul>
+<p>Hopefully these tips will help with common case debugging situations. If you’d
+like to contribute some tips of your own, just contact <a class="reference external" href="mailto:sabre%40nondot.org">Chris</a>.</p>
+</div>
+</div>
+<div class="section" id="future-extensions-planned">
+<h3><a class="toc-backref" href="#id56">Future extensions planned</a><a class="headerlink" href="#future-extensions-planned" title="Permalink to this headline">¶</a></h3>
+<p>Although the LLVM Pass Infrastructure is very capable as it stands, and does
+some nifty stuff, there are things we’d like to add in the future. Here is
+where we are going:</p>
+<div class="section" id="multithreaded-llvm">
+<span id="writing-an-llvm-pass-smp"></span><h4><a class="toc-backref" href="#id57">Multithreaded LLVM</a><a class="headerlink" href="#multithreaded-llvm" title="Permalink to this headline">¶</a></h4>
+<p>Multiple CPU machines are becoming more common and compilation can never be
+fast enough: obviously we should allow for a multithreaded compiler. Because
+of the semantics defined for passes above (specifically they cannot maintain
+state across invocations of their <tt class="docutils literal"><span class="pre">run*</span></tt> methods), a nice clean way to
+implement a multithreaded compiler would be for the <tt class="docutils literal"><span class="pre">PassManager</span></tt> class to
+create multiple instances of each pass object, and allow the separate instances
+to be hacking on different parts of the program at the same time.</p>
+<p>This implementation would prevent each of the passes from having to implement
+multithreaded constructs, requiring only the LLVM core to have locking in a few
+places (for global resources). Although this is a simple extension, we simply
+haven’t had time (or multiprocessor machines, thus a reason) to implement this.
+Despite that, we have kept the LLVM passes SMP ready, and you should too.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToUseAttributes.html" title="How To Use Attributes"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GarbageCollection.html" title="Garbage Collection with LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/YamlIO.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/YamlIO.html?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/YamlIO.html (added)
+++ www-releases/trunk/3.9.1/docs/YamlIO.html Thu Dec 22 14:04:03 2016
@@ -0,0 +1,1030 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>YAML I/O — LLVM 3.9 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.9',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.9 documentation" href="index.html" />
+ <link rel="next" title="The Often Misunderstood GEP Instruction" href="GetElementPtr.html" />
+ <link rel="prev" title="LLVMâs Analysis and Transform Passes" href="Passes.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Passes.html" title="LLVMâs Analysis and Transform Passes"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="yaml-i-o">
+<h1>YAML I/O<a class="headerlink" href="#yaml-i-o" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction-to-yaml" id="id1">Introduction to YAML</a></li>
+<li><a class="reference internal" href="#introduction-to-yaml-i-o" id="id2">Introduction to YAML I/O</a></li>
+<li><a class="reference internal" href="#error-handling" id="id3">Error Handling</a></li>
+<li><a class="reference internal" href="#scalars" id="id4">Scalars</a><ul>
+<li><a class="reference internal" href="#built-in-types" id="id5">Built-in types</a></li>
+<li><a class="reference internal" href="#unique-types" id="id6">Unique types</a></li>
+<li><a class="reference internal" href="#hex-types" id="id7">Hex types</a></li>
+<li><a class="reference internal" href="#scalarenumerationtraits" id="id8">ScalarEnumerationTraits</a></li>
+<li><a class="reference internal" href="#bitvalue" id="id9">BitValue</a></li>
+<li><a class="reference internal" href="#custom-scalar" id="id10">Custom Scalar</a></li>
+<li><a class="reference internal" href="#block-scalars" id="id11">Block Scalars</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#mappings" id="id12">Mappings</a><ul>
+<li><a class="reference internal" href="#no-normalization" id="id13">No Normalization</a></li>
+<li><a class="reference internal" href="#normalization" id="id14">Normalization</a></li>
+<li><a class="reference internal" href="#default-values" id="id15">Default values</a></li>
+<li><a class="reference internal" href="#order-of-keys" id="id16">Order of Keys</a></li>
+<li><a class="reference internal" href="#tags" id="id17">Tags</a></li>
+<li><a class="reference internal" href="#validation" id="id18">Validation</a></li>
+<li><a class="reference internal" href="#flow-mapping" id="id19">Flow Mapping</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#sequence" id="id20">Sequence</a><ul>
+<li><a class="reference internal" href="#flow-sequence" id="id21">Flow Sequence</a></li>
+<li><a class="reference internal" href="#utility-macros" id="id22">Utility Macros</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#document-list" id="id23">Document List</a></li>
+<li><a class="reference internal" href="#user-context-data" id="id24">User Context Data</a></li>
+<li><a class="reference internal" href="#output" id="id25">Output</a></li>
+<li><a class="reference internal" href="#input" id="id26">Input</a></li>
+</ul>
+</div>
+<div class="section" id="introduction-to-yaml">
+<h2><a class="toc-backref" href="#id1">Introduction to YAML</a><a class="headerlink" href="#introduction-to-yaml" title="Permalink to this headline">¶</a></h2>
+<p>YAML is a human readable data serialization language. The full YAML language
+spec can be read at <a class="reference external" href="http://www.yaml.org/spec/1.2/spec.html#Introduction">yaml.org</a>. The simplest form of
+yaml is just “scalars”, “mappings”, and “sequences”. A scalar is any number
+or string. The pound/hash symbol (#) begins a comment line. A mapping is
+a set of key-value pairs where the key ends with a colon. For example:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># a mapping</span>
+<span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+</pre></div>
+</div>
+<p>A sequence is a list of items where each item starts with a leading dash (‘-‘).
+For example:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># a sequence</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86_64</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">PowerPC</span>
+</pre></div>
+</div>
+<p>You can combine mappings and sequences by indenting. For example a sequence
+of mappings in which one of the mapping values is itself a sequence:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># a sequence of mappings with one key's value being a sequence</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86_64</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Bob</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Dan</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">PowerPC</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">x86</span>
+</pre></div>
+</div>
+<p>Sometime sequences are known to be short and the one entry per line is too
+verbose, so YAML offers an alternate syntax for sequences called a “Flow
+Sequence” in which you put comma separated sequence elements into square
+brackets. The above example could then be simplified to :</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># a sequence of mappings with one key's value being a flow sequence</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">x86</span><span class="p-Indicator">,</span> <span class="nv">x86_64</span> <span class="p-Indicator">]</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Bob</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">x86</span> <span class="p-Indicator">]</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Dan</span>
+ <span class="l-Scalar-Plain">cpus</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">PowerPC</span><span class="p-Indicator">,</span> <span class="nv">x86</span> <span class="p-Indicator">]</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="introduction-to-yaml-i-o">
+<h2><a class="toc-backref" href="#id2">Introduction to YAML I/O</a><a class="headerlink" href="#introduction-to-yaml-i-o" title="Permalink to this headline">¶</a></h2>
+<p>The use of indenting makes the YAML easy for a human to read and understand,
+but having a program read and write YAML involves a lot of tedious details.
+The YAML I/O library structures and simplifies reading and writing YAML
+documents.</p>
+<p>YAML I/O assumes you have some “native” data structures which you want to be
+able to dump as YAML and recreate from YAML. The first step is to try
+writing example YAML for your data structures. You may find after looking at
+possible YAML representations that a direct mapping of your data structures
+to YAML is not very readable. Often the fields are not in the order that
+a human would find readable. Or the same information is replicated in multiple
+locations, making it hard for a human to write such YAML correctly.</p>
+<p>In relational database theory there is a design step called normalization in
+which you reorganize fields and tables. The same considerations need to
+go into the design of your YAML encoding. But, you may not want to change
+your existing native data structures. Therefore, when writing out YAML
+there may be a normalization step, and when reading YAML there would be a
+corresponding denormalization step.</p>
+<p>YAML I/O uses a non-invasive, traits based design. YAML I/O defines some
+abstract base templates. You specialize those templates on your data types.
+For instance, if you have an enumerated type FooBar you could specialize
+ScalarEnumerationTraits on that type and define the enumeration() method:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">ScalarEnumerationTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarEnumerationTraits</span><span class="o"><</span><span class="n">FooBar</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">enumeration</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">FooBar</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>As with all YAML I/O template specializations, the ScalarEnumerationTraits is used for
+both reading and writing YAML. That is, the mapping between in-memory enum
+values and the YAML string representation is only in one place.
+This assures that the code for writing and parsing of YAML stays in sync.</p>
+<p>To specify a YAML mappings, you define a specialization on
+llvm::yaml::MappingTraits.
+If your native data structure happens to be a struct that is already normalized,
+then the specialization is simple. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Person</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Person</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">name</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"hat-size"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">hatSize</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>A YAML sequence is automatically inferred if you data type has begin()/end()
+iterators and a push_back() method. Therefore any of the STL containers
+(such as std::vector<>) will automatically translate to YAML sequences.</p>
+<p>Once you have defined specializations for your data types, you can
+programmatically use YAML I/O to write a YAML document:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Output</span><span class="p">;</span>
+
+<span class="n">Person</span> <span class="n">tom</span><span class="p">;</span>
+<span class="n">tom</span><span class="p">.</span><span class="n">name</span> <span class="o">=</span> <span class="s">"Tom"</span><span class="p">;</span>
+<span class="n">tom</span><span class="p">.</span><span class="n">hatSize</span> <span class="o">=</span> <span class="mi">8</span><span class="p">;</span>
+<span class="n">Person</span> <span class="n">dan</span><span class="p">;</span>
+<span class="n">dan</span><span class="p">.</span><span class="n">name</span> <span class="o">=</span> <span class="s">"Dan"</span><span class="p">;</span>
+<span class="n">dan</span><span class="p">.</span><span class="n">hatSize</span> <span class="o">=</span> <span class="mi">7</span><span class="p">;</span>
+<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">Person</span><span class="o">></span> <span class="n">persons</span><span class="p">;</span>
+<span class="n">persons</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">tom</span><span class="p">);</span>
+<span class="n">persons</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">dan</span><span class="p">);</span>
+
+<span class="n">Output</span> <span class="nf">yout</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">outs</span><span class="p">());</span>
+<span class="n">yout</span> <span class="o"><<</span> <span class="n">persons</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This would write the following:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+ <span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">8</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Dan</span>
+ <span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+</pre></div>
+</div>
+<p>And you can also read such YAML documents with the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Input</span><span class="p">;</span>
+
+<span class="k">typedef</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">Person</span><span class="o">></span> <span class="n">PersonList</span><span class="p">;</span>
+<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">PersonList</span><span class="o">></span> <span class="n">docs</span><span class="p">;</span>
+
+<span class="n">Input</span> <span class="nf">yin</span><span class="p">(</span><span class="n">document</span><span class="p">.</span><span class="n">getBuffer</span><span class="p">());</span>
+<span class="n">yin</span> <span class="o">>></span> <span class="n">docs</span><span class="p">;</span>
+
+<span class="k">if</span> <span class="p">(</span> <span class="n">yin</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">)</span>
+ <span class="k">return</span><span class="p">;</span>
+
+<span class="c1">// Process read document</span>
+<span class="k">for</span> <span class="p">(</span> <span class="n">PersonList</span> <span class="o">&</span><span class="n">pl</span> <span class="o">:</span> <span class="n">docs</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span> <span class="n">Person</span> <span class="o">&</span><span class="n">person</span> <span class="o">:</span> <span class="n">pl</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="n">cout</span> <span class="o"><<</span> <span class="s">"name="</span> <span class="o"><<</span> <span class="n">person</span><span class="p">.</span><span class="n">name</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>One other feature of YAML is the ability to define multiple documents in a
+single file. That is why reading YAML produces a vector of your document type.</p>
+</div>
+<div class="section" id="error-handling">
+<h2><a class="toc-backref" href="#id3">Error Handling</a><a class="headerlink" href="#error-handling" title="Permalink to this headline">¶</a></h2>
+<p>When parsing a YAML document, if the input does not match your schema (as
+expressed in your XxxTraits<> specializations). YAML I/O
+will print out an error message and your Input object’s error() method will
+return true. For instance the following document:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+ <span class="l-Scalar-Plain">shoe-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">12</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Dan</span>
+ <span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+</pre></div>
+</div>
+<p>Has a key (shoe-size) that is not defined in the schema. YAML I/O will
+automatically generate this error:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">YAML:2:2</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">error</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">unknown key 'shoe-size'</span>
+ <span class="l-Scalar-Plain">shoe-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">12</span>
+ <span class="l-Scalar-Plain">^~~~~~~~~</span>
+</pre></div>
+</div>
+<p>Similar errors are produced for other input not conforming to the schema.</p>
+</div>
+<div class="section" id="scalars">
+<h2><a class="toc-backref" href="#id4">Scalars</a><a class="headerlink" href="#scalars" title="Permalink to this headline">¶</a></h2>
+<p>YAML scalars are just strings (i.e. not a sequence or mapping). The YAML I/O
+library provides support for translating between YAML scalars and specific
+C++ types.</p>
+<div class="section" id="built-in-types">
+<h3><a class="toc-backref" href="#id5">Built-in types</a><a class="headerlink" href="#built-in-types" title="Permalink to this headline">¶</a></h3>
+<p>The following types have built-in support in YAML I/O:</p>
+<ul class="simple">
+<li>bool</li>
+<li>float</li>
+<li>double</li>
+<li>StringRef</li>
+<li>std::string</li>
+<li>int64_t</li>
+<li>int32_t</li>
+<li>int16_t</li>
+<li>int8_t</li>
+<li>uint64_t</li>
+<li>uint32_t</li>
+<li>uint16_t</li>
+<li>uint8_t</li>
+</ul>
+<p>That is, you can use those types in fields of MappingTraits or as element type
+in sequence. When reading, YAML I/O will validate that the string found
+is convertible to that type and error out if not.</p>
+</div>
+<div class="section" id="unique-types">
+<h3><a class="toc-backref" href="#id6">Unique types</a><a class="headerlink" href="#unique-types" title="Permalink to this headline">¶</a></h3>
+<p>Given that YAML I/O is trait based, the selection of how to convert your data
+to YAML is based on the type of your data. But in C++ type matching, typedefs
+do not generate unique type names. That means if you have two typedefs of
+unsigned int, to YAML I/O both types look exactly like unsigned int. To
+facilitate make unique type names, YAML I/O provides a macro which is used
+like a typedef on built-in types, but expands to create a class with conversion
+operators to and from the base type. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">LLVM_YAML_STRONG_TYPEDEF</span><span class="p">(</span><span class="kt">uint32_t</span><span class="p">,</span> <span class="n">MyFooFlags</span><span class="p">)</span>
+<span class="n">LLVM_YAML_STRONG_TYPEDEF</span><span class="p">(</span><span class="kt">uint32_t</span><span class="p">,</span> <span class="n">MyBarFlags</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This generates two classes MyFooFlags and MyBarFlags which you can use in your
+native data structures instead of uint32_t. They are implicitly
+converted to and from uint32_t. The point of creating these unique types
+is that you can now specify traits on them to get different YAML conversions.</p>
+</div>
+<div class="section" id="hex-types">
+<h3><a class="toc-backref" href="#id7">Hex types</a><a class="headerlink" href="#hex-types" title="Permalink to this headline">¶</a></h3>
+<p>An example use of a unique type is that YAML I/O provides fixed sized unsigned
+integers that are written with YAML I/O as hexadecimal instead of the decimal
+format used by the built-in integer types:</p>
+<ul class="simple">
+<li>Hex64</li>
+<li>Hex32</li>
+<li>Hex16</li>
+<li>Hex8</li>
+</ul>
+<p>You can use llvm::yaml::Hex32 instead of uint32_t and the only different will
+be that when YAML I/O writes out that type it will be formatted in hexadecimal.</p>
+</div>
+<div class="section" id="scalarenumerationtraits">
+<h3><a class="toc-backref" href="#id8">ScalarEnumerationTraits</a><a class="headerlink" href="#scalarenumerationtraits" title="Permalink to this headline">¶</a></h3>
+<p>YAML I/O supports translating between in-memory enumerations and a set of string
+values in YAML documents. This is done by specializing ScalarEnumerationTraits<>
+on your enumeration type and define a enumeration() method.
+For instance, suppose you had an enumeration of CPUs and a struct with it as
+a field:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">CPUs</span> <span class="p">{</span>
+ <span class="n">cpu_x86_64</span> <span class="o">=</span> <span class="mi">5</span><span class="p">,</span>
+ <span class="n">cpu_x86</span> <span class="o">=</span> <span class="mi">7</span><span class="p">,</span>
+ <span class="n">cpu_PowerPC</span> <span class="o">=</span> <span class="mi">8</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">Info</span> <span class="p">{</span>
+ <span class="n">CPUs</span> <span class="n">cpu</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">flags</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>To support reading and writing of this enumeration, you can define a
+ScalarEnumerationTraits specialization on CPUs, which can then be used
+as a field type:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">ScalarEnumerationTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarEnumerationTraits</span><span class="o"><</span><span class="n">CPUs</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">enumeration</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">CPUs</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">enumCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"x86_64"</span><span class="p">,</span> <span class="n">cpu_x86_64</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">enumCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"x86"</span><span class="p">,</span> <span class="n">cpu_x86</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">enumCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"PowerPC"</span><span class="p">,</span> <span class="n">cpu_PowerPC</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Info</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Info</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"cpu"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">cpu</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"flags"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">flags</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>When reading YAML, if the string found does not match any of the strings
+specified by enumCase() methods, an error is automatically generated.
+When writing YAML, if the value being written does not match any of the values
+specified by the enumCase() methods, a runtime assertion is triggered.</p>
+</div>
+<div class="section" id="bitvalue">
+<h3><a class="toc-backref" href="#id9">BitValue</a><a class="headerlink" href="#bitvalue" title="Permalink to this headline">¶</a></h3>
+<p>Another common data structure in C++ is a field where each bit has a unique
+meaning. This is often used in a “flags” field. YAML I/O has support for
+converting such fields to a flow sequence. For instance suppose you
+had the following bit flags defined:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+ <span class="n">flagsPointy</span> <span class="o">=</span> <span class="mi">1</span>
+ <span class="n">flagsHollow</span> <span class="o">=</span> <span class="mi">2</span>
+ <span class="n">flagsFlat</span> <span class="o">=</span> <span class="mi">4</span>
+ <span class="n">flagsRound</span> <span class="o">=</span> <span class="mi">8</span>
+<span class="p">};</span>
+
+<span class="n">LLVM_YAML_STRONG_TYPEDEF</span><span class="p">(</span><span class="kt">uint32_t</span><span class="p">,</span> <span class="n">MyFlags</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>To support reading and writing of MyFlags, you specialize ScalarBitSetTraits<>
+on MyFlags and provide the bit values and their names.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">ScalarBitSetTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarBitSetTraits</span><span class="o"><</span><span class="n">MyFlags</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">bitset</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyFlags</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"hollow"</span><span class="p">,</span> <span class="n">flagHollow</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"flat"</span><span class="p">,</span> <span class="n">flagFlat</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"round"</span><span class="p">,</span> <span class="n">flagRound</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"pointy"</span><span class="p">,</span> <span class="n">flagPointy</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">Info</span> <span class="p">{</span>
+ <span class="n">StringRef</span> <span class="n">name</span><span class="p">;</span>
+ <span class="n">MyFlags</span> <span class="n">flags</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Info</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Info</span><span class="o">&</span> <span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">name</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"flags"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">flags</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>With the above, YAML I/O (when writing) will test mask each value in the
+bitset trait against the flags field, and each that matches will
+cause the corresponding string to be added to the flow sequence. The opposite
+is done when reading and any unknown string values will result in a error. With
+the above schema, a same valid YAML document is:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">flags</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">pointy</span><span class="p-Indicator">,</span> <span class="nv">flat</span> <span class="p-Indicator">]</span>
+</pre></div>
+</div>
+<p>Sometimes a “flags” field might contains an enumeration part
+defined by a bit-mask.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+ <span class="n">flagsFeatureA</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+ <span class="n">flagsFeatureB</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
+ <span class="n">flagsFeatureC</span> <span class="o">=</span> <span class="mi">4</span><span class="p">,</span>
+
+ <span class="n">flagsCPUMask</span> <span class="o">=</span> <span class="mi">24</span><span class="p">,</span>
+
+ <span class="n">flagsCPU1</span> <span class="o">=</span> <span class="mi">8</span><span class="p">,</span>
+ <span class="n">flagsCPU2</span> <span class="o">=</span> <span class="mi">16</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>To support reading and writing such fields, you need to use the maskedBitSet()
+method and provide the bit values, their names and the enumeration mask.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarBitSetTraits</span><span class="o"><</span><span class="n">MyFlags</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">bitset</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyFlags</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"featureA"</span><span class="p">,</span> <span class="n">flagsFeatureA</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"featureB"</span><span class="p">,</span> <span class="n">flagsFeatureB</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">bitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"featureC"</span><span class="p">,</span> <span class="n">flagsFeatureC</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">maskedBitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"CPU1"</span><span class="p">,</span> <span class="n">flagsCPU1</span><span class="p">,</span> <span class="n">flagsCPUMask</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">maskedBitSetCase</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="s">"CPU2"</span><span class="p">,</span> <span class="n">flagsCPU2</span><span class="p">,</span> <span class="n">flagsCPUMask</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>YAML I/O (when writing) will apply the enumeration mask to the flags field,
+and compare the result and values from the bitset. As in case of a regular
+bitset, each that matches will cause the corresponding string to be added
+to the flow sequence.</p>
+</div>
+<div class="section" id="custom-scalar">
+<h3><a class="toc-backref" href="#id10">Custom Scalar</a><a class="headerlink" href="#custom-scalar" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes for readability a scalar needs to be formatted in a custom way. For
+instance your internal data structure may use a integer for time (seconds since
+some epoch), but in YAML it would be much nicer to express that integer in
+some time format (e.g. 4-May-2012 10:30pm). YAML I/O has a way to support
+custom formatting and parsing of scalar types by specializing ScalarTraits<> on
+your data type. When writing, YAML I/O will provide the native type and
+your specialization must create a temporary llvm::StringRef. When reading,
+YAML I/O will provide an llvm::StringRef of scalar and your specialization
+must convert that to your native data type. An outline of a custom scalar type
+looks like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">ScalarTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">ScalarTraits</span><span class="o"><</span><span class="n">MyCustomType</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span><span class="k">const</span> <span class="n">MyCustomType</span> <span class="o">&</span><span class="n">value</span><span class="p">,</span> <span class="kt">void</span><span class="o">*</span><span class="p">,</span>
+ <span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="n">out</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">out</span> <span class="o"><<</span> <span class="n">value</span><span class="p">;</span> <span class="c1">// do custom formatting here</span>
+ <span class="p">}</span>
+ <span class="k">static</span> <span class="n">StringRef</span> <span class="n">input</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">scalar</span><span class="p">,</span> <span class="kt">void</span><span class="o">*</span><span class="p">,</span> <span class="n">MyCustomType</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// do custom parsing here. Return the empty string on success,</span>
+ <span class="c1">// or an error message on failure.</span>
+ <span class="k">return</span> <span class="n">StringRef</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="c1">// Determine if this scalar needs quotes.</span>
+ <span class="k">static</span> <span class="kt">bool</span> <span class="n">mustQuote</span><span class="p">(</span><span class="n">StringRef</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">true</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="block-scalars">
+<h3><a class="toc-backref" href="#id11">Block Scalars</a><a class="headerlink" href="#block-scalars" title="Permalink to this headline">¶</a></h3>
+<p>YAML block scalars are string literals that are represented in YAML using the
+literal block notation, just like the example shown below:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">text</span><span class="p-Indicator">:</span> <span class="p-Indicator">|</span>
+ <span class="no">First line</span>
+ <span class="no">Second line</span>
+</pre></div>
+</div>
+<p>The YAML I/O library provides support for translating between YAML block scalars
+and specific C++ types by allowing you to specialize BlockScalarTraits<> on
+your data type. The library doesn’t provide any built-in support for block
+scalar I/O for types like std::string and llvm::StringRef as they are already
+supported by YAML I/O and use the ordinary scalar notation by default.</p>
+<p>BlockScalarTraits specializations are very similar to the
+ScalarTraits specialization - YAML I/O will provide the native type and your
+specialization must create a temporary llvm::StringRef when writing, and
+it will also provide an llvm::StringRef that has the value of that block scalar
+and your specialization must convert that to your native data type when reading.
+An example of a custom type with an appropriate specialization of
+BlockScalarTraits is shown below:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">BlockScalarTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">MyStringType</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">Str</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">BlockScalarTraits</span><span class="o"><</span><span class="n">MyStringType</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span><span class="k">const</span> <span class="n">MyStringType</span> <span class="o">&</span><span class="n">Value</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Ctxt</span><span class="p">,</span>
+ <span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="n">OS</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">OS</span> <span class="o"><<</span> <span class="n">Value</span><span class="p">.</span><span class="n">Str</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">static</span> <span class="n">StringRef</span> <span class="n">input</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">Scalar</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Ctxt</span><span class="p">,</span>
+ <span class="n">MyStringType</span> <span class="o">&</span><span class="n">Value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Value</span><span class="p">.</span><span class="n">Str</span> <span class="o">=</span> <span class="n">Scalar</span><span class="p">.</span><span class="n">str</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nf">StringRef</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="mappings">
+<h2><a class="toc-backref" href="#id12">Mappings</a><a class="headerlink" href="#mappings" title="Permalink to this headline">¶</a></h2>
+<p>To be translated to or from a YAML mapping for your type T you must specialize
+llvm::yaml::MappingTraits on T and implement the “void mapping(IO &io, T&)”
+method. If your native data structures use pointers to a class everywhere,
+you can specialize on the class pointer. Examples:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="c1">// Example of struct Foo which is used by value</span>
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Foo</span> <span class="o">&</span><span class="n">foo</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"size"</span><span class="p">,</span> <span class="n">foo</span><span class="p">.</span><span class="n">size</span><span class="p">);</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="c1">// Example of struct Bar which is natively always a pointer</span>
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Bar</span><span class="o">*></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Bar</span> <span class="o">*&</span><span class="n">bar</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"size"</span><span class="p">,</span> <span class="n">bar</span><span class="o">-></span><span class="n">size</span><span class="p">);</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<div class="section" id="no-normalization">
+<h3><a class="toc-backref" href="#id13">No Normalization</a><a class="headerlink" href="#no-normalization" title="Permalink to this headline">¶</a></h3>
+<p>The mapping() method is responsible, if needed, for normalizing and
+denormalizing. In a simple case where the native data structure requires no
+normalization, the mapping method just uses mapOptional() or mapRequired() to
+bind the struct’s fields to YAML key names. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Person</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Person</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">name</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapOptional</span><span class="p">(</span><span class="s">"hat-size"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">hatSize</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="normalization">
+<h3><a class="toc-backref" href="#id14">Normalization</a><a class="headerlink" href="#normalization" title="Permalink to this headline">¶</a></h3>
+<p>When [de]normalization is required, the mapping() method needs a way to access
+normalized values as fields. To help with this, there is
+a template MappingNormalization<> which you can then use to automatically
+do the normalization and denormalization. The template is used to create
+a local variable in your mapping() method which contains the normalized keys.</p>
+<p>Suppose you have native data type
+Polar which specifies a position in polar coordinates (distance, angle):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Polar</span> <span class="p">{</span>
+ <span class="kt">float</span> <span class="n">distance</span><span class="p">;</span>
+ <span class="kt">float</span> <span class="n">angle</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>but you’ve decided the normalized YAML for should be in x,y coordinates. That
+is, you want the yaml to look like:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">x</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">10.3</span>
+<span class="l-Scalar-Plain">y</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">-4.7</span>
+</pre></div>
+</div>
+<p>You can support this by defining a MappingTraits that normalizes the polar
+coordinates to x,y coordinates when writing YAML and denormalizes x,y
+coordinates into polar when reading YAML.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Polar</span><span class="o">></span> <span class="p">{</span>
+
+ <span class="k">class</span> <span class="nc">NormalizedPolar</span> <span class="p">{</span>
+ <span class="nl">public:</span>
+ <span class="n">NormalizedPolar</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">)</span>
+ <span class="o">:</span> <span class="n">x</span><span class="p">(</span><span class="mf">0.0</span><span class="p">),</span> <span class="n">y</span><span class="p">(</span><span class="mf">0.0</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">}</span>
+ <span class="n">NormalizedPolar</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="p">,</span> <span class="n">Polar</span> <span class="o">&</span><span class="n">polar</span><span class="p">)</span>
+ <span class="o">:</span> <span class="n">x</span><span class="p">(</span><span class="n">polar</span><span class="p">.</span><span class="n">distance</span> <span class="o">*</span> <span class="n">cos</span><span class="p">(</span><span class="n">polar</span><span class="p">.</span><span class="n">angle</span><span class="p">)),</span>
+ <span class="n">y</span><span class="p">(</span><span class="n">polar</span><span class="p">.</span><span class="n">distance</span> <span class="o">*</span> <span class="n">sin</span><span class="p">(</span><span class="n">polar</span><span class="p">.</span><span class="n">angle</span><span class="p">))</span> <span class="p">{</span>
+ <span class="p">}</span>
+ <span class="n">Polar</span> <span class="n">denormalize</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">Polar</span><span class="p">(</span><span class="n">sqrt</span><span class="p">(</span><span class="n">x</span><span class="o">*</span><span class="n">x</span><span class="o">+</span><span class="n">y</span><span class="o">*</span><span class="n">y</span><span class="p">),</span> <span class="n">arctan</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">y</span><span class="p">));</span>
+ <span class="p">}</span>
+
+ <span class="kt">float</span> <span class="n">x</span><span class="p">;</span>
+ <span class="kt">float</span> <span class="n">y</span><span class="p">;</span>
+ <span class="p">};</span>
+
+ <span class="k">static</span> <span class="kt">void</span> <span class="nf">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Polar</span> <span class="o">&</span><span class="n">polar</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MappingNormalization</span><span class="o"><</span><span class="n">NormalizedPolar</span><span class="p">,</span> <span class="n">Polar</span><span class="o">></span> <span class="n">keys</span><span class="p">(</span><span class="n">io</span><span class="p">,</span> <span class="n">polar</span><span class="p">);</span>
+
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"x"</span><span class="p">,</span> <span class="n">keys</span><span class="o">-></span><span class="n">x</span><span class="p">);</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"y"</span><span class="p">,</span> <span class="n">keys</span><span class="o">-></span><span class="n">y</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>When writing YAML, the local variable “keys” will be a stack allocated
+instance of NormalizedPolar, constructed from the supplied polar object which
+initializes it x and y fields. The mapRequired() methods then write out the x
+and y values as key/value pairs.</p>
+<p>When reading YAML, the local variable “keys” will be a stack allocated instance
+of NormalizedPolar, constructed by the empty constructor. The mapRequired
+methods will find the matching key in the YAML document and fill in the x and y
+fields of the NormalizedPolar object keys. At the end of the mapping() method
+when the local keys variable goes out of scope, the denormalize() method will
+automatically be called to convert the read values back to polar coordinates,
+and then assigned back to the second parameter to mapping().</p>
+<p>In some cases, the normalized class may be a subclass of the native type and
+could be returned by the denormalize() method, except that the temporary
+normalized instance is stack allocated. In these cases, the utility template
+MappingNormalizationHeap<> can be used instead. It just like
+MappingNormalization<> except that it heap allocates the normalized object
+when reading YAML. It never destroys the normalized object. The denormalize()
+method can this return “this”.</p>
+</div>
+<div class="section" id="default-values">
+<h3><a class="toc-backref" href="#id15">Default values</a><a class="headerlink" href="#default-values" title="Permalink to this headline">¶</a></h3>
+<p>Within a mapping() method, calls to io.mapRequired() mean that that key is
+required to exist when parsing YAML documents, otherwise YAML I/O will issue an
+error.</p>
+<p>On the other hand, keys registered with io.mapOptional() are allowed to not
+exist in the YAML document being read. So what value is put in the field
+for those optional keys?
+There are two steps to how those optional fields are filled in. First, the
+second parameter to the mapping() method is a reference to a native class. That
+native class must have a default constructor. Whatever value the default
+constructor initially sets for an optional field will be that field’s value.
+Second, the mapOptional() method has an optional third parameter. If provided
+it is the value that mapOptional() should set that field to if the YAML document
+does not have that key.</p>
+<p>There is one important difference between those two ways (default constructor
+and third parameter to mapOptional). When YAML I/O generates a YAML document,
+if the mapOptional() third parameter is used, if the actual value being written
+is the same as (using ==) the default value, then that key/value is not written.</p>
+</div>
+<div class="section" id="order-of-keys">
+<h3><a class="toc-backref" href="#id16">Order of Keys</a><a class="headerlink" href="#order-of-keys" title="Permalink to this headline">¶</a></h3>
+<p>When writing out a YAML document, the keys are written in the order that the
+calls to mapRequired()/mapOptional() are made in the mapping() method. This
+gives you a chance to write the fields in an order that a human reader of
+the YAML document would find natural. This may be different that the order
+of the fields in the native class.</p>
+<p>When reading in a YAML document, the keys in the document can be in any order,
+but they are processed in the order that the calls to mapRequired()/mapOptional()
+are made in the mapping() method. That enables some interesting
+functionality. For instance, if the first field bound is the cpu and the second
+field bound is flags, and the flags are cpu specific, you can programmatically
+switch how the flags are converted to and from YAML based on the cpu.
+This works for both reading and writing. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">Info</span> <span class="p">{</span>
+ <span class="n">CPUs</span> <span class="n">cpu</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">flags</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Info</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Info</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"cpu"</span><span class="p">,</span> <span class="n">info</span><span class="p">.</span><span class="n">cpu</span><span class="p">);</span>
+ <span class="c1">// flags must come after cpu for this to work when reading yaml</span>
+ <span class="k">if</span> <span class="p">(</span> <span class="n">info</span><span class="p">.</span><span class="n">cpu</span> <span class="o">==</span> <span class="n">cpu_x86_64</span> <span class="p">)</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"flags"</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="n">My86_64Flags</span><span class="o">*</span><span class="p">)</span><span class="n">info</span><span class="p">.</span><span class="n">flags</span><span class="p">);</span>
+ <span class="k">else</span>
+ <span class="n">io</span><span class="p">.</span><span class="n">mapRequired</span><span class="p">(</span><span class="s">"flags"</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="n">My86Flags</span><span class="o">*</span><span class="p">)</span><span class="n">info</span><span class="p">.</span><span class="n">flags</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tags">
+<h3><a class="toc-backref" href="#id17">Tags</a><a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h3>
+<p>The YAML syntax supports tags as a way to specify the type of a node before
+it is parsed. This allows dynamic types of nodes. But the YAML I/O model uses
+static typing, so there are limits to how you can use tags with the YAML I/O
+model. Recently, we added support to YAML I/O for checking/setting the optional
+tag on a map. Using this functionality it is even possbile to support different
+mappings, as long as they are convertable.</p>
+<p>To check a tag, inside your mapping() method you can use io.mapTag() to specify
+what the tag should be. This will also add that tag when writing yaml.</p>
+</div>
+<div class="section" id="validation">
+<h3><a class="toc-backref" href="#id18">Validation</a><a class="headerlink" href="#validation" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes in a yaml map, each key/value pair is valid, but the combination is
+not. This is similar to something having no syntax errors, but still having
+semantic errors. To support semantic level checking, YAML I/O allows
+an optional <tt class="docutils literal"><span class="pre">validate()</span></tt> method in a MappingTraits template specialization.</p>
+<p>When parsing yaml, the <tt class="docutils literal"><span class="pre">validate()</span></tt> method is call <em>after</em> all key/values in
+the map have been processed. Any error message returned by the <tt class="docutils literal"><span class="pre">validate()</span></tt>
+method during input will be printed just a like a syntax error would be printed.
+When writing yaml, the <tt class="docutils literal"><span class="pre">validate()</span></tt> method is called <em>before</em> the yaml
+key/values are written. Any error during output will trigger an <tt class="docutils literal"><span class="pre">assert()</span></tt>
+because it is a programming error to have invalid struct values.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">Stuff</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Stuff</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Stuff</span> <span class="o">&</span><span class="n">stuff</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+ <span class="k">static</span> <span class="n">StringRef</span> <span class="n">validate</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Stuff</span> <span class="o">&</span><span class="n">stuff</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Look at all fields in 'stuff' and if there</span>
+ <span class="c1">// are any bad values return a string describing</span>
+ <span class="c1">// the error. Otherwise return an empty string.</span>
+ <span class="k">return</span> <span class="n">StringRef</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="flow-mapping">
+<h3><a class="toc-backref" href="#id19">Flow Mapping</a><a class="headerlink" href="#flow-mapping" title="Permalink to this headline">¶</a></h3>
+<p>A YAML “flow mapping” is a mapping that uses the inline notation
+(e.g { x: 1, y: 0 } ) when written to YAML. To specify that a type should be
+written in YAML using flow mapping, your MappingTraits specialization should
+add “static const bool flow = true;”. For instance:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">MappingTraits</span><span class="p">;</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">IO</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">Stuff</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">MappingTraits</span><span class="o"><</span><span class="n">Stuff</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">mapping</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">Stuff</span> <span class="o">&</span><span class="n">stuff</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+
+ <span class="k">static</span> <span class="k">const</span> <span class="kt">bool</span> <span class="n">flow</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Flow mappings are subject to line wrapping according to the Output object
+configuration.</p>
+</div>
+</div>
+<div class="section" id="sequence">
+<h2><a class="toc-backref" href="#id20">Sequence</a><a class="headerlink" href="#sequence" title="Permalink to this headline">¶</a></h2>
+<p>To be translated to or from a YAML sequence for your type T you must specialize
+llvm::yaml::SequenceTraits on T and implement two methods:
+<tt class="docutils literal"><span class="pre">size_t</span> <span class="pre">size(IO</span> <span class="pre">&io,</span> <span class="pre">T&)</span></tt> and
+<tt class="docutils literal"><span class="pre">T::value_type&</span> <span class="pre">element(IO</span> <span class="pre">&io,</span> <span class="pre">T&,</span> <span class="pre">size_t</span> <span class="pre">indx)</span></tt>. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">SequenceTraits</span><span class="o"><</span><span class="n">MySeq</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MySeq</span> <span class="o">&</span><span class="n">list</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="n">MySeqEl</span> <span class="o">&</span><span class="n">element</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MySeq</span> <span class="o">&</span><span class="n">list</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">index</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The size() method returns how many elements are currently in your sequence.
+The element() method returns a reference to the i’th element in the sequence.
+When parsing YAML, the element() method may be called with an index one bigger
+than the current size. Your element() method should allocate space for one
+more element (using default constructor if element is a C++ object) and returns
+a reference to that new allocated space.</p>
+<div class="section" id="flow-sequence">
+<h3><a class="toc-backref" href="#id21">Flow Sequence</a><a class="headerlink" href="#flow-sequence" title="Permalink to this headline">¶</a></h3>
+<p>A YAML “flow sequence” is a sequence that when written to YAML it uses the
+inline notation (e.g [ foo, bar ] ). To specify that a sequence type should
+be written in YAML as a flow sequence, your SequenceTraits specialization should
+add “static const bool flow = true;”. For instance:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">SequenceTraits</span><span class="o"><</span><span class="n">MyList</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyList</span> <span class="o">&</span><span class="n">list</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="n">MyListEl</span> <span class="o">&</span><span class="n">element</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyList</span> <span class="o">&</span><span class="n">list</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">index</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+
+ <span class="c1">// The existence of this member causes YAML I/O to use a flow sequence</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="kt">bool</span> <span class="n">flow</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>With the above, if you used MyList as the data type in your native data
+structures, then when converted to YAML, a flow sequence of integers
+will be used (e.g. [ 10, -3, 4 ]).</p>
+<p>Flow sequences are subject to line wrapping according to the Output object
+configuration.</p>
+</div>
+<div class="section" id="utility-macros">
+<h3><a class="toc-backref" href="#id22">Utility Macros</a><a class="headerlink" href="#utility-macros" title="Permalink to this headline">¶</a></h3>
+<p>Since a common source of sequences is std::vector<>, YAML I/O provides macros:
+LLVM_YAML_IS_SEQUENCE_VECTOR() and LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR() which
+can be used to easily specify SequenceTraits<> on a std::vector type. YAML
+I/O does not partial specialize SequenceTraits on std::vector<> because that
+would force all vectors to be sequences. An example use of the macros:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">MyType1</span><span class="o">></span><span class="p">;</span>
+<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">MyType2</span><span class="o">></span><span class="p">;</span>
+<span class="n">LLVM_YAML_IS_SEQUENCE_VECTOR</span><span class="p">(</span><span class="n">MyType1</span><span class="p">)</span>
+<span class="n">LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR</span><span class="p">(</span><span class="n">MyType2</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="document-list">
+<h2><a class="toc-backref" href="#id23">Document List</a><a class="headerlink" href="#document-list" title="Permalink to this headline">¶</a></h2>
+<p>YAML allows you to define multiple “documents” in a single YAML file. Each
+new document starts with a left aligned “—” token. The end of all documents
+is denoted with a left aligned ”...” token. Many users of YAML will never
+have need for multiple documents. The top level node in their YAML schema
+will be a mapping or sequence. For those cases, the following is not needed.
+But for cases where you do want multiple documents, you can specify a
+trait for you document list type. The trait has the same methods as
+SequenceTraits but is named DocumentListTraits. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><></span>
+<span class="k">struct</span> <span class="n">DocumentListTraits</span><span class="o"><</span><span class="n">MyDocList</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyDocList</span> <span class="o">&</span><span class="n">list</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="n">MyDocType</span> <span class="n">element</span><span class="p">(</span><span class="n">IO</span> <span class="o">&</span><span class="n">io</span><span class="p">,</span> <span class="n">MyDocList</span> <span class="o">&</span><span class="n">list</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">index</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="user-context-data">
+<h2><a class="toc-backref" href="#id24">User Context Data</a><a class="headerlink" href="#user-context-data" title="Permalink to this headline">¶</a></h2>
+<p>When an llvm::yaml::Input or llvm::yaml::Output object is created their
+constructors take an optional “context” parameter. This is a pointer to
+whatever state information you might need.</p>
+<p>For instance, in a previous example we showed how the conversion type for a
+flags field could be determined at runtime based on the value of another field
+in the mapping. But what if an inner mapping needs to know some field value
+of an outer mapping? That is where the “context” parameter comes in. You
+can set values in the context in the outer map’s mapping() method and
+retrieve those values in the inner map’s mapping() method.</p>
+<p>The context value is just a void*. All your traits which use the context
+and operate on your native data types, need to agree what the context value
+actually is. It could be a pointer to an object or struct which your various
+traits use to shared context sensitive information.</p>
+</div>
+<div class="section" id="output">
+<h2><a class="toc-backref" href="#id25">Output</a><a class="headerlink" href="#output" title="Permalink to this headline">¶</a></h2>
+<p>The llvm::yaml::Output class is used to generate a YAML document from your
+in-memory data structures, using traits defined on your data types.
+To instantiate an Output object you need an llvm::raw_ostream, an optional
+context pointer and an optional wrapping column:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Output</span> <span class="o">:</span> <span class="k">public</span> <span class="n">IO</span> <span class="p">{</span>
+<span class="nl">public:</span>
+ <span class="n">Output</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">context</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">,</span> <span class="kt">int</span> <span class="n">WrapColumn</span> <span class="o">=</span> <span class="mi">70</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Once you have an Output object, you can use the C++ stream operator on it
+to write your native data as YAML. One thing to recall is that a YAML file
+can contain multiple “documents”. If the top level data structure you are
+streaming as YAML is a mapping, scalar, or sequence, then Output assumes you
+are generating one document and wraps the mapping output
+with “<tt class="docutils literal"><span class="pre">---</span></tt>” and trailing “<tt class="docutils literal"><span class="pre">...</span></tt>”.</p>
+<p>The WrapColumn parameter will cause the flow mappings and sequences to
+line-wrap when they go over the supplied column. Pass 0 to completely
+suppress the wrapping.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Output</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">dumpMyMapDoc</span><span class="p">(</span><span class="k">const</span> <span class="n">MyMapType</span> <span class="o">&</span><span class="n">info</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Output</span> <span class="n">yout</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">outs</span><span class="p">());</span>
+ <span class="n">yout</span> <span class="o"><<</span> <span class="n">info</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The above could produce output like:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="nn">---</span>
+<span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+<span class="nn">...</span>
+</pre></div>
+</div>
+<p>On the other hand, if the top level data structure you are streaming as YAML
+has a DocumentListTraits specialization, then Output walks through each element
+of your DocumentList and generates a “—” before the start of each element
+and ends with a ”...”.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Output</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">dumpMyMapDoc</span><span class="p">(</span><span class="k">const</span> <span class="n">MyDocListType</span> <span class="o">&</span><span class="n">docList</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Output</span> <span class="n">yout</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">outs</span><span class="p">());</span>
+ <span class="n">yout</span> <span class="o"><<</span> <span class="n">docList</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The above could produce output like:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="nn">---</span>
+<span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">hat-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">7</span>
+<span class="nn">---</span>
+<span class="l-Scalar-Plain">name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Tom</span>
+<span class="l-Scalar-Plain">shoe-size</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">11</span>
+<span class="nn">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="input">
+<h2><a class="toc-backref" href="#id26">Input</a><a class="headerlink" href="#input" title="Permalink to this headline">¶</a></h2>
+<p>The llvm::yaml::Input class is used to parse YAML document(s) into your native
+data structures. To instantiate an Input
+object you need a StringRef to the entire YAML file, and optionally a context
+pointer:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Input</span> <span class="o">:</span> <span class="k">public</span> <span class="n">IO</span> <span class="p">{</span>
+<span class="nl">public:</span>
+ <span class="n">Input</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">inputContent</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">context</span><span class="o">=</span><span class="nb">NULL</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Once you have an Input object, you can use the C++ stream operator to read
+the document(s). If you expect there might be multiple YAML documents in
+one file, you’ll need to specialize DocumentListTraits on a list of your
+document type and stream in that document list type. Otherwise you can
+just stream in the document type. Also, you can check if there was
+any syntax errors in the YAML be calling the error() method on the Input
+object. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Reading a single document</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Input</span><span class="p">;</span>
+
+<span class="n">Input</span> <span class="nf">yin</span><span class="p">(</span><span class="n">mb</span><span class="p">.</span><span class="n">getBuffer</span><span class="p">());</span>
+
+<span class="c1">// Parse the YAML file</span>
+<span class="n">MyDocType</span> <span class="n">theDoc</span><span class="p">;</span>
+<span class="n">yin</span> <span class="o">>></span> <span class="n">theDoc</span><span class="p">;</span>
+
+<span class="c1">// Check for error</span>
+<span class="k">if</span> <span class="p">(</span> <span class="n">yin</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">)</span>
+ <span class="k">return</span><span class="p">;</span>
+</pre></div>
+</div>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Reading multiple documents in one file</span>
+<span class="k">using</span> <span class="n">llvm</span><span class="o">::</span><span class="n">yaml</span><span class="o">::</span><span class="n">Input</span><span class="p">;</span>
+
+<span class="n">LLVM_YAML_IS_DOCUMENT_LIST_VECTOR</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">MyDocType</span><span class="o">></span><span class="p">)</span>
+
+<span class="n">Input</span> <span class="n">yin</span><span class="p">(</span><span class="n">mb</span><span class="p">.</span><span class="n">getBuffer</span><span class="p">());</span>
+
+<span class="c1">// Parse the YAML file</span>
+<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">MyDocType</span><span class="o">></span> <span class="n">theDocList</span><span class="p">;</span>
+<span class="n">yin</span> <span class="o">>></span> <span class="n">theDocList</span><span class="p">;</span>
+
+<span class="c1">// Check for error</span>
+<span class="k">if</span> <span class="p">(</span> <span class="n">yin</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">)</span>
+ <span class="k">return</span><span class="p">;</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Passes.html" title="LLVMâs Analysis and Transform Passes"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-12-21.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.9.1/docs/_images/ARM-BE-bitcastfail.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/ARM-BE-bitcastfail.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/ARM-BE-bitcastfail.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/ARM-BE-bitcastsuccess.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/ARM-BE-bitcastsuccess.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/ARM-BE-bitcastsuccess.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/ARM-BE-ld1.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/ARM-BE-ld1.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/ARM-BE-ld1.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/ARM-BE-ldr.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/ARM-BE-ldr.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/ARM-BE-ldr.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/LangImpl05-cfg.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/LangImpl05-cfg.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/LangImpl05-cfg.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/LangImpl5-cfg.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/LangImpl5-cfg.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/LangImpl5-cfg.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/MCJIT-creation.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/MCJIT-creation.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/MCJIT-creation.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/MCJIT-dyld-load.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/MCJIT-dyld-load.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/MCJIT-dyld-load.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/MCJIT-engine-builder.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/MCJIT-engine-builder.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/MCJIT-engine-builder.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/MCJIT-load-object.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/MCJIT-load-object.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/MCJIT-load-object.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/MCJIT-load.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/MCJIT-load.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/MCJIT-load.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/MCJIT-resolve-relocations.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/MCJIT-resolve-relocations.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/MCJIT-resolve-relocations.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/gcc-loops.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/gcc-loops.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/gcc-loops.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_images/linpack-pc.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_images/linpack-pc.png?rev=290368&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.9.1/docs/_images/linpack-pc.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.9.1/docs/_sources/AMDGPUUsage.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_sources/AMDGPUUsage.txt?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/_sources/AMDGPUUsage.txt (added)
+++ www-releases/trunk/3.9.1/docs/_sources/AMDGPUUsage.txt Thu Dec 22 14:04:03 2016
@@ -0,0 +1,205 @@
+==============================
+User Guide for AMDGPU Back-end
+==============================
+
+Introduction
+============
+
+The AMDGPU back-end provides ISA code generation for AMD GPUs, starting with
+the R600 family up until the current Volcanic Islands (GCN Gen 3).
+
+
+Conventions
+===========
+
+Address Spaces
+--------------
+
+The AMDGPU back-end uses the following address space mapping:
+
+ ============= ============================================
+ Address Space Memory Space
+ ============= ============================================
+ 0 Private
+ 1 Global
+ 2 Constant
+ 3 Local
+ 4 Generic (Flat)
+ 5 Region
+ ============= ============================================
+
+The terminology in the table, aside from the region memory space, is from the
+OpenCL standard.
+
+
+Assembler
+=========
+
+The assembler is currently considered experimental.
+
+For syntax examples look in test/MC/AMDGPU.
+
+Below some of the currently supported features (modulo bugs). These
+all apply to the Southern Islands ISA, Sea Islands and Volcanic Islands
+are also supported but may be missing some instructions and have more bugs:
+
+DS Instructions
+---------------
+All DS instructions are supported.
+
+FLAT Instructions
+------------------
+These instructions are only present in the Sea Islands and Volcanic Islands
+instruction set. All FLAT instructions are supported for these architectures
+
+MUBUF Instructions
+------------------
+All non-atomic MUBUF instructions are supported.
+
+SMRD Instructions
+-----------------
+Only the s_load_dword* SMRD instructions are supported.
+
+SOP1 Instructions
+-----------------
+All SOP1 instructions are supported.
+
+SOP2 Instructions
+-----------------
+All SOP2 instructions are supported.
+
+SOPC Instructions
+-----------------
+All SOPC instructions are supported.
+
+SOPP Instructions
+-----------------
+
+Unless otherwise mentioned, all SOPP instructions that have one or more
+operands accept integer operands only. No verification is performed
+on the operands, so it is up to the programmer to be familiar with the
+range or acceptable values.
+
+s_waitcnt
+^^^^^^^^^
+
+s_waitcnt accepts named arguments to specify which memory counter(s) to
+wait for.
+
+.. code-block:: nasm
+
+ ; Wait for all counters to be 0
+ s_waitcnt 0
+
+ ; Equivalent to s_waitcnt 0. Counter names can also be delimited by
+ ; '&' or ','.
+ s_waitcnt vmcnt(0) expcnt(0) lgkcmt(0)
+
+ ; Wait for vmcnt counter to be 1.
+ s_waitcnt vmcnt(1)
+
+VOP1, VOP2, VOP3, VOPC Instructions
+-----------------------------------
+
+All 32-bit and 64-bit encodings should work.
+
+The assembler will automatically detect which encoding size to use for
+VOP1, VOP2, and VOPC instructions based on the operands. If you want to force
+a specific encoding size, you can add an _e32 (for 32-bit encoding) or
+_e64 (for 64-bit encoding) suffix to the instruction. Most, but not all
+instructions support an explicit suffix. These are all valid assembly
+strings:
+
+.. code-block:: nasm
+
+ v_mul_i32_i24 v1, v2, v3
+ v_mul_i32_i24_e32 v1, v2, v3
+ v_mul_i32_i24_e64 v1, v2, v3
+
+Assembler Directives
+--------------------
+
+.hsa_code_object_version major, minor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*major* and *minor* are integers that specify the version of the HSA code
+object that will be generated by the assembler. This value will be stored
+in an entry of the .note section.
+
+.hsa_code_object_isa [major, minor, stepping, vendor, arch]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*major*, *minor*, and *stepping* are all integers that describe the instruction
+set architecture (ISA) version of the assembly program.
+
+*vendor* and *arch* are quoted strings. *vendor* should always be equal to
+"AMD" and *arch* should always be equal to "AMDGPU".
+
+If no arguments are specified, then the assembler will derive the ISA version,
+*vendor*, and *arch* from the value of the -mcpu option that is passed to the
+assembler.
+
+ISA version, *vendor*, and *arch* will all be stored in a single entry of the
+.note section.
+
+.amd_kernel_code_t
+^^^^^^^^^^^^^^^^^^
+
+This directive marks the beginning of a list of key / value pairs that are used
+to specify the amd_kernel_code_t object that will be emitted by the assembler.
+The list must be terminated by the *.end_amd_kernel_code_t* directive. For
+any amd_kernel_code_t values that are unspecified a default value will be
+used. The default value for all keys is 0, with the following exceptions:
+
+- *kernel_code_version_major* defaults to 1.
+- *machine_kind* defaults to 1.
+- *machine_version_major*, *machine_version_minor*, and
+ *machine_version_stepping* are derived from the value of the -mcpu option
+ that is passed to the assembler.
+- *kernel_code_entry_byte_offset* defaults to 256.
+- *wavefront_size* defaults to 6.
+- *kernarg_segment_alignment*, *group_segment_alignment*, and
+ *private_segment_alignment* default to 4. Note that alignments are specified
+ as a power of two, so a value of **n** means an alignment of 2^ **n**.
+
+The *.amd_kernel_code_t* directive must be placed immediately after the
+function label and before any instructions.
+
+For a full list of amd_kernel_code_t keys, see the examples in
+test/CodeGen/AMDGPU/hsa.s. For an explanation of the meanings of the different
+keys, see the comments in lib/Target/AMDGPU/AmdKernelCodeT.h
+
+Here is an example of a minimal amd_kernel_code_t specification:
+
+.. code-block:: nasm
+
+ .hsa_code_object_version 1,0
+ .hsa_code_object_isa
+
+ .hsatext
+ .globl hello_world
+ .p2align 8
+ .amdgpu_hsa_kernel hello_world
+
+ hello_world:
+
+ .amd_kernel_code_t
+ enable_sgpr_kernarg_segment_ptr = 1
+ is_ptr64 = 1
+ compute_pgm_rsrc1_vgprs = 0
+ compute_pgm_rsrc1_sgprs = 0
+ compute_pgm_rsrc2_user_sgpr = 2
+ kernarg_segment_byte_size = 8
+ wavefront_sgpr_count = 2
+ workitem_vgpr_count = 3
+ .end_amd_kernel_code_t
+
+ s_load_dwordx2 s[0:1], s[0:1] 0x0
+ v_mov_b32 v0, 3.14159
+ s_waitcnt lgkmcnt(0)
+ v_mov_b32 v1, s0
+ v_mov_b32 v2, s1
+ flat_store_dword v[1:2], v0
+ s_endpgm
+ .Lfunc_end0:
+ .size hello_world, .Lfunc_end0-hello_world
Added: www-releases/trunk/3.9.1/docs/_sources/AdvancedBuilds.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_sources/AdvancedBuilds.txt?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/_sources/AdvancedBuilds.txt (added)
+++ www-releases/trunk/3.9.1/docs/_sources/AdvancedBuilds.txt Thu Dec 22 14:04:03 2016
@@ -0,0 +1,174 @@
+=============================
+Advanced Build Configurations
+=============================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+`CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
+does not build the project, it generates the files needed by your build tool
+(GNU make, Visual Studio, etc.) for building LLVM.
+
+If **you are a new contributor**, please start with the :doc:`GettingStarted` or
+:doc:`CMake` pages. This page is intended for users doing more complex builds.
+
+Many of the examples below are written assuming specific CMake Generators.
+Unless otherwise explicitly called out these commands should work with any CMake
+generator.
+
+Bootstrap Builds
+================
+
+The Clang CMake build system supports bootstrap (aka multi-stage) builds. At a
+high level a multi-stage build is a chain of builds that pass data from one
+stage into the next. The most common and simple version of this is a traditional
+bootstrap build.
+
+In a simple two-stage bootstrap build, we build clang using the system compiler,
+then use that just-built clang to build clang again. In CMake this simplest form
+of a bootstrap build can be configured with a single option,
+CLANG_ENABLE_BOOTSTRAP.
+
+.. code-block:: console
+
+ $ cmake -G Ninja -DCLANG_ENABLE_BOOTSTRAP=On <path to source>
+ $ ninja stage2
+
+This command itself isn't terribly useful because it assumes default
+configurations for each stage. The next series of examples utilize CMake cache
+scripts to provide more complex options.
+
+The clang build system refers to builds as stages. A stage1 build is a standard
+build using the compiler installed on the host, and a stage2 build is built
+using the stage1 compiler. This nomenclature holds up to more stages too. In
+general a stage*n* build is built using the output from stage*n-1*.
+
+Apple Clang Builds (A More Complex Bootstrap)
+=============================================
+
+Apple's Clang builds are a slightly more complicated example of the simple
+bootstrapping scenario. Apple Clang is built using a 2-stage build.
+
+The stage1 compiler is a host-only compiler with some options set. The stage1
+compiler is a balance of optimization vs build time because it is a throwaway.
+The stage2 compiler is the fully optimized compiler intended to ship to users.
+
+Setting up these compilers requires a lot of options. To simplify the
+configuration the Apple Clang build settings are contained in CMake Cache files.
+You can build an Apple Clang compiler using the following commands:
+
+.. code-block:: console
+
+ $ cmake -G Ninja -C <path to clang>/cmake/caches/Apple-stage1.cmake <path to source>
+ $ ninja stage2-distribution
+
+This CMake invocation configures the stage1 host compiler, and sets
+CLANG_BOOTSTRAP_CMAKE_ARGS to pass the Apple-stage2.cmake cache script to the
+stage2 configuration step.
+
+When you build the stage2-distribution target it builds the minimal stage1
+compiler and required tools, then configures and builds the stage2 compiler
+based on the settings in Apple-stage2.cmake.
+
+This pattern of using cache scripts to set complex settings, and specifically to
+make later stage builds include cache scripts is common in our more advanced
+build configurations.
+
+Multi-stage PGO
+===============
+
+Profile-Guided Optimizations (PGO) is a really great way to optimize the code
+clang generates. Our multi-stage PGO builds are a workflow for generating PGO
+profiles that can be used to optimize clang.
+
+At a high level, the way PGO works is that you build an instrumented compiler,
+then you run the instrumented compiler against sample source files. While the
+instrumented compiler runs it will output a bunch of files containing
+performance counters (.profraw files). After generating all the profraw files
+you use llvm-profdata to merge the files into a single profdata file that you
+can feed into the LLVM_PROFDATA_FILE option.
+
+Our PGO.cmake cache script automates that whole process. You can use it by
+running:
+
+.. code-block:: console
+
+ $ cmake -G Ninja -C <path_to_clang>/cmake/caches/PGO.cmake <source dir>
+ $ ninja stage2-instrumented-generate-profdata
+
+If you let that run for a few hours or so, it will place a profdata file in your
+build directory. This takes a really long time because it builds clang twice,
+and you *must* have compiler-rt in your build tree.
+
+This process uses any source files under the perf-training directory as training
+data as long as the source files are marked up with LIT-style RUN lines.
+
+After it finishes you can use âfind . -name clang.profdataâ to find it, but it
+should be at a path something like:
+
+.. code-block:: console
+
+ <build dir>/tools/clang/stage2-instrumented-bins/utils/perf-training/clang.profdata
+
+You can feed that file into the LLVM_PROFDATA_FILE option when you build your
+optimized compiler.
+
+The PGO came cache has a slightly different stage naming scheme than other
+multi-stage builds. It generates three stages; stage1, stage2-instrumented, and
+stage2. Both of the stage2 builds are built using the stage1 compiler.
+
+The PGO came cache generates the following additional targets:
+
+**stage2-instrumented**
+ Builds a stage1 x86 compiler, runtime, and required tools (llvm-config,
+ llvm-profdata) then uses that compiler to build an instrumented stage2 compiler.
+
+**stage2-instrumented-generate-profdata**
+ Depends on "stage2-instrumented" and will use the instrumented compiler to
+ generate profdata based on the training files in <clang>/utils/perf-training
+
+**stage2**
+ Depends of "stage2-instrumented-generate-profdata" and will use the stage1
+ compiler with the stage2 profdata to build a PGO-optimized compiler.
+
+**stage2-check-llvm**
+ Depends on stage2 and runs check-llvm using the stage2 compiler.
+
+**stage2-check-clang**
+ Depends on stage2 and runs check-clang using the stage2 compiler.
+
+**stage2-check-all**
+ Depends on stage2 and runs check-all using the stage2 compiler.
+
+**stage2-test-suite**
+ Depends on stage2 and runs the test-suite using the stage3 compiler (requires
+ in-tree test-suite).
+
+3-Stage Non-Determinism
+=======================
+
+In the ancient lore of compilers non-determinism is like the multi-headed hydra.
+Whenever it's head pops up, terror and chaos ensue.
+
+Historically one of the tests to verify that a compiler was deterministic would
+be a three stage build. The idea of a three stage build is you take your sources
+and build a compiler (stage1), then use that compiler to rebuild the sources
+(stage2), then you use that compiler to rebuild the sources a third time
+(stage3) with an identical configuration to the stage2 build. At the end of
+this, you have a stage2 and stage3 compiler that should be bit-for-bit
+identical.
+
+You can perform one of these 3-stage builds with LLVM & clang using the
+following commands:
+
+.. code-block:: console
+
+ $ cmake -G Ninja -C <path_to_clang>/cmake/caches/3-stage.cmake <source dir>
+ $ ninja stage3
+
+After the build you can compare the stage2 & stage3 compilers. We have a bot
+setup `here <http://lab.llvm.org:8011/builders/clang-3stage-ubuntu>`_ that runs
+this build and compare configuration.
Added: www-releases/trunk/3.9.1/docs/_sources/AliasAnalysis.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_sources/AliasAnalysis.txt?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/_sources/AliasAnalysis.txt (added)
+++ www-releases/trunk/3.9.1/docs/_sources/AliasAnalysis.txt Thu Dec 22 14:04:03 2016
@@ -0,0 +1,711 @@
+==================================
+LLVM Alias Analysis Infrastructure
+==================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Alias Analysis (aka Pointer Analysis) is a class of techniques which attempt to
+determine whether or not two pointers ever can point to the same object in
+memory. There are many different algorithms for alias analysis and many
+different ways of classifying them: flow-sensitive vs. flow-insensitive,
+context-sensitive vs. context-insensitive, field-sensitive
+vs. field-insensitive, unification-based vs. subset-based, etc. Traditionally,
+alias analyses respond to a query with a `Must, May, or No`_ alias response,
+indicating that two pointers always point to the same object, might point to the
+same object, or are known to never point to the same object.
+
+The LLVM `AliasAnalysis
+<http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__ class is the
+primary interface used by clients and implementations of alias analyses in the
+LLVM system. This class is the common interface between clients of alias
+analysis information and the implementations providing it, and is designed to
+support a wide range of implementations and clients (but currently all clients
+are assumed to be flow-insensitive). In addition to simple alias analysis
+information, this class exposes Mod/Ref information from those implementations
+which can provide it, allowing for powerful analyses and transformations to work
+well together.
+
+This document contains information necessary to successfully implement this
+interface, use it, and to test both sides. It also explains some of the finer
+points about what exactly results mean.
+
+``AliasAnalysis`` Class Overview
+================================
+
+The `AliasAnalysis <http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__
+class defines the interface that the various alias analysis implementations
+should support. This class exports two important enums: ``AliasResult`` and
+``ModRefResult`` which represent the result of an alias query or a mod/ref
+query, respectively.
+
+The ``AliasAnalysis`` interface exposes information about memory, represented in
+several different ways. In particular, memory objects are represented as a
+starting address and size, and function calls are represented as the actual
+``call`` or ``invoke`` instructions that performs the call. The
+``AliasAnalysis`` interface also exposes some helper methods which allow you to
+get mod/ref information for arbitrary instructions.
+
+All ``AliasAnalysis`` interfaces require that in queries involving multiple
+values, values which are not :ref:`constants <constants>` are all
+defined within the same function.
+
+Representation of Pointers
+--------------------------
+
+Most importantly, the ``AliasAnalysis`` class provides several methods which are
+used to query whether or not two memory objects alias, whether function calls
+can modify or read a memory object, etc. For all of these queries, memory
+objects are represented as a pair of their starting address (a symbolic LLVM
+``Value*``) and a static size.
+
+Representing memory objects as a starting address and a size is critically
+important for correct Alias Analyses. For example, consider this (silly, but
+possible) C code:
+
+.. code-block:: c++
+
+ int i;
+ char C[2];
+ char A[10];
+ /* ... */
+ for (i = 0; i != 10; ++i) {
+ C[0] = A[i]; /* One byte store */
+ C[1] = A[9-i]; /* One byte store */
+ }
+
+In this case, the ``basicaa`` pass will disambiguate the stores to ``C[0]`` and
+``C[1]`` because they are accesses to two distinct locations one byte apart, and
+the accesses are each one byte. In this case, the Loop Invariant Code Motion
+(LICM) pass can use store motion to remove the stores from the loop. In
+constrast, the following code:
+
+.. code-block:: c++
+
+ int i;
+ char C[2];
+ char A[10];
+ /* ... */
+ for (i = 0; i != 10; ++i) {
+ ((short*)C)[0] = A[i]; /* Two byte store! */
+ C[1] = A[9-i]; /* One byte store */
+ }
+
+In this case, the two stores to C do alias each other, because the access to the
+``&C[0]`` element is a two byte access. If size information wasn't available in
+the query, even the first case would have to conservatively assume that the
+accesses alias.
+
+.. _alias:
+
+The ``alias`` method
+--------------------
+
+The ``alias`` method is the primary interface used to determine whether or not
+two memory objects alias each other. It takes two memory objects as input and
+returns MustAlias, PartialAlias, MayAlias, or NoAlias as appropriate.
+
+Like all ``AliasAnalysis`` interfaces, the ``alias`` method requires that either
+the two pointer values be defined within the same function, or at least one of
+the values is a :ref:`constant <constants>`.
+
+.. _Must, May, or No:
+
+Must, May, and No Alias Responses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``NoAlias`` response may be used when there is never an immediate dependence
+between any memory reference *based* on one pointer and any memory reference
+*based* the other. The most obvious example is when the two pointers point to
+non-overlapping memory ranges. Another is when the two pointers are only ever
+used for reading memory. Another is when the memory is freed and reallocated
+between accesses through one pointer and accesses through the other --- in this
+case, there is a dependence, but it's mediated by the free and reallocation.
+
+As an exception to this is with the :ref:`noalias <noalias>` keyword;
+the "irrelevant" dependencies are ignored.
+
+The ``MayAlias`` response is used whenever the two pointers might refer to the
+same object.
+
+The ``PartialAlias`` response is used when the two memory objects are known to
+be overlapping in some way, but do not start at the same address.
+
+The ``MustAlias`` response may only be returned if the two memory objects are
+guaranteed to always start at exactly the same location. A ``MustAlias``
+response implies that the pointers compare equal.
+
+The ``getModRefInfo`` methods
+-----------------------------
+
+The ``getModRefInfo`` methods return information about whether the execution of
+an instruction can read or modify a memory location. Mod/Ref information is
+always conservative: if an instruction **might** read or write a location,
+``ModRef`` is returned.
+
+The ``AliasAnalysis`` class also provides a ``getModRefInfo`` method for testing
+dependencies between function calls. This method takes two call sites (``CS1``
+& ``CS2``), returns ``NoModRef`` if neither call writes to memory read or
+written by the other, ``Ref`` if ``CS1`` reads memory written by ``CS2``,
+``Mod`` if ``CS1`` writes to memory read or written by ``CS2``, or ``ModRef`` if
+``CS1`` might read or write memory written to by ``CS2``. Note that this
+relation is not commutative.
+
+Other useful ``AliasAnalysis`` methods
+--------------------------------------
+
+Several other tidbits of information are often collected by various alias
+analysis implementations and can be put to good use by various clients.
+
+The ``pointsToConstantMemory`` method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``pointsToConstantMemory`` method returns true if and only if the analysis
+can prove that the pointer only points to unchanging memory locations
+(functions, constant global variables, and the null pointer). This information
+can be used to refine mod/ref information: it is impossible for an unchanging
+memory location to be modified.
+
+.. _never access memory or only read memory:
+
+The ``doesNotAccessMemory`` and ``onlyReadsMemory`` methods
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These methods are used to provide very simple mod/ref information for function
+calls. The ``doesNotAccessMemory`` method returns true for a function if the
+analysis can prove that the function never reads or writes to memory, or if the
+function only reads from constant memory. Functions with this property are
+side-effect free and only depend on their input arguments, allowing them to be
+eliminated if they form common subexpressions or be hoisted out of loops. Many
+common functions behave this way (e.g., ``sin`` and ``cos``) but many others do
+not (e.g., ``acos``, which modifies the ``errno`` variable).
+
+The ``onlyReadsMemory`` method returns true for a function if analysis can prove
+that (at most) the function only reads from non-volatile memory. Functions with
+this property are side-effect free, only depending on their input arguments and
+the state of memory when they are called. This property allows calls to these
+functions to be eliminated and moved around, as long as there is no store
+instruction that changes the contents of memory. Note that all functions that
+satisfy the ``doesNotAccessMemory`` method also satisfy ``onlyReadsMemory``.
+
+Writing a new ``AliasAnalysis`` Implementation
+==============================================
+
+Writing a new alias analysis implementation for LLVM is quite straight-forward.
+There are already several implementations that you can use for examples, and the
+following information should help fill in any details. For a examples, take a
+look at the `various alias analysis implementations`_ included with LLVM.
+
+Different Pass styles
+---------------------
+
+The first step to determining what type of :doc:`LLVM pass <WritingAnLLVMPass>`
+you need to use for your Alias Analysis. As is the case with most other
+analyses and transformations, the answer should be fairly obvious from what type
+of problem you are trying to solve:
+
+#. If you require interprocedural analysis, it should be a ``Pass``.
+#. If you are a function-local analysis, subclass ``FunctionPass``.
+#. If you don't need to look at the program at all, subclass ``ImmutablePass``.
+
+In addition to the pass that you subclass, you should also inherit from the
+``AliasAnalysis`` interface, of course, and use the ``RegisterAnalysisGroup``
+template to register as an implementation of ``AliasAnalysis``.
+
+Required initialization calls
+-----------------------------
+
+Your subclass of ``AliasAnalysis`` is required to invoke two methods on the
+``AliasAnalysis`` base class: ``getAnalysisUsage`` and
+``InitializeAliasAnalysis``. In particular, your implementation of
+``getAnalysisUsage`` should explicitly call into the
+``AliasAnalysis::getAnalysisUsage`` method in addition to doing any declaring
+any pass dependencies your pass has. Thus you should have something like this:
+
+.. code-block:: c++
+
+ void getAnalysisUsage(AnalysisUsage &AU) const {
+ AliasAnalysis::getAnalysisUsage(AU);
+ // declare your dependencies here.
+ }
+
+Additionally, your must invoke the ``InitializeAliasAnalysis`` method from your
+analysis run method (``run`` for a ``Pass``, ``runOnFunction`` for a
+``FunctionPass``, or ``InitializePass`` for an ``ImmutablePass``). For example
+(as part of a ``Pass``):
+
+.. code-block:: c++
+
+ bool run(Module &M) {
+ InitializeAliasAnalysis(this);
+ // Perform analysis here...
+ return false;
+ }
+
+Required methods to override
+----------------------------
+
+You must override the ``getAdjustedAnalysisPointer`` method on all subclasses
+of ``AliasAnalysis``. An example implementation of this method would look like:
+
+.. code-block:: c++
+
+ void *getAdjustedAnalysisPointer(const void* ID) override {
+ if (ID == &AliasAnalysis::ID)
+ return (AliasAnalysis*)this;
+ return this;
+ }
+
+Interfaces which may be specified
+---------------------------------
+
+All of the `AliasAnalysis
+<http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__ virtual methods
+default to providing :ref:`chaining <aliasanalysis-chaining>` to another alias
+analysis implementation, which ends up returning conservatively correct
+information (returning "May" Alias and "Mod/Ref" for alias and mod/ref queries
+respectively). Depending on the capabilities of the analysis you are
+implementing, you just override the interfaces you can improve.
+
+.. _aliasanalysis-chaining:
+
+``AliasAnalysis`` chaining behavior
+-----------------------------------
+
+With only one special exception (the :ref:`-no-aa <aliasanalysis-no-aa>` pass)
+every alias analysis pass chains to another alias analysis implementation (for
+example, the user can specify "``-basicaa -ds-aa -licm``" to get the maximum
+benefit from both alias analyses). The alias analysis class automatically
+takes care of most of this for methods that you don't override. For methods
+that you do override, in code paths that return a conservative MayAlias or
+Mod/Ref result, simply return whatever the superclass computes. For example:
+
+.. code-block:: c++
+
+ AliasResult alias(const Value *V1, unsigned V1Size,
+ const Value *V2, unsigned V2Size) {
+ if (...)
+ return NoAlias;
+ ...
+
+ // Couldn't determine a must or no-alias result.
+ return AliasAnalysis::alias(V1, V1Size, V2, V2Size);
+ }
+
+In addition to analysis queries, you must make sure to unconditionally pass LLVM
+`update notification`_ methods to the superclass as well if you override them,
+which allows all alias analyses in a change to be updated.
+
+.. _update notification:
+
+Updating analysis results for transformations
+---------------------------------------------
+
+Alias analysis information is initially computed for a static snapshot of the
+program, but clients will use this information to make transformations to the
+code. All but the most trivial forms of alias analysis will need to have their
+analysis results updated to reflect the changes made by these transformations.
+
+The ``AliasAnalysis`` interface exposes four methods which are used to
+communicate program changes from the clients to the analysis implementations.
+Various alias analysis implementations should use these methods to ensure that
+their internal data structures are kept up-to-date as the program changes (for
+example, when an instruction is deleted), and clients of alias analysis must be
+sure to call these interfaces appropriately.
+
+The ``deleteValue`` method
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``deleteValue`` method is called by transformations when they remove an
+instruction or any other value from the program (including values that do not
+use pointers). Typically alias analyses keep data structures that have entries
+for each value in the program. When this method is called, they should remove
+any entries for the specified value, if they exist.
+
+The ``copyValue`` method
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``copyValue`` method is used when a new value is introduced into the
+program. There is no way to introduce a value into the program that did not
+exist before (this doesn't make sense for a safe compiler transformation), so
+this is the only way to introduce a new value. This method indicates that the
+new value has exactly the same properties as the value being copied.
+
+The ``replaceWithNewValue`` method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This method is a simple helper method that is provided to make clients easier to
+use. It is implemented by copying the old analysis information to the new
+value, then deleting the old value. This method cannot be overridden by alias
+analysis implementations.
+
+The ``addEscapingUse`` method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``addEscapingUse`` method is used when the uses of a pointer value have
+changed in ways that may invalidate precomputed analysis information.
+Implementations may either use this callback to provide conservative responses
+for points whose uses have change since analysis time, or may recompute some or
+all of their internal state to continue providing accurate responses.
+
+In general, any new use of a pointer value is considered an escaping use, and
+must be reported through this callback, *except* for the uses below:
+
+* A ``bitcast`` or ``getelementptr`` of the pointer
+* A ``store`` through the pointer (but not a ``store`` *of* the pointer)
+* A ``load`` through the pointer
+
+Efficiency Issues
+-----------------
+
+From the LLVM perspective, the only thing you need to do to provide an efficient
+alias analysis is to make sure that alias analysis **queries** are serviced
+quickly. The actual calculation of the alias analysis results (the "run"
+method) is only performed once, but many (perhaps duplicate) queries may be
+performed. Because of this, try to move as much computation to the run method
+as possible (within reason).
+
+Limitations
+-----------
+
+The AliasAnalysis infrastructure has several limitations which make writing a
+new ``AliasAnalysis`` implementation difficult.
+
+There is no way to override the default alias analysis. It would be very useful
+to be able to do something like "``opt -my-aa -O2``" and have it use ``-my-aa``
+for all passes which need AliasAnalysis, but there is currently no support for
+that, short of changing the source code and recompiling. Similarly, there is
+also no way of setting a chain of analyses as the default.
+
+There is no way for transform passes to declare that they preserve
+``AliasAnalysis`` implementations. The ``AliasAnalysis`` interface includes
+``deleteValue`` and ``copyValue`` methods which are intended to allow a pass to
+keep an AliasAnalysis consistent, however there's no way for a pass to declare
+in its ``getAnalysisUsage`` that it does so. Some passes attempt to use
+``AU.addPreserved<AliasAnalysis>``, however this doesn't actually have any
+effect.
+
+``AliasAnalysisCounter`` (``-count-aa``) are implemented as ``ModulePass``
+classes, so if your alias analysis uses ``FunctionPass``, it won't be able to
+use these utilities. If you try to use them, the pass manager will silently
+route alias analysis queries directly to ``BasicAliasAnalysis`` instead.
+
+Similarly, the ``opt -p`` option introduces ``ModulePass`` passes between each
+pass, which prevents the use of ``FunctionPass`` alias analysis passes.
+
+The ``AliasAnalysis`` API does have functions for notifying implementations when
+values are deleted or copied, however these aren't sufficient. There are many
+other ways that LLVM IR can be modified which could be relevant to
+``AliasAnalysis`` implementations which can not be expressed.
+
+The ``AliasAnalysisDebugger`` utility seems to suggest that ``AliasAnalysis``
+implementations can expect that they will be informed of any relevant ``Value``
+before it appears in an alias query. However, popular clients such as ``GVN``
+don't support this, and are known to trigger errors when run with the
+``AliasAnalysisDebugger``.
+
+Due to several of the above limitations, the most obvious use for the
+``AliasAnalysisCounter`` utility, collecting stats on all alias queries in a
+compilation, doesn't work, even if the ``AliasAnalysis`` implementations don't
+use ``FunctionPass``. There's no way to set a default, much less a default
+sequence, and there's no way to preserve it.
+
+The ``AliasSetTracker`` class (which is used by ``LICM``) makes a
+non-deterministic number of alias queries. This can cause stats collected by
+``AliasAnalysisCounter`` to have fluctuations among identical runs, for
+example. Another consequence is that debugging techniques involving pausing
+execution after a predetermined number of queries can be unreliable.
+
+Many alias queries can be reformulated in terms of other alias queries. When
+multiple ``AliasAnalysis`` queries are chained together, it would make sense to
+start those queries from the beginning of the chain, with care taken to avoid
+infinite looping, however currently an implementation which wants to do this can
+only start such queries from itself.
+
+Using alias analysis results
+============================
+
+There are several different ways to use alias analysis results. In order of
+preference, these are:
+
+Using the ``MemoryDependenceAnalysis`` Pass
+-------------------------------------------
+
+The ``memdep`` pass uses alias analysis to provide high-level dependence
+information about memory-using instructions. This will tell you which store
+feeds into a load, for example. It uses caching and other techniques to be
+efficient, and is used by Dead Store Elimination, GVN, and memcpy optimizations.
+
+.. _AliasSetTracker:
+
+Using the ``AliasSetTracker`` class
+-----------------------------------
+
+Many transformations need information about alias **sets** that are active in
+some scope, rather than information about pairwise aliasing. The
+`AliasSetTracker <http://llvm.org/doxygen/classllvm_1_1AliasSetTracker.html>`__
+class is used to efficiently build these Alias Sets from the pairwise alias
+analysis information provided by the ``AliasAnalysis`` interface.
+
+First you initialize the AliasSetTracker by using the "``add``" methods to add
+information about various potentially aliasing instructions in the scope you are
+interested in. Once all of the alias sets are completed, your pass should
+simply iterate through the constructed alias sets, using the ``AliasSetTracker``
+``begin()``/``end()`` methods.
+
+The ``AliasSet``\s formed by the ``AliasSetTracker`` are guaranteed to be
+disjoint, calculate mod/ref information and volatility for the set, and keep
+track of whether or not all of the pointers in the set are Must aliases. The
+AliasSetTracker also makes sure that sets are properly folded due to call
+instructions, and can provide a list of pointers in each set.
+
+As an example user of this, the `Loop Invariant Code Motion
+<doxygen/structLICM.html>`_ pass uses ``AliasSetTracker``\s to calculate alias
+sets for each loop nest. If an ``AliasSet`` in a loop is not modified, then all
+load instructions from that set may be hoisted out of the loop. If any alias
+sets are stored to **and** are must alias sets, then the stores may be sunk
+to outside of the loop, promoting the memory location to a register for the
+duration of the loop nest. Both of these transformations only apply if the
+pointer argument is loop-invariant.
+
+The AliasSetTracker implementation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The AliasSetTracker class is implemented to be as efficient as possible. It
+uses the union-find algorithm to efficiently merge AliasSets when a pointer is
+inserted into the AliasSetTracker that aliases multiple sets. The primary data
+structure is a hash table mapping pointers to the AliasSet they are in.
+
+The AliasSetTracker class must maintain a list of all of the LLVM ``Value*``\s
+that are in each AliasSet. Since the hash table already has entries for each
+LLVM ``Value*`` of interest, the AliasesSets thread the linked list through
+these hash-table nodes to avoid having to allocate memory unnecessarily, and to
+make merging alias sets extremely efficient (the linked list merge is constant
+time).
+
+You shouldn't need to understand these details if you are just a client of the
+AliasSetTracker, but if you look at the code, hopefully this brief description
+will help make sense of why things are designed the way they are.
+
+Using the ``AliasAnalysis`` interface directly
+----------------------------------------------
+
+If neither of these utility class are what your pass needs, you should use the
+interfaces exposed by the ``AliasAnalysis`` class directly. Try to use the
+higher-level methods when possible (e.g., use mod/ref information instead of the
+`alias`_ method directly if possible) to get the best precision and efficiency.
+
+Existing alias analysis implementations and clients
+===================================================
+
+If you're going to be working with the LLVM alias analysis infrastructure, you
+should know what clients and implementations of alias analysis are available.
+In particular, if you are implementing an alias analysis, you should be aware of
+the `the clients`_ that are useful for monitoring and evaluating different
+implementations.
+
+.. _various alias analysis implementations:
+
+Available ``AliasAnalysis`` implementations
+-------------------------------------------
+
+This section lists the various implementations of the ``AliasAnalysis``
+interface. With the exception of the :ref:`-no-aa <aliasanalysis-no-aa>`
+implementation, all of these :ref:`chain <aliasanalysis-chaining>` to other
+alias analysis implementations.
+
+.. _aliasanalysis-no-aa:
+
+The ``-no-aa`` pass
+^^^^^^^^^^^^^^^^^^^
+
+The ``-no-aa`` pass is just like what it sounds: an alias analysis that never
+returns any useful information. This pass can be useful if you think that alias
+analysis is doing something wrong and are trying to narrow down a problem.
+
+The ``-basicaa`` pass
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``-basicaa`` pass is an aggressive local analysis that *knows* many
+important facts:
+
+* Distinct globals, stack allocations, and heap allocations can never alias.
+* Globals, stack allocations, and heap allocations never alias the null pointer.
+* Different fields of a structure do not alias.
+* Indexes into arrays with statically differing subscripts cannot alias.
+* Many common standard C library functions `never access memory or only read
+ memory`_.
+* Pointers that obviously point to constant globals "``pointToConstantMemory``".
+* Function calls can not modify or references stack allocations if they never
+ escape from the function that allocates them (a common case for automatic
+ arrays).
+
+The ``-globalsmodref-aa`` pass
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This pass implements a simple context-sensitive mod/ref and alias analysis for
+internal global variables that don't "have their address taken". If a global
+does not have its address taken, the pass knows that no pointers alias the
+global. This pass also keeps track of functions that it knows never access
+memory or never read memory. This allows certain optimizations (e.g. GVN) to
+eliminate call instructions entirely.
+
+The real power of this pass is that it provides context-sensitive mod/ref
+information for call instructions. This allows the optimizer to know that calls
+to a function do not clobber or read the value of the global, allowing loads and
+stores to be eliminated.
+
+.. note::
+
+ This pass is somewhat limited in its scope (only support non-address taken
+ globals), but is very quick analysis.
+
+The ``-steens-aa`` pass
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``-steens-aa`` pass implements a variation on the well-known "Steensgaard's
+algorithm" for interprocedural alias analysis. Steensgaard's algorithm is a
+unification-based, flow-insensitive, context-insensitive, and field-insensitive
+alias analysis that is also very scalable (effectively linear time).
+
+The LLVM ``-steens-aa`` pass implements a "speculatively field-**sensitive**"
+version of Steensgaard's algorithm using the Data Structure Analysis framework.
+This gives it substantially more precision than the standard algorithm while
+maintaining excellent analysis scalability.
+
+.. note::
+
+ ``-steens-aa`` is available in the optional "poolalloc" module. It is not part
+ of the LLVM core.
+
+The ``-ds-aa`` pass
+^^^^^^^^^^^^^^^^^^^
+
+The ``-ds-aa`` pass implements the full Data Structure Analysis algorithm. Data
+Structure Analysis is a modular unification-based, flow-insensitive,
+context-**sensitive**, and speculatively field-**sensitive** alias
+analysis that is also quite scalable, usually at ``O(n * log(n))``.
+
+This algorithm is capable of responding to a full variety of alias analysis
+queries, and can provide context-sensitive mod/ref information as well. The
+only major facility not implemented so far is support for must-alias
+information.
+
+.. note::
+
+ ``-ds-aa`` is available in the optional "poolalloc" module. It is not part of
+ the LLVM core.
+
+The ``-scev-aa`` pass
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``-scev-aa`` pass implements AliasAnalysis queries by translating them into
+ScalarEvolution queries. This gives it a more complete understanding of
+``getelementptr`` instructions and loop induction variables than other alias
+analyses have.
+
+Alias analysis driven transformations
+-------------------------------------
+
+LLVM includes several alias-analysis driven transformations which can be used
+with any of the implementations above.
+
+The ``-adce`` pass
+^^^^^^^^^^^^^^^^^^
+
+The ``-adce`` pass, which implements Aggressive Dead Code Elimination uses the
+``AliasAnalysis`` interface to delete calls to functions that do not have
+side-effects and are not used.
+
+The ``-licm`` pass
+^^^^^^^^^^^^^^^^^^
+
+The ``-licm`` pass implements various Loop Invariant Code Motion related
+transformations. It uses the ``AliasAnalysis`` interface for several different
+transformations:
+
+* It uses mod/ref information to hoist or sink load instructions out of loops if
+ there are no instructions in the loop that modifies the memory loaded.
+
+* It uses mod/ref information to hoist function calls out of loops that do not
+ write to memory and are loop-invariant.
+
+* It uses alias information to promote memory objects that are loaded and stored
+ to in loops to live in a register instead. It can do this if there are no may
+ aliases to the loaded/stored memory location.
+
+The ``-argpromotion`` pass
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``-argpromotion`` pass promotes by-reference arguments to be passed in
+by-value instead. In particular, if pointer arguments are only loaded from it
+passes in the value loaded instead of the address to the function. This pass
+uses alias information to make sure that the value loaded from the argument
+pointer is not modified between the entry of the function and any load of the
+pointer.
+
+The ``-gvn``, ``-memcpyopt``, and ``-dse`` passes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These passes use AliasAnalysis information to reason about loads and stores.
+
+.. _the clients:
+
+Clients for debugging and evaluation of implementations
+-------------------------------------------------------
+
+These passes are useful for evaluating the various alias analysis
+implementations. You can use them with commands like:
+
+.. code-block:: bash
+
+ % opt -ds-aa -aa-eval foo.bc -disable-output -stats
+
+The ``-print-alias-sets`` pass
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``-print-alias-sets`` pass is exposed as part of the ``opt`` tool to print
+out the Alias Sets formed by the `AliasSetTracker`_ class. This is useful if
+you're using the ``AliasSetTracker`` class. To use it, use something like:
+
+.. code-block:: bash
+
+ % opt -ds-aa -print-alias-sets -disable-output
+
+The ``-count-aa`` pass
+^^^^^^^^^^^^^^^^^^^^^^
+
+The ``-count-aa`` pass is useful to see how many queries a particular pass is
+making and what responses are returned by the alias analysis. As an example:
+
+.. code-block:: bash
+
+ % opt -basicaa -count-aa -ds-aa -count-aa -licm
+
+will print out how many queries (and what responses are returned) by the
+``-licm`` pass (of the ``-ds-aa`` pass) and how many queries are made of the
+``-basicaa`` pass by the ``-ds-aa`` pass. This can be useful when debugging a
+transformation or an alias analysis implementation.
+
+The ``-aa-eval`` pass
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``-aa-eval`` pass simply iterates through all pairs of pointers in a
+function and asks an alias analysis whether or not the pointers alias. This
+gives an indication of the precision of the alias analysis. Statistics are
+printed indicating the percent of no/may/must aliases found (a more precise
+algorithm will have a lower number of may aliases).
+
+Memory Dependence Analysis
+==========================
+
+If you're just looking to be a client of alias analysis information, consider
+using the Memory Dependence Analysis interface instead. MemDep is a lazy,
+caching layer on top of alias analysis that is able to answer the question of
+what preceding memory operations a given instruction depends on, either at an
+intra- or inter-block level. Because of its laziness and caching policy, using
+MemDep can be a significant performance win over accessing alias analysis
+directly.
Added: www-releases/trunk/3.9.1/docs/_sources/Atomics.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.1/docs/_sources/Atomics.txt?rev=290368&view=auto
==============================================================================
--- www-releases/trunk/3.9.1/docs/_sources/Atomics.txt (added)
+++ www-releases/trunk/3.9.1/docs/_sources/Atomics.txt Thu Dec 22 14:04:03 2016
@@ -0,0 +1,605 @@
+==============================================
+LLVM Atomic Instructions and Concurrency Guide
+==============================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+LLVM supports instructions which are well-defined in the presence of threads and
+asynchronous signals.
+
+The atomic instructions are designed specifically to provide readable IR and
+optimized code generation for the following:
+
+* The C++11 ``<atomic>`` header. (`C++11 draft available here
+ <http://www.open-std.org/jtc1/sc22/wg21/>`_.) (`C11 draft available here
+ <http://www.open-std.org/jtc1/sc22/wg14/>`_.)
+
+* Proper semantics for Java-style memory, for both ``volatile`` and regular
+ shared variables. (`Java Specification
+ <http://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html>`_)
+
+* gcc-compatible ``__sync_*`` builtins. (`Description
+ <https://gcc.gnu.org/onlinedocs/gcc/_005f_005fsync-Builtins.html>`_)
+
+* Other scenarios with atomic semantics, including ``static`` variables with
+ non-trivial constructors in C++.
+
+Atomic and volatile in the IR are orthogonal; "volatile" is the C/C++ volatile,
+which ensures that every volatile load and store happens and is performed in the
+stated order. A couple examples: if a SequentiallyConsistent store is
+immediately followed by another SequentiallyConsistent store to the same
+address, the first store can be erased. This transformation is not allowed for a
+pair of volatile stores. On the other hand, a non-volatile non-atomic load can
+be moved across a volatile load freely, but not an Acquire load.
+
+This document is intended to provide a guide to anyone either writing a frontend
+for LLVM or working on optimization passes for LLVM with a guide for how to deal
+with instructions with special semantics in the presence of concurrency. This
+is not intended to be a precise guide to the semantics; the details can get
+extremely complicated and unreadable, and are not usually necessary.
+
+.. _Optimization outside atomic:
+
+Optimization outside atomic
+===========================
+
+The basic ``'load'`` and ``'store'`` allow a variety of optimizations, but can
+lead to undefined results in a concurrent environment; see `NotAtomic`_. This
+section specifically goes into the one optimizer restriction which applies in
+concurrent environments, which gets a bit more of an extended description
+because any optimization dealing with stores needs to be aware of it.
+
+From the optimizer's point of view, the rule is that if there are not any
+instructions with atomic ordering involved, concurrency does not matter, with
+one exception: if a variable might be visible to another thread or signal
+handler, a store cannot be inserted along a path where it might not execute
+otherwise. Take the following example:
+
+.. code-block:: c
+
+ /* C code, for readability; run through clang -O2 -S -emit-llvm to get
+ equivalent IR */
+ int x;
+ void f(int* a) {
+ for (int i = 0; i < 100; i++) {
+ if (a[i])
+ x += 1;
+ }
+ }
+
+The following is equivalent in non-concurrent situations:
+
+.. code-block:: c
+
+ int x;
+ void f(int* a) {
+ int xtemp = x;
+ for (int i = 0; i < 100; i++) {
+ if (a[i])
+ xtemp += 1;
+ }
+ x = xtemp;
+ }
+
+However, LLVM is not allowed to transform the former to the latter: it could
+indirectly introduce undefined behavior if another thread can access ``x`` at
+the same time. (This example is particularly of interest because before the
+concurrency model was implemented, LLVM would perform this transformation.)
+
+Note that speculative loads are allowed; a load which is part of a race returns
+``undef``, but does not have undefined behavior.
+
+Atomic instructions
+===================
+
+For cases where simple loads and stores are not sufficient, LLVM provides
+various atomic instructions. The exact guarantees provided depend on the
+ordering; see `Atomic orderings`_.
+
+``load atomic`` and ``store atomic`` provide the same basic functionality as
+non-atomic loads and stores, but provide additional guarantees in situations
+where threads and signals are involved.
+
+``cmpxchg`` and ``atomicrmw`` are essentially like an atomic load followed by an
+atomic store (where the store is conditional for ``cmpxchg``), but no other
+memory operation can happen on any thread between the load and store.
+
+A ``fence`` provides Acquire and/or Release ordering which is not part of
+another operation; it is normally used along with Monotonic memory operations.
+A Monotonic load followed by an Acquire fence is roughly equivalent to an
+Acquire load, and a Monotonic store following a Release fence is roughly
+equivalent to a Release store. SequentiallyConsistent fences behave as both
+an Acquire and a Release fence, and offer some additional complicated
+guarantees, see the C++11 standard for details.
+
+Frontends generating atomic instructions generally need to be aware of the
+target to some degree; atomic instructions are guaranteed to be lock-free, and
+therefore an instruction which is wider than the target natively supports can be
+impossible to generate.
+
+.. _Atomic orderings:
+
+Atomic orderings
+================
+
+In order to achieve a balance between performance and necessary guarantees,
+there are six levels of atomicity. They are listed in order of strength; each
+level includes all the guarantees of the previous level except for
+Acquire/Release. (See also `LangRef Ordering <LangRef.html#ordering>`_.)
+
+.. _NotAtomic:
+
+NotAtomic
+---------
+
+NotAtomic is the obvious, a load or store which is not atomic. (This isn't
+really a level of atomicity, but is listed here for comparison.) This is
+essentially a regular load or store. If there is a race on a given memory
+location, loads from that location return undef.
+
+Relevant standard
+ This is intended to match shared variables in C/C++, and to be used in any
+ other context where memory access is necessary, and a race is impossible. (The
+ precise definition is in `LangRef Memory Model <LangRef.html#memmodel>`_.)
+
+Notes for frontends
+ The rule is essentially that all memory accessed with basic loads and stores
+ by multiple threads should be protected by a lock or other synchronization;
+ otherwise, you are likely to run into undefined behavior. If your frontend is
+ for a "safe" language like Java, use Unordered to load and store any shared
+ variable. Note that NotAtomic volatile loads and stores are not properly
+ atomic; do not try to use them as a substitute. (Per the C/C++ standards,
+ volatile does provide some limited guarantees around asynchronous signals, but
+ atomics are generally a better solution.)
+
+Notes for optimizers
+ Introducing loads to shared variables along a codepath where they would not
+ otherwise exist is allowed; introducing stores to shared variables is not. See
+ `Optimization outside atomic`_.
+
+Notes for code generation
+ The one interesting restriction here is that it is not allowed to write to
+ bytes outside of the bytes relevant to a store. This is mostly relevant to
+ unaligned stores: it is not allowed in general to convert an unaligned store
+ into two aligned stores of the same width as the unaligned store. Backends are
+ also expected to generate an i8 store as an i8 store, and not an instruction
+ which writes to surrounding bytes. (If you are writing a backend for an
+ architecture which cannot satisfy these restrictions and cares about
+ concurrency, please send an email to llvm-dev.)
+
+Unordered
+---------
+
+Unordered is the lowest level of atomicity. It essentially guarantees that races
+produce somewhat sane results instead of having undefined behavior. It also
+guarantees the operation to be lock-free, so it does not depend on the data
+being part of a special atomic structure or depend on a separate per-process
+global lock. Note that code generation will fail for unsupported atomic
+operations; if you need such an operation, use explicit locking.
+
+Relevant standard
+ This is intended to match the Java memory model for shared variables.
+
+Notes for frontends
+ This cannot be used for synchronization, but is useful for Java and other
+ "safe" languages which need to guarantee that the generated code never
+ exhibits undefined behavior. Note that this guarantee is cheap on common
+ platforms for loads of a native width, but can be expensive or unavailable for
+ wider loads, like a 64-bit store on ARM. (A frontend for Java or other "safe"
+ languages would normally split a 64-bit store on ARM into two 32-bit unordered
+ stores.)
+
+Notes for optimizers
+ In terms of the optimizer, this prohibits any transformation that transforms a
+ single load into multiple loads, transforms a store into multiple stores,
+ narrows a store, or stores a value which would not be stored otherwise. Some
+ examples of unsafe optimizations are narrowing an assignment into a bitfield,
+ rematerializing a load, and turning loads and stores into a memcpy
+ call. Reordering unordered operations is safe, though, and optimizers should
+ take advantage of that because unordered operations are common in languages
+ that need them.
+
+Notes for code generation
+ These operations are required to be atomic in the sense that if you use
+ unordered loads and unordered stores, a load cannot see a value which was
+ never stored. A normal load or store instruction is usually sufficient, but
+ note that an unordered load or store cannot be split into multiple
+ instructions (or an instruction which does multiple memory operations, like
+ ``LDRD`` on ARM without LPAE, or not naturally-aligned ``LDRD`` on LPAE ARM).
+
+Monotonic
+---------
+
+Monotonic is the weakest level of atomicity that can be used in synchronization
+primitives, although it does not provide any general synchronization. It
+essentially guarantees that if you take all the operations affecting a specific
+address, a consistent ordering exists.
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_relaxed``; see those
+ standards for the exact definition.
+
+Notes for frontends
+ If you are writing a frontend which uses this directly, use with caution. The
+ guarantees in terms of synchronization are very weak, so make sure these are
+ only used in a pattern which you know is correct. Generally, these would
+ either be used for atomic operations which do not protect other memory (like
+ an atomic counter), or along with a ``fence``.
+
+Notes for optimizers
+ In terms of the optimizer, this can be treated as a read+write on the relevant
+ memory location (and alias analysis will take advantage of that). In addition,
+ it is legal to reorder non-atomic and Unordered loads around Monotonic
+ loads. CSE/DSE and a few other optimizations are allowed, but Monotonic
+ operations are unlikely to be used in ways which would make those
+ optimizations useful.
+
+Notes for code generation
+ Code generation is essentially the same as that for unordered for loads and
+ stores. No fences are required. ``cmpxchg`` and ``atomicrmw`` are required
+ to appear as a single operation.
+
+Acquire
+-------
+
+Acquire provides a barrier of the sort necessary to acquire a lock to access
+other memory with normal loads and stores.
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_acquire``. It should also be
+ used for C++11/C11 ``memory_order_consume``.
+
+Notes for frontends
+ If you are writing a frontend which uses this directly, use with caution.
+ Acquire only provides a semantic guarantee when paired with a Release
+ operation.
+
+Notes for optimizers
+ Optimizers not aware of atomics can treat this like a nothrow call. It is
+ also possible to move stores from before an Acquire load or read-modify-write
+ operation to after it, and move non-Acquire loads from before an Acquire
+ operation to after it.
+
+Notes for code generation
+ Architectures with weak memory ordering (essentially everything relevant today
+ except x86 and SPARC) require some sort of fence to maintain the Acquire
+ semantics. The precise fences required varies widely by architecture, but for
+ a simple implementation, most architectures provide a barrier which is strong
+ enough for everything (``dmb`` on ARM, ``sync`` on PowerPC, etc.). Putting
+ such a fence after the equivalent Monotonic operation is sufficient to
+ maintain Acquire semantics for a memory operation.
+
+Release
+-------
+
+Release is similar to Acquire, but with a barrier of the sort necessary to
+release a lock.
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_release``.
+
+Notes for frontends
+ If you are writing a frontend which uses this directly, use with caution.
+ Release only provides a semantic guarantee when paired with a Acquire
+ operation.
+
+Notes for optimizers
+ Optimizers not aware of atomics can treat this like a nothrow call. It is
+ also possible to move loads from after a Release store or read-modify-write
+ operation to before it, and move non-Release stores from after an Release
+ operation to before it.
+
+Notes for code generation
+ See the section on Acquire; a fence before the relevant operation is usually
+ sufficient for Release. Note that a store-store fence is not sufficient to
+ implement Release semantics; store-store fences are generally not exposed to
+ IR because they are extremely difficult to use correctly.
+
+AcquireRelease
+--------------
+
+AcquireRelease (``acq_rel`` in IR) provides both an Acquire and a Release
+barrier (for fences and operations which both read and write memory).
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_acq_rel``.
+
+Notes for frontends
+ If you are writing a frontend which uses this directly, use with caution.
+ Acquire only provides a semantic guarantee when paired with a Release
+ operation, and vice versa.
+
+Notes for optimizers
+ In general, optimizers should treat this like a nothrow call; the possible
+ optimizations are usually not interesting.
+
+Notes for code generation
+ This operation has Acquire and Release semantics; see the sections on Acquire
+ and Release.
+
+SequentiallyConsistent
+----------------------
+
+SequentiallyConsistent (``seq_cst`` in IR) provides Acquire semantics for loads
+and Release semantics for stores. Additionally, it guarantees that a total
+ordering exists between all SequentiallyConsistent operations.
+
+Relevant standard
+ This corresponds to the C++11/C11 ``memory_order_seq_cst``, Java volatile, and
+ the gcc-compatible ``__sync_*`` builtins which do not specify otherwise.
+
+Notes for frontends
+ If a frontend is exposing atomic operations, these are much easier to reason
+ about for the programmer than other kinds of operations, and using them is
+ generally a practical performance tradeoff.
+
+Notes for optimizers
+ Optimizers not aware of atomics can treat this like a nothrow call. For
+ SequentiallyConsistent loads and stores, the same reorderings are allowed as
+ for Acquire loads and Release stores, except that SequentiallyConsistent
+ operations may not be reordered.
+
+Notes for code generation
+ SequentiallyConsistent loads minimally require the same barriers as Acquire
+ operations and SequentiallyConsistent stores require Release
+ barriers. Additionally, the code generator must enforce ordering between
+ SequentiallyConsistent stores followed by SequentiallyConsistent loads. This
+ is usually done by emitting either a full fence before the loads or a full
+ fence after the stores; which is preferred varies by architecture.
+
+Atomics and IR optimization
+===========================
+
+Predicates for optimizer writers to query:
+
+* ``isSimple()``: A load or store which is not volatile or atomic. This is
+ what, for example, memcpyopt would check for operations it might transform.
+
+* ``isUnordered()``: A load or store which is not volatile and at most
+ Unordered. This would be checked, for example, by LICM before hoisting an
+ operation.
+
+* ``mayReadFromMemory()``/``mayWriteToMemory()``: Existing predicate, but note
+ that they return true for any operation which is volatile or at least
+ Monotonic.
+
+* ``isStrongerThan`` / ``isAtLeastOrStrongerThan``: These are predicates on
+ orderings. They can be useful for passes that are aware of atomics, for
+ example to do DSE across a single atomic access, but not across a
+ release-acquire pair (see MemoryDependencyAnalysis for an example of this)
+
+* Alias analysis: Note that AA will return ModRef for anything Acquire or
+ Release, and for the address accessed by any Monotonic operation.
+
+To support optimizing around atomic operations, make sure you are using the
+right predicates; everything should work if that is done. If your pass should
+optimize some atomic operations (Unordered operations in particular), make sure
+it doesn't replace an atomic load or store with a non-atomic operation.
+
+Some examples of how optimizations interact with various kinds of atomic
+operations:
+
+* ``memcpyopt``: An atomic operation cannot be optimized into part of a
+ memcpy/memset, including unordered loads/stores. It can pull operations
+ across some atomic operations.
+
+* LICM: Unordered loads/stores can be moved out of a loop. It just treats
+ monotonic operations like a read+write to a memory location, and anything
+ stricter than that like a nothrow call.
+
+* DSE: Unordered stores can be DSE'ed like normal stores. Monotonic stores can
+ be DSE'ed in some cases, but it's tricky to reason about, and not especially
+ important. It is possible in some case for DSE to operate across a stronger
+ atomic operation, but it is fairly tricky. DSE delegates this reasoning to
+ MemoryDependencyAnalysis (which is also used by other passes like GVN).
+
+* Folding a load: Any atomic load from a constant global can be constant-folded,
+ because it cannot be observed. Similar reasoning allows sroa with
+ atomic loads and stores.
+
+Atomics and Codegen
+===================
+
+Atomic operations are represented in the SelectionDAG with ``ATOMIC_*`` opcodes.
+On architectures which use barrier instructions for all atomic ordering (like
+ARM), appropriate fences can be emitted by the AtomicExpand Codegen pass if
+``setInsertFencesForAtomic()`` was used.
+
+The MachineMemOperand for all atomic operations is currently marked as volatile;
+this is not correct in the IR sense of volatile, but CodeGen handles anything
+marked volatile very conservatively. This should get fixed at some point.
+
+One very important property of the atomic operations is that if your backend
+supports any inline lock-free atomic operations of a given size, you should
+support *ALL* operations of that size in a lock-free manner.
+
+When the target implements atomic ``cmpxchg`` or LL/SC instructions (as most do)
+this is trivial: all the other operations can be implemented on top of those
+primitives. However, on many older CPUs (e.g. ARMv5, SparcV8, Intel 80386) there
+are atomic load and store instructions, but no ``cmpxchg`` or LL/SC. As it is
+invalid to implement ``atomic load`` using the native instruction, but
+``cmpxchg`` using a library call to a function that uses a mutex, ``atomic
+load`` must *also* expand to a library call on such architectures, so that it
+can remain atomic with regards to a simultaneous ``cmpxchg``, by using the same
+mutex.
+
+AtomicExpandPass can help with that: it will expand all atomic operations to the
+proper ``__atomic_*`` libcalls for any size above the maximum set by
+``setMaxAtomicSizeInBitsSupported`` (which defaults to 0).
+
+On x86, all atomic loads generate a ``MOV``. SequentiallyConsistent stores
+generate an ``XCHG``, other stores generate a ``MOV``. SequentiallyConsistent
+fences generate an ``MFENCE``, other fences do not cause any code to be
+generated. ``cmpxchg`` uses the ``LOCK CMPXCHG`` instruction. ``atomicrmw xchg``
+uses ``XCHG``, ``atomicrmw add`` and ``atomicrmw sub`` use ``XADD``, and all
+other ``atomicrmw`` operations generate a loop with ``LOCK CMPXCHG``. Depending
+on the users of the result, some ``atomicrmw`` operations can be translated into
+operations like ``LOCK AND``, but that does not work in general.
+
+On ARM (before v8), MIPS, and many other RISC architectures, Acquire, Release,
+and SequentiallyConsistent semantics require barrier instructions for every such
+operation. Loads and stores generate normal instructions. ``cmpxchg`` and
+``atomicrmw`` can be represented using a loop with LL/SC-style instructions
+which take some sort of exclusive lock on a cache line (``LDREX`` and ``STREX``
+on ARM, etc.).
+
+It is often easiest for backends to use AtomicExpandPass to lower some of the
+atomic constructs. Here are some lowerings it can do:
+
+* cmpxchg -> loop with load-linked/store-conditional
+ by overriding ``shouldExpandAtomicCmpXchgInIR()``, ``emitLoadLinked()``,
+ ``emitStoreConditional()``
+* large loads/stores -> ll-sc/cmpxchg
+ by overriding ``shouldExpandAtomicStoreInIR()``/``shouldExpandAtomicLoadInIR()``
+* strong atomic accesses -> monotonic accesses + fences by overriding
+ ``shouldInsertFencesForAtomic()``, ``emitLeadingFence()``, and
+ ``emitTrailingFence()``
+* atomic rmw -> loop with cmpxchg or load-linked/store-conditional
+ by overriding ``expandAtomicRMWInIR()``
+* expansion to __atomic_* libcalls for unsupported sizes.
+
+For an example of all of these, look at the ARM backend.
+
+Libcalls: __atomic_*
+====================
+
+There are two kinds of atomic library calls that are generated by LLVM. Please
+note that both sets of library functions somewhat confusingly share the names of
+builtin functions defined by clang. Despite this, the library functions are
+not directly related to the builtins: it is *not* the case that ``__atomic_*``
+builtins lower to ``__atomic_*`` library calls and ``__sync_*`` builtins lower
+to ``__sync_*`` library calls.
+
+The first set of library functions are named ``__atomic_*``. This set has been
+"standardized" by GCC, and is described below. (See also `GCC's documentation
+<https://gcc.gnu.org/wiki/Atomic/GCCMM/LIbrary>`_)
+
+LLVM's AtomicExpandPass will translate atomic operations on data sizes above
+``MaxAtomicSizeInBitsSupported`` into calls to these functions.
+
+There are four generic functions, which can be called with data of any size or
+alignment::
+
+ void __atomic_load(size_t size, void *ptr, void *ret, int ordering)
+ void __atomic_store(size_t size, void *ptr, void *val, int ordering)
+ void __atomic_exchange(size_t size, void *ptr, void *val, void *ret, int ordering)
+ bool __atomic_compare_exchange(size_t size, void *ptr, void *expected, void *desired, int success_order, int failure_order)
+
+There are also size-specialized versions of the above functions, which can only
+be used with *naturally-aligned* pointers of the appropriate size. In the
+signatures below, "N" is one of 1, 2, 4, 8, and 16, and "iN" is the appropriate
+integer type of that size; if no such integer type exists, the specialization
+cannot be used::
+
+ iN __atomic_load_N(iN *ptr, iN val, int ordering)
+ void __atomic_store_N(iN *ptr, iN val, int ordering)
+ iN __atomic_exchange_N(iN *ptr, iN val, int ordering)
+ bool __atomic_compare_exchange_N(iN *ptr, iN *expected, iN desired, int success_order, int failure_order)
+
+Finally there are some read-modify-write functions, which are only available in
+the size-specific variants (any other sizes use a ``__atomic_compare_exchange``
+loop)::
+
+ iN __atomic_fetch_add_N(iN *ptr, iN val, int ordering)
+ iN __atomic_fetch_sub_N(iN *ptr, iN val, int ordering)
+ iN __atomic_fetch_and_N(iN *ptr, iN val, int ordering)
+ iN __atomic_fetch_or_N(iN *ptr, iN val, int ordering)
+ iN __atomic_fetch_xor_N(iN *ptr, iN val, int ordering)
+ iN __atomic_fetch_nand_N(iN *ptr, iN val, int ordering)
+
+This set of library functions have some interesting implementation requirements
+to take note of:
+
+- They support all sizes and alignments -- including those which cannot be
+ implemented natively on any existing hardware. Therefore, they will certainly
+ use mutexes in for some sizes/alignments.
+
+- As a consequence, they cannot be shipped in a statically linked
+ compiler-support library, as they have state which must be shared amongst all
+ DSOs loaded in the program. They must be provided in a shared library used by
+ all objects.
+
+- The set of atomic sizes supported lock-free must be a superset of the sizes
+ any compiler can emit. That is: if a new compiler introduces support for
+ inline-lock-free atomics of size N, the ``__atomic_*`` functions must also have a
+ lock-free implementation for size N. This is a requirement so that code
+ produced by an old compiler (which will have called the ``__atomic_*`` function)
+ interoperates with code produced by the new compiler (which will use native
+ the atomic instruction).
+
+Note that it's possible to write an entirely target-independent implementation
+of these library functions by using the compiler atomic builtins themselves to
+implement the operations on naturally-aligned pointers of supported sizes, and a
+generic mutex implementation otherwise.
+
+Libcalls: __sync_*
+==================
+
+Some targets or OS/target combinations can support lock-free atomics, but for
+various reasons, it is not practical to emit the instructions inline.
+
+There's two typical examples of this.
+
+Some CPUs support multiple instruction sets which can be swiched back and forth
+on function-call boundaries. For example, MIPS supports the MIPS16 ISA, which
+has a smaller instruction encoding than the usual MIPS32 ISA. ARM, similarly,
+has the Thumb ISA. In MIPS16 and earlier versions of Thumb, the atomic
+instructions are not encodable. However, those instructions are available via a
+function call to a function with the longer encoding.
+
+Additionally, a few OS/target pairs provide kernel-supported lock-free
+atomics. ARM/Linux is an example of this: the kernel `provides
+<https://www.kernel.org/doc/Documentation/arm/kernel_user_helpers.txt>`_ a
+function which on older CPUs contains a "magically-restartable" atomic sequence
+(which looks atomic so long as there's only one CPU), and contains actual atomic
+instructions on newer multicore models. This sort of functionality can typically
+be provided on any architecture, if all CPUs which are missing atomic
+compare-and-swap support are uniprocessor (no SMP). This is almost always the
+case. The only common architecture without that property is SPARC -- SPARCV8 SMP
+systems were common, yet it doesn't support any sort of compare-and-swap
+operation.
+
+In either of these cases, the Target in LLVM can claim support for atomics of an
+appropriate size, and then implement some subset of the operations via libcalls
+to a ``__sync_*`` function. Such functions *must* not use locks in their
+implementation, because unlike the ``__atomic_*`` routines used by
+AtomicExpandPass, these may be mixed-and-matched with native instructions by the
+target lowering.
+
+Further, these routines do not need to be shared, as they are stateless. So,
+there is no issue with having multiple copies included in one binary. Thus,
+typically these routines are implemented by the statically-linked compiler
+runtime support library.
+
+LLVM will emit a call to an appropriate ``__sync_*`` routine if the target
+ISelLowering code has set the corresponding ``ATOMIC_CMPXCHG``, ``ATOMIC_SWAP``,
+or ``ATOMIC_LOAD_*`` operation to "Expand", and if it has opted-into the
+availability of those library functions via a call to ``initSyncLibcalls()``.
+
+The full set of functions that may be called by LLVM is (for ``N`` being 1, 2,
+4, 8, or 16)::
+
+ iN __sync_val_compare_and_swap_N(iN *ptr, iN expected, iN desired)
+ iN __sync_lock_test_and_set_N(iN *ptr, iN val)
+ iN __sync_fetch_and_add_N(iN *ptr, iN val)
+ iN __sync_fetch_and_sub_N(iN *ptr, iN val)
+ iN __sync_fetch_and_and_N(iN *ptr, iN val)
+ iN __sync_fetch_and_or_N(iN *ptr, iN val)
+ iN __sync_fetch_and_xor_N(iN *ptr, iN val)
+ iN __sync_fetch_and_nand_N(iN *ptr, iN val)
+ iN __sync_fetch_and_max_N(iN *ptr, iN val)
+ iN __sync_fetch_and_umax_N(iN *ptr, iN val)
+ iN __sync_fetch_and_min_N(iN *ptr, iN val)
+ iN __sync_fetch_and_umin_N(iN *ptr, iN val)
+
+This list doesn't include any function for atomic load or store; all known
+architectures support atomic loads and stores directly (possibly by emitting a
+fence on either side of a normal load or store.)
+
+There's also, somewhat separately, the possibility to lower ``ATOMIC_FENCE`` to
+``__sync_synchronize()``. This may happen or not happen independent of all the
+above, controlled purely by ``setOperationAction(ISD::ATOMIC_FENCE, ...)``.
More information about the llvm-commits
mailing list