[llvm-commits] CVS: llvm-www/releases/2.3/docs/AliasAnalysis.html BitCodeFormat.html Bugpoint.html CFEBuildInstrs.html CodeGenerator.html CodingStandards.html CommandLine.html CompilerDriver.html CompilerWriterInfo.html DeveloperPolicy.html ExceptionHandling.html ExtendingLLVM.html FAQ.html GCCFEBuildInstrs.html GarbageCollection.html GetElementPtr.html GettingStarted.html GettingStartedVS.html HowToReleaseLLVM.html HowToSubmitABug.html LangRef.html Lexicon.html LinkTimeOptimization.html Makefile MakefileGuide.html Passes.html ProgrammersManual.html Projects.html ReleaseNotes.html SourceLevelDebugging.html Stacker.html SystemLibrary.html TableGenFundamentals.html TestingGuide.html UsingLibraries.html WritingAnLLVMBackend.html WritingAnLLVMPass.html doxygen.cfg doxygen.cfg.in doxygen.css doxygen.footer doxygen.header doxygen.intro index.html llvm.css
Tanya Lattner
tonic at nondot.org
Mon Jun 9 01:21:48 PDT 2008
Changes in directory llvm-www/releases/2.3/docs:
AliasAnalysis.html added (r1.1)
BitCodeFormat.html added (r1.1)
Bugpoint.html added (r1.1)
CFEBuildInstrs.html added (r1.1)
CodeGenerator.html added (r1.1)
CodingStandards.html added (r1.1)
CommandLine.html added (r1.1)
CompilerDriver.html added (r1.1)
CompilerWriterInfo.html added (r1.1)
DeveloperPolicy.html added (r1.1)
ExceptionHandling.html added (r1.1)
ExtendingLLVM.html added (r1.1)
FAQ.html added (r1.1)
GCCFEBuildInstrs.html added (r1.1)
GarbageCollection.html added (r1.1)
GetElementPtr.html added (r1.1)
GettingStarted.html added (r1.1)
GettingStartedVS.html added (r1.1)
HowToReleaseLLVM.html added (r1.1)
HowToSubmitABug.html added (r1.1)
LangRef.html added (r1.1)
Lexicon.html added (r1.1)
LinkTimeOptimization.html added (r1.1)
Makefile added (r1.1)
MakefileGuide.html added (r1.1)
Passes.html added (r1.1)
ProgrammersManual.html added (r1.1)
Projects.html added (r1.1)
ReleaseNotes.html added (r1.1)
SourceLevelDebugging.html added (r1.1)
Stacker.html added (r1.1)
SystemLibrary.html added (r1.1)
TableGenFundamentals.html added (r1.1)
TestingGuide.html added (r1.1)
UsingLibraries.html added (r1.1)
WritingAnLLVMBackend.html added (r1.1)
WritingAnLLVMPass.html added (r1.1)
doxygen.cfg added (r1.1)
doxygen.cfg.in added (r1.1)
doxygen.css added (r1.1)
doxygen.footer added (r1.1)
doxygen.header added (r1.1)
doxygen.intro added (r1.1)
index.html added (r1.1)
llvm.css added (r1.1)
---
Log message:
Adding 2.3 release
---
Diffs of the changes: (+39509 -0)
AliasAnalysis.html | 984 +++++++
BitCodeFormat.html | 653 +++++
Bugpoint.html | 244 +
CFEBuildInstrs.html | 29
CodeGenerator.html | 2006 ++++++++++++++++
CodingStandards.html | 767 ++++++
CommandLine.html | 1970 +++++++++++++++
CompilerDriver.html | 420 +++
CompilerWriterInfo.html | 261 ++
DeveloperPolicy.html | 555 ++++
ExceptionHandling.html | 478 +++
ExtendingLLVM.html | 391 +++
FAQ.html | 737 +++++
GCCFEBuildInstrs.html | 284 ++
GarbageCollection.html | 1419 +++++++++++
GetElementPtr.html | 370 ++
GettingStarted.html | 1649 +++++++++++++
GettingStartedVS.html | 380 +++
HowToReleaseLLVM.html | 608 ++++
HowToSubmitABug.html | 355 ++
LangRef.html | 5745 ++++++++++++++++++++++++++++++++++++++++++++++
Lexicon.html | 254 ++
LinkTimeOptimization.html | 356 ++
Makefile | 125 +
MakefileGuide.html | 1041 ++++++++
Passes.html | 1952 +++++++++++++++
ProgrammersManual.html | 3195 +++++++++++++++++++++++++
Projects.html | 460 +++
ReleaseNotes.html | 842 ++++++
SourceLevelDebugging.html | 1785 ++++++++++++++
Stacker.html | 1428 +++++++++++
SystemLibrary.html | 344 ++
TableGenFundamentals.html | 753 ++++++
TestingGuide.html | 894 +++++++
UsingLibraries.html | 449 +++
WritingAnLLVMBackend.html | 260 ++
WritingAnLLVMPass.html | 1825 ++++++++++++++
doxygen.cfg | 1230 +++++++++
doxygen.cfg.in | 1230 +++++++++
doxygen.css | 378 +++
doxygen.footer | 13
doxygen.header | 9
doxygen.intro | 18
index.html | 279 ++
llvm.css | 84
45 files changed, 39509 insertions(+)
Index: llvm-www/releases/2.3/docs/AliasAnalysis.html
diff -c /dev/null llvm-www/releases/2.3/docs/AliasAnalysis.html:1.1
*** /dev/null Mon Jun 9 03:20:42 2008
--- llvm-www/releases/2.3/docs/AliasAnalysis.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,984 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>LLVM Alias Analysis Infrastructure</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">
+ LLVM Alias Analysis Infrastructure
+ </div>
+
+ <ol>
+ <li><a href="#introduction">Introduction</a></li>
+
+ <li><a href="#overview"><tt>AliasAnalysis</tt> Class Overview</a>
+ <ul>
+ <li><a href="#pointers">Representation of Pointers</a></li>
+ <li><a href="#alias">The <tt>alias</tt> method</a></li>
+ <li><a href="#ModRefInfo">The <tt>getModRefInfo</tt> methods</a></li>
+ <li><a href="#OtherItfs">Other useful <tt>AliasAnalysis</tt> methods</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#writingnew">Writing a new <tt>AliasAnalysis</tt> Implementation</a>
+ <ul>
+ <li><a href="#passsubclasses">Different Pass styles</a></li>
+ <li><a href="#requiredcalls">Required initialization calls</a></li>
+ <li><a href="#interfaces">Interfaces which may be specified</a></li>
+ <li><a href="#chaining"><tt>AliasAnalysis</tt> chaining behavior</a></li>
+ <li><a href="#updating">Updating analysis results for transformations</a></li>
+ <li><a href="#implefficiency">Efficiency Issues</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#using">Using alias analysis results</a>
+ <ul>
+ <li><a href="#loadvn">Using the <tt>-load-vn</tt> Pass</a></li>
+ <li><a href="#ast">Using the <tt>AliasSetTracker</tt> class</a></li>
+ <li><a href="#direct">Using the <tt>AliasAnalysis</tt> interface directly</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#exist">Existing alias analysis implementations and clients</a>
+ <ul>
+ <li><a href="#impls">Available <tt>AliasAnalysis</tt> implementations</a></li>
+ <li><a href="#aliasanalysis-xforms">Alias analysis driven transformations</a></li>
+ <li><a href="#aliasanalysis-debug">Clients for debugging and evaluation of
+ implementations</a></li>
+ </ul>
+ </li>
+ <li><a href="#memdep">Memory Dependence Analysis</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>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 <a href="#MustMayNo">Must, May, or No</a> 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.</p>
+
+ <p>The LLVM <a
+ href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html"><tt>AliasAnalysis</tt></a>
+ 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.</p>
+
+ <p>This document contains information necessary to successfully implement this
+ interface, use it, and to test both sides. It also explains some of the finer
+ points about what exactly results mean. If you feel that something is unclear
+ or should be added, please <a href="mailto:sabre at nondot.org">let me
+ know</a>.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="overview"><tt>AliasAnalysis</tt> Class Overview</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The <a
+ href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html"><tt>AliasAnalysis</tt></a>
+ class defines the interface that the various alias analysis implementations
+ should support. This class exports two important enums: <tt>AliasResult</tt>
+ and <tt>ModRefResult</tt> which represent the result of an alias query or a
+ mod/ref query, respectively.</p>
+
+ <p>The <tt>AliasAnalysis</tt> 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 <tt>call</tt> or <tt>invoke</tt> instructions that performs the
+ call. The <tt>AliasAnalysis</tt> interface also exposes some helper methods
+ which allow you to get mod/ref information for arbitrary instructions.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="pointers">Representation of Pointers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Most importantly, the <tt>AliasAnalysis</tt> 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 <tt>Value*</tt>) and a static size.</p>
+
+ <p>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:</p>
+
+ <div class="doc_code">
+ <pre>
+ 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 */
+ }
+ </pre>
+ </div>
+
+ <p>In this case, the <tt>basicaa</tt> pass will disambiguate the stores to
+ <tt>C[0]</tt> and <tt>C[1]</tt> because they are accesses to two distinct
+ locations one byte apart, and the accesses are each one byte. In this case, the
+ LICM pass can use store motion to remove the stores from the loop. In
+ constrast, the following code:</p>
+
+ <div class="doc_code">
+ <pre>
+ 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 */
+ }
+ </pre>
+ </div>
+
+ <p>In this case, the two stores to C do alias each other, because the access to
+ the <tt>&C[0]</tt> 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.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="alias">The <tt>alias</tt> method</a>
+ </div>
+
+ <div class="doc_text">
+ The <tt>alias</tt> 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, MayAlias, or NoAlias as appropriate.
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="MustMayNo">Must, May, and No Alias Responses</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>An Alias Analysis implementation can return one of three responses:
+ MustAlias, MayAlias, and NoAlias. The No and May alias results are obvious: if
+ the two pointers can never equal each other, return NoAlias, if they might,
+ return MayAlias.</p>
+
+ <p>The MustAlias response is trickier though. In LLVM, the Must Alias response
+ may only be returned if the two memory objects are guaranteed to always start at
+ exactly the same location. If two memory objects overlap, but do not start at
+ the same location, return MayAlias.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="ModRefInfo">The <tt>getModRefInfo</tt> methods</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>getModRefInfo</tt> 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 <b>might</b> read or write
+ a location, ModRef is returned.</p>
+
+ <p>The <tt>AliasAnalysis</tt> class also provides a <tt>getModRefInfo</tt>
+ method for testing dependencies between function calls. This method takes two
+ call sites (CS1 & CS2), returns NoModRef if the two calls refer to disjoint
+ memory locations, 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
+ accessed by CS2. Note that this relation is not commutative. Clients that use
+ this method should be predicated on the <tt>hasNoModRefInfoForCalls()</tt>
+ method, which indicates whether or not an analysis can provide mod/ref
+ information for function call pairs (most can not). If this predicate is false,
+ the client shouldn't waste analysis time querying the <tt>getModRefInfo</tt>
+ method many times.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="OtherItfs">Other useful <tt>AliasAnalysis</tt> methods</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ Several other tidbits of information are often collected by various alias
+ analysis implementations and can be put to good use by various clients.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ The <tt>getMustAliases</tt> method
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>getMustAliases</tt> method returns all values that are known to
+ always must alias a pointer. This information can be provided in some cases for
+ important objects like the null pointer and global values. Knowing that a
+ pointer always points to a particular function allows indirect calls to be
+ turned into direct calls, for example.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ The <tt>pointsToConstantMemory</tt> method
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>pointsToConstantMemory</tt> 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.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="simplemodref">The <tt>doesNotAccessMemory</tt> and
+ <tt>onlyReadsMemory</tt> methods</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>These methods are used to provide very simple mod/ref information for
+ function calls. The <tt>doesNotAccessMemory</tt> 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., <tt>sin</tt> and
+ <tt>cos</tt>) but many others do not (e.g., <tt>acos</tt>, which modifies the
+ <tt>errno</tt> variable).</p>
+
+ <p>The <tt>onlyReadsMemory</tt> 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 <tt>doesNotAccessMemory</tt> method also satisfies
+ <tt>onlyReadsMemory</tt>.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="writingnew">Writing a new <tt>AliasAnalysis</tt> Implementation</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>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 <a href="#impls">various alias analysis
+ implementations</a> included with LLVM.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="passsubclasses">Different Pass styles</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The first step to determining what type of <a
+ href="WritingAnLLVMPass.html">LLVM pass</a> 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:</p>
+
+ <ol>
+ <li>If you require interprocedural analysis, it should be a
+ <tt>Pass</tt>.</li>
+ <li>If you are a function-local analysis, subclass <tt>FunctionPass</tt>.</li>
+ <li>If you don't need to look at the program at all, subclass
+ <tt>ImmutablePass</tt>.</li>
+ </ol>
+
+ <p>In addition to the pass that you subclass, you should also inherit from the
+ <tt>AliasAnalysis</tt> interface, of course, and use the
+ <tt>RegisterAnalysisGroup</tt> template to register as an implementation of
+ <tt>AliasAnalysis</tt>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="requiredcalls">Required initialization calls</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Your subclass of <tt>AliasAnalysis</tt> is required to invoke two methods on
+ the <tt>AliasAnalysis</tt> base class: <tt>getAnalysisUsage</tt> and
+ <tt>InitializeAliasAnalysis</tt>. In particular, your implementation of
+ <tt>getAnalysisUsage</tt> should explicitly call into the
+ <tt>AliasAnalysis::getAnalysisUsage</tt> method in addition to doing any
+ declaring any pass dependencies your pass has. Thus you should have something
+ like this:</p>
+
+ <div class="doc_code">
+ <pre>
+ void getAnalysisUsage(AnalysisUsage &AU) const {
+ AliasAnalysis::getAnalysisUsage(AU);
+ <i>// declare your dependencies here.</i>
+ }
+ </pre>
+ </div>
+
+ <p>Additionally, your must invoke the <tt>InitializeAliasAnalysis</tt> method
+ from your analysis run method (<tt>run</tt> for a <tt>Pass</tt>,
+ <tt>runOnFunction</tt> for a <tt>FunctionPass</tt>, or <tt>InitializePass</tt>
+ for an <tt>ImmutablePass</tt>). For example (as part of a <tt>Pass</tt>):</p>
+
+ <div class="doc_code">
+ <pre>
+ bool run(Module &M) {
+ InitializeAliasAnalysis(this);
+ <i>// Perform analysis here...</i>
+ return false;
+ }
+ </pre>
+ </div>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="interfaces">Interfaces which may be specified</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>All of the <a
+ href="/doxygen/classllvm_1_1AliasAnalysis.html"><tt>AliasAnalysis</tt></a>
+ virtual methods default to providing <a href="#chaining">chaining</a> 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.</p>
+
+ </div>
+
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="chaining"><tt>AliasAnalysis</tt> chaining behavior</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>With only two special exceptions (the <tt><a
+ href="#basic-aa">basicaa</a></tt> and <a href="#no-aa"><tt>no-aa</tt></a>
+ passes) every alias analysis pass chains to another alias analysis
+ implementation (for example, the user can specify "<tt>-basicaa -ds-aa
+ -anders-aa -licm</tt>" to get the maximum benefit from the three 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:</p>
+
+ <div class="doc_code">
+ <pre>
+ AliasAnalysis::AliasResult alias(const Value *V1, unsigned V1Size,
+ const Value *V2, unsigned V2Size) {
+ if (...)
+ return NoAlias;
+ ...
+
+ <i>// Couldn't determine a must or no-alias result.</i>
+ return AliasAnalysis::alias(V1, V1Size, V2, V2Size);
+ }
+ </pre>
+ </div>
+
+ <p>In addition to analysis queries, you must make sure to unconditionally pass
+ LLVM <a href="#updating">update notification</a> methods to the superclass as
+ well if you override them, which allows all alias analyses in a change to be
+ updated.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="updating">Updating analysis results for transformations</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ 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.
+ </p>
+
+ <p>
+ The <tt>AliasAnalysis</tt> interface exposes two 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.
+ </p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">The <tt>deleteValue</tt> method</div>
+
+ <div class="doc_text">
+ The <tt>deleteValue</tt> 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.
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">The <tt>copyValue</tt> method</div>
+
+ <div class="doc_text">
+ The <tt>copyValue</tt> 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.
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">The <tt>replaceWithNewValue</tt> method</div>
+
+ <div class="doc_text">
+ 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.
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="implefficiency">Efficiency Issues</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>From the LLVM perspective, the only thing you need to do to provide an
+ efficient alias analysis is to make sure that alias analysis <b>queries</b> 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).</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="using">Using alias analysis results</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>There are several different ways to use alias analysis results. In order of
+ preference, these are...</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="loadvn">Using the <tt>-load-vn</tt> Pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>load-vn</tt> pass uses alias analysis to provide value numbering
+ information for <tt>load</tt> instructions and pointer values. If your analysis
+ or transformation can be modeled in a form that uses value numbering
+ information, you don't have to do anything special to handle load instructions:
+ just use the <tt>load-vn</tt> pass, which uses alias analysis.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="ast">Using the <tt>AliasSetTracker</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Many transformations need information about alias <b>sets</b> that are active
+ in some scope, rather than information about pairwise aliasing. The <tt><a
+ href="/doxygen/classllvm_1_1AliasSetTracker.html">AliasSetTracker</a></tt> class
+ is used to efficiently build these Alias Sets from the pairwise alias analysis
+ information provided by the <tt>AliasAnalysis</tt> interface.</p>
+
+ <p>First you initialize the AliasSetTracker by using the "<tt>add</tt>" 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
+ <tt>AliasSetTracker</tt> <tt>begin()</tt>/<tt>end()</tt> methods.</p>
+
+ <p>The <tt>AliasSet</tt>s formed by the <tt>AliasSetTracker</tt> 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.</p>
+
+ <p>As an example user of this, the <a href="/doxygen/structLICM.html">Loop
+ Invariant Code Motion</a> pass uses <tt>AliasSetTracker</tt>s to calculate alias
+ sets for each loop nest. If an <tt>AliasSet</tt> 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 <b>and</b> 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.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ The AliasSetTracker implementation
+ </div>
+
+ <div class="doc_text">
+
+ <p>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.</p>
+
+ <p>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).
+ </p>
+
+ <p>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.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="direct">Using the <tt>AliasAnalysis</tt> interface directly</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If neither of these utility class are what your pass needs, you should use
+ the interfaces exposed by the <tt>AliasAnalysis</tt> class directly. Try to use
+ the higher-level methods when possible (e.g., use mod/ref information instead of
+ the <a href="#alias"><tt>alias</tt></a> method directly if possible) to get the
+ best precision and efficiency.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="exist">Existing alias analysis implementations and clients</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>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 <a href="#aliasanalysis-debug">the clients</a> that are useful
+ for monitoring and evaluating different implementations.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="impls">Available <tt>AliasAnalysis</tt> implementations</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>This section lists the various implementations of the <tt>AliasAnalysis</tt>
+ interface. With the exception of the <a href="#no-aa"><tt>-no-aa</tt></a> and
+ <a href="#basic-aa"><tt>-basicaa</tt></a> implementations, all of these <a
+ href="#chaining">chain</a> to other alias analysis implementations.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="no-aa">The <tt>-no-aa</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-no-aa</tt> 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.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="basic-aa">The <tt>-basicaa</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-basicaa</tt> pass is the default LLVM alias analysis. It is an
+ aggressive local analysis that "knows" many important facts:</p>
+
+ <ul>
+ <li>Distinct globals, stack allocations, and heap allocations can never
+ alias.</li>
+ <li>Globals, stack allocations, and heap allocations never alias the null
+ pointer.</li>
+ <li>Different fields of a structure do not alias.</li>
+ <li>Indexes into arrays with statically differing subscripts cannot alias.</li>
+ <li>Many common standard C library functions <a
+ href="#simplemodref">never access memory or only read memory</a>.</li>
+ <li>Pointers that obviously point to constant globals
+ "<tt>pointToConstantMemory</tt>".</li>
+ <li>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).</li>
+ </ul>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="globalsmodref">The <tt>-globalsmodref-aa</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>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. GCSE) to
+ eliminate call instructions entirely.
+ </p>
+
+ <p>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.</p>
+
+ <p>Note that this pass is somewhat limited in its scope (only support
+ non-address taken globals), but is very quick analysis.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="anders-aa">The <tt>-anders-aa</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-anders-aa</tt> pass implements the well-known "Andersen's algorithm"
+ for interprocedural alias analysis. This algorithm is a subset-based,
+ flow-insensitive, context-insensitive, and field-insensitive alias analysis that
+ is widely believed to be fairly precise. Unfortunately, this algorithm is also
+ O(N<sup>3</sup>). The LLVM implementation currently does not implement any of
+ the refinements (such as "online cycle elimination" or "offline variable
+ substitution") to improve its efficiency, so it can be quite slow in common
+ cases.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="steens-aa">The <tt>-steens-aa</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-steens-aa</tt> 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).</p>
+
+ <p>The LLVM <tt>-steens-aa</tt> pass implements a "speculatively
+ field-<b>sensitive</b>" 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.</p>
+
+ <p>Note that <tt>-steens-aa</tt> is available in the optional "poolalloc"
+ module, it is not part of the LLVM core.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ds-aa">The <tt>-ds-aa</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-ds-aa</tt> pass implements the full Data Structure Analysis
+ algorithm. Data Structure Analysis is a modular unification-based,
+ flow-insensitive, context-<b>sensitive</b>, and speculatively
+ field-<b>sensitive</b> alias analysis that is also quite scalable, usually at
+ O(n*log(n)).</p>
+
+ <p>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.</p>
+
+ <p>Note that <tt>-ds-aa</tt> is available in the optional "poolalloc"
+ module, it is not part of the LLVM core.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="aliasanalysis-xforms">Alias analysis driven transformations</a>
+ </div>
+
+ <div class="doc_text">
+ LLVM includes several alias-analysis driven transformations which can be used
+ with any of the implementations above.
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="adce">The <tt>-adce</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-adce</tt> pass, which implements Aggressive Dead Code Elimination
+ uses the <tt>AliasAnalysis</tt> interface to delete calls to functions that do
+ not have side-effects and are not used.</p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="licm">The <tt>-licm</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-licm</tt> pass implements various Loop Invariant Code Motion related
+ transformations. It uses the <tt>AliasAnalysis</tt> interface for several
+ different transformations:</p>
+
+ <ul>
+ <li>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.</li>
+
+ <li>It uses mod/ref information to hoist function calls out of loops that do not
+ write to memory and are loop-invariant.</li>
+
+ <li>If uses alias information to promote memory objects that are loaded and
+ stored to in loops to live in a register instead. It can do this if there are
+ no may aliases to the loaded/stored memory location.</li>
+ </ul>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="argpromotion">The <tt>-argpromotion</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ The <tt>-argpromotion</tt> 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.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="gcseloadvn">The <tt>-load-vn</tt> & <tt>-gcse</tt> passes</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-load-vn</tt> pass uses alias analysis to "<a href="#loadvn">value
+ number</a>" loads and pointers values, which is used by the GCSE pass to
+ eliminate instructions. The <tt>-load-vn</tt> pass relies on alias information
+ and must-alias information. This combination of passes can make the following
+ transformations:</p>
+
+ <ul>
+ <li>Redundant load instructions are eliminated.</li>
+ <li>Load instructions that follow a store to the same location are replaced with
+ the stored value ("store forwarding").</li>
+ <li>Pointers values (e.g. formal arguments) that must-alias simpler expressions
+ (e.g. global variables or the null pointer) are replaced. Note that this
+ implements transformations like "virtual method resolution", turning indirect
+ calls into direct calls.</li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="aliasanalysis-debug">Clients for debugging and evaluation of
+ implementations</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>These passes are useful for evaluating the various alias analysis
+ implementations. You can use them with commands like '<tt>opt -anders-aa -ds-aa
+ -aa-eval foo.bc -disable-output -stats</tt>'.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="print-alias-sets">The <tt>-print-alias-sets</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-print-alias-sets</tt> pass is exposed as part of the
+ <tt>opt</tt> tool to print out the Alias Sets formed by the <a
+ href="#ast"><tt>AliasSetTracker</tt></a> class. This is useful if you're using
+ the <tt>AliasSetTracker</tt> class. To use it, use something like:</p>
+
+ <div class="doc_code">
+ <pre>
+ % opt -ds-aa -print-alias-sets -disable-output
+ </pre>
+ </div>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="count-aa">The <tt>-count-aa</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-count-aa</tt> 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,</p>
+
+ <div class="doc_code">
+ <pre>
+ % opt -basicaa -count-aa -ds-aa -count-aa -licm
+ </pre>
+ </div>
+
+ <p>will print out how many queries (and what responses are returned) by the
+ <tt>-licm</tt> pass (of the <tt>-ds-aa</tt> pass) and how many queries are made
+ of the <tt>-basicaa</tt> pass by the <tt>-ds-aa</tt> pass. This can be useful
+ when debugging a transformation or an alias analysis implementation.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="aa-eval">The <tt>-aa-eval</tt> pass</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>-aa-eval</tt> 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).</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="memdep">Memory Dependence Analysis</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>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.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/BitCodeFormat.html
diff -c /dev/null llvm-www/releases/2.3/docs/BitCodeFormat.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/BitCodeFormat.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,653 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>LLVM Bitcode File Format</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+ <div class="doc_title"> LLVM Bitcode File Format </div>
+ <ol>
+ <li><a href="#abstract">Abstract</a></li>
+ <li><a href="#overview">Overview</a></li>
+ <li><a href="#bitstream">Bitstream Format</a>
+ <ol>
+ <li><a href="#magic">Magic Numbers</a></li>
+ <li><a href="#primitives">Primitives</a></li>
+ <li><a href="#abbrevid">Abbreviation IDs</a></li>
+ <li><a href="#blocks">Blocks</a></li>
+ <li><a href="#datarecord">Data Records</a></li>
+ <li><a href="#abbreviations">Abbreviations</a></li>
+ <li><a href="#stdblocks">Standard Blocks</a></li>
+ </ol>
+ </li>
+ <li><a href="#llvmir">LLVM IR Encoding</a>
+ <ol>
+ <li><a href="#basics">Basics</a></li>
+ </ol>
+ </li>
+ </ol>
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a>
+ and <a href="http://www.reverberate.org">Joshua Haberman</a>.
+ </p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="abstract">Abstract</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This document describes the LLVM bitstream file format and the encoding of
+ the LLVM IR into it.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="overview">Overview</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>
+ What is commonly known as the LLVM bitcode file format (also, sometimes
+ anachronistically known as bytecode) is actually two things: a <a
+ href="#bitstream">bitstream container format</a>
+ and an <a href="#llvmir">encoding of LLVM IR</a> into the container format.</p>
+
+ <p>
+ The bitstream format is an abstract encoding of structured data, very
+ similar to XML in some ways. Like XML, bitstream files contain tags, and nested
+ structures, and you can parse the file without having to understand the tags.
+ Unlike XML, the bitstream format is a binary encoding, and unlike XML it
+ provides a mechanism for the file to self-describe "abbreviations", which are
+ effectively size optimizations for the content.</p>
+
+ <p>This document first describes the LLVM bitstream format, then describes the
+ record structure used by LLVM IR files.
+ </p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="bitstream">Bitstream Format</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>
+ The bitstream format is literally a stream of bits, with a very simple
+ structure. This structure consists of the following concepts:
+ </p>
+
+ <ul>
+ <li>A "<a href="#magic">magic number</a>" that identifies the contents of
+ the stream.</li>
+ <li>Encoding <a href="#primitives">primitives</a> like variable bit-rate
+ integers.</li>
+ <li><a href="#blocks">Blocks</a>, which define nested content.</li>
+ <li><a href="#datarecord">Data Records</a>, which describe entities within the
+ file.</li>
+ <li>Abbreviations, which specify compression optimizations for the file.</li>
+ </ul>
+
+ <p>Note that the <a
+ href="CommandGuide/html/llvm-bcanalyzer.html">llvm-bcanalyzer</a> tool can be
+ used to dump and inspect arbitrary bitstreams, which is very useful for
+ understanding the encoding.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="magic">Magic Numbers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The first two bytes of a bitcode file are 'BC' (0x42, 0x43).
+ The second two bytes are an application-specific magic number. Generic
+ bitcode tools can look at only the first two bytes to verify the file is
+ bitcode, while application-specific programs will want to look at all four.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="primitives">Primitives</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ A bitstream literally consists of a stream of bits, which are read in order
+ starting with the least significant bit of each byte. The stream is made up of a
+ number of primitive values that encode a stream of unsigned integer values.
+ These
+ integers are are encoded in two ways: either as <a href="#fixedwidth">Fixed
+ Width Integers</a> or as <a href="#variablewidth">Variable Width
+ Integers</a>.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="fixedwidth">Fixed Width Integers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Fixed-width integer values have their low bits emitted directly to the file.
+ For example, a 3-bit integer value encodes 1 as 001. Fixed width integers
+ are used when there are a well-known number of options for a field. For
+ example, boolean values are usually encoded with a 1-bit wide integer.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="variablewidth">Variable Width
+ Integers</a></div>
+
+ <div class="doc_text">
+
+ <p>Variable-width integer (VBR) values encode values of arbitrary size,
+ optimizing for the case where the values are small. Given a 4-bit VBR field,
+ any 3-bit value (0 through 7) is encoded directly, with the high bit set to
+ zero. Values larger than N-1 bits emit their bits in a series of N-1 bit
+ chunks, where all but the last set the high bit.</p>
+
+ <p>For example, the value 27 (0x1B) is encoded as 1011 0011 when emitted as a
+ vbr4 value. The first set of four bits indicates the value 3 (011) with a
+ continuation piece (indicated by a high bit of 1). The next word indicates a
+ value of 24 (011 << 3) with no continuation. The sum (3+24) yields the value
+ 27.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="char6">6-bit characters</a></div>
+
+ <div class="doc_text">
+
+ <p>6-bit characters encode common characters into a fixed 6-bit field. They
+ represent the following characters with the following 6-bit values:</p>
+
+ <ul>
+ <li>'a' .. 'z' - 0 .. 25</li>
+ <li>'A' .. 'Z' - 26 .. 51</li>
+ <li>'0' .. '9' - 52 .. 61</li>
+ <li>'.' - 62</li>
+ <li>'_' - 63</li>
+ </ul>
+
+ <p>This encoding is only suitable for encoding characters and strings that
+ consist only of the above characters. It is completely incapable of encoding
+ characters not in the set.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="wordalign">Word Alignment</a></div>
+
+ <div class="doc_text">
+
+ <p>Occasionally, it is useful to emit zero bits until the bitstream is a
+ multiple of 32 bits. This ensures that the bit position in the stream can be
+ represented as a multiple of 32-bit words.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="abbrevid">Abbreviation IDs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ A bitstream is a sequential series of <a href="#blocks">Blocks</a> and
+ <a href="#datarecord">Data Records</a>. Both of these start with an
+ abbreviation ID encoded as a fixed-bitwidth field. The width is specified by
+ the current block, as described below. The value of the abbreviation ID
+ specifies either a builtin ID (which have special meanings, defined below) or
+ one of the abbreviation IDs defined by the stream itself.
+ </p>
+
+ <p>
+ The set of builtin abbrev IDs is:
+ </p>
+
+ <ul>
+ <li>0 - <a href="#END_BLOCK">END_BLOCK</a> - This abbrev ID marks the end of the
+ current block.</li>
+ <li>1 - <a href="#ENTER_SUBBLOCK">ENTER_SUBBLOCK</a> - This abbrev ID marks the
+ beginning of a new block.</li>
+ <li>2 - <a href="#DEFINE_ABBREV">DEFINE_ABBREV</a> - This defines a new
+ abbreviation.</li>
+ <li>3 - <a href="#UNABBREV_RECORD">UNABBREV_RECORD</a> - This ID specifies the
+ definition of an unabbreviated record.</li>
+ </ul>
+
+ <p>Abbreviation IDs 4 and above are defined by the stream itself, and specify
+ an <a href="#abbrev_records">abbreviated record encoding</a>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="blocks">Blocks</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ Blocks in a bitstream denote nested regions of the stream, and are identified by
+ a content-specific id number (for example, LLVM IR uses an ID of 12 to represent
+ function bodies). Block IDs 0-7 are reserved for <a href="#stdblocks">standard blocks</a>
+ whose meaning is defined by Bitcode; block IDs 8 and greater are
+ application specific. Nested blocks capture the hierachical structure of the data
+ encoded in it, and various properties are associated with blocks as the file is
+ parsed. Block definitions allow the reader to efficiently skip blocks
+ in constant time if the reader wants a summary of blocks, or if it wants to
+ efficiently skip data they do not understand. The LLVM IR reader uses this
+ mechanism to skip function bodies, lazily reading them on demand.
+ </p>
+
+ <p>
+ When reading and encoding the stream, several properties are maintained for the
+ block. In particular, each block maintains:
+ </p>
+
+ <ol>
+ <li>A current abbrev id width. This value starts at 2, and is set every time a
+ block record is entered. The block entry specifies the abbrev id width for
+ the body of the block.</li>
+
+ <li>A set of abbreviations. Abbreviations may be defined within a block, in
+ which case they are only defined in that block (neither subblocks nor
+ enclosing blocks see the abbreviation). Abbreviations can also be defined
+ inside a <a href="#BLOCKINFO">BLOCKINFO</a> block, in which case they are
+ defined in all blocks that match the ID that the BLOCKINFO block is describing.
+ </li>
+ </ol>
+
+ <p>As sub blocks are entered, these properties are saved and the new sub-block
+ has its own set of abbreviations, and its own abbrev id width. When a sub-block
+ is popped, the saved values are restored.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="ENTER_SUBBLOCK">ENTER_SUBBLOCK
+ Encoding</a></div>
+
+ <div class="doc_text">
+
+ <p><tt>[ENTER_SUBBLOCK, blockid<sub>vbr8</sub>, newabbrevlen<sub>vbr4</sub>,
+ <align32bits>, blocklen<sub>32</sub>]</tt></p>
+
+ <p>
+ The ENTER_SUBBLOCK abbreviation ID specifies the start of a new block record.
+ The <tt>blockid</tt> value is encoded as a 8-bit VBR identifier, and indicates
+ the type of block being entered (which can be a <a href="#stdblocks">standard
+ block</a> or an application-specific block). The
+ <tt>newabbrevlen</tt> value is a 4-bit VBR which specifies the
+ abbrev id width for the sub-block. The <tt>blocklen</tt> is a 32-bit aligned
+ value that specifies the size of the subblock, in 32-bit words. This value
+ allows the reader to skip over the entire block in one jump.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="END_BLOCK">END_BLOCK
+ Encoding</a></div>
+
+ <div class="doc_text">
+
+ <p><tt>[END_BLOCK, <align32bits>]</tt></p>
+
+ <p>
+ The END_BLOCK abbreviation ID specifies the end of the current block record.
+ Its end is aligned to 32-bits to ensure that the size of the block is an even
+ multiple of 32-bits.</p>
+
+ </div>
+
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="datarecord">Data Records</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ Data records consist of a record code and a number of (up to) 64-bit integer
+ values. The interpretation of the code and values is application specific and
+ there are multiple different ways to encode a record (with an unabbrev record
+ or with an abbreviation). In the LLVM IR format, for example, there is a record
+ which encodes the target triple of a module. The code is MODULE_CODE_TRIPLE,
+ and the values of the record are the ascii codes for the characters in the
+ string.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="UNABBREV_RECORD">UNABBREV_RECORD
+ Encoding</a></div>
+
+ <div class="doc_text">
+
+ <p><tt>[UNABBREV_RECORD, code<sub>vbr6</sub>, numops<sub>vbr6</sub>,
+ op0<sub>vbr6</sub>, op1<sub>vbr6</sub>, ...]</tt></p>
+
+ <p>An UNABBREV_RECORD provides a default fallback encoding, which is both
+ completely general and also extremely inefficient. It can describe an arbitrary
+ record, by emitting the code and operands as vbrs.</p>
+
+ <p>For example, emitting an LLVM IR target triple as an unabbreviated record
+ requires emitting the UNABBREV_RECORD abbrevid, a vbr6 for the
+ MODULE_CODE_TRIPLE code, a vbr6 for the length of the string (which is equal to
+ the number of operands), and a vbr6 for each character. Since there are no
+ letters with value less than 32, each letter would need to be emitted as at
+ least a two-part VBR, which means that each letter would require at least 12
+ bits. This is not an efficient encoding, but it is fully general.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="abbrev_records">Abbreviated Record
+ Encoding</a></div>
+
+ <div class="doc_text">
+
+ <p><tt>[<abbrevid>, fields...]</tt></p>
+
+ <p>An abbreviated record is a abbreviation id followed by a set of fields that
+ are encoded according to the <a href="#abbreviations">abbreviation
+ definition</a>. This allows records to be encoded significantly more densely
+ than records encoded with the <a href="#UNABBREV_RECORD">UNABBREV_RECORD</a>
+ type, and allows the abbreviation types to be specified in the stream itself,
+ which allows the files to be completely self describing. The actual encoding
+ of abbreviations is defined below.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="abbreviations">Abbreviations</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ Abbreviations are an important form of compression for bitstreams. The idea is
+ to specify a dense encoding for a class of records once, then use that encoding
+ to emit many records. It takes space to emit the encoding into the file, but
+ the space is recouped (hopefully plus some) when the records that use it are
+ emitted.
+ </p>
+
+ <p>
+ Abbreviations can be determined dynamically per client, per file. Since the
+ abbreviations are stored in the bitstream itself, different streams of the same
+ format can contain different sets of abbreviations if the specific stream does
+ not need it. As a concrete example, LLVM IR files usually emit an abbreviation
+ for binary operators. If a specific LLVM module contained no or few binary
+ operators, the abbreviation does not need to be emitted.
+ </p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="DEFINE_ABBREV">DEFINE_ABBREV
+ Encoding</a></div>
+
+ <div class="doc_text">
+
+ <p><tt>[DEFINE_ABBREV, numabbrevops<sub>vbr5</sub>, abbrevop0, abbrevop1,
+ ...]</tt></p>
+
+ <p>A DEFINE_ABBREV record adds an abbreviation to the list of currently
+ defined abbreviations in the scope of this block. This definition only
+ exists inside this immediate block -- it is not visible in subblocks or
+ enclosing blocks.
+ Abbreviations are implicitly assigned IDs
+ sequentially starting from 4 (the first application-defined abbreviation ID).
+ Any abbreviations defined in a BLOCKINFO record receive IDs first, in order,
+ followed by any abbreviations defined within the block itself.
+ Abbreviated data records reference this ID to indicate what abbreviation
+ they are invoking.</p>
+
+ <p>An abbreviation definition consists of the DEFINE_ABBREV abbrevid followed
+ by a VBR that specifies the number of abbrev operands, then the abbrev
+ operands themselves. Abbreviation operands come in three forms. They all start
+ with a single bit that indicates whether the abbrev operand is a literal operand
+ (when the bit is 1) or an encoding operand (when the bit is 0).</p>
+
+ <ol>
+ <li>Literal operands - <tt>[1<sub>1</sub>, litvalue<sub>vbr8</sub>]</tt> -
+ Literal operands specify that the value in the result
+ is always a single specific value. This specific value is emitted as a vbr8
+ after the bit indicating that it is a literal operand.</li>
+ <li>Encoding info without data - <tt>[0<sub>1</sub>, encoding<sub>3</sub>]</tt>
+ - Operand encodings that do not have extra data are just emitted as their code.
+ </li>
+ <li>Encoding info with data - <tt>[0<sub>1</sub>, encoding<sub>3</sub>,
+ value<sub>vbr5</sub>]</tt> - Operand encodings that do have extra data are
+ emitted as their code, followed by the extra data.
+ </li>
+ </ol>
+
+ <p>The possible operand encodings are:</p>
+
+ <ul>
+ <li>1 - Fixed - The field should be emitted as a <a
+ href="#fixedwidth">fixed-width value</a>, whose width
+ is specified by the operand's extra data.</li>
+ <li>2 - VBR - The field should be emitted as a <a
+ href="#variablewidth">variable-width value</a>, whose width
+ is specified by the operand's extra data.</li>
+ <li>3 - Array - This field is an array of values. The array operand has no
+ extra data, but expects another operand to follow it which indicates the
+ element type of the array. When reading an array in an abbreviated record,
+ the first integer is a vbr6 that indicates the array length, followed by
+ the encoded elements of the array. An array may only occur as the last
+ operand of an abbreviation (except for the one final operand that gives
+ the array's type).</li>
+ <li>4 - Char6 - This field should be emitted as a <a href="#char6">char6-encoded
+ value</a>. This operand type takes no extra data.</li>
+ </ul>
+
+ <p>For example, target triples in LLVM modules are encoded as a record of the
+ form <tt>[TRIPLE, 'a', 'b', 'c', 'd']</tt>. Consider if the bitstream emitted
+ the following abbrev entry:</p>
+
+ <ul>
+ <li><tt>[0, Fixed, 4]</tt></li>
+ <li><tt>[0, Array]</tt></li>
+ <li><tt>[0, Char6]</tt></li>
+ </ul>
+
+ <p>When emitting a record with this abbreviation, the above entry would be
+ emitted as:</p>
+
+ <p><tt>[4<sub>abbrevwidth</sub>, 2<sub>4</sub>, 4<sub>vbr6</sub>,
+ 0<sub>6</sub>, 1<sub>6</sub>, 2<sub>6</sub>, 3<sub>6</sub>]</tt></p>
+
+ <p>These values are:</p>
+
+ <ol>
+ <li>The first value, 4, is the abbreviation ID for this abbreviation.</li>
+ <li>The second value, 2, is the code for TRIPLE in LLVM IR files.</li>
+ <li>The third value, 4, is the length of the array.</li>
+ <li>The rest of the values are the char6 encoded values for "abcd".</li>
+ </ol>
+
+ <p>With this abbreviation, the triple is emitted with only 37 bits (assuming a
+ abbrev id width of 3). Without the abbreviation, significantly more space would
+ be required to emit the target triple. Also, since the TRIPLE value is not
+ emitted as a literal in the abbreviation, the abbreviation can also be used for
+ any other string value.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="stdblocks">Standard Blocks</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ In addition to the basic block structure and record encodings, the bitstream
+ also defines specific builtin block types. These block types specify how the
+ stream is to be decoded or other metadata. In the future, new standard blocks
+ may be added. Block IDs 0-7 are reserved for standard blocks.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="BLOCKINFO">#0 - BLOCKINFO
+ Block</a></div>
+
+ <div class="doc_text">
+
+ <p>The BLOCKINFO block allows the description of metadata for other blocks. The
+ currently specified records are:</p>
+
+ <ul>
+ <li><tt>[SETBID (#1), blockid]</tt></li>
+ <li><tt>[DEFINE_ABBREV, ...]</tt></li>
+ </ul>
+
+ <p>
+ The SETBID record indicates which block ID is being described. SETBID
+ records can occur multiple times throughout the block to change which
+ block ID is being described. There must be a SETBID record prior to
+ any other records.
+ </p>
+
+ <p>
+ Standard DEFINE_ABBREV records can occur inside BLOCKINFO blocks, but unlike
+ their occurrence in normal blocks, the abbreviation is defined for blocks
+ matching the block ID we are describing, <i>not</i> the BLOCKINFO block itself.
+ The abbreviations defined in BLOCKINFO blocks receive abbreviation ids
+ as described in <a href="#DEFINE_ABBREV">DEFINE_ABBREV</a>.
+ </p>
+
+ <p>
+ Note that although the data in BLOCKINFO blocks is described as "metadata," the
+ abbreviations they contain are essential for parsing records from the
+ corresponding blocks. It is not safe to skip them.
+ </p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="llvmir">LLVM IR Encoding</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>LLVM IR is encoded into a bitstream by defining blocks and records. It uses
+ blocks for things like constant pools, functions, symbol tables, etc. It uses
+ records for things like instructions, global variable descriptors, type
+ descriptions, etc. This document does not describe the set of abbreviations
+ that the writer uses, as these are fully self-described in the file, and the
+ reader is not allowed to build in any knowledge of this.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="basics">Basics</a>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="ir_magic">LLVM IR Magic Number</a></div>
+
+ <div class="doc_text">
+
+ <p>
+ The magic number for LLVM IR files is:
+ </p>
+
+ <p><tt>[0x0<sub>4</sub>, 0xC<sub>4</sub>, 0xE<sub>4</sub>, 0xD<sub>4</sub>]</tt></p>
+
+ <p>When combined with the bitcode magic number and viewed as bytes, this is "BC 0xC0DE".</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="ir_signed_vbr">Signed VBRs</a></div>
+
+ <div class="doc_text">
+
+ <p>
+ <a href="#variablewidth">Variable Width Integers</a> are an efficient way to
+ encode arbitrary sized unsigned values, but is an extremely inefficient way to
+ encode signed values (as signed values are otherwise treated as maximally large
+ unsigned values).</p>
+
+ <p>As such, signed vbr values of a specific width are emitted as follows:</p>
+
+ <ul>
+ <li>Positive values are emitted as vbrs of the specified width, but with their
+ value shifted left by one.</li>
+ <li>Negative values are emitted as vbrs of the specified width, but the negated
+ value is shifted left by one, and the low bit is set.</li>
+ </ul>
+
+ <p>With this encoding, small positive and small negative values can both be
+ emitted efficiently.</p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="ir_blocks">LLVM IR Blocks</a></div>
+
+ <div class="doc_text">
+
+ <p>
+ LLVM IR is defined with the following blocks:
+ </p>
+
+ <ul>
+ <li>8 - MODULE_BLOCK - This is the top-level block that contains the
+ entire module, and describes a variety of per-module information.</li>
+ <li>9 - PARAMATTR_BLOCK - This enumerates the parameter attributes.</li>
+ <li>10 - TYPE_BLOCK - This describes all of the types in the module.</li>
+ <li>11 - CONSTANTS_BLOCK - This describes constants for a module or
+ function.</li>
+ <li>12 - FUNCTION_BLOCK - This describes a function body.</li>
+ <li>13 - TYPE_SYMTAB_BLOCK - This describes the type symbol table.</li>
+ <li>14 - VALUE_SYMTAB_BLOCK - This describes a value symbol table.</li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="MODULE_BLOCK">MODULE_BLOCK Contents</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ </p>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <hr>
+ <address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/Bugpoint.html
diff -c /dev/null llvm-www/releases/2.3/docs/Bugpoint.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/Bugpoint.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,244 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>LLVM bugpoint tool: design and usage</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+
+ <div class="doc_title">
+ LLVM bugpoint tool: design and usage
+ </div>
+
+ <ul>
+ <li><a href="#desc">Description</a></li>
+ <li><a href="#design">Design Philosophy</a>
+ <ul>
+ <li><a href="#autoselect">Automatic Debugger Selection</a></li>
+ <li><a href="#crashdebug">Crash debugger</a></li>
+ <li><a href="#codegendebug">Code generator debugger</a></li>
+ <li><a href="#miscompilationdebug">Miscompilation debugger</a></li>
+ </ul></li>
+ <li><a href="#advice">Advice for using <tt>bugpoint</tt></a></li>
+ </ul>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="desc">Description</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p><tt>bugpoint</tt> narrows down the source of problems in LLVM tools and
+ passes. It can be used to debug three types of failures: optimizer crashes,
+ miscompilations by optimizers, or bad native code generation (including problems
+ in the static and JIT compilers). It aims to reduce large test cases to small,
+ useful ones. For example, if <tt>opt</tt> crashes while optimizing a
+ file, it will identify the optimization (or combination of optimizations) that
+ causes the crash, and reduce the file down to a small example which triggers the
+ crash.</p>
+
+ <p>For detailed case scenarios, such as debugging <tt>opt</tt>,
+ <tt>llvm-ld</tt>, or one of the LLVM code generators, see <a
+ href="HowToSubmitABug.html">How To Submit a Bug Report document</a>.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="design">Design Philosophy</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p><tt>bugpoint</tt> is designed to be a useful tool without requiring any
+ hooks into the LLVM infrastructure at all. It works with any and all LLVM
+ passes and code generators, and does not need to "know" how they work. Because
+ of this, it may appear to do stupid things or miss obvious
+ simplifications. <tt>bugpoint</tt> is also designed to trade off programmer
+ time for computer time in the compiler-debugging process; consequently, it may
+ take a long period of (unattended) time to reduce a test case, but we feel it
+ is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless
+ debugging a miscompilation where each test of the program (which requires
+ executing it) takes a long time.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="autoselect">Automatic Debugger Selection</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file specified on
+ the command line and links them together into a single module, called the test
+ program. If any LLVM passes are specified on the command line, it runs these
+ passes on the test program. If any of the passes crash, or if they produce
+ malformed output (which causes the verifier to abort), <tt>bugpoint</tt> starts
+ the <a href="#crashdebug">crash debugger</a>.</p>
+
+ <p>Otherwise, if the <tt>-output</tt> option was not specified,
+ <tt>bugpoint</tt> runs the test program with the C backend (which is assumed to
+ generate good code) to generate a reference output. Once <tt>bugpoint</tt> has
+ a reference output for the test program, it tries executing it with the
+ selected code generator. If the selected code generator crashes,
+ <tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a> on the
+ code generator. Otherwise, if the resulting output differs from the reference
+ output, it assumes the difference resulted from a code generator failure, and
+ starts the <a href="#codegendebug">code generator debugger</a>.</p>
+
+ <p>Finally, if the output of the selected code generator matches the reference
+ output, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
+ have been applied to it. If its output differs from the reference output, it
+ assumes the difference resulted from a failure in one of the LLVM passes, and
+ enters the <a href="#miscompilationdebug">miscompilation debugger</a>.
+ Otherwise, there is no problem <tt>bugpoint</tt> can debug.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="crashdebug">Crash debugger</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard
+ as it can to reduce the list of passes (for optimizer crashes) and the size of
+ the test program. First, <tt>bugpoint</tt> figures out which combination of
+ optimizer passes triggers the bug. This is useful when debugging a problem
+ exposed by <tt>opt</tt>, for example, because it runs over 38 passes.</p>
+
+ <p>Next, <tt>bugpoint</tt> tries removing functions from the test program, to
+ reduce its size. Usually it is able to reduce a test program to a single
+ function, when debugging intraprocedural optimizations. Once the number of
+ functions has been reduced, it attempts to delete various edges in the control
+ flow graph, to reduce the size of the function as much as possible. Finally,
+ <tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
+ not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what
+ passes crash, give you a bitcode file, and give you instructions on how to
+ reproduce the failure with <tt>opt</tt> or <tt>llc</tt>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="codegendebug">Code generator debugger</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The code generator debugger attempts to narrow down the amount of code that
+ is being miscompiled by the selected code generator. To do this, it takes the
+ test program and partitions it into two pieces: one piece which it compiles
+ with the C backend (into a shared object), and one piece which it runs with
+ either the JIT or the static LLC compiler. It uses several techniques to
+ reduce the amount of code pushed through the LLVM code generator, to reduce the
+ potential scope of the problem. After it is finished, it emits two bitcode
+ files (called "test" [to be compiled with the code generator] and "safe" [to be
+ compiled with the C backend], respectively), and instructions for reproducing
+ the problem. The code generator debugger assumes that the C backend produces
+ good code.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="miscompilationdebug">Miscompilation debugger</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The miscompilation debugger works similarly to the code generator debugger.
+ It works by splitting the test program into two pieces, running the
+ optimizations specified on one piece, linking the two pieces back together, and
+ then executing the result. It attempts to narrow down the list of passes to
+ the one (or few) which are causing the miscompilation, then reduce the portion
+ of the test program which is being miscompiled. The miscompilation debugger
+ assumes that the selected code generator is working properly.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="advice">Advice for using bugpoint</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
+ non-obvious ways. Here are some hints and tips:<p>
+
+ <ol>
+ <li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
+ works with programs that have deterministic output. Thus, if the program
+ outputs <tt>argv[0]</tt>, the date, time, or any other "random" data,
+ <tt>bugpoint</tt> may misinterpret differences in these data, when output,
+ as the result of a miscompilation. Programs should be temporarily modified
+ to disable outputs that are likely to vary from run to run.
+
+ <li>In the code generator and miscompilation debuggers, debugging will go
+ faster if you manually modify the program or its inputs to reduce the
+ runtime, but still exhibit the problem.
+
+ <li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
+ it helps track down regressions quickly. To avoid having to relink
+ <tt>bugpoint</tt> every time you change your optimization however, have
+ <tt>bugpoint</tt> dynamically load your optimization with the
+ <tt>-load</tt> option.
+
+ <li><p><tt>bugpoint</tt> can generate a lot of output and run for a long period
+ of time. It is often useful to capture the output of the program to file.
+ For example, in the C shell, you can run:</p>
+
+ <div class="doc_code">
+ <p><tt>bugpoint ... |& tee bugpoint.log</tt></p>
+ </div>
+
+ <p>to get a copy of <tt>bugpoint</tt>'s output in the file
+ <tt>bugpoint.log</tt>, as well as on your terminal.</p>
+
+ <li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If
+ <tt>bugpoint</tt> crashes before you see its "All input ok" message,
+ you might try <tt>llvm-link -v</tt> on the same set of input files. If
+ that also crashes, you may be experiencing a linker bug.
+
+ <li>If your program is <b>supposed</b> to crash, <tt>bugpoint</tt> will be
+ confused. One way to deal with this is to cause bugpoint to ignore the exit
+ code from your program, by giving it the <tt>-check-exit-code=false</tt>
+ option.
+
+ <li><tt>bugpoint</tt> is useful for proactively finding bugs in LLVM.
+ Invoking <tt>bugpoint</tt> with the <tt>-find-bugs</tt> option will cause
+ the list of specified optimizations to be randomized and applied to the
+ program. This process will repeat until a bug is found or the user
+ kills <tt>bugpoint</tt>.
+
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/CFEBuildInstrs.html
diff -c /dev/null llvm-www/releases/2.3/docs/CFEBuildInstrs.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/CFEBuildInstrs.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,29 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="stylesheet" href="llvm.css" type="text/css" media="screen">
+ <title>Building the LLVM C/C++ Front-End</title>
+ <meta HTTP-EQUIV="REFRESH" CONTENT="3; URL=GCCFEBuildInstrs.html">
+ </head>
+ <body>
+ <div class="doc_title">
+ This page has moved <a href="GCCFEBuildInstrs.html">here</A>.
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/CodeGenerator.html
diff -c /dev/null llvm-www/releases/2.3/docs/CodeGenerator.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/CodeGenerator.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,2006 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8">
+ <title>The LLVM Target-Independent Code Generator</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">
+ The LLVM Target-Independent Code Generator
+ </div>
+
+ <ol>
+ <li><a href="#introduction">Introduction</a>
+ <ul>
+ <li><a href="#required">Required components in the code generator</a></li>
+ <li><a href="#high-level-design">The high-level design of the code
+ generator</a></li>
+ <li><a href="#tablegen">Using TableGen for target description</a></li>
+ </ul>
+ </li>
+ <li><a href="#targetdesc">Target description classes</a>
+ <ul>
+ <li><a href="#targetmachine">The <tt>TargetMachine</tt> class</a></li>
+ <li><a href="#targetdata">The <tt>TargetData</tt> class</a></li>
+ <li><a href="#targetlowering">The <tt>TargetLowering</tt> class</a></li>
+ <li><a href="#targetregisterinfo">The <tt>TargetRegisterInfo</tt> class</a></li>
+ <li><a href="#targetinstrinfo">The <tt>TargetInstrInfo</tt> class</a></li>
+ <li><a href="#targetframeinfo">The <tt>TargetFrameInfo</tt> class</a></li>
+ <li><a href="#targetsubtarget">The <tt>TargetSubtarget</tt> class</a></li>
+ <li><a href="#targetjitinfo">The <tt>TargetJITInfo</tt> class</a></li>
+ </ul>
+ </li>
+ <li><a href="#codegendesc">Machine code description classes</a>
+ <ul>
+ <li><a href="#machineinstr">The <tt>MachineInstr</tt> class</a></li>
+ <li><a href="#machinebasicblock">The <tt>MachineBasicBlock</tt>
+ class</a></li>
+ <li><a href="#machinefunction">The <tt>MachineFunction</tt> class</a></li>
+ </ul>
+ </li>
+ <li><a href="#codegenalgs">Target-independent code generation algorithms</a>
+ <ul>
+ <li><a href="#instselect">Instruction Selection</a>
+ <ul>
+ <li><a href="#selectiondag_intro">Introduction to SelectionDAGs</a></li>
+ <li><a href="#selectiondag_process">SelectionDAG Code Generation
+ Process</a></li>
+ <li><a href="#selectiondag_build">Initial SelectionDAG
+ Construction</a></li>
+ <li><a href="#selectiondag_legalize">SelectionDAG Legalize Phase</a></li>
+ <li><a href="#selectiondag_optimize">SelectionDAG Optimization
+ Phase: the DAG Combiner</a></li>
+ <li><a href="#selectiondag_select">SelectionDAG Select Phase</a></li>
+ <li><a href="#selectiondag_sched">SelectionDAG Scheduling and Formation
+ Phase</a></li>
+ <li><a href="#selectiondag_future">Future directions for the
+ SelectionDAG</a></li>
+ </ul></li>
+ <li><a href="#liveintervals">Live Intervals</a>
+ <ul>
+ <li><a href="#livevariable_analysis">Live Variable Analysis</a></li>
+ <li><a href="#liveintervals_analysis">Live Intervals Analysis</a></li>
+ </ul></li>
+ <li><a href="#regalloc">Register Allocation</a>
+ <ul>
+ <li><a href="#regAlloc_represent">How registers are represented in
+ LLVM</a></li>
+ <li><a href="#regAlloc_howTo">Mapping virtual registers to physical
+ registers</a></li>
+ <li><a href="#regAlloc_twoAddr">Handling two address instructions</a></li>
+ <li><a href="#regAlloc_ssaDecon">The SSA deconstruction phase</a></li>
+ <li><a href="#regAlloc_fold">Instruction folding</a></li>
+ <li><a href="#regAlloc_builtIn">Built in register allocators</a></li>
+ </ul></li>
+ <li><a href="#codeemit">Code Emission</a>
+ <ul>
+ <li><a href="#codeemit_asm">Generating Assembly Code</a></li>
+ <li><a href="#codeemit_bin">Generating Binary Machine Code</a></li>
+ </ul></li>
+ </ul>
+ </li>
+ <li><a href="#targetimpls">Target-specific Implementation Notes</a>
+ <ul>
+ <li><a href="#tailcallopt">Tail call optimization</a></li>
+ <li><a href="#x86">The X86 backend</a></li>
+ <li><a href="#ppc">The PowerPC backend</a>
+ <ul>
+ <li><a href="#ppc_abi">LLVM PowerPC ABI</a></li>
+ <li><a href="#ppc_frame">Frame Layout</a></li>
+ <li><a href="#ppc_prolog">Prolog/Epilog</a></li>
+ <li><a href="#ppc_dynamic">Dynamic Allocation</a></li>
+ </ul></li>
+ </ul></li>
+
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a>,
+ <a href="mailto:isanbard at gmail.com">Bill Wendling</a>,
+ <a href="mailto:pronesto at gmail.com">Fernando Magno Quintao
+ Pereira</a> and
+ <a href="mailto:jlaskey at mac.com">Jim Laskey</a></p>
+ </div>
+
+ <div class="doc_warning">
+ <p>Warning: This is a work in progress.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The LLVM target-independent code generator is a framework that provides a
+ suite of reusable components for translating the LLVM internal representation to
+ the machine code for a specified target—either in assembly form (suitable
+ for a static compiler) or in binary machine code format (usable for a JIT
+ compiler). The LLVM target-independent code generator consists of five main
+ components:</p>
+
+ <ol>
+ <li><a href="#targetdesc">Abstract target description</a> interfaces which
+ capture important properties about various aspects of the machine, independently
+ of how they will be used. These interfaces are defined in
+ <tt>include/llvm/Target/</tt>.</li>
+
+ <li>Classes used to represent the <a href="#codegendesc">machine code</a> being
+ generated for a target. These classes are intended to be abstract enough to
+ represent the machine code for <i>any</i> target machine. These classes are
+ defined in <tt>include/llvm/CodeGen/</tt>.</li>
+
+ <li><a href="#codegenalgs">Target-independent algorithms</a> used to implement
+ various phases of native code generation (register allocation, scheduling, stack
+ frame representation, etc). This code lives in <tt>lib/CodeGen/</tt>.</li>
+
+ <li><a href="#targetimpls">Implementations of the abstract target description
+ interfaces</a> for particular targets. These machine descriptions make use of
+ the components provided by LLVM, and can optionally provide custom
+ target-specific passes, to build complete code generators for a specific target.
+ Target descriptions live in <tt>lib/Target/</tt>.</li>
+
+ <li><a href="#jit">The target-independent JIT components</a>. The LLVM JIT is
+ completely target independent (it uses the <tt>TargetJITInfo</tt> structure to
+ interface for target-specific issues. The code for the target-independent
+ JIT lives in <tt>lib/ExecutionEngine/JIT</tt>.</li>
+
+ </ol>
+
+ <p>
+ Depending on which part of the code generator you are interested in working on,
+ different pieces of this will be useful to you. In any case, you should be
+ familiar with the <a href="#targetdesc">target description</a> and <a
+ href="#codegendesc">machine code representation</a> classes. If you want to add
+ a backend for a new target, you will need to <a href="#targetimpls">implement the
+ target description</a> classes for your new target and understand the <a
+ href="LangRef.html">LLVM code representation</a>. If you are interested in
+ implementing a new <a href="#codegenalgs">code generation algorithm</a>, it
+ should only depend on the target-description and machine code representation
+ classes, ensuring that it is portable.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="required">Required components in the code generator</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The two pieces of the LLVM code generator are the high-level interface to the
+ code generator and the set of reusable components that can be used to build
+ target-specific backends. The two most important interfaces (<a
+ href="#targetmachine"><tt>TargetMachine</tt></a> and <a
+ href="#targetdata"><tt>TargetData</tt></a>) are the only ones that are
+ required to be defined for a backend to fit into the LLVM system, but the others
+ must be defined if the reusable code generator components are going to be
+ used.</p>
+
+ <p>This design has two important implications. The first is that LLVM can
+ support completely non-traditional code generation targets. For example, the C
+ backend does not require register allocation, instruction selection, or any of
+ the other standard components provided by the system. As such, it only
+ implements these two interfaces, and does its own thing. Another example of a
+ code generator like this is a (purely hypothetical) backend that converts LLVM
+ to the GCC RTL form and uses GCC to emit machine code for a target.</p>
+
+ <p>This design also implies that it is possible to design and
+ implement radically different code generators in the LLVM system that do not
+ make use of any of the built-in components. Doing so is not recommended at all,
+ but could be required for radically different targets that do not fit into the
+ LLVM machine description model: FPGAs for example.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="high-level-design">The high-level design of the code generator</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The LLVM target-independent code generator is designed to support efficient and
+ quality code generation for standard register-based microprocessors. Code
+ generation in this model is divided into the following stages:</p>
+
+ <ol>
+ <li><b><a href="#instselect">Instruction Selection</a></b> - This phase
+ determines an efficient way to express the input LLVM code in the target
+ instruction set.
+ This stage produces the initial code for the program in the target instruction
+ set, then makes use of virtual registers in SSA form and physical registers that
+ represent any required register assignments due to target constraints or calling
+ conventions. This step turns the LLVM code into a DAG of target
+ instructions.</li>
+
+ <li><b><a href="#selectiondag_sched">Scheduling and Formation</a></b> - This
+ phase takes the DAG of target instructions produced by the instruction selection
+ phase, determines an ordering of the instructions, then emits the instructions
+ as <tt><a href="#machineinstr">MachineInstr</a></tt>s with that ordering. Note
+ that we describe this in the <a href="#instselect">instruction selection
+ section</a> because it operates on a <a
+ href="#selectiondag_intro">SelectionDAG</a>.
+ </li>
+
+ <li><b><a href="#ssamco">SSA-based Machine Code Optimizations</a></b> - This
+ optional stage consists of a series of machine-code optimizations that
+ operate on the SSA-form produced by the instruction selector. Optimizations
+ like modulo-scheduling or peephole optimization work here.
+ </li>
+
+ <li><b><a href="#regalloc">Register Allocation</a></b> - The
+ target code is transformed from an infinite virtual register file in SSA form
+ to the concrete register file used by the target. This phase introduces spill
+ code and eliminates all virtual register references from the program.</li>
+
+ <li><b><a href="#proepicode">Prolog/Epilog Code Insertion</a></b> - Once the
+ machine code has been generated for the function and the amount of stack space
+ required is known (used for LLVM alloca's and spill slots), the prolog and
+ epilog code for the function can be inserted and "abstract stack location
+ references" can be eliminated. This stage is responsible for implementing
+ optimizations like frame-pointer elimination and stack packing.</li>
+
+ <li><b><a href="#latemco">Late Machine Code Optimizations</a></b> - Optimizations
+ that operate on "final" machine code can go here, such as spill code scheduling
+ and peephole optimizations.</li>
+
+ <li><b><a href="#codeemit">Code Emission</a></b> - The final stage actually
+ puts out the code for the current function, either in the target assembler
+ format or in machine code.</li>
+
+ </ol>
+
+ <p>The code generator is based on the assumption that the instruction selector
+ will use an optimal pattern matching selector to create high-quality sequences of
+ native instructions. Alternative code generator designs based on pattern
+ expansion and aggressive iterative peephole optimization are much slower. This
+ design permits efficient compilation (important for JIT environments) and
+ aggressive optimization (used when generating code offline) by allowing
+ components of varying levels of sophistication to be used for any step of
+ compilation.</p>
+
+ <p>In addition to these stages, target implementations can insert arbitrary
+ target-specific passes into the flow. For example, the X86 target uses a
+ special pass to handle the 80x87 floating point stack architecture. Other
+ targets with unusual requirements can be supported with custom passes as
+ needed.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="tablegen">Using TableGen for target description</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The target description classes require a detailed description of the target
+ architecture. These target descriptions often have a large amount of common
+ information (e.g., an <tt>add</tt> instruction is almost identical to a
+ <tt>sub</tt> instruction).
+ In order to allow the maximum amount of commonality to be factored out, the LLVM
+ code generator uses the <a href="TableGenFundamentals.html">TableGen</a> tool to
+ describe big chunks of the target machine, which allows the use of
+ domain-specific and target-specific abstractions to reduce the amount of
+ repetition.</p>
+
+ <p>As LLVM continues to be developed and refined, we plan to move more and more
+ of the target description to the <tt>.td</tt> form. Doing so gives us a
+ number of advantages. The most important is that it makes it easier to port
+ LLVM because it reduces the amount of C++ code that has to be written, and the
+ surface area of the code generator that needs to be understood before someone
+ can get something working. Second, it makes it easier to change things. In
+ particular, if tables and other things are all emitted by <tt>tblgen</tt>, we
+ only need a change in one place (<tt>tblgen</tt>) to update all of the targets
+ to a new interface.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="targetdesc">Target description classes</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The LLVM target description classes (located in the
+ <tt>include/llvm/Target</tt> directory) provide an abstract description of the
+ target machine independent of any particular client. These classes are
+ designed to capture the <i>abstract</i> properties of the target (such as the
+ instructions and registers it has), and do not incorporate any particular pieces
+ of code generation algorithms.</p>
+
+ <p>All of the target description classes (except the <tt><a
+ href="#targetdata">TargetData</a></tt> class) are designed to be subclassed by
+ the concrete target implementation, and have virtual methods implemented. To
+ get to these implementations, the <tt><a
+ href="#targetmachine">TargetMachine</a></tt> class provides accessors that
+ should be implemented by the target.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetmachine">The <tt>TargetMachine</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>TargetMachine</tt> class provides virtual methods that are used to
+ access the target-specific implementations of the various target description
+ classes via the <tt>get*Info</tt> methods (<tt>getInstrInfo</tt>,
+ <tt>getRegisterInfo</tt>, <tt>getFrameInfo</tt>, etc.). This class is
+ designed to be specialized by
+ a concrete target implementation (e.g., <tt>X86TargetMachine</tt>) which
+ implements the various virtual methods. The only required target description
+ class is the <a href="#targetdata"><tt>TargetData</tt></a> class, but if the
+ code generator components are to be used, the other interfaces should be
+ implemented as well.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetdata">The <tt>TargetData</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>TargetData</tt> class is the only required target description class,
+ and it is the only class that is not extensible (you cannot derived a new
+ class from it). <tt>TargetData</tt> specifies information about how the target
+ lays out memory for structures, the alignment requirements for various data
+ types, the size of pointers in the target, and whether the target is
+ little-endian or big-endian.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetlowering">The <tt>TargetLowering</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>TargetLowering</tt> class is used by SelectionDAG based instruction
+ selectors primarily to describe how LLVM code should be lowered to SelectionDAG
+ operations. Among other things, this class indicates:</p>
+
+ <ul>
+ <li>an initial register class to use for various <tt>ValueType</tt>s</li>
+ <li>which operations are natively supported by the target machine</li>
+ <li>the return type of <tt>setcc</tt> operations</li>
+ <li>the type to use for shift amounts</li>
+ <li>various high-level characteristics, like whether it is profitable to turn
+ division by a constant into a multiplication sequence</li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetregisterinfo">The <tt>TargetRegisterInfo</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>TargetRegisterInfo</tt> class is used to describe the register
+ file of the target and any interactions between the registers.</p>
+
+ <p>Registers in the code generator are represented in the code generator by
+ unsigned integers. Physical registers (those that actually exist in the target
+ description) are unique small numbers, and virtual registers are generally
+ large. Note that register #0 is reserved as a flag value.</p>
+
+ <p>Each register in the processor description has an associated
+ <tt>TargetRegisterDesc</tt> entry, which provides a textual name for the
+ register (used for assembly output and debugging dumps) and a set of aliases
+ (used to indicate whether one register overlaps with another).
+ </p>
+
+ <p>In addition to the per-register description, the <tt>TargetRegisterInfo</tt>
+ class exposes a set of processor specific register classes (instances of the
+ <tt>TargetRegisterClass</tt> class). Each register class contains sets of
+ registers that have the same properties (for example, they are all 32-bit
+ integer registers). Each SSA virtual register created by the instruction
+ selector has an associated register class. When the register allocator runs, it
+ replaces virtual registers with a physical register in the set.</p>
+
+ <p>
+ The target-specific implementations of these classes is auto-generated from a <a
+ href="TableGenFundamentals.html">TableGen</a> description of the register file.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetinstrinfo">The <tt>TargetInstrInfo</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+ <p>The <tt>TargetInstrInfo</tt> class is used to describe the machine
+ instructions supported by the target. It is essentially an array of
+ <tt>TargetInstrDescriptor</tt> objects, each of which describes one
+ instruction the target supports. Descriptors define things like the mnemonic
+ for the opcode, the number of operands, the list of implicit register uses
+ and defs, whether the instruction has certain target-independent properties
+ (accesses memory, is commutable, etc), and holds any target-specific
+ flags.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetframeinfo">The <tt>TargetFrameInfo</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+ <p>The <tt>TargetFrameInfo</tt> class is used to provide information about the
+ stack frame layout of the target. It holds the direction of stack growth,
+ the known stack alignment on entry to each function, and the offset to the
+ local area. The offset to the local area is the offset from the stack
+ pointer on function entry to the first location where function data (local
+ variables, spill locations) can be stored.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetsubtarget">The <tt>TargetSubtarget</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+ <p>The <tt>TargetSubtarget</tt> class is used to provide information about the
+ specific chip set being targeted. A sub-target informs code generation of
+ which instructions are supported, instruction latencies and instruction
+ execution itinerary; i.e., which processing units are used, in what order, and
+ for how long.</p>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetjitinfo">The <tt>TargetJITInfo</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+ <p>The <tt>TargetJITInfo</tt> class exposes an abstract interface used by the
+ Just-In-Time code generator to perform target-specific activities, such as
+ emitting stubs. If a <tt>TargetMachine</tt> supports JIT code generation, it
+ should provide one of these objects through the <tt>getJITInfo</tt>
+ method.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="codegendesc">Machine code description classes</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>At the high-level, LLVM code is translated to a machine specific
+ representation formed out of
+ <a href="#machinefunction"><tt>MachineFunction</tt></a>,
+ <a href="#machinebasicblock"><tt>MachineBasicBlock</tt></a>, and <a
+ href="#machineinstr"><tt>MachineInstr</tt></a> instances
+ (defined in <tt>include/llvm/CodeGen</tt>). This representation is completely
+ target agnostic, representing instructions in their most abstract form: an
+ opcode and a series of operands. This representation is designed to support
+ both an SSA representation for machine code, as well as a register allocated,
+ non-SSA form.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="machineinstr">The <tt>MachineInstr</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Target machine instructions are represented as instances of the
+ <tt>MachineInstr</tt> class. This class is an extremely abstract way of
+ representing machine instructions. In particular, it only keeps track of
+ an opcode number and a set of operands.</p>
+
+ <p>The opcode number is a simple unsigned integer that only has meaning to a
+ specific backend. All of the instructions for a target should be defined in
+ the <tt>*InstrInfo.td</tt> file for the target. The opcode enum values
+ are auto-generated from this description. The <tt>MachineInstr</tt> class does
+ not have any information about how to interpret the instruction (i.e., what the
+ semantics of the instruction are); for that you must refer to the
+ <tt><a href="#targetinstrinfo">TargetInstrInfo</a></tt> class.</p>
+
+ <p>The operands of a machine instruction can be of several different types:
+ a register reference, a constant integer, a basic block reference, etc. In
+ addition, a machine operand should be marked as a def or a use of the value
+ (though only registers are allowed to be defs).</p>
+
+ <p>By convention, the LLVM code generator orders instruction operands so that
+ all register definitions come before the register uses, even on architectures
+ that are normally printed in other orders. For example, the SPARC add
+ instruction: "<tt>add %i1, %i2, %i3</tt>" adds the "%i1", and "%i2" registers
+ and stores the result into the "%i3" register. In the LLVM code generator,
+ the operands should be stored as "<tt>%i3, %i1, %i2</tt>": with the destination
+ first.</p>
+
+ <p>Keeping destination (definition) operands at the beginning of the operand
+ list has several advantages. In particular, the debugging printer will print
+ the instruction like this:</p>
+
+ <div class="doc_code">
+ <pre>
+ %r3 = add %i1, %i2
+ </pre>
+ </div>
+
+ <p>Also if the first operand is a def, it is easier to <a
+ href="#buildmi">create instructions</a> whose only def is the first
+ operand.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="buildmi">Using the <tt>MachineInstrBuilder.h</tt> functions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Machine instructions are created by using the <tt>BuildMI</tt> functions,
+ located in the <tt>include/llvm/CodeGen/MachineInstrBuilder.h</tt> file. The
+ <tt>BuildMI</tt> functions make it easy to build arbitrary machine
+ instructions. Usage of the <tt>BuildMI</tt> functions look like this:</p>
+
+ <div class="doc_code">
+ <pre>
+ // Create a 'DestReg = mov 42' (rendered in X86 assembly as 'mov DestReg, 42')
+ // instruction. The '1' specifies how many operands will be added.
+ MachineInstr *MI = BuildMI(X86::MOV32ri, 1, DestReg).addImm(42);
+
+ // Create the same instr, but insert it at the end of a basic block.
+ MachineBasicBlock &MBB = ...
+ BuildMI(MBB, X86::MOV32ri, 1, DestReg).addImm(42);
+
+ // Create the same instr, but insert it before a specified iterator point.
+ MachineBasicBlock::iterator MBBI = ...
+ BuildMI(MBB, MBBI, X86::MOV32ri, 1, DestReg).addImm(42);
+
+ // Create a 'cmp Reg, 0' instruction, no destination reg.
+ MI = BuildMI(X86::CMP32ri, 2).addReg(Reg).addImm(0);
+ // Create an 'sahf' instruction which takes no operands and stores nothing.
+ MI = BuildMI(X86::SAHF, 0);
+
+ // Create a self looping branch instruction.
+ BuildMI(MBB, X86::JNE, 1).addMBB(&MBB);
+ </pre>
+ </div>
+
+ <p>The key thing to remember with the <tt>BuildMI</tt> functions is that you
+ have to specify the number of operands that the machine instruction will take.
+ This allows for efficient memory allocation. You also need to specify if
+ operands default to be uses of values, not definitions. If you need to add a
+ definition operand (other than the optional destination register), you must
+ explicitly mark it as such:</p>
+
+ <div class="doc_code">
+ <pre>
+ MI.addReg(Reg, MachineOperand::Def);
+ </pre>
+ </div>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="fixedregs">Fixed (preassigned) registers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>One important issue that the code generator needs to be aware of is the
+ presence of fixed registers. In particular, there are often places in the
+ instruction stream where the register allocator <em>must</em> arrange for a
+ particular value to be in a particular register. This can occur due to
+ limitations of the instruction set (e.g., the X86 can only do a 32-bit divide
+ with the <tt>EAX</tt>/<tt>EDX</tt> registers), or external factors like calling
+ conventions. In any case, the instruction selector should emit code that
+ copies a virtual register into or out of a physical register when needed.</p>
+
+ <p>For example, consider this simple LLVM example:</p>
+
+ <div class="doc_code">
+ <pre>
+ int %test(int %X, int %Y) {
+ %Z = div int %X, %Y
+ ret int %Z
+ }
+ </pre>
+ </div>
+
+ <p>The X86 instruction selector produces this machine code for the <tt>div</tt>
+ and <tt>ret</tt> (use
+ "<tt>llc X.bc -march=x86 -print-machineinstrs</tt>" to get this):</p>
+
+ <div class="doc_code">
+ <pre>
+ ;; Start of div
+ %EAX = mov %reg1024 ;; Copy X (in reg1024) into EAX
+ %reg1027 = sar %reg1024, 31
+ %EDX = mov %reg1027 ;; Sign extend X into EDX
+ idiv %reg1025 ;; Divide by Y (in reg1025)
+ %reg1026 = mov %EAX ;; Read the result (Z) out of EAX
+
+ ;; Start of ret
+ %EAX = mov %reg1026 ;; 32-bit return value goes in EAX
+ ret
+ </pre>
+ </div>
+
+ <p>By the end of code generation, the register allocator has coalesced
+ the registers and deleted the resultant identity moves producing the
+ following code:</p>
+
+ <div class="doc_code">
+ <pre>
+ ;; X is in EAX, Y is in ECX
+ mov %EAX, %EDX
+ sar %EDX, 31
+ idiv %ECX
+ ret
+ </pre>
+ </div>
+
+ <p>This approach is extremely general (if it can handle the X86 architecture,
+ it can handle anything!) and allows all of the target specific
+ knowledge about the instruction stream to be isolated in the instruction
+ selector. Note that physical registers should have a short lifetime for good
+ code generation, and all physical registers are assumed dead on entry to and
+ exit from basic blocks (before register allocation). Thus, if you need a value
+ to be live across basic block boundaries, it <em>must</em> live in a virtual
+ register.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ssa">Machine code in SSA form</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>MachineInstr</tt>'s are initially selected in SSA-form, and
+ are maintained in SSA-form until register allocation happens. For the most
+ part, this is trivially simple since LLVM is already in SSA form; LLVM PHI nodes
+ become machine code PHI nodes, and virtual registers are only allowed to have a
+ single definition.</p>
+
+ <p>After register allocation, machine code is no longer in SSA-form because there
+ are no virtual registers left in the code.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="machinebasicblock">The <tt>MachineBasicBlock</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>MachineBasicBlock</tt> class contains a list of machine instructions
+ (<tt><a href="#machineinstr">MachineInstr</a></tt> instances). It roughly
+ corresponds to the LLVM code input to the instruction selector, but there can be
+ a one-to-many mapping (i.e. one LLVM basic block can map to multiple machine
+ basic blocks). The <tt>MachineBasicBlock</tt> class has a
+ "<tt>getBasicBlock</tt>" method, which returns the LLVM basic block that it
+ comes from.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="machinefunction">The <tt>MachineFunction</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>MachineFunction</tt> class contains a list of machine basic blocks
+ (<tt><a href="#machinebasicblock">MachineBasicBlock</a></tt> instances). It
+ corresponds one-to-one with the LLVM function input to the instruction selector.
+ In addition to a list of basic blocks, the <tt>MachineFunction</tt> contains a
+ a <tt>MachineConstantPool</tt>, a <tt>MachineFrameInfo</tt>, a
+ <tt>MachineFunctionInfo</tt>, and a <tt>MachineRegisterInfo</tt>. See
+ <tt>include/llvm/CodeGen/MachineFunction.h</tt> for more information.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="codegenalgs">Target-independent code generation algorithms</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This section documents the phases described in the <a
+ href="#high-level-design">high-level design of the code generator</a>. It
+ explains how they work and some of the rationale behind their design.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="instselect">Instruction Selection</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ Instruction Selection is the process of translating LLVM code presented to the
+ code generator into target-specific machine instructions. There are several
+ well-known ways to do this in the literature. LLVM uses a SelectionDAG based
+ instruction selector.
+ </p>
+
+ <p>Portions of the DAG instruction selector are generated from the target
+ description (<tt>*.td</tt>) files. Our goal is for the entire instruction
+ selector to be generated from these <tt>.td</tt> files, though currently
+ there are still things that require custom C++ code.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_intro">Introduction to SelectionDAGs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The SelectionDAG provides an abstraction for code representation in a way
+ that is amenable to instruction selection using automatic techniques
+ (e.g. dynamic-programming based optimal pattern matching selectors). It is also
+ well-suited to other phases of code generation; in particular,
+ instruction scheduling (SelectionDAG's are very close to scheduling DAGs
+ post-selection). Additionally, the SelectionDAG provides a host representation
+ where a large variety of very-low-level (but target-independent)
+ <a href="#selectiondag_optimize">optimizations</a> may be
+ performed; ones which require extensive information about the instructions
+ efficiently supported by the target.</p>
+
+ <p>The SelectionDAG is a Directed-Acyclic-Graph whose nodes are instances of the
+ <tt>SDNode</tt> class. The primary payload of the <tt>SDNode</tt> is its
+ operation code (Opcode) that indicates what operation the node performs and
+ the operands to the operation.
+ The various operation node types are described at the top of the
+ <tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt> file.</p>
+
+ <p>Although most operations define a single value, each node in the graph may
+ define multiple values. For example, a combined div/rem operation will define
+ both the dividend and the remainder. Many other situations require multiple
+ values as well. Each node also has some number of operands, which are edges
+ to the node defining the used value. Because nodes may define multiple values,
+ edges are represented by instances of the <tt>SDOperand</tt> class, which is
+ a <tt><SDNode, unsigned></tt> pair, indicating the node and result
+ value being used, respectively. Each value produced by an <tt>SDNode</tt> has
+ an associated <tt>MVT::ValueType</tt> indicating what type the value is.</p>
+
+ <p>SelectionDAGs contain two different kinds of values: those that represent
+ data flow and those that represent control flow dependencies. Data values are
+ simple edges with an integer or floating point value type. Control edges are
+ represented as "chain" edges which are of type <tt>MVT::Other</tt>. These edges
+ provide an ordering between nodes that have side effects (such as
+ loads, stores, calls, returns, etc). All nodes that have side effects should
+ take a token chain as input and produce a new one as output. By convention,
+ token chain inputs are always operand #0, and chain results are always the last
+ value produced by an operation.</p>
+
+ <p>A SelectionDAG has designated "Entry" and "Root" nodes. The Entry node is
+ always a marker node with an Opcode of <tt>ISD::EntryToken</tt>. The Root node
+ is the final side-effecting node in the token chain. For example, in a single
+ basic block function it would be the return node.</p>
+
+ <p>One important concept for SelectionDAGs is the notion of a "legal" vs.
+ "illegal" DAG. A legal DAG for a target is one that only uses supported
+ operations and supported types. On a 32-bit PowerPC, for example, a DAG with
+ a value of type i1, i8, i16, or i64 would be illegal, as would a DAG that uses a
+ SREM or UREM operation. The
+ <a href="#selectiondag_legalize">legalize</a> phase is responsible for turning
+ an illegal DAG into a legal DAG.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_process">SelectionDAG Instruction Selection Process</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>SelectionDAG-based instruction selection consists of the following steps:</p>
+
+ <ol>
+ <li><a href="#selectiondag_build">Build initial DAG</a> - This stage
+ performs a simple translation from the input LLVM code to an illegal
+ SelectionDAG.</li>
+ <li><a href="#selectiondag_optimize">Optimize SelectionDAG</a> - This stage
+ performs simple optimizations on the SelectionDAG to simplify it, and
+ recognize meta instructions (like rotates and <tt>div</tt>/<tt>rem</tt>
+ pairs) for targets that support these meta operations. This makes the
+ resultant code more efficient and the <a href="#selectiondag_select">select
+ instructions from DAG</a> phase (below) simpler.</li>
+ <li><a href="#selectiondag_legalize">Legalize SelectionDAG</a> - This stage
+ converts the illegal SelectionDAG to a legal SelectionDAG by eliminating
+ unsupported operations and data types.</li>
+ <li><a href="#selectiondag_optimize">Optimize SelectionDAG (#2)</a> - This
+ second run of the SelectionDAG optimizes the newly legalized DAG to
+ eliminate inefficiencies introduced by legalization.</li>
+ <li><a href="#selectiondag_select">Select instructions from DAG</a> - Finally,
+ the target instruction selector matches the DAG operations to target
+ instructions. This process translates the target-independent input DAG into
+ another DAG of target instructions.</li>
+ <li><a href="#selectiondag_sched">SelectionDAG Scheduling and Formation</a>
+ - The last phase assigns a linear order to the instructions in the
+ target-instruction DAG and emits them into the MachineFunction being
+ compiled. This step uses traditional prepass scheduling techniques.</li>
+ </ol>
+
+ <p>After all of these steps are complete, the SelectionDAG is destroyed and the
+ rest of the code generation passes are run.</p>
+
+ <p>One great way to visualize what is going on here is to take advantage of a
+ few LLC command line options. In particular, the <tt>-view-isel-dags</tt>
+ option pops up a window with the SelectionDAG input to the Select phase for all
+ of the code compiled (if you only get errors printed to the console while using
+ this, you probably <a href="ProgrammersManual.html#ViewGraph">need to configure
+ your system</a> to add support for it). The <tt>-view-sched-dags</tt> option
+ views the SelectionDAG output from the Select phase and input to the Scheduler
+ phase. The <tt>-view-sunit-dags</tt> option views the ScheduleDAG, which is
+ based on the final SelectionDAG, with nodes that must be scheduled as a unit
+ bundled together into a single node, and with immediate operands and other
+ nodes that aren't relevent for scheduling omitted.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_build">Initial SelectionDAG Construction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The initial SelectionDAG is naïvely peephole expanded from the LLVM
+ input by the <tt>SelectionDAGLowering</tt> class in the
+ <tt>lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp</tt> file. The intent of this
+ pass is to expose as much low-level, target-specific details to the SelectionDAG
+ as possible. This pass is mostly hard-coded (e.g. an LLVM <tt>add</tt> turns
+ into an <tt>SDNode add</tt> while a <tt>geteelementptr</tt> is expanded into the
+ obvious arithmetic). This pass requires target-specific hooks to lower calls,
+ returns, varargs, etc. For these features, the
+ <tt><a href="#targetlowering">TargetLowering</a></tt> interface is used.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_legalize">SelectionDAG Legalize Phase</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The Legalize phase is in charge of converting a DAG to only use the types and
+ operations that are natively supported by the target. This involves two major
+ tasks:</p>
+
+ <ol>
+ <li><p>Convert values of unsupported types to values of supported types.</p>
+ <p>There are two main ways of doing this: converting small types to
+ larger types ("promoting"), and breaking up large integer types
+ into smaller ones ("expanding"). For example, a target might require
+ that all f32 values are promoted to f64 and that all i1/i8/i16 values
+ are promoted to i32. The same target might require that all i64 values
+ be expanded into i32 values. These changes can insert sign and zero
+ extensions as needed to make sure that the final code has the same
+ behavior as the input.</p>
+ <p>A target implementation tells the legalizer which types are supported
+ (and which register class to use for them) by calling the
+ <tt>addRegisterClass</tt> method in its TargetLowering constructor.</p>
+ </li>
+
+ <li><p>Eliminate operations that are not supported by the target.</p>
+ <p>Targets often have weird constraints, such as not supporting every
+ operation on every supported datatype (e.g. X86 does not support byte
+ conditional moves and PowerPC does not support sign-extending loads from
+ a 16-bit memory location). Legalize takes care of this by open-coding
+ another sequence of operations to emulate the operation ("expansion"), by
+ promoting one type to a larger type that supports the operation
+ ("promotion"), or by using a target-specific hook to implement the
+ legalization ("custom").</p>
+ <p>A target implementation tells the legalizer which operations are not
+ supported (and which of the above three actions to take) by calling the
+ <tt>setOperationAction</tt> method in its <tt>TargetLowering</tt>
+ constructor.</p>
+ </li>
+ </ol>
+
+ <p>Prior to the existance of the Legalize pass, we required that every target
+ <a href="#selectiondag_optimize">selector</a> supported and handled every
+ operator and type even if they are not natively supported. The introduction of
+ the Legalize phase allows all of the cannonicalization patterns to be shared
+ across targets, and makes it very easy to optimize the cannonicalized code
+ because it is still in the form of a DAG.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_optimize">SelectionDAG Optimization Phase: the DAG
+ Combiner</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The SelectionDAG optimization phase is run twice for code generation: once
+ immediately after the DAG is built and once after legalization. The first run
+ of the pass allows the initial code to be cleaned up (e.g. performing
+ optimizations that depend on knowing that the operators have restricted type
+ inputs). The second run of the pass cleans up the messy code generated by the
+ Legalize pass, which allows Legalize to be very simple (it can focus on making
+ code legal instead of focusing on generating <em>good</em> and legal code).</p>
+
+ <p>One important class of optimizations performed is optimizing inserted sign
+ and zero extension instructions. We currently use ad-hoc techniques, but could
+ move to more rigorous techniques in the future. Here are some good papers on
+ the subject:</p>
+
+ <p>
+ "<a href="http://www.eecs.harvard.edu/~nr/pubs/widen-abstract.html">Widening
+ integer arithmetic</a>"<br>
+ Kevin Redwine and Norman Ramsey<br>
+ International Conference on Compiler Construction (CC) 2004
+ </p>
+
+
+ <p>
+ "<a href="http://portal.acm.org/citation.cfm?doid=512529.512552">Effective
+ sign extension elimination</a>"<br>
+ Motohiro Kawahito, Hideaki Komatsu, and Toshio Nakatani<br>
+ Proceedings of the ACM SIGPLAN 2002 Conference on Programming Language Design
+ and Implementation.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_select">SelectionDAG Select Phase</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The Select phase is the bulk of the target-specific code for instruction
+ selection. This phase takes a legal SelectionDAG as input, pattern matches the
+ instructions supported by the target to this DAG, and produces a new DAG of
+ target code. For example, consider the following LLVM fragment:</p>
+
+ <div class="doc_code">
+ <pre>
+ %t1 = add float %W, %X
+ %t2 = mul float %t1, %Y
+ %t3 = add float %t2, %Z
+ </pre>
+ </div>
+
+ <p>This LLVM code corresponds to a SelectionDAG that looks basically like
+ this:</p>
+
+ <div class="doc_code">
+ <pre>
+ (fadd:f32 (fmul:f32 (fadd:f32 W, X), Y), Z)
+ </pre>
+ </div>
+
+ <p>If a target supports floating point multiply-and-add (FMA) operations, one
+ of the adds can be merged with the multiply. On the PowerPC, for example, the
+ output of the instruction selector might look like this DAG:</p>
+
+ <div class="doc_code">
+ <pre>
+ (FMADDS (FADDS W, X), Y, Z)
+ </pre>
+ </div>
+
+ <p>The <tt>FMADDS</tt> instruction is a ternary instruction that multiplies its
+ first two operands and adds the third (as single-precision floating-point
+ numbers). The <tt>FADDS</tt> instruction is a simple binary single-precision
+ add instruction. To perform this pattern match, the PowerPC backend includes
+ the following instruction definitions:</p>
+
+ <div class="doc_code">
+ <pre>
+ def FMADDS : AForm_1<59, 29,
+ (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRC, F4RC:$FRB),
+ "fmadds $FRT, $FRA, $FRC, $FRB",
+ [<b>(set F4RC:$FRT, (fadd (fmul F4RC:$FRA, F4RC:$FRC),
+ F4RC:$FRB))</b>]>;
+ def FADDS : AForm_2<59, 21,
+ (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRB),
+ "fadds $FRT, $FRA, $FRB",
+ [<b>(set F4RC:$FRT, (fadd F4RC:$FRA, F4RC:$FRB))</b>]>;
+ </pre>
+ </div>
+
+ <p>The portion of the instruction definition in bold indicates the pattern used
+ to match the instruction. The DAG operators (like <tt>fmul</tt>/<tt>fadd</tt>)
+ are defined in the <tt>lib/Target/TargetSelectionDAG.td</tt> file.
+ "<tt>F4RC</tt>" is the register class of the input and result values.<p>
+
+ <p>The TableGen DAG instruction selector generator reads the instruction
+ patterns in the <tt>.td</tt> file and automatically builds parts of the pattern
+ matching code for your target. It has the following strengths:</p>
+
+ <ul>
+ <li>At compiler-compiler time, it analyzes your instruction patterns and tells
+ you if your patterns make sense or not.</li>
+ <li>It can handle arbitrary constraints on operands for the pattern match. In
+ particular, it is straight-forward to say things like "match any immediate
+ that is a 13-bit sign-extended value". For examples, see the
+ <tt>immSExt16</tt> and related <tt>tblgen</tt> classes in the PowerPC
+ backend.</li>
+ <li>It knows several important identities for the patterns defined. For
+ example, it knows that addition is commutative, so it allows the
+ <tt>FMADDS</tt> pattern above to match "<tt>(fadd X, (fmul Y, Z))</tt>" as
+ well as "<tt>(fadd (fmul X, Y), Z)</tt>", without the target author having
+ to specially handle this case.</li>
+ <li>It has a full-featured type-inferencing system. In particular, you should
+ rarely have to explicitly tell the system what type parts of your patterns
+ are. In the <tt>FMADDS</tt> case above, we didn't have to tell
+ <tt>tblgen</tt> that all of the nodes in the pattern are of type 'f32'. It
+ was able to infer and propagate this knowledge from the fact that
+ <tt>F4RC</tt> has type 'f32'.</li>
+ <li>Targets can define their own (and rely on built-in) "pattern fragments".
+ Pattern fragments are chunks of reusable patterns that get inlined into your
+ patterns during compiler-compiler time. For example, the integer
+ "<tt>(not x)</tt>" operation is actually defined as a pattern fragment that
+ expands as "<tt>(xor x, -1)</tt>", since the SelectionDAG does not have a
+ native '<tt>not</tt>' operation. Targets can define their own short-hand
+ fragments as they see fit. See the definition of '<tt>not</tt>' and
+ '<tt>ineg</tt>' for examples.</li>
+ <li>In addition to instructions, targets can specify arbitrary patterns that
+ map to one or more instructions using the 'Pat' class. For example,
+ the PowerPC has no way to load an arbitrary integer immediate into a
+ register in one instruction. To tell tblgen how to do this, it defines:
+ <br>
+ <br>
+ <div class="doc_code">
+ <pre>
+ // Arbitrary immediate support. Implement in terms of LIS/ORI.
+ def : Pat<(i32 imm:$imm),
+ (ORI (LIS (HI16 imm:$imm)), (LO16 imm:$imm))>;
+ </pre>
+ </div>
+ <br>
+ If none of the single-instruction patterns for loading an immediate into a
+ register match, this will be used. This rule says "match an arbitrary i32
+ immediate, turning it into an <tt>ORI</tt> ('or a 16-bit immediate') and an
+ <tt>LIS</tt> ('load 16-bit immediate, where the immediate is shifted to the
+ left 16 bits') instruction". To make this work, the
+ <tt>LO16</tt>/<tt>HI16</tt> node transformations are used to manipulate the
+ input immediate (in this case, take the high or low 16-bits of the
+ immediate).</li>
+ <li>While the system does automate a lot, it still allows you to write custom
+ C++ code to match special cases if there is something that is hard to
+ express.</li>
+ </ul>
+
+ <p>While it has many strengths, the system currently has some limitations,
+ primarily because it is a work in progress and is not yet finished:</p>
+
+ <ul>
+ <li>Overall, there is no way to define or match SelectionDAG nodes that define
+ multiple values (e.g. <tt>ADD_PARTS</tt>, <tt>LOAD</tt>, <tt>CALL</tt>,
+ etc). This is the biggest reason that you currently still <em>have to</em>
+ write custom C++ code for your instruction selector.</li>
+ <li>There is no great way to support matching complex addressing modes yet. In
+ the future, we will extend pattern fragments to allow them to define
+ multiple values (e.g. the four operands of the <a href="#x86_memory">X86
+ addressing mode</a>, which are currently matched with custom C++ code).
+ In addition, we'll extend fragments so that a
+ fragment can match multiple different patterns.</li>
+ <li>We don't automatically infer flags like isStore/isLoad yet.</li>
+ <li>We don't automatically generate the set of supported registers and
+ operations for the <a href="#selectiondag_legalize">Legalizer</a> yet.</li>
+ <li>We don't have a way of tying in custom legalized nodes yet.</li>
+ </ul>
+
+ <p>Despite these limitations, the instruction selector generator is still quite
+ useful for most of the binary and logical operations in typical instruction
+ sets. If you run into any problems or can't figure out how to do something,
+ please let Chris know!</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_sched">SelectionDAG Scheduling and Formation Phase</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The scheduling phase takes the DAG of target instructions from the selection
+ phase and assigns an order. The scheduler can pick an order depending on
+ various constraints of the machines (i.e. order for minimal register pressure or
+ try to cover instruction latencies). Once an order is established, the DAG is
+ converted to a list of <tt><a href="#machineinstr">MachineInstr</a></tt>s and
+ the SelectionDAG is destroyed.</p>
+
+ <p>Note that this phase is logically separate from the instruction selection
+ phase, but is tied to it closely in the code because it operates on
+ SelectionDAGs.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_future">Future directions for the SelectionDAG</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ol>
+ <li>Optional function-at-a-time selection.</li>
+ <li>Auto-generate entire selector from <tt>.td</tt> file.</li>
+ </ol>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="ssamco">SSA-based Machine Code Optimizations</a>
+ </div>
+ <div class="doc_text"><p>To Be Written</p></div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="liveintervals">Live Intervals</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Live Intervals are the ranges (intervals) where a variable is <i>live</i>.
+ They are used by some <a href="#regalloc">register allocator</a> passes to
+ determine if two or more virtual registers which require the same physical
+ register are live at the same point in the program (i.e., they conflict). When
+ this situation occurs, one virtual register must be <i>spilled</i>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="livevariable_analysis">Live Variable Analysis</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The first step in determining the live intervals of variables is to
+ calculate the set of registers that are immediately dead after the
+ instruction (i.e., the instruction calculates the value, but it is
+ never used) and the set of registers that are used by the instruction,
+ but are never used after the instruction (i.e., they are killed). Live
+ variable information is computed for each <i>virtual</i> register and
+ <i>register allocatable</i> physical register in the function. This
+ is done in a very efficient manner because it uses SSA to sparsely
+ compute lifetime information for virtual registers (which are in SSA
+ form) and only has to track physical registers within a block. Before
+ register allocation, LLVM can assume that physical registers are only
+ live within a single basic block. This allows it to do a single,
+ local analysis to resolve physical register lifetimes within each
+ basic block. If a physical register is not register allocatable (e.g.,
+ a stack pointer or condition codes), it is not tracked.</p>
+
+ <p>Physical registers may be live in to or out of a function. Live in values
+ are typically arguments in registers. Live out values are typically return
+ values in registers. Live in values are marked as such, and are given a dummy
+ "defining" instruction during live intervals analysis. If the last basic block
+ of a function is a <tt>return</tt>, then it's marked as using all live out
+ values in the function.</p>
+
+ <p><tt>PHI</tt> nodes need to be handled specially, because the calculation
+ of the live variable information from a depth first traversal of the CFG of
+ the function won't guarantee that a virtual register used by the <tt>PHI</tt>
+ node is defined before it's used. When a <tt>PHI</tt> node is encounted, only
+ the definition is handled, because the uses will be handled in other basic
+ blocks.</p>
+
+ <p>For each <tt>PHI</tt> node of the current basic block, we simulate an
+ assignment at the end of the current basic block and traverse the successor
+ basic blocks. If a successor basic block has a <tt>PHI</tt> node and one of
+ the <tt>PHI</tt> node's operands is coming from the current basic block,
+ then the variable is marked as <i>alive</i> within the current basic block
+ and all of its predecessor basic blocks, until the basic block with the
+ defining instruction is encountered.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="liveintervals_analysis">Live Intervals Analysis</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>We now have the information available to perform the live intervals analysis
+ and build the live intervals themselves. We start off by numbering the basic
+ blocks and machine instructions. We then handle the "live-in" values. These
+ are in physical registers, so the physical register is assumed to be killed by
+ the end of the basic block. Live intervals for virtual registers are computed
+ for some ordering of the machine instructions <tt>[1, N]</tt>. A live interval
+ is an interval <tt>[i, j)</tt>, where <tt>1 <= i <= j < N</tt>, for which a
+ variable is live.</p>
+
+ <p><i><b>More to come...</b></i></p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="regalloc">Register Allocation</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <i>Register Allocation problem</i> consists in mapping a program
+ <i>P<sub>v</sub></i>, that can use an unbounded number of virtual
+ registers, to a program <i>P<sub>p</sub></i> that contains a finite
+ (possibly small) number of physical registers. Each target architecture has
+ a different number of physical registers. If the number of physical
+ registers is not enough to accommodate all the virtual registers, some of
+ them will have to be mapped into memory. These virtuals are called
+ <i>spilled virtuals</i>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+
+ <div class="doc_subsubsection">
+ <a name="regAlloc_represent">How registers are represented in LLVM</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>In LLVM, physical registers are denoted by integer numbers that
+ normally range from 1 to 1023. To see how this numbering is defined
+ for a particular architecture, you can read the
+ <tt>GenRegisterNames.inc</tt> file for that architecture. For
+ instance, by inspecting
+ <tt>lib/Target/X86/X86GenRegisterNames.inc</tt> we see that the 32-bit
+ register <tt>EAX</tt> is denoted by 15, and the MMX register
+ <tt>MM0</tt> is mapped to 48.</p>
+
+ <p>Some architectures contain registers that share the same physical
+ location. A notable example is the X86 platform. For instance, in the
+ X86 architecture, the registers <tt>EAX</tt>, <tt>AX</tt> and
+ <tt>AL</tt> share the first eight bits. These physical registers are
+ marked as <i>aliased</i> in LLVM. Given a particular architecture, you
+ can check which registers are aliased by inspecting its
+ <tt>RegisterInfo.td</tt> file. Moreover, the method
+ <tt>TargetRegisterInfo::getAliasSet(p_reg)</tt> returns an array containing
+ all the physical registers aliased to the register <tt>p_reg</tt>.</p>
+
+ <p>Physical registers, in LLVM, are grouped in <i>Register Classes</i>.
+ Elements in the same register class are functionally equivalent, and can
+ be interchangeably used. Each virtual register can only be mapped to
+ physical registers of a particular class. For instance, in the X86
+ architecture, some virtuals can only be allocated to 8 bit registers.
+ A register class is described by <tt>TargetRegisterClass</tt> objects.
+ To discover if a virtual register is compatible with a given physical,
+ this code can be used:
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ bool RegMapping_Fer::compatible_class(MachineFunction &mf,
+ unsigned v_reg,
+ unsigned p_reg) {
+ assert(TargetRegisterInfo::isPhysicalRegister(p_reg) &&
+ "Target register must be physical");
+ const TargetRegisterClass *trc = mf.getRegInfo().getRegClass(v_reg);
+ return trc->contains(p_reg);
+ }
+ </pre>
+ </div>
+
+ <p>Sometimes, mostly for debugging purposes, it is useful to change
+ the number of physical registers available in the target
+ architecture. This must be done statically, inside the
+ <tt>TargetRegsterInfo.td</tt> file. Just <tt>grep</tt> for
+ <tt>RegisterClass</tt>, the last parameter of which is a list of
+ registers. Just commenting some out is one simple way to avoid them
+ being used. A more polite way is to explicitly exclude some registers
+ from the <i>allocation order</i>. See the definition of the
+ <tt>GR</tt> register class in
+ <tt>lib/Target/IA64/IA64RegisterInfo.td</tt> for an example of this
+ (e.g., <tt>numReservedRegs</tt> registers are hidden.)</p>
+
+ <p>Virtual registers are also denoted by integer numbers. Contrary to
+ physical registers, different virtual registers never share the same
+ number. The smallest virtual register is normally assigned the number
+ 1024. This may change, so, in order to know which is the first virtual
+ register, you should access
+ <tt>TargetRegisterInfo::FirstVirtualRegister</tt>. Any register whose
+ number is greater than or equal to
+ <tt>TargetRegisterInfo::FirstVirtualRegister</tt> is considered a virtual
+ register. Whereas physical registers are statically defined in a
+ <tt>TargetRegisterInfo.td</tt> file and cannot be created by the
+ application developer, that is not the case with virtual registers.
+ In order to create new virtual registers, use the method
+ <tt>MachineRegisterInfo::createVirtualRegister()</tt>. This method will return a
+ virtual register with the highest code.
+ </p>
+
+ <p>Before register allocation, the operands of an instruction are
+ mostly virtual registers, although physical registers may also be
+ used. In order to check if a given machine operand is a register, use
+ the boolean function <tt>MachineOperand::isRegister()</tt>. To obtain
+ the integer code of a register, use
+ <tt>MachineOperand::getReg()</tt>. An instruction may define or use a
+ register. For instance, <tt>ADD reg:1026 := reg:1025 reg:1024</tt>
+ defines the registers 1024, and uses registers 1025 and 1026. Given a
+ register operand, the method <tt>MachineOperand::isUse()</tt> informs
+ if that register is being used by the instruction. The method
+ <tt>MachineOperand::isDef()</tt> informs if that registers is being
+ defined.</p>
+
+ <p>We will call physical registers present in the LLVM bitcode before
+ register allocation <i>pre-colored registers</i>. Pre-colored
+ registers are used in many different situations, for instance, to pass
+ parameters of functions calls, and to store results of particular
+ instructions. There are two types of pre-colored registers: the ones
+ <i>implicitly</i> defined, and those <i>explicitly</i>
+ defined. Explicitly defined registers are normal operands, and can be
+ accessed with <tt>MachineInstr::getOperand(int)::getReg()</tt>. In
+ order to check which registers are implicitly defined by an
+ instruction, use the
+ <tt>TargetInstrInfo::get(opcode)::ImplicitDefs</tt>, where
+ <tt>opcode</tt> is the opcode of the target instruction. One important
+ difference between explicit and implicit physical registers is that
+ the latter are defined statically for each instruction, whereas the
+ former may vary depending on the program being compiled. For example,
+ an instruction that represents a function call will always implicitly
+ define or use the same set of physical registers. To read the
+ registers implicitly used by an instruction, use
+ <tt>TargetInstrInfo::get(opcode)::ImplicitUses</tt>. Pre-colored
+ registers impose constraints on any register allocation algorithm. The
+ register allocator must make sure that none of them is been
+ overwritten by the values of virtual registers while still alive.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+
+ <div class="doc_subsubsection">
+ <a name="regAlloc_howTo">Mapping virtual registers to physical registers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>There are two ways to map virtual registers to physical registers (or to
+ memory slots). The first way, that we will call <i>direct mapping</i>,
+ is based on the use of methods of the classes <tt>TargetRegisterInfo</tt>,
+ and <tt>MachineOperand</tt>. The second way, that we will call
+ <i>indirect mapping</i>, relies on the <tt>VirtRegMap</tt> class in
+ order to insert loads and stores sending and getting values to and from
+ memory.</p>
+
+ <p>The direct mapping provides more flexibility to the developer of
+ the register allocator; however, it is more error prone, and demands
+ more implementation work. Basically, the programmer will have to
+ specify where load and store instructions should be inserted in the
+ target function being compiled in order to get and store values in
+ memory. To assign a physical register to a virtual register present in
+ a given operand, use <tt>MachineOperand::setReg(p_reg)</tt>. To insert
+ a store instruction, use
+ <tt>TargetRegisterInfo::storeRegToStackSlot(...)</tt>, and to insert a load
+ instruction, use <tt>TargetRegisterInfo::loadRegFromStackSlot</tt>.</p>
+
+ <p>The indirect mapping shields the application developer from the
+ complexities of inserting load and store instructions. In order to map
+ a virtual register to a physical one, use
+ <tt>VirtRegMap::assignVirt2Phys(vreg, preg)</tt>. In order to map a
+ certain virtual register to memory, use
+ <tt>VirtRegMap::assignVirt2StackSlot(vreg)</tt>. This method will
+ return the stack slot where <tt>vreg</tt>'s value will be located. If
+ it is necessary to map another virtual register to the same stack
+ slot, use <tt>VirtRegMap::assignVirt2StackSlot(vreg,
+ stack_location)</tt>. One important point to consider when using the
+ indirect mapping, is that even if a virtual register is mapped to
+ memory, it still needs to be mapped to a physical register. This
+ physical register is the location where the virtual register is
+ supposed to be found before being stored or after being reloaded.</p>
+
+ <p>If the indirect strategy is used, after all the virtual registers
+ have been mapped to physical registers or stack slots, it is necessary
+ to use a spiller object to place load and store instructions in the
+ code. Every virtual that has been mapped to a stack slot will be
+ stored to memory after been defined and will be loaded before being
+ used. The implementation of the spiller tries to recycle load/store
+ instructions, avoiding unnecessary instructions. For an example of how
+ to invoke the spiller, see
+ <tt>RegAllocLinearScan::runOnMachineFunction</tt> in
+ <tt>lib/CodeGen/RegAllocLinearScan.cpp</tt>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="regAlloc_twoAddr">Handling two address instructions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>With very rare exceptions (e.g., function calls), the LLVM machine
+ code instructions are three address instructions. That is, each
+ instruction is expected to define at most one register, and to use at
+ most two registers. However, some architectures use two address
+ instructions. In this case, the defined register is also one of the
+ used register. For instance, an instruction such as <tt>ADD %EAX,
+ %EBX</tt>, in X86 is actually equivalent to <tt>%EAX = %EAX +
+ %EBX</tt>.</p>
+
+ <p>In order to produce correct code, LLVM must convert three address
+ instructions that represent two address instructions into true two
+ address instructions. LLVM provides the pass
+ <tt>TwoAddressInstructionPass</tt> for this specific purpose. It must
+ be run before register allocation takes place. After its execution,
+ the resulting code may no longer be in SSA form. This happens, for
+ instance, in situations where an instruction such as <tt>%a = ADD %b
+ %c</tt> is converted to two instructions such as:</p>
+
+ <div class="doc_code">
+ <pre>
+ %a = MOVE %b
+ %a = ADD %a %b
+ </pre>
+ </div>
+
+ <p>Notice that, internally, the second instruction is represented as
+ <tt>ADD %a[def/use] %b</tt>. I.e., the register operand <tt>%a</tt> is
+ both used and defined by the instruction.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="regAlloc_ssaDecon">The SSA deconstruction phase</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>An important transformation that happens during register allocation is called
+ the <i>SSA Deconstruction Phase</i>. The SSA form simplifies many
+ analyses that are performed on the control flow graph of
+ programs. However, traditional instruction sets do not implement
+ PHI instructions. Thus, in order to generate executable code, compilers
+ must replace PHI instructions with other instructions that preserve their
+ semantics.</p>
+
+ <p>There are many ways in which PHI instructions can safely be removed
+ from the target code. The most traditional PHI deconstruction
+ algorithm replaces PHI instructions with copy instructions. That is
+ the strategy adopted by LLVM. The SSA deconstruction algorithm is
+ implemented in n<tt>lib/CodeGen/>PHIElimination.cpp</tt>. In order to
+ invoke this pass, the identifier <tt>PHIEliminationID</tt> must be
+ marked as required in the code of the register allocator.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="regAlloc_fold">Instruction folding</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><i>Instruction folding</i> is an optimization performed during
+ register allocation that removes unnecessary copy instructions. For
+ instance, a sequence of instructions such as:</p>
+
+ <div class="doc_code">
+ <pre>
+ %EBX = LOAD %mem_address
+ %EAX = COPY %EBX
+ </pre>
+ </div>
+
+ <p>can be safely substituted by the single instruction:
+
+ <div class="doc_code">
+ <pre>
+ %EAX = LOAD %mem_address
+ </pre>
+ </div>
+
+ <p>Instructions can be folded with the
+ <tt>TargetRegisterInfo::foldMemoryOperand(...)</tt> method. Care must be
+ taken when folding instructions; a folded instruction can be quite
+ different from the original instruction. See
+ <tt>LiveIntervals::addIntervalsForSpills</tt> in
+ <tt>lib/CodeGen/LiveIntervalAnalysis.cpp</tt> for an example of its use.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+
+ <div class="doc_subsubsection">
+ <a name="regAlloc_builtIn">Built in register allocators</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The LLVM infrastructure provides the application developer with
+ three different register allocators:</p>
+
+ <ul>
+ <li><i>Simple</i> - This is a very simple implementation that does
+ not keep values in registers across instructions. This register
+ allocator immediately spills every value right after it is
+ computed, and reloads all used operands from memory to temporary
+ registers before each instruction.</li>
+ <li><i>Local</i> - This register allocator is an improvement on the
+ <i>Simple</i> implementation. It allocates registers on a basic
+ block level, attempting to keep values in registers and reusing
+ registers as appropriate.</li>
+ <li><i>Linear Scan</i> - <i>The default allocator</i>. This is the
+ well-know linear scan register allocator. Whereas the
+ <i>Simple</i> and <i>Local</i> algorithms use a direct mapping
+ implementation technique, the <i>Linear Scan</i> implementation
+ uses a spiller in order to place load and stores.</li>
+ </ul>
+
+ <p>The type of register allocator used in <tt>llc</tt> can be chosen with the
+ command line option <tt>-regalloc=...</tt>:</p>
+
+ <div class="doc_code">
+ <pre>
+ $ llc -f -regalloc=simple file.bc -o sp.s;
+ $ llc -f -regalloc=local file.bc -o lc.s;
+ $ llc -f -regalloc=linearscan file.bc -o ln.s;
+ </pre>
+ </div>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="proepicode">Prolog/Epilog Code Insertion</a>
+ </div>
+ <div class="doc_text"><p>To Be Written</p></div>
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="latemco">Late Machine Code Optimizations</a>
+ </div>
+ <div class="doc_text"><p>To Be Written</p></div>
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="codeemit">Code Emission</a>
+ </div>
+ <div class="doc_text"><p>To Be Written</p></div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="codeemit_asm">Generating Assembly Code</a>
+ </div>
+ <div class="doc_text"><p>To Be Written</p></div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="codeemit_bin">Generating Binary Machine Code</a>
+ </div>
+
+ <div class="doc_text">
+ <p>For the JIT or <tt>.o</tt> file writer</p>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="targetimpls">Target-specific Implementation Notes</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This section of the document explains features or design decisions that
+ are specific to the code generator for a particular target.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="tailcallopt">Tail call optimization</a>
+ </div>
+
+ <div class="doc_text">
+ <p>Tail call optimization, callee reusing the stack of the caller, is currently supported on x86/x86-64 and PowerPC. It is performed if:
+ <ul>
+ <li>Caller and callee have the calling convention <tt>fastcc</tt>.</li>
+ <li>The call is a tail call - in tail position (ret immediately follows call and ret uses value of call or is void).</li>
+ <li>Option <tt>-tailcallopt</tt> is enabled.</li>
+ <li>Platform specific constraints are met.</li>
+ </ul>
+ </p>
+
+ <p>x86/x86-64 constraints:
+ <ul>
+ <li>No variable argument lists are used.</li>
+ <li>On x86-64 when generating GOT/PIC code only module-local calls (visibility = hidden or protected) are supported.</li>
+ </ul>
+ </p>
+ <p>PowerPC constraints:
+ <ul>
+ <li>No variable argument lists are used.</li>
+ <li>No byval parameters are used.</li>
+ <li>On ppc32/64 GOT/PIC only module-local calls (visibility = hidden or protected) are supported.</li>
+ </ul>
+ </p>
+ <p>Example:</p>
+ <p>Call as <tt>llc -tailcallopt test.ll</tt>.
+ <div class="doc_code">
+ <pre>
+ declare fastcc i32 @tailcallee(i32 inreg %a1, i32 inreg %a2, i32 %a3, i32 %a4)
+
+ define fastcc i32 @tailcaller(i32 %in1, i32 %in2) {
+ %l1 = add i32 %in1, %in2
+ %tmp = tail call fastcc i32 @tailcallee(i32 %in1 inreg, i32 %in2 inreg, i32 %in1, i32 %l1)
+ ret i32 %tmp
+ }</pre>
+ </div>
+ </p>
+ <p>Implications of <tt>-tailcallopt</tt>:</p>
+ <p>To support tail call optimization in situations where the callee has more arguments than the caller a 'callee pops arguments' convention is used. This currently causes each <tt>fastcc</tt> call that is not tail call optimized (because one or more of above constraints are not met) to be followed by a readjustment of the stack. So performance might be worse in such cases.</p>
+ <p>On x86 and x86-64 one register is reserved for indirect tail calls (e.g via a function pointer). So there is one less register for integer argument passing. For x86 this means 2 registers (if <tt>inreg</tt> parameter attribute is used) and for x86-64 this means 5 register are used.</p>
+ </div>
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="x86">The X86 backend</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The X86 code generator lives in the <tt>lib/Target/X86</tt> directory. This
+ code generator is capable of targeting a variety of x86-32 and x86-64
+ processors, and includes support for ISA extensions such as MMX and SSE.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="x86_tt">X86 Target Triples Supported</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The following are the known target triples that are supported by the X86
+ backend. This is not an exhaustive list, and it would be useful to add those
+ that people test.</p>
+
+ <ul>
+ <li><b>i686-pc-linux-gnu</b> - Linux</li>
+ <li><b>i386-unknown-freebsd5.3</b> - FreeBSD 5.3</li>
+ <li><b>i686-pc-cygwin</b> - Cygwin on Win32</li>
+ <li><b>i686-pc-mingw32</b> - MingW on Win32</li>
+ <li><b>i386-pc-mingw32msvc</b> - MingW crosscompiler on Linux</li>
+ <li><b>i686-apple-darwin*</b> - Apple Darwin on X86</li>
+ </ul>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="x86_cc">X86 Calling Conventions supported</a>
+ </div>
+
+
+ <div class="doc_text">
+
+ <p>The folowing target-specific calling conventions are known to backend:</p>
+
+ <ul>
+ <li><b>x86_StdCall</b> - stdcall calling convention seen on Microsoft Windows
+ platform (CC ID = 64).</li>
+ <li><b>x86_FastCall</b> - fastcall calling convention seen on Microsoft Windows
+ platform (CC ID = 65).</li>
+ </ul>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="x86_memory">Representing X86 addressing modes in MachineInstrs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The x86 has a very flexible way of accessing memory. It is capable of
+ forming memory addresses of the following expression directly in integer
+ instructions (which use ModR/M addressing):</p>
+
+ <div class="doc_code">
+ <pre>
+ Base + [1,2,4,8] * IndexReg + Disp32
+ </pre>
+ </div>
+
+ <p>In order to represent this, LLVM tracks no less than 4 operands for each
+ memory operand of this form. This means that the "load" form of '<tt>mov</tt>'
+ has the following <tt>MachineOperand</tt>s in this order:</p>
+
+ <pre>
+ Index: 0 | 1 2 3 4
+ Meaning: DestReg, | BaseReg, Scale, IndexReg, Displacement
+ OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg, SignExtImm
+ </pre>
+
+ <p>Stores, and all other instructions, treat the four memory operands in the
+ same way and in the same order.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="x86_names">Instruction naming</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>An instruction name consists of the base name, a default operand size, and a
+ a character per operand with an optional special size. For example:</p>
+
+ <p>
+ <tt>ADD8rr</tt> -> add, 8-bit register, 8-bit register<br>
+ <tt>IMUL16rmi</tt> -> imul, 16-bit register, 16-bit memory, 16-bit immediate<br>
+ <tt>IMUL16rmi8</tt> -> imul, 16-bit register, 16-bit memory, 8-bit immediate<br>
+ <tt>MOVSX32rm16</tt> -> movsx, 32-bit register, 16-bit memory
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="ppc">The PowerPC backend</a>
+ </div>
+
+ <div class="doc_text">
+ <p>The PowerPC code generator lives in the lib/Target/PowerPC directory. The
+ code generation is retargetable to several variations or <i>subtargets</i> of
+ the PowerPC ISA; including ppc32, ppc64 and altivec.
+ </p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ppc_abi">LLVM PowerPC ABI</a>
+ </div>
+
+ <div class="doc_text">
+ <p>LLVM follows the AIX PowerPC ABI, with two deviations. LLVM uses a PC
+ relative (PIC) or static addressing for accessing global values, so no TOC (r2)
+ is used. Second, r31 is used as a frame pointer to allow dynamic growth of a
+ stack frame. LLVM takes advantage of having no TOC to provide space to save
+ the frame pointer in the PowerPC linkage area of the caller frame. Other
+ details of PowerPC ABI can be found at <a href=
+ "http://developer.apple.com/documentation/DeveloperTools/Conceptual/LowLevelABI/Articles/32bitPowerPC.html"
+ >PowerPC ABI.</a> Note: This link describes the 32 bit ABI. The
+ 64 bit ABI is similar except space for GPRs are 8 bytes wide (not 4) and r13 is
+ reserved for system use.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ppc_frame">Frame Layout</a>
+ </div>
+
+ <div class="doc_text">
+ <p>The size of a PowerPC frame is usually fixed for the duration of a
+ function’s invocation. Since the frame is fixed size, all references into
+ the frame can be accessed via fixed offsets from the stack pointer. The
+ exception to this is when dynamic alloca or variable sized arrays are present,
+ then a base pointer (r31) is used as a proxy for the stack pointer and stack
+ pointer is free to grow or shrink. A base pointer is also used if llvm-gcc is
+ not passed the -fomit-frame-pointer flag. The stack pointer is always aligned to
+ 16 bytes, so that space allocated for altivec vectors will be properly
+ aligned.</p>
+ <p>An invocation frame is layed out as follows (low memory at top);</p>
+ </div>
+
+ <div class="doc_text">
+ <table class="layout">
+ <tr>
+ <td>Linkage<br><br></td>
+ </tr>
+ <tr>
+ <td>Parameter area<br><br></td>
+ </tr>
+ <tr>
+ <td>Dynamic area<br><br></td>
+ </tr>
+ <tr>
+ <td>Locals area<br><br></td>
+ </tr>
+ <tr>
+ <td>Saved registers area<br><br></td>
+ </tr>
+ <tr style="border-style: none hidden none hidden;">
+ <td><br></td>
+ </tr>
+ <tr>
+ <td>Previous Frame<br><br></td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="doc_text">
+ <p>The <i>linkage</i> area is used by a callee to save special registers prior
+ to allocating its own frame. Only three entries are relevant to LLVM. The
+ first entry is the previous stack pointer (sp), aka link. This allows probing
+ tools like gdb or exception handlers to quickly scan the frames in the stack. A
+ function epilog can also use the link to pop the frame from the stack. The
+ third entry in the linkage area is used to save the return address from the lr
+ register. Finally, as mentioned above, the last entry is used to save the
+ previous frame pointer (r31.) The entries in the linkage area are the size of a
+ GPR, thus the linkage area is 24 bytes long in 32 bit mode and 48 bytes in 64
+ bit mode.</p>
+ </div>
+
+ <div class="doc_text">
+ <p>32 bit linkage area</p>
+ <table class="layout">
+ <tr>
+ <td>0</td>
+ <td>Saved SP (r1)</td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td>Saved CR</td>
+ </tr>
+ <tr>
+ <td>8</td>
+ <td>Saved LR</td>
+ </tr>
+ <tr>
+ <td>12</td>
+ <td>Reserved</td>
+ </tr>
+ <tr>
+ <td>16</td>
+ <td>Reserved</td>
+ </tr>
+ <tr>
+ <td>20</td>
+ <td>Saved FP (r31)</td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="doc_text">
+ <p>64 bit linkage area</p>
+ <table class="layout">
+ <tr>
+ <td>0</td>
+ <td>Saved SP (r1)</td>
+ </tr>
+ <tr>
+ <td>8</td>
+ <td>Saved CR</td>
+ </tr>
+ <tr>
+ <td>16</td>
+ <td>Saved LR</td>
+ </tr>
+ <tr>
+ <td>24</td>
+ <td>Reserved</td>
+ </tr>
+ <tr>
+ <td>32</td>
+ <td>Reserved</td>
+ </tr>
+ <tr>
+ <td>40</td>
+ <td>Saved FP (r31)</td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="doc_text">
+ <p>The <i>parameter area</i> is used to store arguments being passed to a callee
+ function. Following the PowerPC ABI, the first few arguments are actually
+ passed in registers, with the space in the parameter area unused. However, if
+ there are not enough registers or the callee is a thunk or vararg function,
+ these register arguments can be spilled into the parameter area. Thus, the
+ parameter area must be large enough to store all the parameters for the largest
+ call sequence made by the caller. The size must also be mimimally large enough
+ to spill registers r3-r10. This allows callees blind to the call signature,
+ such as thunks and vararg functions, enough space to cache the argument
+ registers. Therefore, the parameter area is minimally 32 bytes (64 bytes in 64
+ bit mode.) Also note that since the parameter area is a fixed offset from the
+ top of the frame, that a callee can access its spilt arguments using fixed
+ offsets from the stack pointer (or base pointer.)</p>
+ </div>
+
+ <div class="doc_text">
+ <p>Combining the information about the linkage, parameter areas and alignment. A
+ stack frame is minimally 64 bytes in 32 bit mode and 128 bytes in 64 bit
+ mode.</p>
+ </div>
+
+ <div class="doc_text">
+ <p>The <i>dynamic area</i> starts out as size zero. If a function uses dynamic
+ alloca then space is added to the stack, the linkage and parameter areas are
+ shifted to top of stack, and the new space is available immediately below the
+ linkage and parameter areas. The cost of shifting the linkage and parameter
+ areas is minor since only the link value needs to be copied. The link value can
+ be easily fetched by adding the original frame size to the base pointer. Note
+ that allocations in the dynamic space need to observe 16 byte aligment.</p>
+ </div>
+
+ <div class="doc_text">
+ <p>The <i>locals area</i> is where the llvm compiler reserves space for local
+ variables.</p>
+ </div>
+
+ <div class="doc_text">
+ <p>The <i>saved registers area</i> is where the llvm compiler spills callee saved
+ registers on entry to the callee.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ppc_prolog">Prolog/Epilog</a>
+ </div>
+
+ <div class="doc_text">
+ <p>The llvm prolog and epilog are the same as described in the PowerPC ABI, with
+ the following exceptions. Callee saved registers are spilled after the frame is
+ created. This allows the llvm epilog/prolog support to be common with other
+ targets. The base pointer callee saved register r31 is saved in the TOC slot of
+ linkage area. This simplifies allocation of space for the base pointer and
+ makes it convenient to locate programatically and during debugging.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ppc_dynamic">Dynamic Allocation</a>
+ </div>
+
+ <div class="doc_text">
+ <p></p>
+ </div>
+
+ <div class="doc_text">
+ <p><i>TODO - More to come.</i></p>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/CodingStandards.html
diff -c /dev/null llvm-www/releases/2.3/docs/CodingStandards.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/CodingStandards.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,767 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ <title>A Few Coding Standards</title>
+ </head>
+ <body>
+
+ <div class="doc_title">
+ A Few Coding Standards
+ </div>
+
+ <ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#mechanicalissues">Mechanical Source Issues</a>
+ <ol>
+ <li><a href="#sourceformating">Source Code Formatting</a>
+ <ol>
+ <li><a href="#scf_commenting">Commenting</a></li>
+ <li><a href="#scf_commentformat">Comment Formatting</a></li>
+ <li><a href="#scf_includes"><tt>#include</tt> Style</a></li>
+ <li><a href="#scf_codewidth">Source Code Width</a></li>
+ <li><a href="#scf_spacestabs">Use Spaces Instead of Tabs</a></li>
+ <li><a href="#scf_indentation">Indent Code Consistently</a></li>
+ </ol></li>
+ <li><a href="#compilerissues">Compiler Issues</a>
+ <ol>
+ <li><a href="#ci_warningerrors">Treat Compiler Warnings Like
+ Errors</a></li>
+ <li><a href="#ci_portable_code">Write Portable Code</a></li>
+ <li><a href="#ci_class_struct">Use of class/struct Keywords</a></li>
+ </ol></li>
+ </ol></li>
+ <li><a href="#styleissues">Style Issues</a>
+ <ol>
+ <li><a href="#macro">The High Level Issues</a>
+ <ol>
+ <li><a href="#hl_module">A Public Header File <b>is</b> a
+ Module</a></li>
+ <li><a href="#hl_dontinclude">#include as Little as Possible</a></li>
+ <li><a href="#hl_privateheaders">Keep "internal" Headers
+ Private</a></li>
+ <li><a href="#ll_iostream"><tt>#include <iostream></tt> is
+ <em>forbidden</em></a></li>
+ </ol></li>
+ <li><a href="#micro">The Low Level Issues</a>
+ <ol>
+ <li><a href="#ll_assert">Assert Liberally</a></li>
+ <li><a href="#ll_ns_std">Do not use 'using namespace std'</a></li>
+ <li><a href="#ll_virtual_anch">Provide a virtual method anchor for
+ classes in headers</a></li>
+ <li><a href="#ll_preincrement">Prefer Preincrement</a></li>
+ <li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
+ </ol></li>
+ </ol></li>
+ <li><a href="#seealso">See Also</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a> and
+ <a href="mailto:void at nondot.org">Bill Wendling</a></p>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This document attempts to describe a few coding standards that are being used
+ in the LLVM source tree. Although no coding standards should be regarded as
+ absolute requirements to be followed in all instances, coding standards can be
+ useful.</p>
+
+ <p>This document intentionally does not prescribe fixed standards for religious
+ issues such as brace placement and space usage. For issues like this, follow
+ the golden rule:</p>
+
+ <blockquote>
+
+ <p><b><a name="goldenrule">If you are adding a significant body of source to a
+ project, feel free to use whatever style you are most comfortable with. If you
+ are extending, enhancing, or bug fixing already implemented code, use the style
+ that is already being used so that the source is uniform and easy to
+ follow.</a></b></p>
+
+ </blockquote>
+
+ <p>The ultimate goal of these guidelines is the increase readability and
+ maintainability of our common source base. If you have suggestions for topics to
+ be included, please mail them to <a
+ href="mailto:sabre at nondot.org">Chris</a>.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="mechanicalissues">Mechanical Source Issues</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="sourceformating">Source Code Formatting</a>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="scf_commenting">Commenting</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Comments are one critical part of readability and maintainability. Everyone
+ knows they should comment, so should you. Although we all should probably
+ comment our code more than we do, there are a few very critical places that
+ documentation is very useful:</p>
+
+ <b>File Headers</b>
+
+ <p>Every source file should have a header on it that describes the basic
+ purpose of the file. If a file does not have a header, it should not be
+ checked into Subversion. Most source trees will probably have a standard
+ file header format. The standard format for the LLVM source tree looks like
+ this:</p>
+
+ <div class="doc_code">
+ <pre>
+ //===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
+ //
+ // The LLVM Compiler Infrastructure
+ //
+ // This file is distributed under the University of Illinois Open Source
+ // License. See LICENSE.TXT for details.
+ //
+ //===----------------------------------------------------------------------===//
+ //
+ // This file contains the declaration of the Instruction class, which is the
+ // base class for all of the VM instructions.
+ //
+ //===----------------------------------------------------------------------===//
+ </pre>
+ </div>
+
+ <p>A few things to note about this particular format: The "<tt>-*- C++
+ -*-</tt>" string on the first line is there to tell Emacs that the source file
+ is a C++ file, not a C file (Emacs assumes .h files are C files by default).
+ Note that this tag is not necessary in .cpp files. The name of the file is also
+ on the first line, along with a very short description of the purpose of the
+ file. This is important when printing out code and flipping though lots of
+ pages.</p>
+
+ <p>The next section in the file is a concise note that defines the license
+ that the file is released under. This makes it perfectly clear what terms the
+ source code can be distributed under and should not be modified in any way.</p>
+
+ <p>The main body of the description does not have to be very long in most cases.
+ Here it's only two lines. If an algorithm is being implemented or something
+ tricky is going on, a reference to the paper where it is published should be
+ included, as well as any notes or "gotchas" in the code to watch out for.</p>
+
+ <b>Class overviews</b>
+
+ <p>Classes are one fundamental part of a good object oriented design. As such,
+ a class definition should have a comment block that explains what the class is
+ used for... if it's not obvious. If it's so completely obvious your grandma
+ could figure it out, it's probably safe to leave it out. Naming classes
+ something sane goes a long ways towards avoiding writing documentation.</p>
+
+
+ <b>Method information</b>
+
+ <p>Methods defined in a class (as well as any global functions) should also be
+ documented properly. A quick note about what it does any a description of the
+ borderline behaviour is all that is necessary here (unless something
+ particularly tricky or insideous is going on). The hope is that people can
+ figure out how to use your interfaces without reading the code itself... that is
+ the goal metric.</p>
+
+ <p>Good things to talk about here are what happens when something unexpected
+ happens: does the method return null? Abort? Format your hard disk?</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="scf_commentformat">Comment Formatting</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space,
+ require less typing, don't have nesting problems, etc. There are a few cases
+ when it is useful to use C style (<tt>/* */</tt>) comments however:</p>
+
+ <ol>
+ <li>When writing a C code: Obviously if you are writing C code, use C style
+ comments.</li>
+ <li>When writing a header file that may be <tt>#include</tt>d by a C source
+ file.</li>
+ <li>When writing a source file that is used by a tool that only accepts C
+ style comments.</li>
+ </ol>
+
+ <p>To comment out a large block of code, use <tt>#if 0</tt> and <tt>#endif</tt>.
+ These nest properly and are better behaved in general than C style comments.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="scf_includes"><tt>#include</tt> Style</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Immediately after the <a href="#scf_commenting">header file comment</a> (and
+ include guards if working on a header file), the <a
+ href="#hl_dontinclude">minimal</a> list of <tt>#include</tt>s required by the
+ file should be listed. We prefer these <tt>#include</tt>s to be listed in this
+ order:</p>
+
+ <ol>
+ <li><a href="#mmheader">Main Module header</a></li>
+ <li><a href="#hl_privateheaders">Local/Private Headers</a></li>
+ <li><tt>llvm/*</tt></li>
+ <li><tt>llvm/Analysis/*</tt></li>
+ <li><tt>llvm/Assembly/*</tt></li>
+ <li><tt>llvm/Bytecode/*</tt></li>
+ <li><tt>llvm/CodeGen/*</tt></li>
+ <li>...</li>
+ <li><tt>Support/*</tt></li>
+ <li><tt>Config/*</tt></li>
+ <li>System <tt>#includes</tt></li>
+ </ol>
+
+ <p>... and each catagory should be sorted by name.</p>
+
+ <p><a name="mmheader">The "Main Module Header"</a> file applies to .cpp file
+ which implement an interface defined by a .h file. This <tt>#include</tt>
+ should always be included <b>first</b> regardless of where it lives on the file
+ system. By including a header file first in the .cpp files that implement the
+ interfaces, we ensure that the header does not have any hidden dependencies
+ which are not explicitly #included in the header, but should be. It is also a
+ form of documentation in the .cpp file to indicate where the interfaces it
+ implements are defined.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="scf_codewidth">Source Code Width</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Write your code to fit within 80 columns of text. This helps those of us who
+ like to print out code and look at your code in an xterm without resizing
+ it.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>In all cases, prefer spaces to tabs in source files. People have different
+ prefered indentation levels, and different styles of indentation that they
+ like... this is fine. What isn't is that different editors/viewers expand tabs
+ out to different tab stops. This can cause your code to look completely
+ unreadable, and it is not worth dealing with.</p>
+
+ <p>As always, follow the <a href="#goldenrule">Golden Rule</a> above: follow the
+ style of existing code if your are modifying and extending it. If you like four
+ spaces of indentation, <b>DO NOT</b> do that in the middle of a chunk of code
+ with two spaces of indentation. Also, do not reindent a whole source file: it
+ makes for incredible diffs that are absolutely worthless.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="scf_indentation">Indent Code Consistently</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Okay, your first year of programming you were told that indentation is
+ important. If you didn't believe and internalize this then, now is the time.
+ Just do it.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="compilerissues">Compiler Issues</a>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If your code has compiler warnings in it, something is wrong: you aren't
+ casting values correctly, your have "questionable" constructs in your code, or
+ you are doing something legitimately wrong. Compiler warnings can cover up
+ legitimate errors in output and make dealing with a translation unit
+ difficult.</p>
+
+ <p>It is not possible to prevent all warnings from all compilers, nor is it
+ desirable. Instead, pick a standard compiler (like <tt>gcc</tt>) that provides
+ a good thorough set of warnings, and stick to them. At least in the case of
+ <tt>gcc</tt>, it is possible to work around any spurious errors by changing the
+ syntax of the code slightly. For example, an warning that annoys me occurs when
+ I write code like this:</p>
+
+ <div class="doc_code">
+ <pre>
+ if (V = getValue()) {
+ ...
+ }
+ </pre>
+ </div>
+
+ <p><tt>gcc</tt> will warn me that I probably want to use the <tt>==</tt>
+ operator, and that I probably mistyped it. In most cases, I haven't, and I
+ really don't want the spurious errors. To fix this particular problem, I
+ rewrite the code like this:</p>
+
+ <div class="doc_code">
+ <pre>
+ if ((V = getValue())) {
+ ...
+ }
+ </pre>
+ </div>
+
+ <p>...which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can
+ be fixed by massaging the code appropriately.</p>
+
+ <p>These are the <tt>gcc</tt> warnings that I prefer to enable: <tt>-Wall
+ -Winline -W -Wwrite-strings -Wno-unused</tt></p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ci_portable_code">Write Portable Code</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>In almost all cases, it is possible and within reason to write completely
+ portable code. If there are cases where it isn't possible to write portable
+ code, isolate it behind a well defined (and well documented) interface.</p>
+
+ <p>In practice, this means that you shouldn't assume much about the host
+ compiler, including its support for "high tech" features like partial
+ specialization of templates. In fact, Visual C++ 6 could be an important target
+ for our work in the future, and we don't want to have to rewrite all of our code
+ to support it.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
+ </div>
+ <div class="doc_text">
+
+ <p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost
+ interchangeably. The only difference is when they are used to declare a class:
+ <tt>class</tt> makes all members private by default while <tt>struct</tt> makes
+ all members public by default.</p>
+
+ <p>Unfortunately, not all compilers follow the rules and some will generate
+ different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to
+ declare the symbol. This can lead to problems at link time.</p>
+
+ <p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless
+ <b>all</b> members are public, in which case <tt>struct</tt> is allowed.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="styleissues">Style Issues</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="macro">The High Level Issues</a>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="hl_module">A Public Header File <b>is</b> a Module</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>C++ doesn't do too well in the modularity department. There is no real
+ encapsulation or data hiding (unless you use expensive protocol classes), but it
+ is what we have to work with. When you write a public header file (in the LLVM
+ source tree, they live in the top level "include" directory), you are defining a
+ module of functionality.</p>
+
+ <p>Ideally, modules should be completely independent of each other, and their
+ header files should only include the absolute minimum number of headers
+ possible. A module is not just a class, a function, or a namespace: <a
+ href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection
+ of these</a> that defines an interface. This interface may be several
+ functions, classes or data structures, but the important issue is how they work
+ together.</p>
+
+ <p>In general, a module should be implemented with one or more <tt>.cpp</tt>
+ files. Each of these <tt>.cpp</tt> files should include the header that defines
+ their interface first. This ensure that all of the dependences of the module
+ header have been properly added to the module header itself, and are not
+ implicit. System headers should be included after user headers for a
+ translation unit.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>#include</tt> hurts compile time performance. Don't do it unless you
+ have to, especially in header files.</p>
+
+ <p>But wait, sometimes you need to have the definition of a class to use it, or
+ to inherit from it. In these cases go ahead and <tt>#include</tt> that header
+ file. Be aware however that there are many cases where you don't need to have
+ the full definition of a class. If you are using a pointer or reference to a
+ class, you don't need the header file. If you are simply returning a class
+ instance from a prototyped function or method, you don't need it. In fact, for
+ most cases, you simply don't need the definition of a class... and not
+ <tt>#include</tt>'ing speeds up compilation.</p>
+
+ <p>It is easy to try to go too overboard on this recommendation, however. You
+ <b>must</b> include all of the header files that you are using -- you can
+ include them either directly
+ or indirectly (through another header file). To make sure that you don't
+ accidently forget to include a header file in your module header, make sure to
+ include your module header <b>first</b> in the implementation file (as mentioned
+ above). This way there won't be any hidden dependencies that you'll find out
+ about later...</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="hl_privateheaders">Keep "internal" Headers Private</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Many modules have a complex implementation that causes them to use more than
+ one implementation (<tt>.cpp</tt>) file. It is often tempting to put the
+ internal communication interface (helper classes, extra functions, etc) in the
+ public module header file. Don't do this.</p>
+
+ <p>If you really need to do something like this, put a private header file in
+ the same directory as the source files, and include it locally. This ensures
+ that your private interface remains private and undisturbed by outsiders.</p>
+
+ <p>Note however, that it's okay to put extra implementation methods a public
+ class itself... just make them private (or protected), and all is well.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The use of <tt>#include <iostream></tt> in library files is
+ hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
+ support clients using LLVM libraries as part of larger systems. In particular,
+ we statically link LLVM into some dynamic libraries. Even if LLVM isn't used,
+ the static c'tors are run whenever an application start up that uses the dynamic
+ library. There are two problems with this:</p>
+
+ <ol>
+ <li>The time to run the static c'tors impacts startup time of
+ applications—a critical time for GUI apps.</li>
+ <li>The static c'tors cause the app to pull many extra pages of memory off the
+ disk: both the code for the static c'tors in each <tt>.o</tt> file and the
+ small amount of data that gets touched. In addition, touched/dirty pages
+ put more pressure on the VM system on low-memory machines.</li>
+ </ol>
+
+ <div align="center">
+ <table>
+ <tbody>
+ <tr>
+ <th>Old Way</th>
+ <th>New Way</th>
+ </tr>
+ <tr>
+ <td align="left"><pre>#include <iostream></pre></td>
+ <td align="left"><pre>#include "llvm/Support/Streams.h"</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>DEBUG(std::cerr << ...);
+ DEBUG(dump(std::cerr));</pre></td>
+ <td align="left"><pre>DOUT << ...;
+ DEBUG(dump(DOUT));</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cerr << "Hello world\n";</pre></td>
+ <td align="left"><pre>llvm::cerr << "Hello world\n";</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cout << "Hello world\n";</pre></td>
+ <td align="left"><pre>llvm::cout << "Hello world\n";</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cin >> Var;</pre></td>
+ <td align="left"><pre>llvm::cin >> Var;</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::ostream</pre></td>
+ <td align="left"><pre>llvm::OStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::istream</pre></td>
+ <td align="left"><pre>llvm::IStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::stringstream</pre></td>
+ <td align="left"><pre>llvm::StringStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>void print(std::ostream &Out);
+ // ...
+ print(std::cerr);</pre></td>
+ <td align="left"><pre>void print(llvm::OStream Out);<sup>1</sup>
+ // ...
+ print(llvm::cerr);</pre>
+
+ </td> </tbody> </table>
+ </div>
+
+ <div class="doc_text">
+ <p><sup>1</sup><tt>llvm::OStream</tt> is a light-weight class so it should never
+ be passed by reference. This is important because in some configurations,
+ <tt>DOUT</tt> is an rvalue.</p>
+ </div>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="micro">The Low Level Issues</a>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ll_assert">Assert Liberally</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Use the "<tt>assert</tt>" function to its fullest. Check all of your
+ preconditions and assumptions, you never know when a bug (not neccesarily even
+ yours) might be caught early by an assertion, which reduces debugging time
+ dramatically. The "<tt><cassert></tt>" header file is probably already
+ included by the header files you are using, so it doesn't cost anything to use
+ it.</p>
+
+ <p>To further assist with debugging, make sure to put some kind of error message
+ in the assertion statement (which is printed if the assertion is tripped). This
+ helps the poor debugging make sense of why an assertion is being made and
+ enforced, and hopefully what to do about it. Here is one complete example:</p>
+
+ <div class="doc_code">
+ <pre>
+ inline Value *getOperand(unsigned i) {
+ assert(i < Operands.size() && "getOperand() out of range!");
+ return Operands[i];
+ }
+ </pre>
+ </div>
+
+ <p>Here are some examples:</p>
+
+ <div class="doc_code">
+ <pre>
+ assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
+
+ assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
+
+ assert(idx < getNumSuccessors() && "Successor # out of range!");
+
+ assert(V1.getType() == V2.getType() && "Constant types must be identical!");
+
+ assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
+ </pre>
+ </div>
+
+ <p>You get the idea...</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ll_ns_std">Do not use '<tt>using namespace std</tt>'</a>
+ </div>
+
+ <div class="doc_text">
+ <p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
+ namespace with an "<tt>std::</tt>" prefix, rather than rely on
+ "<tt>using namespace std;</tt>".</p>
+
+ <p> In header files, adding a '<tt>using namespace XXX</tt>' directive pollutes
+ the namespace of any source file that includes the header. This is clearly a
+ bad thing.</p>
+
+ <p>In implementation files (e.g. .cpp files), the rule is more of a stylistic
+ rule, but is still important. Basically, using explicit namespace prefixes
+ makes the code <b>clearer</b>, because it is immediately obvious what facilities
+ are being used and where they are coming from, and <b>more portable</b>, because
+ namespace clashes cannot occur between LLVM code and other namespaces. The
+ portability rule is important because different standard library implementations
+ expose different symbols (potentially ones they shouldn't), and future revisions
+ to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
+ such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
+
+ <p>The exception to the general rule (i.e. it's not an exception for
+ the <tt>std</tt> namespace) is for implementation files. For example, all of
+ the code in the LLVM project implements code that lives in the 'llvm' namespace.
+ As such, it is ok, and actually clearer, for the .cpp files to have a '<tt>using
+ namespace llvm</tt>' directive at their top, after the <tt>#include</tt>s. The
+ general form of this rule is that any .cpp file that implements code in any
+ namespace may use that namespace (and its parents'), but should not use any
+ others.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ll_virtual_anch">Provide a virtual method anchor for classes
+ in headers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If a class is defined in a header file and has a v-table (either it has
+ virtual methods or it derives from classes with virtual methods), it must
+ always have at least one out-of-line virtual method in the class. Without
+ this, the compiler will copy the vtable and RTTI into every .o file that
+ #includes the header, bloating .o file sizes and increasing link times.
+ </p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ll_preincrement">Prefer Preincrement</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
+ postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use
+ preincrementation whenever possible.</p>
+
+ <p>The semantics of postincrement include making a copy of the value being
+ incremented, returning it, and then preincrementing the "work value". For
+ primitive types, this isn't a big deal... but for iterators, it can be a huge
+ issue (for example, some iterators contains stack and set objects in them...
+ copying an iterator could invoke the copy ctor's of these as well). In general,
+ get in the habit of always using preincrement, and you won't have a problem.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline
+ to the output stream specified. In addition to doing this, however, it also
+ flushes the output stream. In other words, these are equivalent:</p>
+
+ <div class="doc_code">
+ <pre>
+ std::cout << std::endl;
+ std::cout << '\n' << std::flush;
+ </pre>
+ </div>
+
+ <p>Most of the time, you probably have no reason to flush the output stream, so
+ it's better to use a literal <tt>'\n'</tt>.</p>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="seealso">See Also</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>A lot of these comments and recommendations have been culled for other
+ sources. Two particularly important books for our work are:</p>
+
+ <ol>
+
+ <li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
+ C++</a> by Scott Meyers. Also
+ interesting and useful are "More Effective C++" and "Effective STL" by the same
+ author.</li>
+
+ <li>Large-Scale C++ Software Design by John Lakos</li>
+
+ </ol>
+
+ <p>If you get some free time, and you haven't read them: do so, you might learn
+ something.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/CommandLine.html
diff -c /dev/null llvm-www/releases/2.3/docs/CommandLine.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/CommandLine.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,1970 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>CommandLine 2.0 Library Manual</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">
+ CommandLine 2.0 Library Manual
+ </div>
+
+ <ol>
+ <li><a href="#introduction">Introduction</a></li>
+
+ <li><a href="#quickstart">Quick Start Guide</a>
+ <ol>
+ <li><a href="#bool">Boolean Arguments</a></li>
+ <li><a href="#alias">Argument Aliases</a></li>
+ <li><a href="#onealternative">Selecting an alternative from a
+ set of possibilities</a></li>
+ <li><a href="#namedalternatives">Named alternatives</a></li>
+ <li><a href="#list">Parsing a list of options</a></li>
+ <li><a href="#bits">Collecting options as a set of flags</a></li>
+ <li><a href="#description">Adding freeform text to help output</a></li>
+ </ol></li>
+
+ <li><a href="#referenceguide">Reference Guide</a>
+ <ol>
+ <li><a href="#positional">Positional Arguments</a>
+ <ul>
+ <li><a href="#--">Specifying positional options with hyphens</a></li>
+ <li><a href="#getPosition">Determining absolute position with
+ getPosition</a></li>
+ <li><a href="#cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt>
+ modifier</a></li>
+ </ul></li>
+
+ <li><a href="#storage">Internal vs External Storage</a></li>
+
+ <li><a href="#attributes">Option Attributes</a></li>
+
+ <li><a href="#modifiers">Option Modifiers</a>
+ <ul>
+ <li><a href="#hiding">Hiding an option from <tt>--help</tt>
+ output</a></li>
+ <li><a href="#numoccurrences">Controlling the number of occurrences
+ required and allowed</a></li>
+ <li><a href="#valrequired">Controlling whether or not a value must be
+ specified</a></li>
+ <li><a href="#formatting">Controlling other formatting options</a></li>
+ <li><a href="#misc">Miscellaneous option modifiers</a></li>
+ <li><a href="#response">Response files</a></li>
+ </ul></li>
+
+ <li><a href="#toplevel">Top-Level Classes and Functions</a>
+ <ul>
+ <li><a href="#cl::ParseCommandLineOptions">The
+ <tt>cl::ParseCommandLineOptions</tt> function</a></li>
+ <li><a href="#cl::ParseEnvironmentOptions">The
+ <tt>cl::ParseEnvironmentOptions</tt> function</a></li>
+ <li><a href="#cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
+ function</a></li>
+ <li><a href="#cl::opt">The <tt>cl::opt</tt> class</a></li>
+ <li><a href="#cl::list">The <tt>cl::list</tt> class</a></li>
+ <li><a href="#cl::bits">The <tt>cl::bits</tt> class</a></li>
+ <li><a href="#cl::alias">The <tt>cl::alias</tt> class</a></li>
+ <li><a href="#cl::extrahelp">The <tt>cl::extrahelp</tt> class</a></li>
+ </ul></li>
+
+ <li><a href="#builtinparsers">Builtin parsers</a>
+ <ul>
+ <li><a href="#genericparser">The Generic <tt>parser<t></tt>
+ parser</a></li>
+ <li><a href="#boolparser">The <tt>parser<bool></tt>
+ specialization</a></li>
+ <li><a href="#boolOrDefaultparser">The <tt>parser<boolOrDefault></tt>
+ specialization</a></li>
+ <li><a href="#stringparser">The <tt>parser<string></tt>
+ specialization</a></li>
+ <li><a href="#intparser">The <tt>parser<int></tt>
+ specialization</a></li>
+ <li><a href="#doubleparser">The <tt>parser<double></tt> and
+ <tt>parser<float></tt> specializations</a></li>
+ </ul></li>
+ </ol></li>
+ <li><a href="#extensionguide">Extension Guide</a>
+ <ol>
+ <li><a href="#customparser">Writing a custom parser</a></li>
+ <li><a href="#explotingexternal">Exploiting external storage</a></li>
+ <li><a href="#dynamicopts">Dynamically adding command line
+ options</a></li>
+ </ol></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This document describes the CommandLine argument processing library. It will
+ show you how to use it, and what it can do. The CommandLine library uses a
+ declarative approach to specifying the command line options that your program
+ takes. By default, these options declarations implicitly hold the value parsed
+ for the option declared (of course this <a href="#storage">can be
+ changed</a>).</p>
+
+ <p>Although there are a <b>lot</b> of command line argument parsing libraries
+ out there in many different languages, none of them fit well with what I needed.
+ By looking at the features and problems of other libraries, I designed the
+ CommandLine library to have the following features:</p>
+
+ <ol>
+ <li>Speed: The CommandLine library is very quick and uses little resources. The
+ parsing time of the library is directly proportional to the number of arguments
+ parsed, not the the number of options recognized. Additionally, command line
+ argument values are captured transparently into user defined global variables,
+ which can be accessed like any other variable (and with the same
+ performance).</li>
+
+ <li>Type Safe: As a user of CommandLine, you don't have to worry about
+ remembering the type of arguments that you want (is it an int? a string? a
+ bool? an enum?) and keep casting it around. Not only does this help prevent
+ error prone constructs, it also leads to dramatically cleaner source code.</li>
+
+ <li>No subclasses required: To use CommandLine, you instantiate variables that
+ correspond to the arguments that you would like to capture, you don't subclass a
+ parser. This means that you don't have to write <b>any</b> boilerplate
+ code.</li>
+
+ <li>Globally accessible: Libraries can specify command line arguments that are
+ automatically enabled in any tool that links to the library. This is possible
+ because the application doesn't have to keep a list of arguments to pass to
+ the parser. This also makes supporting <a href="#dynamicopts">dynamically
+ loaded options</a> trivial.</li>
+
+ <li>Cleaner: CommandLine supports enum and other types directly, meaning that
+ there is less error and more security built into the library. You don't have to
+ worry about whether your integral command line argument accidentally got
+ assigned a value that is not valid for your enum type.</li>
+
+ <li>Powerful: The CommandLine library supports many different types of
+ arguments, from simple <a href="#boolparser">boolean flags</a> to <a
+ href="#cl::opt">scalars arguments</a> (<a href="#stringparser">strings</a>, <a
+ href="#intparser">integers</a>, <a href="#genericparser">enums</a>, <a
+ href="#doubleparser">doubles</a>), to <a href="#cl::list">lists of
+ arguments</a>. This is possible because CommandLine is...</li>
+
+ <li>Extensible: It is very simple to add a new argument type to CommandLine.
+ Simply specify the parser that you want to use with the command line option when
+ you declare it. <a href="#customparser">Custom parsers</a> are no problem.</li>
+
+ <li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
+ that you, the user, have to do. For example, it automatically provides a
+ <tt>--help</tt> option that shows the available command line options for your
+ tool. Additionally, it does most of the basic correctness checking for
+ you.</li>
+
+ <li>Capable: The CommandLine library can handle lots of different forms of
+ options often found in real programs. For example, <a
+ href="#positional">positional</a> arguments, <tt>ls</tt> style <a
+ href="#cl::Grouping">grouping</a> options (to allow processing '<tt>ls
+ -lad</tt>' naturally), <tt>ld</tt> style <a href="#cl::Prefix">prefix</a>
+ options (to parse '<tt>-lmalloc -L/usr/lib</tt>'), and <a
+ href="#cl::ConsumeAfter">interpreter style options</a>.</li>
+
+ </ol>
+
+ <p>This document will hopefully let you jump in and start using CommandLine in
+ your utility quickly and painlessly. Additionally it should be a simple
+ reference manual to figure out how stuff works. If it is failing in some area
+ (or you want an extension to the library), nag the author, <a
+ href="mailto:sabre at nondot.org">Chris Lattner</a>.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="quickstart">Quick Start Guide</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This section of the manual runs through a simple CommandLine'ification of a
+ basic compiler tool. This is intended to show you how to jump into using the
+ CommandLine library in your own program, and show you some of the cool things it
+ can do.</p>
+
+ <p>To start out, you need to include the CommandLine header file into your
+ program:</p>
+
+ <div class="doc_code"><pre>
+ #include "llvm/Support/CommandLine.h"
+ </pre></div>
+
+ <p>Additionally, you need to add this as the first line of your main
+ program:</p>
+
+ <div class="doc_code"><pre>
+ int main(int argc, char **argv) {
+ <a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv);
+ ...
+ }
+ </pre></div>
+
+ <p>... which actually parses the arguments and fills in the variable
+ declarations.</p>
+
+ <p>Now that you are ready to support command line arguments, we need to tell the
+ system which ones we want, and what type of arguments they are. The CommandLine
+ library uses a declarative syntax to model command line arguments with the
+ global variable declarations that capture the parsed values. This means that
+ for every command line option that you would like to support, there should be a
+ global variable declaration to capture the result. For example, in a compiler,
+ we would like to support the Unix-standard '<tt>-o <filename></tt>' option
+ to specify where to put the output. With the CommandLine library, this is
+ represented like this:</p>
+
+ <a name="value_desc_example"></a>
+ <div class="doc_code"><pre>
+ <a href="#cl::opt">cl::opt</a><string> OutputFilename("<i>o</i>", <a href="#cl::desc">cl::desc</a>("<i>Specify output filename</i>"), <a href="#cl::value_desc">cl::value_desc</a>("<i>filename</i>"));
+ </pre></div>
+
+ <p>This declares a global variable "<tt>OutputFilename</tt>" that is used to
+ capture the result of the "<tt>o</tt>" argument (first parameter). We specify
+ that this is a simple scalar option by using the "<tt><a
+ href="#cl::opt">cl::opt</a></tt>" template (as opposed to the <a
+ href="#list">"<tt>cl::list</tt> template</a>), and tell the CommandLine library
+ that the data type that we are parsing is a string.</p>
+
+ <p>The second and third parameters (which are optional) are used to specify what
+ to output for the "<tt>--help</tt>" option. In this case, we get a line that
+ looks like this:</p>
+
+ <div class="doc_code"><pre>
+ USAGE: compiler [options]
+
+ OPTIONS:
+ -help - display available options (--help-hidden for more)
+ <b>-o <filename> - Specify output filename</b>
+ </pre></div>
+
+ <p>Because we specified that the command line option should parse using the
+ <tt>string</tt> data type, the variable declared is automatically usable as a
+ real string in all contexts that a normal C++ string object may be used. For
+ example:</p>
+
+ <div class="doc_code"><pre>
+ ...
+ std::ofstream Output(OutputFilename.c_str());
+ if (Output.good()) ...
+ ...
+ </pre></div>
+
+ <p>There are many different options that you can use to customize the command
+ line option handling library, but the above example shows the general interface
+ to these options. The options can be specified in any order, and are specified
+ with helper functions like <a href="#cl::desc"><tt>cl::desc(...)</tt></a>, so
+ there are no positional dependencies to remember. The available options are
+ discussed in detail in the <a href="#referenceguide">Reference Guide</a>.</p>
+
+ <p>Continuing the example, we would like to have our compiler take an input
+ filename as well as an output filename, but we do not want the input filename to
+ be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this
+ style of argument, the CommandLine library allows for <a
+ href="#positional">positional</a> arguments to be specified for the program.
+ These positional arguments are filled with command line parameters that are not
+ in option form. We use this feature like this:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
+ </pre></div>
+
+ <p>This declaration indicates that the first positional argument should be
+ treated as the input filename. Here we use the <tt><a
+ href="#cl::init">cl::init</a></tt> option to specify an initial value for the
+ command line option, which is used if the option is not specified (if you do not
+ specify a <tt><a href="#cl::init">cl::init</a></tt> modifier for an option, then
+ the default constructor for the data type is used to initialize the value).
+ Command line options default to being optional, so if we would like to require
+ that the user always specify an input filename, we would add the <tt><a
+ href="#cl::Required">cl::Required</a></tt> flag, and we could eliminate the
+ <tt><a href="#cl::init">cl::init</a></tt> modifier, like this:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <b><a href="#cl::Required">cl::Required</a></b>);
+ </pre></div>
+
+ <p>Again, the CommandLine library does not require the options to be specified
+ in any particular order, so the above declaration is equivalent to:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::Required">cl::Required</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"));
+ </pre></div>
+
+ <p>By simply adding the <tt><a href="#cl::Required">cl::Required</a></tt> flag,
+ the CommandLine library will automatically issue an error if the argument is not
+ specified, which shifts all of the command line option verification code out of
+ your application into the library. This is just one example of how using flags
+ can alter the default behaviour of the library, on a per-option basis. By
+ adding one of the declarations above, the <tt>--help</tt> option synopsis is now
+ extended to:</p>
+
+ <div class="doc_code"><pre>
+ USAGE: compiler [options] <b><input file></b>
+
+ OPTIONS:
+ -help - display available options (--help-hidden for more)
+ -o <filename> - Specify output filename
+ </pre></div>
+
+ <p>... indicating that an input filename is expected.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="bool">Boolean Arguments</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>In addition to input and output filenames, we would like the compiler example
+ to support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
+ file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
+ compatibility with some of our users. We can support these by declaring options
+ of boolean type like this:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
+ <a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
+ <a href="#cl::opt">cl::opt</a><bool> Quiet2("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"), <a href="#cl::Hidden">cl::Hidden</a>);
+ </pre></div>
+
+ <p>This does what you would expect: it declares three boolean variables
+ ("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
+ options. Note that the "<tt>-q</tt>" option is specified with the "<a
+ href="#cl::Hidden"><tt>cl::Hidden</tt></a>" flag. This modifier prevents it
+ from being shown by the standard "<tt>--help</tt>" output (note that it is still
+ shown in the "<tt>--help-hidden</tt>" output).</p>
+
+ <p>The CommandLine library uses a <a href="#builtinparsers">different parser</a>
+ for different data types. For example, in the string case, the argument passed
+ to the option is copied literally into the content of the string variable... we
+ obviously cannot do that in the boolean case, however, so we must use a smarter
+ parser. In the case of the boolean parser, it allows no options (in which case
+ it assigns the value of true to the variable), or it allows the values
+ "<tt>true</tt>" or "<tt>false</tt>" to be specified, allowing any of the
+ following inputs:</p>
+
+ <div class="doc_code"><pre>
+ compiler -f # No value, 'Force' == true
+ compiler -f=true # Value specified, 'Force' == true
+ compiler -f=TRUE # Value specified, 'Force' == true
+ compiler -f=FALSE # Value specified, 'Force' == false
+ </pre></div>
+
+ <p>... you get the idea. The <a href="#boolparser">bool parser</a> just turns
+ the string values into boolean values, and rejects things like '<tt>compiler
+ -f=foo</tt>'. Similarly, the <a href="#doubleparser">float</a>, <a
+ href="#doubleparser">double</a>, and <a href="#intparser">int</a> parsers work
+ like you would expect, using the '<tt>strtol</tt>' and '<tt>strtod</tt>' C
+ library calls to parse the string value into the specified data type.</p>
+
+ <p>With the declarations above, "<tt>compiler --help</tt>" emits this:</p>
+
+ <div class="doc_code"><pre>
+ USAGE: compiler [options] <input file>
+
+ OPTIONS:
+ <b>-f - Overwrite output files</b>
+ -o - Override output filename
+ <b>-quiet - Don't print informational messages</b>
+ -help - display available options (--help-hidden for more)
+ </pre></div>
+
+ <p>and "<tt>compiler --help-hidden</tt>" prints this:</p>
+
+ <div class="doc_code"><pre>
+ USAGE: compiler [options] <input file>
+
+ OPTIONS:
+ -f - Overwrite output files
+ -o - Override output filename
+ <b>-q - Don't print informational messages</b>
+ -quiet - Don't print informational messages
+ -help - display available options (--help-hidden for more)
+ </pre></div>
+
+ <p>This brief example has shown you how to use the '<tt><a
+ href="#cl::opt">cl::opt</a></tt>' class to parse simple scalar command line
+ arguments. In addition to simple scalar arguments, the CommandLine library also
+ provides primitives to support CommandLine option <a href="#alias">aliases</a>,
+ and <a href="#list">lists</a> of options.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="alias">Argument Aliases</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>So far, the example works well, except for the fact that we need to check the
+ quiet condition like this now:</p>
+
+ <div class="doc_code"><pre>
+ ...
+ if (!Quiet && !Quiet2) printInformationalMessage(...);
+ ...
+ </pre></div>
+
+ <p>... which is a real pain! Instead of defining two values for the same
+ condition, we can use the "<tt><a href="#cl::alias">cl::alias</a></tt>" class to make the "<tt>-q</tt>"
+ option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing
+ a value itself:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
+ <a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
+ <a href="#cl::alias">cl::alias</a> QuietA("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Alias for -quiet</i>"), <a href="#cl::aliasopt">cl::aliasopt</a>(Quiet));
+ </pre></div>
+
+ <p>The third line (which is the only one we modified from above) defines a
+ "<tt>-q</tt>" alias that updates the "<tt>Quiet</tt>" variable (as specified by
+ the <tt><a href="#cl::aliasopt">cl::aliasopt</a></tt> modifier) whenever it is
+ specified. Because aliases do not hold state, the only thing the program has to
+ query is the <tt>Quiet</tt> variable now. Another nice feature of aliases is
+ that they automatically hide themselves from the <tt>-help</tt> output
+ (although, again, they are still visible in the <tt>--help-hidden
+ output</tt>).</p>
+
+ <p>Now the application code can simply use:</p>
+
+ <div class="doc_code"><pre>
+ ...
+ if (!Quiet) printInformationalMessage(...);
+ ...
+ </pre></div>
+
+ <p>... which is much nicer! The "<tt><a href="#cl::alias">cl::alias</a></tt>"
+ can be used to specify an alternative name for any variable type, and has many
+ uses.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="onealternative">Selecting an alternative from a set of
+ possibilities</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>So far we have seen how the CommandLine library handles builtin types like
+ <tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
+ things it doesn't know about, like enums or '<tt>int*</tt>'s?</p>
+
+ <p>The answer is that it uses a table-driven generic parser (unless you specify
+ your own parser, as described in the <a href="#extensionguide">Extension
+ Guide</a>). This parser maps literal strings to whatever type is required, and
+ requires you to tell it what this mapping should be.</p>
+
+ <p>Let's say that we would like to add four optimization levels to our
+ optimizer, using the standard flags "<tt>-g</tt>", "<tt>-O0</tt>",
+ "<tt>-O1</tt>", and "<tt>-O2</tt>". We could easily implement this with boolean
+ options like above, but there are several problems with this strategy:</p>
+
+ <ol>
+ <li>A user could specify more than one of the options at a time, for example,
+ "<tt>compiler -O3 -O2</tt>". The CommandLine library would not be able to
+ catch this erroneous input for us.</li>
+
+ <li>We would have to test 4 different variables to see which ones are set.</li>
+
+ <li>This doesn't map to the numeric levels that we want... so we cannot easily
+ see if some level >= "<tt>-O1</tt>" is enabled.</li>
+
+ </ol>
+
+ <p>To cope with these problems, we can use an enum value, and have the
+ CommandLine library fill it in with the appropriate level directly, which is
+ used like this:</p>
+
+ <div class="doc_code"><pre>
+ enum OptLevel {
+ g, O1, O2, O3
+ };
+
+ <a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumVal(g , "<i>No optimizations, enable debugging</i>"),
+ clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
+ clEnumVal(O2, "<i>Enable default optimizations</i>"),
+ clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
+ clEnumValEnd));
+
+ ...
+ if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
+ ...
+ </pre></div>
+
+ <p>This declaration defines a variable "<tt>OptimizationLevel</tt>" of the
+ "<tt>OptLevel</tt>" enum type. This variable can be assigned any of the values
+ that are listed in the declaration (Note that the declaration list must be
+ terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine
+ library enforces
+ that the user can only specify one of the options, and it ensure that only valid
+ enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the
+ command line arguments matched the enum values. With this option added, our
+ help output now is:</p>
+
+ <div class="doc_code"><pre>
+ USAGE: compiler [options] <input file>
+
+ OPTIONS:
+ <b>Choose optimization level:
+ -g - No optimizations, enable debugging
+ -O1 - Enable trivial optimizations
+ -O2 - Enable default optimizations
+ -O3 - Enable expensive optimizations</b>
+ -f - Overwrite output files
+ -help - display available options (--help-hidden for more)
+ -o <filename> - Specify output filename
+ -quiet - Don't print informational messages
+ </pre></div>
+
+ <p>In this case, it is sort of awkward that flag names correspond directly to
+ enum names, because we probably don't want a enum definition named "<tt>g</tt>"
+ in our program. Because of this, we can alternatively write this example like
+ this:</p>
+
+ <div class="doc_code"><pre>
+ enum OptLevel {
+ Debug, O1, O2, O3
+ };
+
+ <a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumValN(Debug, "g", "<i>No optimizations, enable debugging</i>"),
+ clEnumVal(O1 , "<i>Enable trivial optimizations</i>"),
+ clEnumVal(O2 , "<i>Enable default optimizations</i>"),
+ clEnumVal(O3 , "<i>Enable expensive optimizations</i>"),
+ clEnumValEnd));
+
+ ...
+ if (OptimizationLevel == Debug) outputDebugInfo(...);
+ ...
+ </pre></div>
+
+ <p>By using the "<tt>clEnumValN</tt>" macro instead of "<tt>clEnumVal</tt>", we
+ can directly specify the name that the flag should get. In general a direct
+ mapping is nice, but sometimes you can't or don't want to preserve the mapping,
+ which is when you would use it.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="namedalternatives">Named Alternatives</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Another useful argument form is a named alternative style. We shall use this
+ style in our compiler to specify different debug levels that can be used.
+ Instead of each debug level being its own switch, we want to support the
+ following options, of which only one can be specified at a time:
+ "<tt>--debug-level=none</tt>", "<tt>--debug-level=quick</tt>",
+ "<tt>--debug-level=detailed</tt>". To do this, we use the exact same format as
+ our optimization level flags, but we also specify an option name. For this
+ case, the code looks like this:</p>
+
+ <div class="doc_code"><pre>
+ enum DebugLev {
+ nodebuginfo, quick, detailed
+ };
+
+ // Enable Debug Options to be specified on the command line
+ <a href="#cl::opt">cl::opt</a><DebugLev> DebugLevel("<i>debug_level</i>", <a href="#cl::desc">cl::desc</a>("<i>Set the debugging level:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumValN(nodebuginfo, "none", "<i>disable debug information</i>"),
+ clEnumVal(quick, "<i>enable quick debug information</i>"),
+ clEnumVal(detailed, "<i>enable detailed debug information</i>"),
+ clEnumValEnd));
+ </pre></div>
+
+ <p>This definition defines an enumerated command line variable of type "<tt>enum
+ DebugLev</tt>", which works exactly the same way as before. The difference here
+ is just the interface exposed to the user of your program and the help output by
+ the "<tt>--help</tt>" option:</p>
+
+ <div class="doc_code"><pre>
+ USAGE: compiler [options] <input file>
+
+ OPTIONS:
+ Choose optimization level:
+ -g - No optimizations, enable debugging
+ -O1 - Enable trivial optimizations
+ -O2 - Enable default optimizations
+ -O3 - Enable expensive optimizations
+ <b>-debug_level - Set the debugging level:
+ =none - disable debug information
+ =quick - enable quick debug information
+ =detailed - enable detailed debug information</b>
+ -f - Overwrite output files
+ -help - display available options (--help-hidden for more)
+ -o <filename> - Specify output filename
+ -quiet - Don't print informational messages
+ </pre></div>
+
+ <p>Again, the only structural difference between the debug level declaration and
+ the optimization level declaration is that the debug level declaration includes
+ an option name (<tt>"debug_level"</tt>), which automatically changes how the
+ library processes the argument. The CommandLine library supports both forms so
+ that you can choose the form most appropriate for your application.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="list">Parsing a list of options</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Now that we have the standard run-of-the-mill argument types out of the way,
+ lets get a little wild and crazy. Lets say that we want our optimizer to accept
+ a <b>list</b> of optimizations to perform, allowing duplicates. For example, we
+ might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In
+ this case, the order of the arguments and the number of appearances is very
+ important. This is what the "<tt><a href="#cl::list">cl::list</a></tt>"
+ template is for. First, start by defining an enum of the optimizations that you
+ would like to perform:</p>
+
+ <div class="doc_code"><pre>
+ enum Opts {
+ // 'inline' is a C++ keyword, so name it 'inlining'
+ dce, constprop, inlining, strip
+ };
+ </pre></div>
+
+ <p>Then define your "<tt><a href="#cl::list">cl::list</a></tt>" variable:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::list">cl::list</a><Opts> OptimizationList(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumVal(dce , "<i>Dead Code Elimination</i>"),
+ clEnumVal(constprop , "<i>Constant Propagation</i>"),
+ clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
+ clEnumVal(strip , "<i>Strip Symbols</i>"),
+ clEnumValEnd));
+ </pre></div>
+
+ <p>This defines a variable that is conceptually of the type
+ "<tt>std::vector<enum Opts></tt>". Thus, you can access it with standard
+ vector methods:</p>
+
+ <div class="doc_code"><pre>
+ for (unsigned i = 0; i != OptimizationList.size(); ++i)
+ switch (OptimizationList[i])
+ ...
+ </pre></div>
+
+ <p>... to iterate through the list of options specified.</p>
+
+ <p>Note that the "<tt><a href="#cl::list">cl::list</a></tt>" template is
+ completely general and may be used with any data types or other arguments that
+ you can use with the "<tt><a href="#cl::opt">cl::opt</a></tt>" template. One
+ especially useful way to use a list is to capture all of the positional
+ arguments together if there may be more than one specified. In the case of a
+ linker, for example, the linker takes several '<tt>.o</tt>' files, and needs to
+ capture them into a list. This is naturally specified as:</p>
+
+ <div class="doc_code"><pre>
+ ...
+ <a href="#cl::list">cl::list</a><std::string> InputFilenames(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<Input files>"), <a href="#cl::OneOrMore">cl::OneOrMore</a>);
+ ...
+ </pre></div>
+
+ <p>This variable works just like a "<tt>vector<string></tt>" object. As
+ such, accessing the list is simple, just like above. In this example, we used
+ the <tt><a href="#cl::OneOrMore">cl::OneOrMore</a></tt> modifier to inform the
+ CommandLine library that it is an error if the user does not specify any
+ <tt>.o</tt> files on our command line. Again, this just reduces the amount of
+ checking we have to do.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="bits">Collecting options as a set of flags</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Instead of collecting sets of options in a list, it is also possible to
+ gather information for enum values in a <b>bit vector</b>. The represention used by
+ the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned</tt>
+ integer. An enum value is represented by a 0/1 in the enum's ordinal value bit
+ position. 1 indicating that the enum was specified, 0 otherwise. As each
+ specified value is parsed, the resulting enum's bit is set in the option's bit
+ vector:</p>
+
+ <div class="doc_code"><pre>
+ <i>bits</i> |= 1 << (unsigned)<i>enum</i>;
+ </pre></div>
+
+ <p>Options that are specified multiple times are redundant. Any instances after
+ the first are discarded.</p>
+
+ <p>Reworking the above list example, we could replace <a href="#list">
+ <tt>cl::list</tt></a> with <a href="#bits"><tt>cl::bits</tt></a>:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::bits">cl::bits</a><Opts> OptimizationBits(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumVal(dce , "<i>Dead Code Elimination</i>"),
+ clEnumVal(constprop , "<i>Constant Propagation</i>"),
+ clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
+ clEnumVal(strip , "<i>Strip Symbols</i>"),
+ clEnumValEnd));
+ </pre></div>
+
+ <p>To test to see if <tt>constprop</tt> was specified, we can use the
+ <tt>cl:bits::isSet</tt> function:</p>
+
+ <div class="doc_code"><pre>
+ if (OptimizationBits.isSet(constprop)) {
+ ...
+ }
+ </pre></div>
+
+ <p>It's also possible to get the raw bit vector using the
+ <tt>cl::bits::getBits</tt> function:</p>
+
+ <div class="doc_code"><pre>
+ unsigned bits = OptimizationBits.getBits();
+ </pre></div>
+
+ <p>Finally, if external storage is used, then the location specified must be of
+ <b>type</b> <tt>unsigned</tt>. In all other ways a <a
+ href="#bits"><tt>cl::bits</tt></a> option is equivalent to a <a
+ href="#list"> <tt>cl::list</tt></a> option.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="description">Adding freeform text to help output</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>As our program grows and becomes more mature, we may decide to put summary
+ information about what it does into the help output. The help output is styled
+ to look similar to a Unix <tt>man</tt> page, providing concise information about
+ a program. Unix <tt>man</tt> pages, however often have a description about what
+ the program does. To add this to your CommandLine program, simply pass a third
+ argument to the <a
+ href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
+ call in main. This additional argument is then printed as the overview
+ information for your program, allowing you to include any additional information
+ that you want. For example:</p>
+
+ <div class="doc_code"><pre>
+ int main(int argc, char **argv) {
+ <a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv, " CommandLine compiler example\n\n"
+ " This program blah blah blah...\n");
+ ...
+ }
+ </pre></div>
+
+ <p>would yield the help output:</p>
+
+ <div class="doc_code"><pre>
+ <b>OVERVIEW: CommandLine compiler example
+
+ This program blah blah blah...</b>
+
+ USAGE: compiler [options] <input file>
+
+ OPTIONS:
+ ...
+ -help - display available options (--help-hidden for more)
+ -o <filename> - Specify output filename
+ </pre></div>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="referenceguide">Reference Guide</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Now that you know the basics of how to use the CommandLine library, this
+ section will give you the detailed information you need to tune how command line
+ options work, as well as information on more "advanced" command line option
+ processing capabilities.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="positional">Positional Arguments</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Positional arguments are those arguments that are not named, and are not
+ specified with a hyphen. Positional arguments should be used when an option is
+ specified by its position alone. For example, the standard Unix <tt>grep</tt>
+ tool takes a regular expression argument, and an optional filename to search
+ through (which defaults to standard input if a filename is not specified).
+ Using the CommandLine library, this would be specified as:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::opt">cl::opt</a><string> Regex (<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><regular expression></i>"), <a href="#cl::Required">cl::Required</a>);
+ <a href="#cl::opt">cl::opt</a><string> Filename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
+ </pre></div>
+
+ <p>Given these two option declarations, the <tt>--help</tt> output for our grep
+ replacement would look like this:</p>
+
+ <div class="doc_code"><pre>
+ USAGE: spiffygrep [options] <b><regular expression> <input file></b>
+
+ OPTIONS:
+ -help - display available options (--help-hidden for more)
+ </pre></div>
+
+ <p>... and the resultant program could be used just like the standard
+ <tt>grep</tt> tool.</p>
+
+ <p>Positional arguments are sorted by their order of construction. This means
+ that command line options will be ordered according to how they are listed in a
+ .cpp file, but will not have an ordering defined if the positional arguments
+ are defined in multiple .cpp files. The fix for this problem is simply to
+ define all of your positional arguments in one .cpp file.</p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="--">Specifying positional options with hyphens</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Sometimes you may want to specify a value to your positional argument that
+ starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At
+ first, you will have trouble doing this, because it will try to find an argument
+ named '<tt>-foo</tt>', and will fail (and single quotes will not save you).
+ Note that the system <tt>grep</tt> has the same problem:</p>
+
+ <div class="doc_code"><pre>
+ $ spiffygrep '-foo' test.txt
+ Unknown command line argument '-foo'. Try: spiffygrep --help'
+
+ $ grep '-foo' test.txt
+ grep: illegal option -- f
+ grep: illegal option -- o
+ grep: illegal option -- o
+ Usage: grep -hblcnsviw pattern file . . .
+ </pre></div>
+
+ <p>The solution for this problem is the same for both your tool and the system
+ version: use the '<tt>--</tt>' marker. When the user specifies '<tt>--</tt>' on
+ the command line, it is telling the program that all options after the
+ '<tt>--</tt>' should be treated as positional arguments, not options. Thus, we
+ can use it like this:</p>
+
+ <div class="doc_code"><pre>
+ $ spiffygrep -- -foo test.txt
+ ...output...
+ </pre></div>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="getPosition">Determining absolute position with getPosition()</a>
+ </div>
+ <div class="doc_text">
+ <p>Sometimes an option can affect or modify the meaning of another option. For
+ example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells
+ <tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force
+ the file to be interpreted as if it contained source code in language
+ <tt>LANG</tt>. In order to handle this properly, you need to know the
+ absolute position of each argument, especially those in lists, so their
+ interaction(s) can be applied correctly. This is also useful for options like
+ <tt>-llibname</tt> which is actually a positional argument that starts with
+ a dash.</p>
+ <p>So, generally, the problem is that you have two <tt>cl::list</tt> variables
+ that interact in some way. To ensure the correct interaction, you can use the
+ <tt>cl::list::getPosition(optnum)</tt> method. This method returns the
+ absolute position (as found on the command line) of the <tt>optnum</tt>
+ item in the <tt>cl::list</tt>.</p>
+ <p>The idiom for usage is like this:</p>
+
+ <div class="doc_code"><pre>
+ static cl::list<std::string> Files(cl::Positional, cl::OneOrMore);
+ static cl::list<std::string> Libraries("l", cl::ZeroOrMore);
+
+ int main(int argc, char**argv) {
+ // ...
+ std::vector<std::string>::iterator fileIt = Files.begin();
+ std::vector<std::string>::iterator libIt = Libraries.begin();
+ unsigned libPos = 0, filePos = 0;
+ while ( 1 ) {
+ if ( libIt != Libraries.end() )
+ libPos = Libraries.getPosition( libIt - Libraries.begin() );
+ else
+ libPos = 0;
+ if ( fileIt != Files.end() )
+ filePos = Files.getPosition( fileIt - Files.begin() );
+ else
+ filePos = 0;
+
+ if ( filePos != 0 && (libPos == 0 || filePos < libPos) ) {
+ // Source File Is next
+ ++fileIt;
+ }
+ else if ( libPos != 0 && (filePos == 0 || libPos < filePos) ) {
+ // Library is next
+ ++libIt;
+ }
+ else
+ break; // we're done with the list
+ }
+ }</pre></div>
+
+ <p>Note that, for compatibility reasons, the <tt>cl::opt</tt> also supports an
+ <tt>unsigned getPosition()</tt> option that will provide the absolute position
+ of that option. You can apply the same approach as above with a
+ <tt>cl::opt</tt> and a <tt>cl::list</tt> option as you can with two lists.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is
+ used to construct programs that use "interpreter style" option processing. With
+ this style of option processing, all arguments specified after the last
+ positional argument are treated as special interpreter arguments that are not
+ interpreted by the command line argument.</p>
+
+ <p>As a concrete example, lets say we are developing a replacement for the
+ standard Unix Bourne shell (<tt>/bin/sh</tt>). To run <tt>/bin/sh</tt>, first
+ you specify options to the shell itself (like <tt>-x</tt> which turns on trace
+ output), then you specify the name of the script to run, then you specify
+ arguments to the script. These arguments to the script are parsed by the Bourne
+ shell command line option processor, but are not interpreted as options to the
+ shell itself. Using the CommandLine library, we would specify this as:</p>
+
+ <div class="doc_code"><pre>
+ <a href="#cl::opt">cl::opt</a><string> Script(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input script></i>"), <a href="#cl::init">cl::init</a>("-"));
+ <a href="#cl::list">cl::list</a><string> Argv(<a href="#cl::ConsumeAfter">cl::ConsumeAfter</a>, <a href="#cl::desc">cl::desc</a>("<i><program arguments>...</i>"));
+ <a href="#cl::opt">cl::opt</a><bool> Trace("<i>x</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable trace output</i>"));
+ </pre></div>
+
+ <p>which automatically provides the help output:</p>
+
+ <div class="doc_code"><pre>
+ USAGE: spiffysh [options] <b><input script> <program arguments>...</b>
+
+ OPTIONS:
+ -help - display available options (--help-hidden for more)
+ <b>-x - Enable trace output</b>
+ </pre></div>
+
+ <p>At runtime, if we run our new shell replacement as `<tt>spiffysh -x test.sh
+ -a -x -y bar</tt>', the <tt>Trace</tt> variable will be set to true, the
+ <tt>Script</tt> variable will be set to "<tt>test.sh</tt>", and the
+ <tt>Argv</tt> list will contain <tt>["-a", "-x", "-y", "bar"]</tt>, because they
+ were specified after the last positional argument (which is the script
+ name).</p>
+
+ <p>There are several limitations to when <tt>cl::ConsumeAfter</tt> options can
+ be specified. For example, only one <tt>cl::ConsumeAfter</tt> can be specified
+ per program, there must be at least one <a href="#positional">positional
+ argument</a> specified, there must not be any <a href="#cl::list">cl::list</a>
+ positional arguments, and the <tt>cl::ConsumeAfter</tt> option should be a <a
+ href="#cl::list">cl::list</a> option.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="storage">Internal vs External Storage</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>By default, all command line options automatically hold the value that they
+ parse from the command line. This is very convenient in the common case,
+ especially when combined with the ability to define command line options in the
+ files that use them. This is called the internal storage model.</p>
+
+ <p>Sometimes, however, it is nice to separate the command line option processing
+ code from the storage of the value parsed. For example, lets say that we have a
+ '<tt>-debug</tt>' option that we would like to use to enable debug information
+ across the entire body of our program. In this case, the boolean value
+ controlling the debug code should be globally accessable (in a header file, for
+ example) yet the command line option processing code should not be exposed to
+ all of these clients (requiring lots of .cpp files to #include
+ <tt>CommandLine.h</tt>).</p>
+
+ <p>To do this, set up your .h file with your option, like this for example:</p>
+
+ <div class="doc_code">
+ <pre>
+ <i>// DebugFlag.h - Get access to the '-debug' command line option
+ //
+
+ // DebugFlag - This boolean is set to true if the '-debug' command line option
+ // is specified. This should probably not be referenced directly, instead, use
+ // the DEBUG macro below.
+ //</i>
+ extern bool DebugFlag;
+
+ <i>// DEBUG macro - This macro should be used by code to emit debug information.
+ // In the '-debug' option is specified on the command line, and if this is a
+ // debug build, then the code specified as the option to the macro will be
+ // executed. Otherwise it will not be.</i>
+ <span class="doc_hilite">#ifdef NDEBUG
+ #define DEBUG(X)
+ #else
+ #define DEBUG(X)</span> do { if (DebugFlag) { X; } } while (0)
+ <span class="doc_hilite">#endif</span>
+ </pre>
+ </div>
+
+ <p>This allows clients to blissfully use the <tt>DEBUG()</tt> macro, or the
+ <tt>DebugFlag</tt> explicitly if they want to. Now we just need to be able to
+ set the <tt>DebugFlag</tt> boolean when the option is set. To do this, we pass
+ an additional argument to our command line argument processor, and we specify
+ where to fill in with the <a href="#cl::location">cl::location</a>
+ attribute:</p>
+
+ <div class="doc_code">
+ <pre>
+ bool DebugFlag; <i>// the actual value</i>
+ static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i>
+ Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>"), <a href="#cl::Hidden">cl::Hidden</a>, <a href="#cl::location">cl::location</a>(DebugFlag));
+ </pre>
+ </div>
+
+ <p>In the above example, we specify "<tt>true</tt>" as the second argument to
+ the <tt><a href="#cl::opt">cl::opt</a></tt> template, indicating that the
+ template should not maintain a copy of the value itself. In addition to this,
+ we specify the <tt><a href="#cl::location">cl::location</a></tt> attribute, so
+ that <tt>DebugFlag</tt> is automatically set.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="attributes">Option Attributes</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>This section describes the basic attributes that you can specify on
+ options.</p>
+
+ <ul>
+
+ <li>The option name attribute (which is required for all options, except <a
+ href="#positional">positional options</a>) specifies what the option name is.
+ This option is specified in simple double quotes:
+
+ <pre>
+ <a href="#cl::opt">cl::opt</a><<b>bool</b>> Quiet("<i>quiet</i>");
+ </pre>
+
+ </li>
+
+ <li><a name="cl::desc">The <b><tt>cl::desc</tt></b></a> attribute specifies a
+ description for the option to be shown in the <tt>--help</tt> output for the
+ program.</li>
+
+ <li><a name="cl::value_desc">The <b><tt>cl::value_desc</tt></b></a> attribute
+ specifies a string that can be used to fine tune the <tt>--help</tt> output for
+ a command line option. Look <a href="#value_desc_example">here</a> for an
+ example.</li>
+
+ <li><a name="cl::init">The <b><tt>cl::init</tt></b></a> attribute specifies an
+ inital value for a <a href="#cl::opt">scalar</a> option. If this attribute is
+ not specified then the command line option value defaults to the value created
+ by the default constructor for the type. <b>Warning</b>: If you specify both
+ <b><tt>cl::init</tt></b> and <b><tt>cl::location</tt></b> for an option,
+ you must specify <b><tt>cl::location</tt></b> first, so that when the
+ command-line parser sees <b><tt>cl::init</tt></b>, it knows where to put the
+ initial value. (You will get an error at runtime if you don't put them in
+ the right order.)</li>
+
+ <li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where to
+ store the value for a parsed command line option if using external storage. See
+ the section on <a href="#storage">Internal vs External Storage</a> for more
+ information.</li>
+
+ <li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b></a> attribute
+ specifies which option a <tt><a href="#cl::alias">cl::alias</a></tt> option is
+ an alias for.</li>
+
+ <li><a name="cl::values">The <b><tt>cl::values</tt></b></a> attribute specifies
+ the string-to-value mapping to be used by the generic parser. It takes a
+ <b>clEnumValEnd terminated</b> list of (option, value, description) triplets
+ that
+ specify the option name, the value mapped to, and the description shown in the
+ <tt>--help</tt> for the tool. Because the generic parser is used most
+ frequently with enum values, two macros are often useful:
+
+ <ol>
+
+ <li><a name="clEnumVal">The <b><tt>clEnumVal</tt></b></a> macro is used as a
+ nice simple way to specify a triplet for an enum. This macro automatically
+ makes the option name be the same as the enum name. The first option to the
+ macro is the enum, the second is the description for the command line
+ option.</li>
+
+ <li><a name="clEnumValN">The <b><tt>clEnumValN</tt></b></a> macro is used to
+ specify macro options where the option name doesn't equal the enum name. For
+ this macro, the first argument is the enum value, the second is the flag name,
+ and the second is the description.</li>
+
+ </ol>
+
+ You will get a compile time error if you try to use cl::values with a parser
+ that does not support it.</li>
+
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="modifiers">Option Modifiers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Option modifiers are the flags and expressions that you pass into the
+ constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
+ href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to
+ tweak how options are parsed and how <tt>--help</tt> output is generated to fit
+ your application well.</p>
+
+ <p>These options fall into five main catagories:</p>
+
+ <ol>
+ <li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a></li>
+ <li><a href="#numoccurrences">Controlling the number of occurrences
+ required and allowed</a></li>
+ <li><a href="#valrequired">Controlling whether or not a value must be
+ specified</a></li>
+ <li><a href="#formatting">Controlling other formatting options</a></li>
+ <li><a href="#misc">Miscellaneous option modifiers</a></li>
+ </ol>
+
+ <p>It is not possible to specify two options from the same catagory (you'll get
+ a runtime error) to a single option, except for options in the miscellaneous
+ catagory. The CommandLine library specifies defaults for all of these settings
+ that are the most useful in practice and the most common, which mean that you
+ usually shouldn't have to worry about these.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="hiding">Hiding an option from <tt>--help</tt> output</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
+ <tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
+ appears in the <tt>--help</tt> and <tt>--help-hidden</tt> output for the
+ compiled program:</p>
+
+ <ul>
+
+ <li><a name="cl::NotHidden">The <b><tt>cl::NotHidden</tt></b></a> modifier
+ (which is the default for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
+ href="#cl::list">cl::list</a></tt> options) indicates the option is to appear
+ in both help listings.</li>
+
+ <li><a name="cl::Hidden">The <b><tt>cl::Hidden</tt></b></a> modifier (which is the
+ default for <tt><a href="#cl::alias">cl::alias</a></tt> options) indicates that
+ the option should not appear in the <tt>--help</tt> output, but should appear in
+ the <tt>--help-hidden</tt> output.</li>
+
+ <li><a name="cl::ReallyHidden">The <b><tt>cl::ReallyHidden</tt></b></a> modifier
+ indicates that the option should not appear in any help output.</li>
+
+ </ul>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="numoccurrences">Controlling the number of occurrences required and
+ allowed</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>This group of options is used to control how many time an option is allowed
+ (or required) to be specified on the command line of your program. Specifying a
+ value for this setting allows the CommandLine library to do error checking for
+ you.</p>
+
+ <p>The allowed values for this option group are:</p>
+
+ <ul>
+
+ <li><a name="cl::Optional">The <b><tt>cl::Optional</tt></b></a> modifier (which
+ is the default for the <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
+ href="#cl::alias">cl::alias</a></tt> classes) indicates that your program will
+ allow either zero or one occurrence of the option to be specified.</li>
+
+ <li><a name="cl::ZeroOrMore">The <b><tt>cl::ZeroOrMore</tt></b></a> modifier
+ (which is the default for the <tt><a href="#cl::list">cl::list</a></tt> class)
+ indicates that your program will allow the option to be specified zero or more
+ times.</li>
+
+ <li><a name="cl::Required">The <b><tt>cl::Required</tt></b></a> modifier
+ indicates that the specified option must be specified exactly one time.</li>
+
+ <li><a name="cl::OneOrMore">The <b><tt>cl::OneOrMore</tt></b></a> modifier
+ indicates that the option must be specified at least one time.</li>
+
+ <li>The <b><tt>cl::ConsumeAfter</tt></b> modifier is described in the <a
+ href="#positional">Positional arguments section</a>.</li>
+
+ </ul>
+
+ <p>If an option is not specified, then the value of the option is equal to the
+ value specified by the <tt><a href="#cl::init">cl::init</a></tt> attribute. If
+ the <tt><a href="#cl::init">cl::init</a></tt> attribute is not specified, the
+ option value is initialized with the default constructor for the data type.</p>
+
+ <p>If an option is specified multiple times for an option of the <tt><a
+ href="#cl::opt">cl::opt</a></tt> class, only the last value will be
+ retained.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="valrequired">Controlling whether or not a value must be specified</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>This group of options is used to control whether or not the option allows a
+ value to be present. In the case of the CommandLine library, a value is either
+ specified with an equal sign (e.g. '<tt>-index-depth=17</tt>') or as a trailing
+ string (e.g. '<tt>-o a.out</tt>').</p>
+
+ <p>The allowed values for this option group are:</p>
+
+ <ul>
+
+ <li><a name="cl::ValueOptional">The <b><tt>cl::ValueOptional</tt></b></a> modifier
+ (which is the default for <tt>bool</tt> typed options) specifies that it is
+ acceptable to have a value, or not. A boolean argument can be enabled just by
+ appearing on the command line, or it can have an explicit '<tt>-foo=true</tt>'.
+ If an option is specified with this mode, it is illegal for the value to be
+ provided without the equal sign. Therefore '<tt>-foo true</tt>' is illegal. To
+ get this behavior, you must use the <a
+ href="#cl::ValueRequired">cl::ValueRequired</a> modifier.</li>
+
+ <li><a name="cl::ValueRequired">The <b><tt>cl::ValueRequired</tt></b></a> modifier
+ (which is the default for all other types except for <a
+ href="#onealternative">unnamed alternatives using the generic parser</a>)
+ specifies that a value must be provided. This mode informs the command line
+ library that if an option is not provides with an equal sign, that the next
+ argument provided must be the value. This allows things like '<tt>-o
+ a.out</tt>' to work.</li>
+
+ <li><a name="cl::ValueDisallowed">The <b><tt>cl::ValueDisallowed</tt></b></a>
+ modifier (which is the default for <a href="#onealternative">unnamed
+ alternatives using the generic parser</a>) indicates that it is a runtime error
+ for the user to specify a value. This can be provided to disallow users from
+ providing options to boolean options (like '<tt>-foo=true</tt>').</li>
+
+ </ul>
+
+ <p>In general, the default values for this option group work just like you would
+ want them to. As mentioned above, you can specify the <a
+ href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier to a boolean
+ argument to restrict your command line parser. These options are mostly useful
+ when <a href="#extensionguide">extending the library</a>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="formatting">Controlling other formatting options</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The formatting option group is used to specify that the command line option
+ has special abilities and is otherwise different from other command line
+ arguments. As usual, you can only specify one of these arguments at most.</p>
+
+ <ul>
+
+ <li><a name="cl::NormalFormatting">The <b><tt>cl::NormalFormatting</tt></b></a>
+ modifier (which is the default all options) specifies that this option is
+ "normal".</li>
+
+ <li><a name="cl::Positional">The <b><tt>cl::Positional</tt></b></a> modifier
+ specifies that this is a positional argument that does not have a command line
+ option associated with it. See the <a href="#positional">Positional
+ Arguments</a> section for more information.</li>
+
+ <li>The <b><a href="#cl::ConsumeAfter"><tt>cl::ConsumeAfter</tt></a></b> modifier
+ specifies that this option is used to capture "interpreter style" arguments. See <a href="#cl::ConsumeAfter">this section for more information</a>.</li>
+
+ <li><a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b></a> modifier specifies
+ that this option prefixes its value. With 'Prefix' options, the equal sign does
+ not separate the value from the option name specified. Instead, the value is
+ everything after the prefix, including any equal sign if present. This is useful
+ for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a
+ linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
+ '<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
+ options, that have the <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b>
+ modifier added to allow the CommandLine library to recognize them. Note that
+ <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b> options must not have the
+ <b><tt><a href="#cl::ValueDisallowed">cl::ValueDisallowed</a></tt></b> modifier
+ specified.</li>
+
+ <li><a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b></a> modifier is used
+ to implement Unix-style tools (like <tt>ls</tt>) that have lots of single letter
+ arguments, but only require a single dash. For example, the '<tt>ls -labF</tt>'
+ command actually enables four different options, all of which are single
+ letters. Note that <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b>
+ options cannot have values.</li>
+
+ </ul>
+
+ <p>The CommandLine library does not restrict how you use the <b><tt><a
+ href="#cl::Prefix">cl::Prefix</a></tt></b> or <b><tt><a
+ href="#cl::Grouping">cl::Grouping</a></tt></b> modifiers, but it is possible to
+ specify ambiguous argument settings. Thus, it is possible to have multiple
+ letter options that are prefix or grouping options, and they will still work as
+ designed.</p>
+
+ <p>To do this, the CommandLine library uses a greedy algorithm to parse the
+ input option into (potentially multiple) prefix and grouping options. The
+ strategy basically looks like this:</p>
+
+ <div class="doc_code"><tt>parse(string OrigInput) {</tt>
+
+ <ol>
+ <li><tt>string input = OrigInput;</tt>
+ <li><tt>if (isOption(input)) return getOption(input).parse();</tt> <i>// Normal option</i>
+ <li><tt>while (!isOption(input) && !input.empty()) input.pop_back();</tt> <i>// Remove the last letter</i>
+ <li><tt>if (input.empty()) return error();</tt> <i>// No matching option</i>
+ <li><tt>if (getOption(input).isPrefix())<br>
+ return getOption(input).parse(input);</tt>
+ <li><tt>while (!input.empty()) { <i>// Must be grouping options</i><br>
+ getOption(input).parse();<br>
+ OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());<br>
+ input = OrigInput;<br>
+ while (!isOption(input) && !input.empty()) input.pop_back();<br>
+ }</tt>
+ <li><tt>if (!OrigInput.empty()) error();</tt></li>
+ </ol>
+
+ <p><tt>}</tt></p>
+ </div>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="misc">Miscellaneous option modifiers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The miscellaneous option modifiers are the only flags where you can specify
+ more than one flag from the set: they are not mutually exclusive. These flags
+ specify boolean properties that modify the option.</p>
+
+ <ul>
+
+ <li><a name="cl::CommaSeparated">The <b><tt>cl::CommaSeparated</tt></b></a> modifier
+ indicates that any commas specified for an option's value should be used to
+ split the value up into multiple values for the option. For example, these two
+ options are equivalent when <tt>cl::CommaSeparated</tt> is specified:
+ "<tt>-foo=a -foo=b -foo=c</tt>" and "<tt>-foo=a,b,c</tt>". This option only
+ makes sense to be used in a case where the option is allowed to accept one or
+ more values (i.e. it is a <a href="#cl::list">cl::list</a> option).</li>
+
+ <li><a name="cl::PositionalEatsArgs">The
+ <b><tt>cl::PositionalEatsArgs</tt></b></a> modifier (which only applies to
+ positional arguments, and only makes sense for lists) indicates that positional
+ argument should consume any strings after it (including strings that start with
+ a "-") up until another recognized positional argument. For example, if you
+ have two "eating" positional arguments, "<tt>pos1</tt>" and "<tt>pos2</tt>", the
+ string "<tt>-pos1 -foo -bar baz -pos2 -bork</tt>" would cause the "<tt>-foo -bar
+ -baz</tt>" strings to be applied to the "<tt>-pos1</tt>" option and the
+ "<tt>-bork</tt>" string to be applied to the "<tt>-pos2</tt>" option.</li>
+
+ <li><a name="cl::Sink">The <b><tt>cl::Sink</tt></b></a> modifier is
+ used to handle unknown options. If there is at least one option with
+ <b><tt>cl::Sink</tt></b></a> modifier specified, the parser passes
+ unrecognized option strings to it as values instead of signaling an
+ error. As with <b><tt>cl::CommaSeparated</tt></b></a>, this modifier
+ only makes sense with a <a href="#cl::list">cl::list</a> option.</li>
+
+
+ </ul>
+
+ <p>So far, these are the only three miscellaneous option modifiers.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="response">Response files</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Some systems, such as certain variants of Microsoft Windows and
+ some older Unices have a relatively low limit on command-line
+ length. It is therefore customary to use the so-called 'response
+ files' to circumvent this restriction. These files are mentioned on
+ the command-line (using the "@file") syntax. The program reads these
+ files and inserts the contents into argv, thereby working around the
+ command-line length limits. Response files are enabled by an optional
+ fourth argument to
+ <a href="#cl::ParseEnvironmentOptions"><tt>cl::ParseEnvironmentOptions</tt></a>
+ and
+ <a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
+ </p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="toplevel">Top-Level Classes and Functions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Despite all of the built-in flexibility, the CommandLine option library
+ really only consists of one function (<a
+ href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>)
+ and three main classes: <a href="#cl::opt"><tt>cl::opt</tt></a>, <a
+ href="#cl::list"><tt>cl::list</tt></a>, and <a
+ href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three
+ classes in detail.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt>
+ function</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
+ directly from <tt>main</tt>, and is used to fill in the values of all of the
+ command line option variables once <tt>argc</tt> and <tt>argv</tt> are
+ available.</p>
+
+ <p>The <tt>cl::ParseCommandLineOptions</tt> function requires two parameters
+ (<tt>argc</tt> and <tt>argv</tt>), but may also take an optional third parameter
+ which holds <a href="#description">additional extra text</a> to emit when the
+ <tt>--help</tt> option is invoked, and a fourth boolean parameter that enables
+ <a href="#response">response files</a>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::ParseEnvironmentOptions">The <tt>cl::ParseEnvironmentOptions</tt>
+ function</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects
+ as <a
+ href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>,
+ except that it is designed to take values for options from an environment
+ variable, for those cases in which reading the command line is not convenient or
+ desired. It fills in the values of all the command line option variables just
+ like <a
+ href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
+ does.</p>
+
+ <p>It takes four parameters: the name of the program (since <tt>argv</tt> may
+ not be available, it can't just look in <tt>argv[0]</tt>), the name of the
+ environment variable to examine, the optional
+ <a href="#description">additional extra text</a> to emit when the
+ <tt>--help</tt> option is invoked, and the boolean
+ switch that controls whether <a href="#response">reponse files</a>
+ should be read.</p>
+
+ <p><tt>cl::ParseEnvironmentOptions</tt> will break the environment
+ variable's value up into words and then process them using
+ <a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
+ <b>Note:</b> Currently <tt>cl::ParseEnvironmentOptions</tt> does not support
+ quoting, so an environment variable containing <tt>-option "foo bar"</tt> will
+ be parsed as three words, <tt>-option</tt>, <tt>"foo</tt>, and <tt>bar"</tt>,
+ which is different from what you would get from the shell with the same
+ input.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
+ function</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
+ directly from <tt>main</tt> and <i>before</i>
+ <tt>cl::ParseCommandLineOptions</tt>. Its use is optional. It simply arranges
+ for a function to be called in response to the <tt>--version</tt> option instead
+ of having the <tt>CommandLine</tt> library print out the usual version string
+ for LLVM. This is useful for programs that are not part of LLVM but wish to use
+ the <tt>CommandLine</tt> facilities. Such programs should just define a small
+ function that takes no arguments and returns <tt>void</tt> and that prints out
+ whatever version information is appropriate for the program. Pass the address
+ of that function to <tt>cl::SetVersionPrinter</tt> to arrange for it to be
+ called when the <tt>--version</tt> option is given by the user.</p>
+
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::opt">The <tt>cl::opt</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::opt</tt> class is the class used to represent scalar command line
+ options, and is the one used most of the time. It is a templated class which
+ can take up to three arguments (all except for the first have default values
+ though):</p>
+
+ <div class="doc_code"><pre>
+ <b>namespace</b> cl {
+ <b>template</b> <<b>class</b> DataType, <b>bool</b> ExternalStorage = <b>false</b>,
+ <b>class</b> ParserClass = parser<DataType> >
+ <b>class</b> opt;
+ }
+ </pre></div>
+
+ <p>The first template argument specifies what underlying data type the command
+ line argument is, and is used to select a default parser implementation. The
+ second template argument is used to specify whether the option should contain
+ the storage for the option (the default) or whether external storage should be
+ used to contain the value parsed for the option (see <a href="#storage">Internal
+ vs External Storage</a> for more information).</p>
+
+ <p>The third template argument specifies which parser to use. The default value
+ selects an instantiation of the <tt>parser</tt> class based on the underlying
+ data type of the option. In general, this default works well for most
+ applications, so this option is only used when using a <a
+ href="#customparser">custom parser</a>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::list">The <tt>cl::list</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::list</tt> class is the class used to represent a list of command
+ line options. It too is a templated class which can take up to three
+ arguments:</p>
+
+ <div class="doc_code"><pre>
+ <b>namespace</b> cl {
+ <b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
+ <b>class</b> ParserClass = parser<DataType> >
+ <b>class</b> list;
+ }
+ </pre></div>
+
+ <p>This class works the exact same as the <a
+ href="#cl::opt"><tt>cl::opt</tt></a> class, except that the second argument is
+ the <b>type</b> of the external storage, not a boolean value. For this class,
+ the marker type '<tt>bool</tt>' is used to indicate that internal storage should
+ be used.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::bits">The <tt>cl::bits</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::bits</tt> class is the class used to represent a list of command
+ line options in the form of a bit vector. It is also a templated class which
+ can take up to three arguments:</p>
+
+ <div class="doc_code"><pre>
+ <b>namespace</b> cl {
+ <b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
+ <b>class</b> ParserClass = parser<DataType> >
+ <b>class</b> bits;
+ }
+ </pre></div>
+
+ <p>This class works the exact same as the <a
+ href="#cl::opt"><tt>cl::lists</tt></a> class, except that the second argument
+ must be of <b>type</b> <tt>unsigned</tt> if external storage is used.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::alias">The <tt>cl::alias</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
+ aliases for other arguments.</p>
+
+ <div class="doc_code"><pre>
+ <b>namespace</b> cl {
+ <b>class</b> alias;
+ }
+ </pre></div>
+
+ <p>The <a href="#cl::aliasopt"><tt>cl::aliasopt</tt></a> attribute should be
+ used to specify which option this is an alias for. Alias arguments default to
+ being <a href="#cl::Hidden">Hidden</a>, and use the aliased options parser to do
+ the conversion from string to data.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
+ help text to be printed out for the <tt>--help</tt> option.</p>
+
+ <div class="doc_code"><pre>
+ <b>namespace</b> cl {
+ <b>struct</b> extrahelp;
+ }
+ </pre></div>
+
+ <p>To use the extrahelp, simply construct one with a <tt>const char*</tt>
+ parameter to the constructor. The text passed to the constructor will be printed
+ at the bottom of the help message, verbatim. Note that multiple
+ <tt>cl::extrahelp</tt> <b>can</b> be used, but this practice is discouraged. If
+ your tool needs to print additional help information, put all that help into a
+ single <tt>cl::extrahelp</tt> instance.</p>
+ <p>For example:</p>
+ <div class="doc_code"><pre>
+ cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n");
+ </pre></div>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="builtinparsers">Builtin parsers</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Parsers control how the string value taken from the command line is
+ translated into a typed value, suitable for use in a C++ program. By default,
+ the CommandLine library uses an instance of <tt>parser<type></tt> if the
+ command line option specifies that it uses values of type '<tt>type</tt>'.
+ Because of this, custom option processing is specified with specializations of
+ the '<tt>parser</tt>' class.</p>
+
+ <p>The CommandLine library provides the following builtin parser
+ specializations, which are sufficient for most applications. It can, however,
+ also be extended to work with new data types and new ways of interpreting the
+ same data. See the <a href="#customparser">Writing a Custom Parser</a> for more
+ details on this type of library extension.</p>
+
+ <ul>
+
+ <li><a name="genericparser">The <b>generic <tt>parser<t></tt> parser</b></a>
+ can be used to map strings values to any data type, through the use of the <a
+ href="#cl::values">cl::values</a> property, which specifies the mapping
+ information. The most common use of this parser is for parsing enum values,
+ which allows you to use the CommandLine library for all of the error checking to
+ make sure that only valid enum values are specified (as opposed to accepting
+ arbitrary strings). Despite this, however, the generic parser class can be used
+ for any data type.</li>
+
+ <li><a name="boolparser">The <b><tt>parser<bool></tt> specialization</b></a>
+ is used to convert boolean strings to a boolean value. Currently accepted
+ strings are "<tt>true</tt>", "<tt>TRUE</tt>", "<tt>True</tt>", "<tt>1</tt>",
+ "<tt>false</tt>", "<tt>FALSE</tt>", "<tt>False</tt>", and "<tt>0</tt>".</li>
+
+ <li><a name="boolOrDefaultparser">The <b><tt>parser<boolOrDefault></tt>
+ specialization</b></a> is used for cases where the value is boolean,
+ but we also need to know whether the option was specified at all. boolOrDefault
+ is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts
+ the same strings as <b><tt>parser<bool></tt></b>.</li>
+
+ <li><a name="stringparser">The <b><tt>parser<string></tt>
+ specialization</b></a> simply stores the parsed string into the string value
+ specified. No conversion or modification of the data is performed.</li>
+
+ <li><a name="intparser">The <b><tt>parser<int></tt> specialization</b></a>
+ uses the C <tt>strtol</tt> function to parse the string input. As such, it will
+ accept a decimal number (with an optional '+' or '-' prefix) which must start
+ with a non-zero digit. It accepts octal numbers, which are identified with a
+ '<tt>0</tt>' prefix digit, and hexadecimal numbers with a prefix of
+ '<tt>0x</tt>' or '<tt>0X</tt>'.</li>
+
+ <li><a name="doubleparser">The <b><tt>parser<double></tt></b></a> and
+ <b><tt>parser<float></tt> specializations</b> use the standard C
+ <tt>strtod</tt> function to convert floating point strings into floating point
+ values. As such, a broad range of string formats is supported, including
+ exponential notation (ex: <tt>1.7e15</tt>) and properly supports locales.
+ </li>
+
+ </ul>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="extensionguide">Extension Guide</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Although the CommandLine library has a lot of functionality built into it
+ already (as discussed previously), one of its true strengths lie in its
+ extensibility. This section discusses how the CommandLine library works under
+ the covers and illustrates how to do some simple, common, extensions.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="customparser">Writing a custom parser</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>One of the simplest and most common extensions is the use of a custom parser.
+ As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
+ of the CommandLine library that turns string input from the user into a
+ particular parsed data type, validating the input in the process.</p>
+
+ <p>There are two ways to use a new parser:</p>
+
+ <ol>
+
+ <li>
+
+ <p>Specialize the <a href="#genericparser"><tt>cl::parser</tt></a> template for
+ your custom data type.<p>
+
+ <p>This approach has the advantage that users of your custom data type will
+ automatically use your custom parser whenever they define an option with a value
+ type of your data type. The disadvantage of this approach is that it doesn't
+ work if your fundamental data type is something that is already supported.</p>
+
+ </li>
+
+ <li>
+
+ <p>Write an independent class, using it explicitly from options that need
+ it.</p>
+
+ <p>This approach works well in situations where you would line to parse an
+ option using special syntax for a not-very-special data-type. The drawback of
+ this approach is that users of your parser have to be aware that they are using
+ your parser instead of the builtin ones.</p>
+
+ </li>
+
+ </ol>
+
+ <p>To guide the discussion, we will discuss a custom parser that accepts file
+ sizes, specified with an optional unit after the numeric size. For example, we
+ would like to parse "102kb", "41M", "1G" into the appropriate integer value. In
+ this case, the underlying data type we want to parse into is
+ '<tt>unsigned</tt>'. We choose approach #2 above because we don't want to make
+ this the default for all <tt>unsigned</tt> options.</p>
+
+ <p>To start out, we declare our new <tt>FileSizeParser</tt> class:</p>
+
+ <div class="doc_code"><pre>
+ <b>struct</b> FileSizeParser : <b>public</b> cl::basic_parser<<b>unsigned</b>> {
+ <i>// parse - Return true on error.</i>
+ <b>bool</b> parse(cl::Option &O, <b>const char</b> *ArgName, <b>const</b> std::string &ArgValue,
+ <b>unsigned</b> &Val);
+ };
+ </pre></div>
+
+ <p>Our new class inherits from the <tt>cl::basic_parser</tt> template class to
+ fill in the default, boiler plate code for us. We give it the data type that
+ we parse into, the last argument to the <tt>parse</tt> method, so that clients of
+ our custom parser know what object type to pass in to the parse method. (Here we
+ declare that we parse into '<tt>unsigned</tt>' variables.)</p>
+
+ <p>For most purposes, the only method that must be implemented in a custom
+ parser is the <tt>parse</tt> method. The <tt>parse</tt> method is called
+ whenever the option is invoked, passing in the option itself, the option name,
+ the string to parse, and a reference to a return value. If the string to parse
+ is not well-formed, the parser should output an error message and return true.
+ Otherwise it should return false and set '<tt>Val</tt>' to the parsed value. In
+ our example, we implement <tt>parse</tt> as:</p>
+
+ <div class="doc_code"><pre>
+ <b>bool</b> FileSizeParser::parse(cl::Option &O, <b>const char</b> *ArgName,
+ <b>const</b> std::string &Arg, <b>unsigned</b> &Val) {
+ <b>const char</b> *ArgStart = Arg.c_str();
+ <b>char</b> *End;
+
+ <i>// Parse integer part, leaving 'End' pointing to the first non-integer char</i>
+ Val = (unsigned)strtol(ArgStart, &End, 0);
+
+ <b>while</b> (1) {
+ <b>switch</b> (*End++) {
+ <b>case</b> 0: <b>return</b> false; <i>// No error</i>
+ <b>case</b> 'i': <i>// Ignore the 'i' in KiB if people use that</i>
+ <b>case</b> 'b': <b>case</b> 'B': <i>// Ignore B suffix</i>
+ <b>break</b>;
+
+ <b>case</b> 'g': <b>case</b> 'G': Val *= 1024*1024*1024; <b>break</b>;
+ <b>case</b> 'm': <b>case</b> 'M': Val *= 1024*1024; <b>break</b>;
+ <b>case</b> 'k': <b>case</b> 'K': Val *= 1024; <b>break</b>;
+
+ default:
+ <i>// Print an error message if unrecognized character!</i>
+ <b>return</b> O.error(": '" + Arg + "' value invalid for file size argument!");
+ }
+ }
+ }
+ </pre></div>
+
+ <p>This function implements a very simple parser for the kinds of strings we are
+ interested in. Although it has some holes (it allows "<tt>123KKK</tt>" for
+ example), it is good enough for this example. Note that we use the option
+ itself to print out the error message (the <tt>error</tt> method always returns
+ true) in order to get a nice error message (shown below). Now that we have our
+ parser class, we can use it like this:</p>
+
+ <div class="doc_code"><pre>
+ <b>static</b> <a href="#cl::opt">cl::opt</a><<b>unsigned</b>, <b>false</b>, FileSizeParser>
+ MFS(<i>"max-file-size"</i>, <a href="#cl::desc">cl::desc</a>(<i>"Maximum file size to accept"</i>),
+ <a href="#cl::value_desc">cl::value_desc</a>("<i>size</i>"));
+ </pre></div>
+
+ <p>Which adds this to the output of our program:</p>
+
+ <div class="doc_code"><pre>
+ OPTIONS:
+ -help - display available options (--help-hidden for more)
+ ...
+ <b>-max-file-size=<size> - Maximum file size to accept</b>
+ </pre></div>
+
+ <p>And we can test that our parse works correctly now (the test program just
+ prints out the max-file-size argument value):</p>
+
+ <div class="doc_code"><pre>
+ $ ./test
+ MFS: 0
+ $ ./test -max-file-size=123MB
+ MFS: 128974848
+ $ ./test -max-file-size=3G
+ MFS: 3221225472
+ $ ./test -max-file-size=dog
+ -max-file-size option: 'dog' value invalid for file size argument!
+ </pre></div>
+
+ <p>It looks like it works. The error message that we get is nice and helpful,
+ and we seem to accept reasonable file sizes. This wraps up the "custom parser"
+ tutorial.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="explotingexternal">Exploiting external storage</a>
+ </div>
+
+ <div class="doc_text">
+ <p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
+ will automatically be included in any program that links with that library.
+ This is a feature. However, sometimes it is necessary to know the value of the
+ command line option outside of the library. In these cases the library does or
+ should provide an external storage location that is accessible to users of the
+ library. Examples of this include the <tt>llvm::DebugFlag</tt> exported by the
+ <tt>lib/Support/Debug.cpp</tt> file and the <tt>llvm::TimePassesIsEnabled</tt>
+ flag exported by the <tt>lib/VMCore/Pass.cpp</tt> file.</p>
+
+ <p>TODO: complete this section</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="dynamicopts">Dynamically adding command line options</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>TODO: fill in this section</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/CompilerDriver.html
diff -c /dev/null llvm-www/releases/2.3/docs/CompilerDriver.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/CompilerDriver.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,420 ----
+ <?xml version="1.0" encoding="utf-8" ?>
+ <!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" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+ <title>Customizing LLVMC: Reference Manual</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css" />
+ </head>
+ <body>
+ <div class="document" id="customizing-llvmc-reference-manual">
+
+ <div class="doc_title">Customizing LLVMC: Reference Manual</div>
+
+ <div class="doc_warning">
+ <p>Note: This document is a work-in-progress. Additions and clarifications
+ are welcome.</p>
+ </div>
+
+ <p>LLVMC is a generic compiler driver, designed to be customizable and
+ extensible. It plays the same role for LLVM as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program
+ does for GCC - LLVMC's job is essentially to transform a set of input
+ files into a set of targets depending on configuration rules and user
+ options. What makes LLVMC different is that these transformation rules
+ are completely customizable - in fact, LLVMC knows nothing about the
+ specifics of transformation (even the command-line options are mostly
+ not hard-coded) and regards the transformation structure as an
+ abstract graph. This makes it possible to adapt LLVMC for other
+ purposes - for example, as a build tool for game resources.</p>
+ <p>Because LLVMC employs TableGen <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a> as its configuration language, you
+ need to be familiar with it to customize LLVMC.</p>
+ <div class="contents topic">
+ <ul class="simple">
+ <li><a class="reference" href="#compiling-with-llvmc" id="id3" name="id3">Compiling with LLVMC</a></li>
+ <li><a class="reference" href="#predefined-options" id="id4" name="id4">Predefined options</a></li>
+ <li><a class="reference" href="#customizing-llvmc-the-compilation-graph" id="id5" name="id5">Customizing LLVMC: the compilation graph</a></li>
+ <li><a class="reference" href="#writing-a-tool-description" id="id6" name="id6">Writing a tool description</a></li>
+ <li><a class="reference" href="#option-list-specifying-all-options-in-a-single-place" id="id7" name="id7">Option list - specifying all options in a single place</a></li>
+ <li><a class="reference" href="#using-hooks-and-environment-variables-in-the-cmd-line-property" id="id8" name="id8">Using hooks and environment variables in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> property</a></li>
+ <li><a class="reference" href="#conditional-evaluation-the-case-expression" id="id9" name="id9">Conditional evaluation: the <tt class="docutils literal"><span class="pre">case</span></tt> expression</a></li>
+ <li><a class="reference" href="#language-map" id="id10" name="id10">Language map</a></li>
+ <li><a class="reference" href="#references" id="id11" name="id11">References</a></li>
+ </ul>
+ </div>
+
+ <div class="doc_author">Written by Mikhail Glushenkov</div>
+
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id3" id="compiling-with-llvmc" name="compiling-with-llvmc">Compiling with LLVMC</a></div>
+ <p>LLVMC tries hard to be as compatible with <tt class="docutils literal"><span class="pre">gcc</span></tt> as possible,
+ although there are some small differences. Most of the time, however,
+ you shouldn't be able to notice them:</p>
+ <pre class="literal-block">
+ $ # This works as expected:
+ $ llvmc2 -O3 -Wall hello.cpp
+ $ ./a.out
+ hello
+ </pre>
+ <p>One nice feature of LLVMC is that one doesn't have to distinguish
+ between different compilers for different languages (think <tt class="docutils literal"><span class="pre">g++</span></tt> and
+ <tt class="docutils literal"><span class="pre">gcc</span></tt>) - the right toolchain is chosen automatically based on input
+ language names (which are, in turn, determined from file
+ extensions). If you want to force files ending with ".c" to compile as
+ C++, use the <tt class="docutils literal"><span class="pre">-x</span></tt> option, just like you would do it with <tt class="docutils literal"><span class="pre">gcc</span></tt>:</p>
+ <pre class="literal-block">
+ $ llvmc2 -x c hello.cpp
+ $ # hello.cpp is really a C file
+ $ ./a.out
+ hello
+ </pre>
+ <p>On the other hand, when using LLVMC as a linker to combine several C++
+ object files you should provide the <tt class="docutils literal"><span class="pre">--linker</span></tt> option since it's
+ impossible for LLVMC to choose the right linker in that case:</p>
+ <pre class="literal-block">
+ $ llvmc2 -c hello.cpp
+ $ llvmc2 hello.o
+ [A lot of link-time errors skipped]
+ $ llvmc2 --linker=c++ hello.o
+ $ ./a.out
+ hello
+ </pre>
+ </div>
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id4" id="predefined-options" name="predefined-options">Predefined options</a></div>
+ <p>LLVMC has some built-in options that can't be overridden in the
+ configuration files:</p>
+ <ul class="simple">
+ <li><tt class="docutils literal"><span class="pre">-o</span> <span class="pre">FILE</span></tt> - Output file name.</li>
+ <li><tt class="docutils literal"><span class="pre">-x</span> <span class="pre">LANGUAGE</span></tt> - Specify the language of the following input files
+ until the next -x option.</li>
+ <li><tt class="docutils literal"><span class="pre">-v</span></tt> - Enable verbose mode, i.e. print out all executed commands.</li>
+ <li><tt class="docutils literal"><span class="pre">--view-graph</span></tt> - Show a graphical representation of the compilation
+ graph. Requires that you have <tt class="docutils literal"><span class="pre">dot</span></tt> and <tt class="docutils literal"><span class="pre">gv</span></tt> commands
+ installed. Hidden option, useful for debugging.</li>
+ <li><tt class="docutils literal"><span class="pre">--write-graph</span></tt> - Write a <tt class="docutils literal"><span class="pre">compilation-graph.dot</span></tt> file in the
+ current directory with the compilation graph description in the
+ Graphviz format. Hidden option, useful for debugging.</li>
+ <li><tt class="docutils literal"><span class="pre">--save-temps</span></tt> - Write temporary files to the current directory
+ and do not delete them on exit. Hidden option, useful for debugging.</li>
+ <li><tt class="docutils literal"><span class="pre">--help</span></tt>, <tt class="docutils literal"><span class="pre">--help-hidden</span></tt>, <tt class="docutils literal"><span class="pre">--version</span></tt> - These options have
+ their standard meaning.</li>
+ </ul>
+ </div>
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id5" id="customizing-llvmc-the-compilation-graph" name="customizing-llvmc-the-compilation-graph">Customizing LLVMC: the compilation graph</a></div>
+ <p>At the time of writing LLVMC does not support on-the-fly reloading of
+ configuration, so to customize LLVMC you'll have to recompile the
+ source code (which lives under <tt class="docutils literal"><span class="pre">$LLVM_DIR/tools/llvmc2</span></tt>). The
+ default configuration files are <tt class="docutils literal"><span class="pre">Common.td</span></tt> (contains common
+ definitions, don't forget to <tt class="docutils literal"><span class="pre">include</span></tt> it in your configuration
+ files), <tt class="docutils literal"><span class="pre">Tools.td</span></tt> (tool descriptions) and <tt class="docutils literal"><span class="pre">Graph.td</span></tt> (compilation
+ graph definition).</p>
+ <p>To compile LLVMC with your own configuration file (say,``MyGraph.td``),
+ run <tt class="docutils literal"><span class="pre">make</span></tt> like this:</p>
+ <pre class="literal-block">
+ $ cd $LLVM_DIR/tools/llvmc2
+ $ make GRAPH=MyGraph.td TOOLNAME=my_llvmc
+ </pre>
+ <p>This will build an executable named <tt class="docutils literal"><span class="pre">my_llvmc</span></tt>. There are also
+ several sample configuration files in the <tt class="docutils literal"><span class="pre">llvmc2/examples</span></tt>
+ subdirectory that should help to get you started.</p>
+ <p>Internally, LLVMC stores information about possible source
+ transformations in form of a graph. Nodes in this graph represent
+ tools, and edges between two nodes represent a transformation path. A
+ special "root" node is used to mark entry points for the
+ transformations. LLVMC also assigns a weight to each edge (more on
+ this later) to choose between several alternative edges.</p>
+ <p>The definition of the compilation graph (see file <tt class="docutils literal"><span class="pre">Graph.td</span></tt>) is
+ just a list of edges:</p>
+ <pre class="literal-block">
+ def CompilationGraph : CompilationGraph<[
+ Edge<root, llvm_gcc_c>,
+ Edge<root, llvm_gcc_assembler>,
+ ...
+
+ Edge<llvm_gcc_c, llc>,
+ Edge<llvm_gcc_cpp, llc>,
+ ...
+
+ OptionalEdge<llvm_gcc_c, opt, [(switch_on "opt")]>,
+ OptionalEdge<llvm_gcc_cpp, opt, [(switch_on "opt")]>,
+ ...
+
+ OptionalEdge<llvm_gcc_assembler, llvm_gcc_cpp_linker,
+ (case (input_languages_contain "c++"), (inc_weight),
+ (or (parameter_equals "linker", "g++"),
+ (parameter_equals "linker", "c++")), (inc_weight))>,
+ ...
+
+ ]>;
+ </pre>
+ <p>As you can see, the edges can be either default or optional, where
+ optional edges are differentiated by sporting a <tt class="docutils literal"><span class="pre">case</span></tt> expression
+ used to calculate the edge's weight.</p>
+ <p>The default edges are assigned a weight of 1, and optional edges get a
+ weight of 0 + 2*N where N is the number of tests that evaluated to
+ true in the <tt class="docutils literal"><span class="pre">case</span></tt> expression. It is also possible to provide an
+ integer parameter to <tt class="docutils literal"><span class="pre">inc_weight</span></tt> and <tt class="docutils literal"><span class="pre">dec_weight</span></tt> - in this case,
+ the weight is increased (or decreased) by the provided value instead
+ of the default 2.</p>
+ <p>When passing an input file through the graph, LLVMC picks the edge
+ with the maximum weight. To avoid ambiguity, there should be only one
+ default edge between two nodes (with the exception of the root node,
+ which gets a special treatment - there you are allowed to specify one
+ default edge <em>per language</em>).</p>
+ <p>To get a visual representation of the compilation graph (useful for
+ debugging), run <tt class="docutils literal"><span class="pre">llvmc2</span> <span class="pre">--view-graph</span></tt>. You will need <tt class="docutils literal"><span class="pre">dot</span></tt> and
+ <tt class="docutils literal"><span class="pre">gsview</span></tt> installed for this to work properly.</p>
+ </div>
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id6" id="writing-a-tool-description" name="writing-a-tool-description">Writing a tool description</a></div>
+ <p>As was said earlier, nodes in the compilation graph represent tools,
+ which are described separately. A tool definition looks like this
+ (taken from the <tt class="docutils literal"><span class="pre">Tools.td</span></tt> file):</p>
+ <pre class="literal-block">
+ def llvm_gcc_cpp : Tool<[
+ (in_language "c++"),
+ (out_language "llvm-assembler"),
+ (output_suffix "bc"),
+ (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
+ (sink)
+ ]>;
+ </pre>
+ <p>This defines a new tool called <tt class="docutils literal"><span class="pre">llvm_gcc_cpp</span></tt>, which is an alias for
+ <tt class="docutils literal"><span class="pre">llvm-g++</span></tt>. As you can see, a tool definition is just a list of
+ properties; most of them should be self-explanatory. The <tt class="docutils literal"><span class="pre">sink</span></tt>
+ property means that this tool should be passed all command-line
+ options that lack explicit descriptions.</p>
+ <p>The complete list of the currently implemented tool properties follows:</p>
+ <ul class="simple">
+ <li>Possible tool properties:<ul>
+ <li><tt class="docutils literal"><span class="pre">in_language</span></tt> - input language name.</li>
+ <li><tt class="docutils literal"><span class="pre">out_language</span></tt> - output language name.</li>
+ <li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - output file suffix.</li>
+ <li><tt class="docutils literal"><span class="pre">cmd_line</span></tt> - the actual command used to run the tool. You can
+ use <tt class="docutils literal"><span class="pre">$INFILE</span></tt> and <tt class="docutils literal"><span class="pre">$OUTFILE</span></tt> variables, output redirection
+ with <tt class="docutils literal"><span class="pre">></span></tt>, hook invocations (<tt class="docutils literal"><span class="pre">$CALL</span></tt>), environment variables
+ (via <tt class="docutils literal"><span class="pre">$ENV</span></tt>) and the <tt class="docutils literal"><span class="pre">case</span></tt> construct (more on this below).</li>
+ <li><tt class="docutils literal"><span class="pre">join</span></tt> - this tool is a "join node" in the graph, i.e. it gets a
+ list of input files and joins them together. Used for linkers.</li>
+ <li><tt class="docutils literal"><span class="pre">sink</span></tt> - all command-line options that are not handled by other
+ tools are passed to this tool.</li>
+ </ul>
+ </li>
+ </ul>
+ <p>The next tool definition is slightly more complex:</p>
+ <pre class="literal-block">
+ def llvm_gcc_linker : Tool<[
+ (in_language "object-code"),
+ (out_language "executable"),
+ (output_suffix "out"),
+ (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
+ (join),
+ (prefix_list_option "L", (forward),
+ (help "add a directory to link path")),
+ (prefix_list_option "l", (forward),
+ (help "search a library when linking")),
+ (prefix_list_option "Wl", (unpack_values),
+ (help "pass options to linker"))
+ ]>;
+ </pre>
+ <p>This tool has a "join" property, which means that it behaves like a
+ linker. This tool also defines several command-line options: <tt class="docutils literal"><span class="pre">-l</span></tt>,
+ <tt class="docutils literal"><span class="pre">-L</span></tt> and <tt class="docutils literal"><span class="pre">-Wl</span></tt> which have their usual meaning. An option has two
+ attributes: a name and a (possibly empty) list of properties. All
+ currently implemented option types and properties are described below:</p>
+ <ul>
+ <li><p class="first">Possible option types:</p>
+ <blockquote>
+ <ul class="simple">
+ <li><tt class="docutils literal"><span class="pre">switch_option</span></tt> - a simple boolean switch, for example <tt class="docutils literal"><span class="pre">-time</span></tt>.</li>
+ <li><tt class="docutils literal"><span class="pre">parameter_option</span></tt> - option that takes an argument, for example
+ <tt class="docutils literal"><span class="pre">-std=c99</span></tt>;</li>
+ <li><tt class="docutils literal"><span class="pre">parameter_list_option</span></tt> - same as the above, but more than one
+ occurence of the option is allowed.</li>
+ <li><tt class="docutils literal"><span class="pre">prefix_option</span></tt> - same as the parameter_option, but the option name
+ and parameter value are not separated.</li>
+ <li><tt class="docutils literal"><span class="pre">prefix_list_option</span></tt> - same as the above, but more than one
+ occurence of the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li>
+ <li><tt class="docutils literal"><span class="pre">alias_option</span></tt> - a special option type for creating
+ aliases. Unlike other option types, aliases are not allowed to
+ have any properties besides the aliased option name. Usage
+ example: <tt class="docutils literal"><span class="pre">(alias_option</span> <span class="pre">"preprocess",</span> <span class="pre">"E")</span></tt></li>
+ </ul>
+ </blockquote>
+ </li>
+ <li><p class="first">Possible option properties:</p>
+ <blockquote>
+ <ul class="simple">
+ <li><tt class="docutils literal"><span class="pre">append_cmd</span></tt> - append a string to the tool invocation command.</li>
+ <li><tt class="docutils literal"><span class="pre">forward</span></tt> - forward this option unchanged.</li>
+ <li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - modify the output suffix of this
+ tool. Example : <tt class="docutils literal"><span class="pre">(switch</span> <span class="pre">"E",</span> <span class="pre">(output_suffix</span> <span class="pre">"i")</span></tt>.</li>
+ <li><tt class="docutils literal"><span class="pre">stop_compilation</span></tt> - stop compilation after this phase.</li>
+ <li><tt class="docutils literal"><span class="pre">unpack_values</span></tt> - used for for splitting and forwarding
+ comma-separated lists of options, e.g. <tt class="docutils literal"><span class="pre">-Wa,-foo=bar,-baz</span></tt> is
+ converted to <tt class="docutils literal"><span class="pre">-foo=bar</span> <span class="pre">-baz</span></tt> and appended to the tool invocation
+ command.</li>
+ <li><tt class="docutils literal"><span class="pre">help</span></tt> - help string associated with this option. Used for
+ <tt class="docutils literal"><span class="pre">--help</span></tt> output.</li>
+ <li><tt class="docutils literal"><span class="pre">required</span></tt> - this option is obligatory.</li>
+ </ul>
+ </blockquote>
+ </li>
+ </ul>
+ </div>
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id7" id="option-list-specifying-all-options-in-a-single-place" name="option-list-specifying-all-options-in-a-single-place">Option list - specifying all options in a single place</a></div>
+ <p>It can be handy to have all information about options gathered in a
+ single place to provide an overview. This can be achieved by using a
+ so-called <tt class="docutils literal"><span class="pre">OptionList</span></tt>:</p>
+ <pre class="literal-block">
+ def Options : OptionList<[
+ (switch_option "E", (help "Help string")),
+ (alias_option "quiet", "q")
+ ...
+ ]>;
+ </pre>
+ <p><tt class="docutils literal"><span class="pre">OptionList</span></tt> is also a good place to specify option aliases.</p>
+ <p>Tool-specific option properties like <tt class="docutils literal"><span class="pre">append_cmd</span></tt> have (obviously)
+ no meaning in the context of <tt class="docutils literal"><span class="pre">OptionList</span></tt>, so the only properties
+ allowed there are <tt class="docutils literal"><span class="pre">help</span></tt> and <tt class="docutils literal"><span class="pre">required</span></tt>.</p>
+ <p>Option lists are used at the file scope. See file
+ <tt class="docutils literal"><span class="pre">examples/Clang.td</span></tt> for an example of <tt class="docutils literal"><span class="pre">OptionList</span></tt> usage.</p>
+ </div>
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id8" id="using-hooks-and-environment-variables-in-the-cmd-line-property" name="using-hooks-and-environment-variables-in-the-cmd-line-property">Using hooks and environment variables in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> property</a></div>
+ <p>Normally, LLVMC executes programs from the system <tt class="docutils literal"><span class="pre">PATH</span></tt>. Sometimes,
+ this is not sufficient: for example, we may want to specify tool names
+ in the configuration file. This can be achieved via the mechanism of
+ hooks - to compile LLVMC with your hooks, just drop a .cpp file into
+ <tt class="docutils literal"><span class="pre">tools/llvmc2</span></tt> directory. Hooks should live in the <tt class="docutils literal"><span class="pre">hooks</span></tt>
+ namespace and have the signature <tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::MyHookName</span>
+ <span class="pre">(void)</span></tt>. They can be used from the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> tool property:</p>
+ <pre class="literal-block">
+ (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
+ </pre>
+ <p>It is also possible to use environment variables in the same manner:</p>
+ <pre class="literal-block">
+ (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
+ </pre>
+ <p>To change the command line string based on user-provided options use
+ the <tt class="docutils literal"><span class="pre">case</span></tt> expression (documented below):</p>
+ <pre class="literal-block">
+ (cmd_line
+ (case
+ (switch_on "E"),
+ "llvm-g++ -E -x c $INFILE -o $OUTFILE",
+ (default),
+ "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm"))
+ </pre>
+ </div>
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id9" id="conditional-evaluation-the-case-expression" name="conditional-evaluation-the-case-expression">Conditional evaluation: the <tt class="docutils literal"><span class="pre">case</span></tt> expression</a></div>
+ <p>The 'case' construct can be used to calculate weights of the optional
+ edges and to choose between several alternative command line strings
+ in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> tool property. It is designed after the
+ similarly-named construct in functional languages and takes the form
+ <tt class="docutils literal"><span class="pre">(case</span> <span class="pre">(test_1),</span> <span class="pre">statement_1,</span> <span class="pre">(test_2),</span> <span class="pre">statement_2,</span> <span class="pre">...</span> <span class="pre">(test_N),</span>
+ <span class="pre">statement_N)</span></tt>. The statements are evaluated only if the corresponding
+ tests evaluate to true.</p>
+ <p>Examples:</p>
+ <pre class="literal-block">
+ // Increases edge weight by 5 if "-A" is provided on the
+ // command-line, and by 5 more if "-B" is also provided.
+ (case
+ (switch_on "A"), (inc_weight 5),
+ (switch_on "B"), (inc_weight 5))
+
+ // Evaluates to "cmdline1" if option "-A" is provided on the
+ // command line, otherwise to "cmdline2"
+ (case
+ (switch_on "A"), "cmdline1",
+ (switch_on "B"), "cmdline2",
+ (default), "cmdline3")
+ </pre>
+ <p>Note the slight difference in 'case' expression handling in contexts
+ of edge weights and command line specification - in the second example
+ the value of the <tt class="docutils literal"><span class="pre">"B"</span></tt> switch is never checked when switch <tt class="docutils literal"><span class="pre">"A"</span></tt> is
+ enabled, and the whole expression always evaluates to <tt class="docutils literal"><span class="pre">"cmdline1"</span></tt> in
+ that case.</p>
+ <p>Case expressions can also be nested, i.e. the following is legal:</p>
+ <pre class="literal-block">
+ (case (switch_on "E"), (case (switch_on "o"), ..., (default), ...)
+ (default), ...)
+ </pre>
+ <p>You should, however, try to avoid doing that because it hurts
+ readability. It is usually better to split tool descriptions and/or
+ use TableGen inheritance instead.</p>
+ <ul class="simple">
+ <li>Possible tests are:<ul>
+ <li><tt class="docutils literal"><span class="pre">switch_on</span></tt> - Returns true if a given command-line option is
+ provided by the user. Example: <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">"opt")</span></tt>. Note that
+ you have to define all possible command-line options separately in
+ the tool descriptions. See the next doc_text for the discussion of
+ different kinds of command-line options.</li>
+ <li><tt class="docutils literal"><span class="pre">parameter_equals</span></tt> - Returns true if a command-line parameter equals
+ a given value. Example: <tt class="docutils literal"><span class="pre">(parameter_equals</span> <span class="pre">"W",</span> <span class="pre">"all")</span></tt>.</li>
+ <li><tt class="docutils literal"><span class="pre">element_in_list</span></tt> - Returns true if a command-line parameter list
+ includes a given value. Example: <tt class="docutils literal"><span class="pre">(parameter_in_list</span> <span class="pre">"l",</span> <span class="pre">"pthread")</span></tt>.</li>
+ <li><tt class="docutils literal"><span class="pre">input_languages_contain</span></tt> - Returns true if a given language
+ belongs to the current input language set. Example:
+ <tt class="docutils literal"><span class="pre">`(input_languages_contain</span> <span class="pre">"c++")</span></tt>.</li>
+ <li><tt class="docutils literal"><span class="pre">in_language</span></tt> - Evaluates to true if the language of the input
+ file equals to the argument. Valid only when using <tt class="docutils literal"><span class="pre">case</span></tt>
+ expression in a <tt class="docutils literal"><span class="pre">cmd_line</span></tt> tool property. Example:
+ <tt class="docutils literal"><span class="pre">`(in_language</span> <span class="pre">"c++")</span></tt>.</li>
+ <li><tt class="docutils literal"><span class="pre">not_empty</span></tt> - Returns true if a given option (which should be
+ either a parameter or a parameter list) is set by the
+ user. Example: <tt class="docutils literal"><span class="pre">`(not_empty</span> <span class="pre">"o")</span></tt>.</li>
+ <li><tt class="docutils literal"><span class="pre">default</span></tt> - Always evaluates to true. Should always be the last
+ test in the <tt class="docutils literal"><span class="pre">case</span></tt> expression.</li>
+ <li><tt class="docutils literal"><span class="pre">and</span></tt> - A standard logical combinator that returns true iff all
+ of its arguments return true. Used like this: <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(test1),</span>
+ <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>. Nesting of <tt class="docutils literal"><span class="pre">and</span></tt> and <tt class="docutils literal"><span class="pre">or</span></tt> is allowed,
+ but not encouraged.</li>
+ <li><tt class="docutils literal"><span class="pre">or</span></tt> - Another logical combinator that returns true only if any
+ one of its arguments returns true. Example: <tt class="docutils literal"><span class="pre">(or</span> <span class="pre">(test1),</span>
+ <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>.</li>
+ </ul>
+ </li>
+ </ul>
+ </div>
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id10" id="language-map" name="language-map">Language map</a></div>
+ <p>One last thing that you will need to modify when adding support for a
+ new language to LLVMC is the language map, which defines mappings from
+ file extensions to language names. It is used to choose the proper
+ toolchain(s) for a given input file set. Language map definition is
+ located in the file <tt class="docutils literal"><span class="pre">Tools.td</span></tt> and looks like this:</p>
+ <pre class="literal-block">
+ def LanguageMap : LanguageMap<
+ [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
+ LangToSuffixes<"c", ["c"]>,
+ ...
+ ]>;
+ </pre>
+ </div>
+ <div class="doc_text">
+ <div class="doc_section"><a class="toc-backref" href="#id11" id="references" name="references">References</a></div>
+ <table class="docutils footnote" frame="void" id="id2" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>TableGen Fundamentals
+ <a class="reference" href="http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html">http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html</a></td></tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <hr />
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" /></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" /></a>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br/>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/CompilerWriterInfo.html
diff -c /dev/null llvm-www/releases/2.3/docs/CompilerWriterInfo.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/CompilerWriterInfo.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,261 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Architecture/platform information for compiler writers</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+
+ <div class="doc_title">
+ Architecture/platform information for compiler writers
+ </div>
+
+ <div class="doc_warning">
+ <p>Note: This document is a work-in-progress. Additions and clarifications
+ are welcome.</p>
+ </div>
+
+ <ol>
+ <li><a href="#hw">Hardware</a>
+ <ol>
+ <li><a href="#alpha">Alpha</a></li>
+ <li><a href="#arm">ARM</a></li>
+ <li><a href="#ia64">Itanium</a></li>
+ <li><a href="#mips">MIPS</a></li>
+ <li><a href="#ppc">PowerPC</a></li>
+ <li><a href="#sparc">SPARC</a></li>
+ <li><a href="#x86">X86</a></li>
+ <li><a href="#other">Other lists</a></li>
+ </ol></li>
+ <li><a href="#abi">Application Binary Interface (ABI)</a>
+ <ol>
+ <li><a href="#linux">Linux</a></li>
+ <li><a href="#osx">OS X</a></li>
+ </ol></li>
+ <li><a href="#misc">Miscellaneous resources</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Compiled by <a href="http://misha.brukman.net">Misha Brukman</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="hw">Hardware</a></div>
+ <!-- *********************************************************************** -->
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="alpha">Alpha</a></div>
+
+ <div class="doc_text">
+ <ul>
+ <li><a
+ href="http://ftp.digital.com/pub/Digital/info/semiconductor/literature/dsc-library.html">Alpha manuals</a>
+ </li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="arm">ARM</a></div>
+
+ <div class="doc_text">
+ <ul>
+ <li><a href="http://www.arm.com/documentation/">ARM documentation</a>
+ (<a href="http://www.arm.com/documentation/ARMProcessor_Cores/">Processor
+ Cores</a>)</li>
+ <li><a href="http://www.arm.com/products/DevTools/ABI.html">ABI</a></li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="ia64">Itanium (ia64)</a></div>
+
+ <div class="doc_text">
+ <ul>
+ <li><a
+ href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium documentation</a>
+ </li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="mips">MIPS</a></div>
+
+ <div class="doc_text">
+ <ul>
+ <li><a
+ href="http://mips.com/content/Documentation/MIPSDocumentation/ProcessorArchitecture/doclibrary">MIPS
+ Processor Architecture</a></li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="ppc">PowerPC</a></div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">IBM - Official manuals and docs</div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><a
+ href="http://www-106.ibm.com/developerworks/eserver/articles/archguide.html">PowerPC
+ Architecture Book</a>
+ <ul>
+ <li>Book I: <a
+ href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub1.pdf">PowerPC
+ User Instruction Set Architecture</a></li>
+ <li>Book II: <a
+ href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub2.pdf">PowerPC
+ Virtual Environment Architecture</a></li>
+ <li>Book III: <a
+ href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub3.pdf">PowerPC
+ Operating Environment Architecture</a></li>
+ </ul></li>
+ <li><a
+ href="http://www-3.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6">PowerPC
+ Compiler Writer's Guide</a></li>
+ <li><A
+ href="http://www-3.ibm.com/chips/techlib/techlib.nsf/products/PowerPC">PowerPC
+ Processor Manuals</a></li>
+ <li><a
+ href="http://www-106.ibm.com/developerworks/linux/library/l-powarch/">Intro to
+ PowerPC architecture</a></li>
+ <li><a href="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixassem/alangref/alangreftfrm.htm">IBM AIX/5L for POWER Assembly reference</a></li>
+ </ul>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Other documents, collections, notes</div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><a href="http://penguinppc.org/dev/#library">PowerPC ABI documents</a></li>
+ <li><a href="http://gcc.gnu.org/ml/gcc-patches/2003-09/msg00997.html">PowerPC64
+ alignment of long doubles (from GCC)</a></li>
+ <li><a href="http://sources.redhat.com/ml/binutils/2002-04/msg00573.html">Long
+ branch stubs for powerpc64-linux (from binutils)</a></li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="sparc">SPARC</a></div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><a href="http://www.sparc.org/resource.htm">SPARC resources</a></li>
+ <li><a href="http://www.sparc.org/standards.html">SPARC standards</a></li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="x86">X86</a></div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">AMD - Official manuals and docs</div>
+
+ <div class="doc_text">
+ <ul>
+ <li><a
+ href="http://www.amd.com/us-en/Processors/TechnicalResources/0,,30_182_739,00.html">AMD processor manuals</a></li>
+ <li><a href="http://www.x86-64.org/documentation">X86-64 ABI</a></li>
+ </ul>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Intel - Official manuals and docs</div>
+
+ <div class="doc_text">
+ <ul>
+ <li><a
+ href="http://developer.intel.com/design/pentium4/manuals/index_new.htm">IA-32
+ manuals</a></li>
+ <li><a
+ href="http://www.intel.com/design/itanium/documentation.htm?iid=ipp_srvr_proc_itanium2+techdocs">Intel
+ Itanium documentation</a></li>
+ </ul>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Other x86-specific information</div>
+
+ <div class="doc_text">
+ <ul>
+ <li><a href="http://www.agner.org/assem/calling_conventions.pdf">Calling
+ conventions for different C++ compilers and operating systems</a></li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="other">Other relevant lists</a></div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><a href="http://gcc.gnu.org/readings.html">GCC reading list</a></li>
+ </ul>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="abi">ABI</a></div>
+ <!-- *********************************************************************** -->
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="linux">Linux</a></div>
+
+ <div class="doc_text">
+ <ol>
+ <li><a href="http://www.linuxbase.org/spec/ELF/ppc64/">PowerPC 64-bit ELF ABI
+ Supplement</a></li>
+ </ol>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="osx">OS X</a></div>
+
+ <div class="doc_text">
+ <ol>
+ <li><a
+ href="http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html">Mach-O
+ Runtime Architecture</a></li>
+ <li><a href="http://www.unsanity.org/archives/000044.php">Notes on Mach-O
+ ABI</a></li>
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="misc">Miscellaneous resources</a></div>
+ <!-- *********************************************************************** -->
+
+ <ul>
+ <li><a
+ href="http://www.nondot.org/sabre/os/articles/ExecutableFileFormats/">Executable
+ File Format library</a></li>
+ <li><a href="http://gcc.gnu.org/projects/prefetch.html">GCC prefetch project</a>
+ page has a good survey of the prefetching capabilities of a variety of modern
+ processors.</li>
+ </ul>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="http://misha.brukman.net">Misha Brukman</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/DeveloperPolicy.html
diff -c /dev/null llvm-www/releases/2.3/docs/DeveloperPolicy.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/DeveloperPolicy.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,555 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>LLVM Developer Policy</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">LLVM Developer Policy</div>
+ <ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#policies">Developer Policies</a>
+ <ol>
+ <li><a href="#informed">Stay Informed</a></li>
+ <li><a href="#patches">Making a Patch</a></li>
+ <li><a href="#reviews">Code Reviews</a></li>
+ <li><a href="#owners">Code Owners</a></li>
+ <li><a href="#testcases">Test Cases</a></li>
+ <li><a href="#quality">Quality</a></li>
+ <li><a href="#commitaccess">Obtaining Commit Access</a></li>
+ <li><a href="#newwork">Making a Major Change</a></li>
+ <li><a href="#incremental">Incremental Development</a></li>
+ <li><a href="#attribution">Attribution of Changes</a></li>
+ </ol></li>
+ <li><a href="#clp">Copyright, License, and Patents</a>
+ <ol>
+ <li><a href="#copyright">Copyright</a></li>
+ <li><a href="#license">License</a></li>
+ <li><a href="#patents">Patents</a></li>
+ <li><a href="#devagree">Developer Agreements</a></li>
+ </ol></li>
+ </ol>
+ <div class="doc_author">Written by the LLVM Oversight Team</div>
+
+ <!--=========================================================================-->
+ <div class="doc_section"><a name="introduction">Introduction</a></div>
+ <!--=========================================================================-->
+ <div class="doc_text">
+ <p>This document contains the LLVM Developer Policy which defines the
+ project's policy towards developers and their contributions. The intent of
+ this policy is to eliminate mis-communication, rework, and confusion that
+ might arise from the distributed nature of LLVM's development. By stating
+ the policy in clear terms, we hope each developer can know ahead of time
+ what to expect when making LLVM contributions.</p>
+ <p>This policy is also designed to accomplish the following objectives:</p>
+ <ol>
+ <li>Attract both users and developers to the LLVM project.</li>
+ <li>Make life as simple and easy for contributors as possible.</li>
+ <li>Keep the top of Subversion trees as stable as possible.</li>
+ </ol>
+
+ <p>This policy is aimed at frequent contributors to LLVM. People interested in
+ contributing one-off patches can do so in an informal way by sending them to
+ the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">
+ llvm-commits mailing list</a> and engaging another developer to see it through
+ the process.</p>
+
+ </div>
+
+ <!--=========================================================================-->
+ <div class="doc_section"><a name="policies">Developer Policies</a></div>
+ <!--=========================================================================-->
+ <div class="doc_text">
+ <p>This section contains policies that pertain to frequent LLVM
+ developers. We always welcome <a href="#patches">one-off patches</a> from
+ people who do not routinely contribute to LLVM, but we expect more from
+ frequent contributors to keep the system as efficient as possible for
+ everyone.
+ Frequent LLVM contributors are expected to meet the following requirements in
+ order for LLVM to maintain a high standard of quality.<p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="informed">Stay Informed</a> </div>
+ <div class="doc_text">
+ <p>Developers should stay informed by reading at least the
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a>
+ email list. If you are doing anything more than just casual work on LLVM,
+ it is suggested that you also subscribe to the
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a>
+ list and pay attention to changes being made by others.</p>
+ <p>We recommend that active developers register an email account with
+ <a href="http://llvm.org/bugs/">LLVM Bugzilla</a> and preferably subscribe to
+ the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmbugs">llvm-bugs</a>
+ email list to keep track of bugs and enhancements occurring in LLVM.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="patches">Making a Patch</a></div>
+
+ <div class="doc_text">
+
+ <p>When making a patch for review, the goal is to make it as easy for the
+ reviewer to read it as possible. As such, we recommend that you:</p>
+ <ol>
+ <li>Make your patch against the Subversion trunk, not a branch, and not an
+ old version of LLVM. This makes it easy to apply the patch.</li>
+
+ <li>Similarly, patches should be submitted soon after they are generated.
+ Old patches may not apply correctly if the underlying code changes between
+ the time the patch was created and the time it is applied.</li>
+
+ <li>Patches should be made with this command:
+ <pre>svn diff -x -u</pre>
+ or with the utility <tt>utils/mkpatch</tt>, which makes it easy to read the
+ diff.</li>
+
+ <li>Patches should not include differences in generated code such as the
+ code generated by <tt>flex</tt>, <tt>bison</tt> or <tt>tblgen</tt>. The
+ <tt>utils/mkpatch</tt> utility takes care of this for you.</li>
+
+ </ol>
+
+ <p>When sending a patch to a mailing list, it is a good idea to send it as an
+ <em>attachment</em> to the message, not embedded into the text of the
+ message. This ensures that your mailer will not mangle the patch when it
+ sends it (e.g. by making whitespace changes or by wrapping lines).</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="reviews">Code Reviews</a></div>
+ <div class="doc_text">
+ <p>LLVM has a code review policy. Code review is one way to increase the
+ quality of software. We generally follow these policies:</p>
+ <ol>
+ <li>All developers are required to have significant changes reviewed
+ before they are committed to the repository.</li>
+ <li>Code reviews are conducted by email, usually on the llvm-commits
+ list.</li>
+ <li>Code can be reviewed either before it is committed or after. We expect
+ major changes to be reviewed before being committed, but smaller
+ changes (or changes where the developer owns the component) can be
+ reviewed after commit.</li>
+ <li>The developer responsible for a code change is also responsible for
+ making all necessary review-related changes.</li>
+ <li>Code review can be an iterative process, which continues until the patch
+ is ready to be committed.</li>
+ </ol>
+
+ <p>Developers should participate in code reviews as both reviewers and
+ reviewees. If someone is kind enough to review your code, you should
+ return the favor for someone else. Note that anyone is welcome to review
+ and give feedback on a patch, but only people with Subversion write access
+ can approve it.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="owners">Code Owners</a></div>
+ <div class="doc_text">
+
+ <p>The LLVM Project relies on two features of its process to maintain rapid
+ development in addition to the high quality of its source base: the
+ combination of code review plus post-commit review for trusted maintainers.
+ Having both is a great way for the project to take advantage of the fact
+ that most people do the right thing most of the time, and only commit
+ patches without pre-commit review when they are confident they are
+ right.</p>
+
+ <p>The trick to this is that the project has to guarantee that all patches
+ that are committed are reviewed after they go in: you don't want everyone
+ to assume someone else will review it, allowing the patch to go unreviewed.
+ To solve this problem, we have a notion of an 'owner' for a piece of the
+ code. The sole responsibility of a code owner is to ensure that a commit
+ to their area of the code is appropriately reviewed, either by themself or
+ by someone else. The current code owners are:</p>
+
+ <ol>
+ <li><b>Anton Korobeynikov</b>: Exception handling, debug information, and
+ Windows codegen.</li>
+ <li><b>Duncan Sands</b>: llvm-gcc 4.2.</li>
+ <li><b>Evan Cheng</b>: Code generator and all targets.</li>
+ <li><b>Chris Lattner</b>: Everything else.</li>
+ </ol>
+
+ <p>Note that code ownership is completely different than reviewers: anyone can
+ review a piece of code, and we welcome code review from anyone who is
+ interested. Code owners are the "last line of defense" to guarantee that
+ all patches that are committed are actually reviewed.</p>
+
+ <p>Being a code owner is a somewhat unglamorous position, but it is incredibly
+ important for the ongoing success of the project. Because people get busy,
+ interests change, and unexpected things happen, code ownership is purely
+ opt-in, and anyone can choose to resign their "title" at any time. For now,
+ we do not have an official policy on how one gets elected to be a code
+ owner.
+ </p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="testcases">Test Cases</a></div>
+ <div class="doc_text">
+ <p>Developers are required to create test cases for any bugs fixed and any new
+ features added. Some tips for getting your testcase approved:</p>
+ <ol>
+ <li>All feature and regression test cases are added to the
+ <tt>llvm/test</tt> directory. The appropriate sub-directory should be
+ selected (see the <a href="TestingGuide.html">Testing Guide</a> for
+ details).</li>
+ <li>Test cases should be written in
+ <a href="LangRef.html">LLVM assembly language</a> unless the
+ feature or regression being tested requires another language (e.g. the
+ bug being fixed or feature being implemented is in the llvm-gcc C++
+ front-end, in which case it must be written in C++).</li>
+ <li>Test cases, especially for regressions, should be reduced as much as
+ possible, by <a href="Bugpoint.html">bugpoint</a> or
+ manually. It is unacceptable
+ to place an entire failing program into <tt>llvm/test</tt> as this creates
+ a <i>time-to-test</i> burden on all developers. Please keep them short.</li>
+ </ol>
+
+ <p>Note that llvm/test is designed for regression and small feature tests
+ only. More extensive test cases (e.g., entire applications, benchmarks,
+ etc) should be added to the <tt>llvm-test</tt> test suite. The llvm-test
+ suite is for coverage (correctness, performance, etc) testing, not feature
+ or regression testing.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="quality">Quality</a></div>
+ <div class="doc_text">
+ <p>The minimum quality standards that any change must satisfy before being
+ committed to the main development branch are:</p>
+ <ol>
+ <li>Code must adhere to the
+ <a href="CodingStandards.html">LLVM Coding Standards</a>.</li>
+ <li>Code must compile cleanly (no errors, no warnings) on at least one
+ platform.</li>
+ <li>Bug fixes and new features should <a href="#testcases">include a
+ testcase</a> so we know if the fix/feature ever regresses in the
+ future.</li>
+ <li>Code must pass the dejagnu (<tt>llvm/test</tt>) test suite.</li>
+ <li>The code must not cause regressions on a reasonable subset of llvm-test,
+ where "reasonable" depends on the contributor's judgement and the scope
+ of the change (more invasive changes require more testing). A reasonable
+ subset is "<tt>llvm-test/MultiSource/Benchmarks</tt>".</li>
+ </ol>
+ <p>Additionally, the committer is responsible for addressing any problems
+ found in the future that the change is responsible for. For example:</p>
+ <ul>
+ <li>The code should compile cleanly on all supported platforms.</li>
+ <li>The changes should not cause any correctness regressions in the
+ <tt>llvm-test</tt> suite and must not cause any major performance
+ regressions.</li>
+ <li>The change set should not cause performance or correctness regressions
+ for the LLVM tools.</li>
+ <li>The changes should not cause performance or correctness regressions in
+ code compiled by LLVM on all applicable targets.</li>
+ <li>You are expected to address any <a href="http://llvm.org/bugs/">bugzilla
+ bugs</a> that result from your change.</li>
+ </ul>
+
+ <p>We prefer for this to be handled before submission but understand that it
+ isn't possible to test all of this for every submission. Our nightly
+ testing
+ infrastructure normally finds these problems. A good rule of thumb is to
+ check the nightly testers for regressions the day after your change.</p>
+
+ <p>Commits that violate these quality standards (e.g. are very broken) may
+ be reverted. This is necessary when the change blocks other developers from
+ making progress. The developer is welcome to re-commit the change after
+ the problem has been fixed.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection">
+ <a name="commitaccess">Obtaining Commit Access</a></div>
+ <div class="doc_text">
+
+ <p>
+ We grant commit access to contributors with a track record of submitting high
+ quality patches. If you would like commit access, please send an email to
+ <a href="mailto:sabre at nondot.org">Chris</a> with the following information:</p>
+
+ <ol>
+ <li>The user name you want to commit with, e.g. "sabre".</li>
+ <li>The full name and email address you want message to llvm-commits to come
+ from, e.g. "Chris Lattner <sabre at nondot.org>".</li>
+ <li>A "password hash" of the password you want to use, e.g. "2ACR96qjUqsyM".
+ Note that you don't ever tell us what your password is, you just give it
+ to us in an encrypted form. To get this, run "htpasswd" (a utility that
+ comes with apache) in crypt mode (often enabled with "-d"), or find a web
+ page that will do it for you.</li>
+ </ol>
+
+ <p>Once you've been granted commit access, you should be able to check out an
+ LLVM tree with an SVN URL of "https://username@llvm.org/..." instead of the
+ normal anonymous URL of "http://llvm.org/...". The first time you commit
+ you'll have to type in your password. Note that you may get a warning from
+ SVN about an untrusted key, you can ignore this. To verify that your commit
+ access works, please do a test commit (e.g. change a comment or add a blank
+ line). Your first commit to a repository may require the autogenerated email
+ to be approved by a mailing list. This is normal, and will be done when
+ the mailing list owner has time.</p>
+
+ <p>If you have recently been granted commit access, these policies apply:</p>
+
+ <ol>
+ <li>You are granted <i>commit-after-approval</i> to all parts of LLVM.
+ To get approval, submit a <a href="#patches">patch</a> to
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">
+ llvm-commits</a>. When approved you may commit it yourself.</li>
+ <li>You are allowed to commit patches without approval which you think are
+ obvious. This is clearly a subjective decision — we simply expect you
+ to use good judgement. Examples include: fixing build breakage, reverting
+ obviously broken patches, documentation/comment changes, any other minor
+ changes.</li>
+ <li>You are allowed to commit patches without approval to those portions
+ of LLVM that you have contributed or maintain (i.e., have been assigned
+ responsibility for), with the proviso that such commits must not break the
+ build. This is a "trust but verify" policy and commits of this nature are
+ reviewed after they are committed.</li>
+ <li>Multiple violations of these policies or a single egregious violation
+ may cause commit access to be revoked.</li>
+ </ol>
+
+ <p>In any case, your changes are still subject to <a href="#reviews">code
+ review</a> (either before or after they are committed, depending on the nature
+ of the change). You are encouraged to review other peoples' patches as well,
+ but you aren't required to.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="newwork">Making a Major Change</a></div>
+ <div class="doc_text">
+ <p>When a developer begins a major new project with the aim of contributing
+ it back to LLVM, s/he should inform the community with an email to
+ the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a>
+ email list, to the extent possible. The reason for this is to:
+ <ol>
+ <li>keep the community informed about future changes to LLVM, </li>
+ <li>avoid duplication of effort by preventing multiple parties working on
+ the same thing and not knowing about it, and</li>
+ <li>ensure that any technical issues around the proposed work are
+ discussed and resolved before any significant work is done.</li>
+ </ol>
+
+ <p>The design of LLVM is carefully controlled to ensure that all the pieces
+ fit together well and are as consistent as possible. If you plan to make a
+ major change to the way LLVM works or want to add a major new extension, it
+ is a good idea to get consensus with the development
+ community before you start working on it.</p>
+
+ <p>Once the design of the new feature is finalized, the work itself should be
+ done as a series of <a href="#incremental">incremental changes</a>, not as
+ a long-term development branch.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="incremental">Incremental Development</a>
+ </div>
+ <div class="doc_text">
+ <p>In the LLVM project, we do all significant changes as a series of
+ incremental patches. We have a strong dislike for huge changes or
+ long-term development branches. Long-term development branches have a
+ number of drawbacks:</p>
+
+ <ol>
+ <li>Branches must have mainline merged into them periodically. If the branch
+ development and mainline development occur in the same pieces of code,
+ resolving merge conflicts can take a lot of time.</li>
+ <li>Other people in the community tend to ignore work on branches.</li>
+ <li>Huge changes (produced when a branch is merged back onto mainline) are
+ extremely difficult to <a href="#reviews">code review</a>.</li>
+ <li>Branches are not routinely tested by our nightly tester
+ infrastructure.</li>
+ <li>Changes developed as monolithic large changes often don't work until the
+ entire set of changes is done. Breaking it down into a set of smaller
+ changes increases the odds that any of the work will be committed to the
+ main repository.</li>
+ </ol>
+
+ <p>
+ To address these problems, LLVM uses an incremental development style and we
+ require contributors to follow this practice when making a large/invasive
+ change. Some tips:</p>
+
+ <ul>
+ <li>Large/invasive changes usually have a number of secondary changes that
+ are required before the big change can be made (e.g. API cleanup, etc).
+ These sorts of changes can often be done before the major change is done,
+ independently of that work.</li>
+ <li>The remaining inter-related work should be decomposed into unrelated
+ sets of changes if possible. Once this is done, define the first increment
+ and get consensus on what the end goal of the change is.</li>
+
+ <li>Each change in the set can be stand alone (e.g. to fix a bug), or part
+ of a planned series of changes that works towards the development goal.</li>
+
+ <li>Each change should be kept as small as possible. This simplifies your
+ work (into a logical progression), simplifies code review and reduces the
+ chance that you will get negative feedback on the change. Small increments
+ also facilitate the maintenance of a high quality code base.</li>
+
+ <li>Often, an independent precursor to a big change is to add a new API and
+ slowly migrate clients to use the new API. Each change to use the new
+ API is often "obvious" and can be committed without review. Once the
+ new API is in place and used, it is much easier to replace the
+ underlying implementation of the API. This implementation change is
+ logically separate from the API change.</li>
+ </ul>
+
+ <p>If you are interested in making a large change, and this scares you, please
+ make sure to first <a href="#newwork">discuss the change/gather
+ consensus</a> then ask about the best way to go about making
+ the change.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="attribution">Attribution of
+ Changes</a></div>
+ <div class="doc_text">
+ <p>We believe in correct attribution of contributions to
+ their contributors. However, we do not want the source code to be littered
+ with random attributions "this code written by J Random Guy" (this is noisy
+ and distracting. In practice, the revision control system keeps a perfect
+ history of who change what, and the CREDITS.txt file describes higher-level
+ contributions.</p>
+
+ <p>Overall, please do not add contributor names to the source base.</p>
+ </div>
+
+
+
+ <!--=========================================================================-->
+ <div class="doc_section">
+ <a name="clp">Copyright, License, and Patents</a>
+ </div>
+ <!--=========================================================================-->
+
+ <div class="doc_text">
+ <p>This section addresses the issues of copyright, license and patents for
+ the LLVM project.
+ Currently, the University of Illinois is the LLVM copyright holder and the
+ terms of its license to LLVM users and developers is the
+ <a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of
+ Illinois/NCSA Open Source License</a>.</p>
+
+ <div class="doc_notes">
+ <p><b>NOTE: This section deals with legal matters but does not provide
+ legal advice. We are not lawyers, please seek legal counsel from an
+ attorney.</b></p>
+ </div>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="copyright">Copyright</a></div>
+ <div class="doc_text">
+ <p>
+ <p>For consistency and ease of management, the project requires the
+ copyright for all LLVM software to be held by a single copyright holder:
+ the University of Illinois (UIUC).</p>
+
+ <p>
+ Although UIUC may eventually reassign the copyright of the software to another
+ entity (e.g. a dedicated non-profit "LLVM Organization", or something)
+ the intent for the project is to always have a single entity hold the
+ copyrights to LLVM at any given time.</p>
+
+ <p>We believe that having a single copyright
+ holder is in the best interests of all developers and users as it greatly
+ reduces the managerial burden for any kind of administrative or technical
+ decisions about LLVM. The goal of the LLVM project is to always keep the code
+ open and <a href="#license">licensed under a very liberal license</a>.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="license">License</a></div>
+ <div class="doc_text">
+ <p>We intend to keep LLVM perpetually open source
+ and to use a liberal open source license. The current license is the
+ <a href="http://www.opensource.org/licenses/UoI-NCSA.php">
+ University of Illinois/NCSA Open Source License</a>, which boils
+ down to this:</p>
+ <ul>
+ <li>You can freely distribute LLVM.</li>
+ <li>You must retain the copyright notice if you redistribute LLVM.</li>
+ <li>Binaries derived from LLVM must reproduce the copyright notice.</li>
+ <li>You can't use our names to promote your LLVM derived products.</li>
+ <li>There's no warranty on LLVM at all.</li>
+ </ul>
+
+ <p>We believe this fosters the widest adoption of LLVM because it <b>allows
+ commercial products to be derived from LLVM</b> with few restrictions and
+ without a requirement for making any derived works also open source (i.e.
+ LLVM's license is not a "copyleft" license like the GPL). We suggest that you
+ read the <a href="http://www.opensource.org/licenses/UoI-NCSA.php">License</a>
+ if further clarification is needed.</p>
+
+ <p>Note that the LLVM Project does distribute llvm-gcc, <b>which is GPL.</b>
+ This means that anything "linked" into llvm-gcc must itself be compatible
+ with the GPL, and must be releasable under the terms of the GPL. This implies
+ that <b>any code linked into llvm-gcc and distributed to others may be subject
+ to the viral aspects of the GPL</b> (for example, a proprietary code generator
+ linked into llvm-gcc must be made available under the GPL). This is not a
+ problem for code already distributed under a more liberal license (like the
+ UIUC license), and does not affect code generated by llvm-gcc. It may be a
+ problem if you intend to base commercial development on llvm-gcc without
+ redistributing your source code.</p>
+
+ <p>We have no plans to change the license of LLVM. If you have questions
+ or comments about the license, please contact the <a
+ href="mailto:llvm-oversight at cs.uiuc.edu">LLVM Oversight Group</a>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="patents">Patents</a></div>
+ <div class="doc_text">
+
+ <p>To the best of our knowledge, LLVM does not infringe on any patents (we have
+ actually removed code from LLVM in the past that was found to infringe).
+ Having code in LLVM that infringes on patents would violate an important
+ goal of the project by making it hard or impossible to reuse the code for
+ arbitrary purposes (including commercial use).</p>
+
+ <p>When contributing code, we expect contributors to notify us of any potential
+ for patent-related trouble with their changes. If you own the rights to a
+ patent and would like to contribute code to LLVM that relies on it, we
+ require that you sign an agreement that allows any other user of LLVM to
+ freely use your patent. Please contact the <a
+ href="mailto:llvm-oversight at cs.uiuc.edu">oversight group</a> for more
+ details.</p>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="devagree">Developer Agreements</a></div>
+ <div class="doc_text">
+ <p>With regards to the LLVM copyright and licensing, developers agree to
+ assign their copyrights to UIUC for any contribution made so that
+ the entire software base can be managed by a single copyright holder. This
+ implies that any contributions can be licensed under the license that the
+ project uses.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+ Written by the
+ <a href="mailto:llvm-oversight at cs.uiuc.edu">LLVM Oversight Group</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/ExceptionHandling.html
diff -c /dev/null llvm-www/releases/2.3/docs/ExceptionHandling.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/ExceptionHandling.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,478 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>Exception Handling in LLVM</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">Exception Handling in LLVM</div>
+
+ <table class="layout" style="width:100%">
+ <tr class="layout">
+ <td class="left">
+ <ul>
+ <li><a href="#introduction">Introduction</a>
+ <ol>
+ <li><a href="#itanium">Itanium ABI Zero-cost Exception Handling</a></li>
+ <li><a href="#overview">Overview</a></li>
+ </ol></li>
+ <li><a href="#codegen">LLVM Code Generation</a>
+ <ol>
+ <li><a href="#throw">Throw</a></li>
+ <li><a href="#try_catch">Try/Catch</a></li>
+ <li><a href="#cleanups">Cleanups</a></li>
+ <li><a href="#throw_filters">Throw Filters</a></li>
+ <li><a href="#restrictions">Restrictions</a></li>
+ </ol></li>
+ <li><a href="#format_common_intrinsics">Exception Handling Intrinsics</a>
+ <ol>
+ <li><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a></li>
+ <li><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a></li>
+ <li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a></li>
+ </ol></li>
+ <li><a href="#asm">Asm Table Formats</a>
+ <ol>
+ <li><a href="#unwind_tables">Exception Handling Frame</a></li>
+ <li><a href="#exception_tables">Exception Tables</a></li>
+ </ol></li>
+ <li><a href="#todo">ToDo</a></li>
+ </ul>
+ </td>
+ </tr></table>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:jlaskey at mac.com">Jim Laskey</a></p>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="introduction">Introduction</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This document is the central repository for all information pertaining to
+ exception handling in LLVM. It describes the format that LLVM exception
+ handling information takes, which is useful for those interested in creating
+ front-ends or dealing directly with the information. Further, this document
+ provides specific examples of what exception handling information is used for
+ C/C++.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="itanium">Itanium ABI Zero-cost Exception Handling</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Exception handling for most programming languages is designed to recover from
+ conditions that rarely occur during general use of an application. To that end,
+ exception handling should not interfere with the main flow of an
+ application's algorithm by performing checkpointing tasks such as saving
+ the current pc or register state.</p>
+
+ <p>The Itanium ABI Exception Handling Specification defines a methodology for
+ providing outlying data in the form of exception tables without inlining
+ speculative exception handling code in the flow of an application's main
+ algorithm. Thus, the specification is said to add "zero-cost" to the normal
+ execution of an application.</p>
+
+ <p>A more complete description of the Itanium ABI exception handling runtime
+ support of can be found at <a
+ href="http://www.codesourcery.com/cxx-abi/abi-eh.html">Itanium C++ ABI:
+ Exception Handling.</a> A description of the exception frame format can be found
+ at <a href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-
+ Core-generic/ehframechpt.html">Exception Frames</a>, with details of the Dwarf
+ specification at <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3
+ Standard.</a> A description for the C++ exception table formats can be found at
+ <a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling
+ Tables.</a></p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="overview">Overview</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>When an exception is thrown in llvm code, the runtime does a best effort to
+ find a handler suited to process the circumstance.</p>
+
+ <p>The runtime first attempts to find an <i>exception frame</i> corresponding to
+ the function where the exception was thrown. If the programming language (ex.
+ C++) supports exception handling, the exception frame contains a reference to an
+ exception table describing how to process the exception. If the language (ex.
+ C) does not support exception handling or if the exception needs to be forwarded
+ to a prior activation, the exception frame contains information about how to
+ unwind the current activation and restore the state of the prior activation.
+ This process is repeated until the exception is handled. If the exception is
+ not handled and no activations remain, then the application is terminated with
+ an appropriate error message.</p>
+
+ <p>Since different programming languages have different behaviors when handling
+ exceptions, the exception handling ABI provides a mechanism for supplying
+ <i>personalities.</i> An exception handling personality is defined by way of a
+ <i>personality function</i> (ex. for C++ <tt>__gxx_personality_v0</tt>) which
+ receives the context of the exception, an <i>exception structure</i> containing
+ the exception object type and value, and a reference to the exception table for
+ the current function. The personality function for the current compile unit is
+ specified in a <i>common exception frame</i>.</p>
+
+ <p>The organization of an exception table is language dependent. For C++, an
+ exception table is organized as a series of code ranges defining what to do if
+ an exception occurs in that range. Typically, the information associated with a
+ range defines which types of exception objects (using C++ <i>type info</i>) that
+ are handled in that range, and an associated action that should take place.
+ Actions typically pass control to a <i>landing pad</i>.</p>
+
+ <p>A landing pad corresponds to the code found in the catch portion of a
+ try/catch sequence. When execution resumes at a landing pad, it receives the
+ exception structure and a selector corresponding to the <i>type</i> of exception
+ thrown. The selector is then used to determine which catch should actually
+ process the exception.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_section">
+ <a name="codegen">LLVM Code Generation</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>At the time of this writing, only C++ exception handling support is available
+ in LLVM. So the remainder of this document will be somewhat C++-centric.</p>
+
+ <p>From the C++ developers perspective, exceptions are defined in terms of the
+ <tt>throw</tt> and <tt>try/catch</tt> statements. In this section we will
+ describe the implementation of llvm exception handling in terms of C++
+ examples.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="throw">Throw</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Languages that support exception handling typically provide a <tt>throw</tt>
+ operation to initiate the exception process. Internally, a throw operation
+ breaks down into two steps. First, a request is made to allocate exception
+ space for an exception structure. This structure needs to survive beyond the
+ current activation. This structure will contain the type and value of the
+ object being thrown. Second, a call is made to the runtime to raise the
+ exception, passing the exception structure as an argument.</p>
+
+ <p>In C++, the allocation of the exception structure is done by the
+ <tt>__cxa_allocate_exception</tt> runtime function. The exception raising is
+ handled by <tt>__cxa_throw</tt>. The type of the exception is represented using
+ a C++ RTTI type info structure.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="try_catch">Try/Catch</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>A call within the scope of a try statement can potentially raise an exception.
+ In those circumstances, the LLVM C++ front-end replaces the call with an
+ <tt>invoke</tt> instruction. Unlike a call, the invoke has two potential
+ continuation points; where to continue when the call succeeds as per normal, and
+ where to continue if the call raises an exception, either by a throw or the
+ unwinding of a throw.</p>
+
+ <p>The term used to define a the place where an invoke continues after an
+ exception is called a <i>landing pad</i>. LLVM landing pads are conceptually
+ alternative function entry points where a exception structure reference and a type
+ info index are passed in as arguments. The landing pad saves the exception
+ structure reference and then proceeds to select the catch block that corresponds
+ to the type info of the exception object.</p>
+
+ <p>Two llvm intrinsic functions are used convey information about the landing
+ pad to the back end.</p>
+
+ <p><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a> takes no
+ arguments and returns the exception structure reference. The backend replaces
+ this intrinsic with the code that accesses the first argument of a call. The
+ LLVM C++ front end generates code to save this value in an alloca location for
+ further use in the landing pad and catch code.</p>
+
+ <p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of
+ three arguments. The first argument is the reference to the exception
+ structure. The second argument is a reference to the personality function to be
+ used for this try catch sequence. Each of the remaining arguments is either a
+ reference to the type info for a catch statement,
+ a <a href="#throw_filters">filter</a> expression,
+ or the number zero representing a <a href="#cleanups">cleanup</a>.
+ The exception is tested against the arguments sequentially from first to last.
+ The result of the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a
+ positive number if the exception matched a type info, a negative number if it matched
+ a filter, and zero if it matched a cleanup. If nothing is matched, the behaviour of
+ the program is <a href="#restrictions">undefined</a>.
+ The LLVM C++ front end generates code to save the selector value in an alloca
+ location for further use in the landing pad and catch code.
+ If a type info matched then the selector value is the index of the type info in
+ the exception table, which can be obtained using the
+ <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p>
+
+ <p>Once the landing pad has the type info selector, the code branches to the
+ code for the first catch. The catch then checks the value of the type info
+ selector against the index of type info for that catch. Since the type info
+ index is not known until all the type info have been gathered in the backend,
+ the catch code will call the <a
+ href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic to
+ determine the index for a given type info. If the catch fails to match the
+ selector then control is passed on to the next catch. Note: Since the landing
+ pad will not be used if there is no match in the list of type info on the call
+ to <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>, then neither the
+ last catch nor <i>catch all</i> need to perform the the check against the
+ selector.</p>
+
+ <p>Finally, the entry and exit of catch code is bracketed with calls to
+ <tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.
+ <tt>__cxa_begin_catch</tt> takes a exception structure reference as an argument
+ and returns the value of the exception object. <tt>__cxa_end_catch</tt>
+ takes a exception structure reference as an argument. This function clears the
+ exception from the exception space. Note: a rethrow from within the catch may
+ replace this call with a <tt>__cxa_rethrow</tt>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="cleanups">Cleanups</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>To handle destructors and cleanups in try code, control may not run directly
+ from a landing pad to the first catch. Control may actually flow from the
+ landing pad to clean up code and then to the first catch. Since the required
+ clean up for each invoke in a try may be different (ex., intervening
+ constructor), there may be several landing pads for a given try. If cleanups
+ need to be run, the number zero should be passed as the last
+ <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument.
+ However for C++ a <tt>null i8*</tt> <a href="#restrictions">must</a> be passed
+ instead.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="throw_filters">Throw Filters</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>C++ allows the specification of which exception types that can be thrown from
+ a function. To represent this a top level landing pad may exist to filter out
+ invalid types. To express this in LLVM code the landing pad will call <a
+ href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The arguments are the
+ length of the filter expression (the number of type infos plus one), followed by
+ the type infos themselves.
+ <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> will return a negative
+ value if the exception does not match any of the type infos. If no match is
+ found then a call to <tt>__cxa_call_unexpected</tt> should be made, otherwise
+ <tt>_Unwind_Resume</tt>. Each of these functions require a reference to the
+ exception structure.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="restrictions">Restrictions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The semantics of the invoke instruction require that any exception that
+ unwinds through an invoke call should result in a branch to the invoke's unwind
+ label. However such a branch will only happen if the
+ <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> matches.
+ Thus in order to ensure correct operation, the front-end must only generate
+ <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls that are
+ guaranteed to always match whatever exception unwinds through the invoke.
+ For most languages it is enough to pass zero, indicating the presence of
+ a <a href="#cleanups">cleanup</a>, as the last
+ <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument.
+ However for C++ this is not sufficient, because the C++ personality function
+ will terminate the program if it detects that unwinding the exception only
+ results in matches with cleanups. For C++ a <tt>null i8*</tt> should
+ be passed as the last
+ <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument instead.
+ This is interpreted as a catch-all by the C++ personality function, and will
+ always match.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_section">
+ <a name="format_common_intrinsics">Exception Handling Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to
+ provide exception handling information at various points in generated code.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection">
+ <a name="llvm_eh_exception">llvm.eh.exception</a>
+ </div>
+
+ <div class="doc_text">
+ <pre>
+ i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>( )
+ </pre>
+
+ <p>This intrinsic indicates that the exception structure is available at this
+ point in the code. The backend will replace this intrinsic with code to fetch
+ the first argument of a call. The effect is that the intrinsic result is the
+ exception structure reference.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection">
+ <a name="llvm_eh_selector">llvm.eh.selector</a>
+ </div>
+
+ <div class="doc_text">
+ <pre>
+ i32 %<a href="#llvm_eh_selector">llvm.eh.selector.i32</a>(i8*, i8*, i8*, ...)
+ i64 %<a href="#llvm_eh_selector">llvm.eh.selector.i64</a>(i8*, i8*, i8*, ...)
+ </pre>
+
+ <p>This intrinsic indicates that the exception selector is available at this
+ point in the code. The backend will replace this intrinsic with code to fetch
+ the second argument of a call. The effect is that the intrinsic result is the
+ exception selector.</p>
+
+ <p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of
+ three arguments. The first argument is the reference to the exception
+ structure. The second argument is a reference to the personality function to be
+ used for this try catch sequence. Each of the remaining arguments is either a
+ reference to the type info for a catch statement,
+ a <a href="#throw_filters">filter</a> expression,
+ or the number zero representing a <a href="#cleanups">cleanup</a>.
+ The exception is tested against the arguments sequentially from first to last.
+ The result of the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a
+ positive number if the exception matched a type info, a negative number if it matched
+ a filter, and zero if it matched a cleanup. If nothing is matched, the behaviour of
+ the program is <a href="#restrictions">undefined</a>.
+ If a type info matched then the selector value is the index of the type info in
+ the exception table, which can be obtained using the
+ <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection">
+ <a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a>
+ </div>
+
+ <div class="doc_text">
+ <pre>
+ i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for.i32</a>(i8*)
+ i64 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for.i64</a>(i8*)
+ </pre>
+
+ <p>This intrinsic returns the type info index in the exception table of the
+ current function. This value can be used to compare against the result of <a
+ href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The single argument is
+ a reference to a type info.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_section">
+ <a name="asm">Asm Table Formats</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>There are two tables that are used by the exception handling runtime to
+ determine which actions should take place when an exception is thrown.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="unwind_tables">Exception Handling Frame</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind
+ frame used by dwarf debug info. The frame contains all the information
+ necessary to tear down the current frame and restore the state of the prior
+ frame. There is an exception handling frame for each function in a compile
+ unit, plus a common exception handling frame that defines information common to
+ all functions in the unit.</p>
+
+ <p>Todo - Table details here.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="exception_tables">Exception Tables</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>An exception table contains information about what actions to take when an
+ exception is thrown in a particular part of a function's code. There is
+ one exception table per function except leaf routines and functions that have
+ only calls to non-throwing functions will not need an exception table.</p>
+
+ <p>Todo - Table details here.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_section">
+ <a name="todo">ToDo</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ol>
+
+ <li><p>Testing/Testing/Testing.</p></li>
+
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/ExtendingLLVM.html
diff -c /dev/null llvm-www/releases/2.3/docs/ExtendingLLVM.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/ExtendingLLVM.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,391 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>Extending LLVM: Adding instructions, intrinsics, types, etc.</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+
+ <body>
+
+ <div class="doc_title">
+ Extending LLVM: Adding instructions, intrinsics, types, etc.
+ </div>
+
+ <ol>
+ <li><a href="#introduction">Introduction and Warning</a></li>
+ <li><a href="#intrinsic">Adding a new intrinsic function</a></li>
+ <li><a href="#instruction">Adding a new instruction</a></li>
+ <li><a href="#sdnode">Adding a new SelectionDAG node</a></li>
+ <li><a href="#type">Adding a new type</a>
+ <ol>
+ <li><a href="#fund_type">Adding a new fundamental type</a></li>
+ <li><a href="#derived_type">Adding a new derived type</a></li>
+ </ol></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="http://misha.brukman.net">Misha Brukman</a>,
+ Brad Jones, Nate Begeman,
+ and <a href="http://nondot.org/sabre">Chris Lattner</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction and Warning</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>During the course of using LLVM, you may wish to customize it for your
+ research project or for experimentation. At this point, you may realize that
+ you need to add something to LLVM, whether it be a new fundamental type, a new
+ intrinsic function, or a whole new instruction.</p>
+
+ <p>When you come to this realization, stop and think. Do you really need to
+ extend LLVM? Is it a new fundamental capability that LLVM does not support at
+ its current incarnation or can it be synthesized from already pre-existing LLVM
+ elements? If you are not sure, ask on the <a
+ href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM-dev</a> list. The
+ reason is that extending LLVM will get involved as you need to update all the
+ different passes that you intend to use with your extension, and there are
+ <em>many</em> LLVM analyses and transformations, so it may be quite a bit of
+ work.</p>
+
+ <p>Adding an <a href="#intrinsic">intrinsic function</a> is far easier than
+ adding an instruction, and is transparent to optimization passes. If your added
+ functionality can be expressed as a
+ function call, an intrinsic function is the method of choice for LLVM
+ extension.</p>
+
+ <p>Before you invest a significant amount of effort into a non-trivial
+ extension, <span class="doc_warning">ask on the list</span> if what you are
+ looking to do can be done with already-existing infrastructure, or if maybe
+ someone else is already working on it. You will save yourself a lot of time and
+ effort by doing so.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="intrinsic">Adding a new intrinsic function</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Adding a new intrinsic function to LLVM is much easier than adding a new
+ instruction. Almost all extensions to LLVM should start as an intrinsic
+ function and then be turned into an instruction if warranted.</p>
+
+ <ol>
+ <li><tt>llvm/docs/LangRef.html</tt>:
+ Document the intrinsic. Decide whether it is code generator specific and
+ what the restrictions are. Talk to other people about it so that you are
+ sure it's a good idea.</li>
+
+ <li><tt>llvm/include/llvm/Intrinsics*.td</tt>:
+ Add an entry for your intrinsic. Describe its memory access characteristics
+ for optimization (this controls whether it will be DCE'd, CSE'd, etc). Note
+ that any intrinsic using the <tt>llvm_int_ty</tt> type for an argument will
+ be deemed by <tt>tblgen</tt> as overloaded and the corresponding suffix
+ will be required on the intrinsic's name.</li>
+
+ <li><tt>llvm/lib/Analysis/ConstantFolding.cpp</tt>: If it is possible to
+ constant fold your intrinsic, add support to it in the
+ <tt>canConstantFoldCallTo</tt> and <tt>ConstantFoldCall</tt> functions.</li>
+
+ <li><tt>llvm/test/Regression/*</tt>: Add test cases for your test cases to the
+ test suite</li>
+ </ol>
+
+ <p>Once the intrinsic has been added to the system, you must add code generator
+ support for it. Generally you must do the following steps:</p>
+
+ <dl>
+ <dt>Add support to the C backend in <tt>lib/Target/CBackend/</tt></dt>
+
+ <dd>Depending on the intrinsic, there are a few ways to implement this. For
+ most intrinsics, it makes sense to add code to lower your intrinsic in
+ <tt>LowerIntrinsicCall</tt> in <tt>lib/CodeGen/IntrinsicLowering.cpp</tt>.
+ Second, if it makes sense to lower the intrinsic to an expanded sequence of
+ C code in all cases, just emit the expansion in <tt>visitCallInst</tt> in
+ <tt>Writer.cpp</tt>. If the intrinsic has some way to express it with GCC
+ (or any other compiler) extensions, it can be conditionally supported based
+ on the compiler compiling the CBE output (see <tt>llvm.prefetch</tt> for an
+ example). Third, if the intrinsic really has no way to be lowered, just
+ have the code generator emit code that prints an error message and calls
+ abort if executed.</dd>
+
+ <dt>Add support to the .td file for the target(s) of your choice in
+ <tt>lib/Target/*/*.td</tt>.</dt>
+
+ <dd>This is usually a matter of adding a pattern to the .td file that matches
+ the intrinsic, though it may obviously require adding the instructions you
+ want to generate as well. There are lots of examples in the PowerPC and X86
+ backend to follow.</dd>
+ </dl>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="sdnode">Adding a new SelectionDAG node</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier
+ than adding a new instruction. New nodes are often added to help represent
+ instructions common to many targets. These nodes often map to an LLVM
+ instruction (add, sub) or intrinsic (byteswap, population count). In other
+ cases, new nodes have been added to allow many targets to perform a common task
+ (converting between floating point and integer representation) or capture more
+ complicated behavior in a single node (rotate).</p>
+
+ <ol>
+ <li><tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>:
+ Add an enum value for the new SelectionDAG node.</li>
+ <li><tt>lib/CodeGen/SelectionDAG/SelectionDAG.cpp</tt>:
+ Add code to print the node to <tt>getOperationName</tt>. If your new node
+ can be evaluated at compile time when given constant arguments (such as an
+ add of a constant with another constant), find the <tt>getNode</tt> method
+ that takes the appropriate number of arguments, and add a case for your node
+ to the switch statement that performs constant folding for nodes that take
+ the same number of arguments as your new node.</li>
+ <li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
+ Add code to <a href="CodeGenerator.html#selectiondag_legalize">legalize,
+ promote, and expand</a> the node as necessary. At a minimum, you will need
+ to add a case statement for your node in <tt>LegalizeOp</tt> which calls
+ LegalizeOp on the node's operands, and returns a new node if any of the
+ operands changed as a result of being legalized. It is likely that not all
+ targets supported by the SelectionDAG framework will natively support the
+ new node. In this case, you must also add code in your node's case
+ statement in <tt>LegalizeOp</tt> to Expand your node into simpler, legal
+ operations. The case for <tt>ISD::UREM</tt> for expanding a remainder into
+ a divide, multiply, and a subtract is a good example.</li>
+ <li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
+ If targets may support the new node being added only at certain sizes, you
+ will also need to add code to your node's case statement in
+ <tt>LegalizeOp</tt> to Promote your node's operands to a larger size, and
+ perform the correct operation. You will also need to add code to
+ <tt>PromoteOp</tt> to do this as well. For a good example, see
+ <tt>ISD::BSWAP</tt>,
+ which promotes its operand to a wider size, performs the byteswap, and then
+ shifts the correct bytes right to emulate the narrower byteswap in the
+ wider type.</li>
+ <li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
+ Add a case for your node in <tt>ExpandOp</tt> to teach the legalizer how to
+ perform the action represented by the new node on a value that has been
+ split into high and low halves. This case will be used to support your
+ node with a 64 bit operand on a 32 bit target.</li>
+ <li><tt>lib/CodeGen/SelectionDAG/DAGCombiner.cpp</tt>:
+ If your node can be combined with itself, or other existing nodes in a
+ peephole-like fashion, add a visit function for it, and call that function
+ from <tt></tt>. There are several good examples for simple combines you
+ can do; <tt>visitFABS</tt> and <tt>visitSRL</tt> are good starting places.
+ </li>
+ <li><tt>lib/Target/PowerPC/PPCISelLowering.cpp</tt>:
+ Each target has an implementation of the <tt>TargetLowering</tt> class,
+ usually in its own file (although some targets include it in the same
+ file as the DAGToDAGISel). The default behavior for a target is to
+ assume that your new node is legal for all types that are legal for
+ that target. If this target does not natively support your node, then
+ tell the target to either Promote it (if it is supported at a larger
+ type) or Expand it. This will cause the code you wrote in
+ <tt>LegalizeOp</tt> above to decompose your new node into other legal
+ nodes for this target.</li>
+ <li><tt>lib/Target/TargetSelectionDAG.td</tt>:
+ Most current targets supported by LLVM generate code using the DAGToDAG
+ method, where SelectionDAG nodes are pattern matched to target-specific
+ nodes, which represent individual instructions. In order for the targets
+ to match an instruction to your new node, you must add a def for that node
+ to the list in this file, with the appropriate type constraints. Look at
+ <tt>add</tt>, <tt>bswap</tt>, and <tt>fadd</tt> for examples.</li>
+ <li><tt>lib/Target/PowerPC/PPCInstrInfo.td</tt>:
+ Each target has a tablegen file that describes the target's instruction
+ set. For targets that use the DAGToDAG instruction selection framework,
+ add a pattern for your new node that uses one or more target nodes.
+ Documentation for this is a bit sparse right now, but there are several
+ decent examples. See the patterns for <tt>rotl</tt> in
+ <tt>PPCInstrInfo.td</tt>.</li>
+ <li>TODO: document complex patterns.</li>
+ <li><tt>llvm/test/Regression/CodeGen/*</tt>: Add test cases for your new node
+ to the test suite. <tt>llvm/test/Regression/CodeGen/X86/bswap.ll</tt> is
+ a good example.</li>
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="instruction">Adding a new instruction</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p><span class="doc_warning">WARNING: adding instructions changes the bitcode
+ format, and it will take some effort to maintain compatibility with
+ the previous version.</span> Only add an instruction if it is absolutely
+ necessary.</p>
+
+ <ol>
+
+ <li><tt>llvm/include/llvm/Instruction.def</tt>:
+ add a number for your instruction and an enum name</li>
+
+ <li><tt>llvm/include/llvm/Instructions.h</tt>:
+ add a definition for the class that will represent your instruction</li>
+
+ <li><tt>llvm/include/llvm/Support/InstVisitor.h</tt>:
+ add a prototype for a visitor to your new instruction type</li>
+
+ <li><tt>llvm/lib/AsmParser/Lexer.l</tt>:
+ add a new token to parse your instruction from assembly text file</li>
+
+ <li><tt>llvm/lib/AsmParser/llvmAsmParser.y</tt>:
+ add the grammar on how your instruction can be read and what it will
+ construct as a result</li>
+
+ <li><tt>llvm/lib/Bitcode/Reader/Reader.cpp</tt>:
+ add a case for your instruction and how it will be parsed from bitcode</li>
+
+ <li><tt>llvm/lib/VMCore/Instruction.cpp</tt>:
+ add a case for how your instruction will be printed out to assembly</li>
+
+ <li><tt>llvm/lib/VMCore/Instructions.cpp</tt>:
+ implement the class you defined in
+ <tt>llvm/include/llvm/Instructions.h</tt></li>
+
+ <li>Test your instruction</li>
+
+ <li><tt>llvm/lib/Target/*</tt>:
+ Add support for your instruction to code generators, or add a lowering
+ pass.</li>
+
+ <li><tt>llvm/test/Regression/*</tt>: add your test cases to the test suite.</li>
+
+ </ol>
+
+ <p>Also, you need to implement (or modify) any analyses or passes that you want
+ to understand this new instruction.</p>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="type">Adding a new type</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p><span class="doc_warning">WARNING: adding new types changes the bitcode
+ format, and will break compatibility with currently-existing LLVM
+ installations.</span> Only add new types if it is absolutely necessary.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="fund_type">Adding a fundamental type</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ol>
+
+ <li><tt>llvm/include/llvm/Type.h</tt>:
+ add enum for the new type; add static <tt>Type*</tt> for this type</li>
+
+ <li><tt>llvm/lib/VMCore/Type.cpp</tt>:
+ add mapping from <tt>TypeID</tt> => <tt>Type*</tt>;
+ initialize the static <tt>Type*</tt></li>
+
+ <li><tt>llvm/lib/AsmReader/Lexer.l</tt>:
+ add ability to parse in the type from text assembly</li>
+
+ <li><tt>llvm/lib/AsmReader/llvmAsmParser.y</tt>:
+ add a token for that type</li>
+
+ </ol>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="derived_type">Adding a derived type</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ol>
+ <li><tt>llvm/include/llvm/Type.h</tt>:
+ add enum for the new type; add a forward declaration of the type
+ also</li>
+
+ <li><tt>llvm/include/llvm/DerivedTypes.h</tt>:
+ add new class to represent new class in the hierarchy; add forward
+ declaration to the TypeMap value type</li>
+
+ <li><tt>llvm/lib/VMCore/Type.cpp</tt>:
+ add support for derived type to:
+ <div class="doc_code">
+ <pre>
+ std::string getTypeDescription(const Type &Ty,
+ std::vector<const Type*> &TypeStack)
+ bool TypesEqual(const Type *Ty, const Type *Ty2,
+ std::map<const Type*, const Type*> & EqTypes)
+ </pre>
+ </div>
+ add necessary member functions for type, and factory methods</li>
+
+ <li><tt>llvm/lib/AsmReader/Lexer.l</tt>:
+ add ability to parse in the type from text assembly</li>
+
+ <li><tt>llvm/lib/BitCode/Writer/Writer.cpp</tt>:
+ modify <tt>void BitcodeWriter::outputType(const Type *T)</tt> to serialize
+ your type</li>
+
+ <li><tt>llvm/lib/BitCode/Reader/Reader.cpp</tt>:
+ modify <tt>const Type *BitcodeReader::ParseType()</tt> to read your data
+ type</li>
+
+ <li><tt>llvm/lib/VMCore/AsmWriter.cpp</tt>:
+ modify
+ <div class="doc_code">
+ <pre>
+ void calcTypeName(const Type *Ty,
+ std::vector<const Type*> &TypeStack,
+ std::map<const Type*,std::string> &TypeNames,
+ std::string & Result)
+ </pre>
+ </div>
+ to output the new derived type
+ </li>
+
+
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a>
+ <br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/FAQ.html
diff -c /dev/null llvm-www/releases/2.3/docs/FAQ.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/FAQ.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,737 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>LLVM: Frequently Asked Questions</title>
+ <style type="text/css">
+ @import url("llvm.css");
+ .question { font-weight: bold }
+ .answer { margin-left: 2em }
+ </style>
+ </head>
+ <body>
+
+ <div class="doc_title">
+ LLVM: Frequently Asked Questions
+ </div>
+
+ <ol>
+ <li><a href="#license">License</a>
+ <ol>
+ <li>Why are the LLVM source code and the front-end distributed under different
+ licenses?</li>
+ <li>Does the University of Illinois Open Source License really qualify as an
+ "open source" license?</li>
+ <li>Can I modify LLVM source code and redistribute the modified source?</li>
+ <li>Can I modify LLVM source code and redistribute binaries or other tools
+ based on it, without redistributing the source?</li>
+ </ol></li>
+
+ <li><a href="#source">Source code</a>
+ <ol>
+ <li>In what language is LLVM written?</li>
+ <li>How portable is the LLVM source code?</li>
+ </ol></li>
+
+ <li><a href="#build">Build Problems</a>
+ <ol>
+ <li>When I run configure, it finds the wrong C compiler.</li>
+ <li>The <tt>configure</tt> script finds the right C compiler, but it uses the
+ LLVM linker from a previous build. What do I do?</li>
+ <li>When creating a dynamic library, I get a strange GLIBC error.</li>
+ <li>I've updated my source tree from Subversion, and now my build is trying
+ to use a file/directory that doesn't exist.</li>
+ <li>I've modified a Makefile in my source tree, but my build tree keeps using
+ the old version. What do I do?</li>
+ <li>I've upgraded to a new version of LLVM, and I get strange build
+ errors.</li>
+ <li>I've built LLVM and am testing it, but the tests freeze.</li>
+ <li>Why do test results differ when I perform different types of builds?</li>
+ <li>Compiling LLVM with GCC 3.3.2 fails, what should I do?</li>
+ <li>When I use the test suite, all of the C Backend tests fail. What is
+ wrong?</li>
+ <li>After Subversion update, rebuilding gives the error "No rule to make
+ target".</li>
+ <li><a href="#llvmc">The <tt>llvmc</tt> program gives me errors/doesn't
+ work.</a></li>
+ </ol></li>
+
+ <li><a href="#felangs">Source Languages</a>
+ <ol>
+ <li><a href="#langs">What source languages are supported?</a></li>
+ <li><a href="#langirgen">I'd like to write a self-hosting LLVM compiler. How
+ should I interface with the LLVM middle-end optimizers and back-end code
+ generators?</a></div>
+ <li><a href="#langhlsupp">What support is there for higher level source
+ language constructs for building a compiler?</a></li>
+ <li><a href="GetElementPtr.html">I don't understand the GetElementPtr
+ instruction. Help!</a></li>
+ </ol>
+
+ <li><a href="#cfe">Using the GCC Front End</a>
+ <ol>
+ <li>
+ When I compile software that uses a configure script, the configure script
+ thinks my system has all of the header files and libraries it is testing
+ for. How do I get configure to work correctly?
+ </li>
+
+ <li>
+ When I compile code using the LLVM GCC front end, it complains that it
+ cannot find libcrtend.a.
+ </li>
+
+ <li>
+ How can I disable all optimizations when compiling code using the LLVM GCC front end?
+ </li>
+
+ <li><a href="#translatec++">Can I use LLVM to convert C++ code to C code?</a></li>
+
+ </ol>
+ </li>
+
+ <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
+ <ol>
+ <li><a href="#iosinit">What is this <tt>llvm.global_ctors</tt> and
+ <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I
+ #include <iostream>?</a></li>
+ <li><a href="#codedce">Where did all of my code go??</a></li>
+ <li><a href="#undef">What is this "<tt>undef</tt>" thing that shows up in my code?</a></li>
+ </ol>
+ </li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="http://llvm.org">The LLVM Team</a></p>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="license">License</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="question">
+ <p>Why are the LLVM source code and the front-end distributed under different
+ licenses?</p>
+ </div>
+
+ <div class="answer">
+ <p>The C/C++ front-ends are based on GCC and must be distributed under the GPL.
+ Our aim is to distribute LLVM source code under a <em>much less restrictive</em>
+ license, in particular one that does not compel users who distribute tools based
+ on modifying the source to redistribute the modified source code as well.</p>
+ </div>
+
+ <div class="question">
+ <p>Does the University of Illinois Open Source License really qualify as an
+ "open source" license?</p>
+ </div>
+
+ <div class="answer">
+ <p>Yes, the license is <a
+ href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open
+ Source Initiative (OSI).</p>
+ </div>
+
+ <div class="question">
+ <p>Can I modify LLVM source code and redistribute the modified source?</p>
+ </div>
+
+ <div class="answer">
+ <p>Yes. The modified source distribution must retain the copyright notice and
+ follow the three bulletted conditions listed in the <a
+ href="http://llvm.org/releases/1.3/LICENSE.TXT">LLVM license</a>.</p>
+ </div>
+
+ <div class="question">
+ <p>Can I modify LLVM source code and redistribute binaries or other tools based
+ on it, without redistributing the source?</p>
+ </div>
+
+ <div class="answer">
+ <p>Yes, this is why we distribute LLVM under a less restrictive license than
+ GPL, as explained in the first question above.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="source">Source Code</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="question">
+ <p>In what language is LLVM written?</p>
+ </div>
+
+ <div class="answer">
+ <p>All of the LLVM tools and libraries are written in C++ with extensive use of
+ the STL.</p>
+ </div>
+
+ <div class="question">
+ <p>How portable is the LLVM source code?</p>
+ </div>
+
+ <div class="answer">
+ <p>The LLVM source code should be portable to most modern UNIX-like operating
+ systems. Most of the code is written in standard C++ with operating system
+ services abstracted to a support library. The tools required to build and test
+ LLVM have been ported to a plethora of platforms.</p>
+
+ <p>Some porting problems may exist in the following areas:</p>
+
+ <ul>
+ <li>The GCC front end code is not as portable as the LLVM suite, so it may not
+ compile as well on unsupported platforms.</li>
+
+ <li>The LLVM build system relies heavily on UNIX shell tools, like the Bourne
+ Shell and sed. Porting to systems without these tools (MacOS 9, Plan 9)
+ will require more effort.</li>
+ </ul>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="build">Build Problems</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="question">
+ <p>When I run configure, it finds the wrong C compiler.</p>
+ </div>
+
+ <div class="answer">
+
+ <p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then
+ <tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt> and <tt>CXX</tt>
+ for the C and C++ compiler, respectively.</p>
+
+ <p>If <tt>configure</tt> finds the wrong compiler, either adjust your
+ <tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
+ explicitly.</p>
+
+ </div>
+
+ <div class="question">
+ <p>The <tt>configure</tt> script finds the right C compiler, but it uses the
+ LLVM linker from a previous build. What do I do?</p>
+ </div>
+
+ <div class="answer">
+ <p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so
+ if it's grabbing the wrong linker/assembler/etc, there are two ways to fix
+ it:</p>
+
+ <ol>
+ <li><p>Adjust your <tt>PATH</tt> environment variable so that the correct
+ program appears first in the <tt>PATH</tt>. This may work, but may not be
+ convenient when you want them <i>first</i> in your path for other
+ work.</p></li>
+
+ <li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
+ correct. In a Borne compatible shell, the syntax would be:</p>
+
+ <div class="doc_code">
+ <pre>
+ % PATH=[the path without the bad program] ./configure ...
+ </pre>
+ </div>
+
+ <p>This is still somewhat inconvenient, but it allows <tt>configure</tt>
+ to do its work without having to adjust your <tt>PATH</tt>
+ permanently.</p></li>
+ </ol>
+
+ </div>
+
+ <div class="question">
+ <p>When creating a dynamic library, I get a strange GLIBC error.</p>
+ </div>
+
+ <div class="answer">
+ <p>Under some operating systems (i.e. Linux), libtool does not work correctly if
+ GCC was compiled with the --disable-shared option. To work around this, install
+ your own version of GCC that has shared libraries enabled by default.</p>
+ </div>
+
+ <div class="question">
+ <p>I've updated my source tree from Subversion, and now my build is trying to
+ use a file/directory that doesn't exist.</p>
+ </div>
+
+ <div class="answer">
+ <p>You need to re-run configure in your object directory. When new Makefiles
+ are added to the source tree, they have to be copied over to the object tree in
+ order to be used by the build.</p>
+ </div>
+
+ <div class="question">
+ <p>I've modified a Makefile in my source tree, but my build tree keeps using the
+ old version. What do I do?</p>
+ </div>
+
+ <div class="answer">
+ <p>If the Makefile already exists in your object tree, you
+ can just run the following command in the top level directory of your object
+ tree:</p>
+
+ <div class="doc_code">
+ <pre>% ./config.status <relative path to Makefile></pre>
+ </div>
+
+ <p>If the Makefile is new, you will have to modify the configure script to copy
+ it over.</p>
+
+ </div>
+
+ <div class="question">
+ <p>I've upgraded to a new version of LLVM, and I get strange build errors.</p>
+ </div>
+
+ <div class="answer">
+
+ <p>Sometimes, changes to the LLVM source code alters how the build system works.
+ Changes in libtool, autoconf, or header file dependencies are especially prone
+ to this sort of problem.</p>
+
+ <p>The best thing to try is to remove the old files and re-build. In most
+ cases, this takes care of the problem. To do this, just type <tt>make
+ clean</tt> and then <tt>make</tt> in the directory that fails to build.</p>
+
+ </div>
+
+ <div class="question">
+ <p>I've built LLVM and am testing it, but the tests freeze.</p>
+ </div>
+
+ <div class="answer">
+
+ <p>This is most likely occurring because you built a profile or release
+ (optimized) build of LLVM and have not specified the same information on the
+ <tt>gmake</tt> command line.</p>
+
+ <p>For example, if you built LLVM with the command:</p>
+
+ <div class="doc_code">
+ <pre>% gmake ENABLE_PROFILING=1</pre>
+ </div>
+
+ <p>...then you must run the tests with the following commands:</p>
+
+ <div class="doc_code">
+ <pre>
+ % cd llvm/test
+ % gmake ENABLE_PROFILING=1
+ </pre>
+ </div>
+
+ </div>
+
+ <div class="question">
+ <p>Why do test results differ when I perform different types of builds?</p>
+ </div>
+
+ <div class="answer">
+
+ <p>The LLVM test suite is dependent upon several features of the LLVM tools and
+ libraries.</p>
+
+ <p>First, the debugging assertions in code are not enabled in optimized or
+ profiling builds. Hence, tests that used to fail may pass.</p>
+
+ <p>Second, some tests may rely upon debugging options or behavior that is only
+ available in the debug build. These tests will fail in an optimized or profile
+ build.</p>
+
+ </div>
+
+ <div class="question">
+ <p>Compiling LLVM with GCC 3.3.2 fails, what should I do?</p>
+ </div>
+
+ <div class="answer">
+ <p>This is <a href="http://gcc.gnu.org/PR?13392">a bug in GCC</a>, and
+ affects projects other than LLVM. Try upgrading or downgrading your GCC.</p>
+ </div>
+
+ <div class="question">
+ <p>After Subversion update, rebuilding gives the error "No rule to make
+ target".</p>
+ </div>
+
+ <div class="answer">
+ <p>If the error is of the form:</p>
+
+ <div class="doc_code">
+ <pre>
+ gmake[2]: *** No rule to make target `/path/to/somefile', needed by
+ `/path/to/another/file.d'.<br>
+ Stop.
+ </pre>
+ </div>
+
+ <p>This may occur anytime files are moved within the Subversion repository or
+ removed entirely. In this case, the best solution is to erase all
+ <tt>.d</tt> files, which list dependencies for source files, and rebuild:</p>
+
+ <div class="doc_code">
+ <pre>
+ % cd $LLVM_OBJ_DIR
+ % rm -f `find . -name \*\.d`
+ % gmake
+ </pre>
+ </div>
+
+ <p>In other cases, it may be necessary to run <tt>make clean</tt> before
+ rebuilding.</p>
+ </div>
+
+ <div class="question"><p><a name="llvmc">
+ The <tt>llvmc</tt> program gives me errors/doesn't work.</a></p>
+ </div>
+
+ <div class="answer">
+ <p><tt>llvmc</tt> is experimental and isn't really supported. We suggest
+ using <tt>llvm-gcc</tt> instead.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="felangs">Source Languages</a></div>
+
+ <div class="question"><p>
+ <a name="langs">What source languages are supported?</a></p>
+ </div>
+ <div class="answer">
+ <p>LLVM currently has full support for C and C++ source languages. These are
+ available through a special version of GCC that LLVM calls the
+ <a href="#cfe">C Front End</a></p>
+ <p>There is an incomplete version of a Java front end available in the
+ <tt>java</tt> module. There is no documentation on this yet so
+ you'll need to download the code, compile it, and try it.</p>
+ <p>In the <tt>stacker</tt> module is a compiler and runtime
+ library for the Stacker language, a "toy" language loosely based on Forth.</p>
+ <p>The PyPy developers are working on integrating LLVM into the PyPy backend
+ so that PyPy language can translate to LLVM.</p>
+ </div>
+
+ <div class="question"><p><a name="langirgen">
+ I'd like to write a self-hosting LLVM compiler. How should I interface with
+ the LLVM middle-end optimizers and back-end code generators?
+ </a></p></div>
+ <div class="answer">
+ <p>Your compiler front-end will communicate with LLVM by creating a module in
+ the LLVM intermediate representation (IR) format. Assuming you want to
+ write your language's compiler in the language itself (rather than C++),
+ there are 3 major ways to tackle generating LLVM IR from a front-end:</p>
+ <ul>
+ <li>
+ <strong>Call into the LLVM libraries code using your language's FFI
+ (foreign function interface).</strong>
+ <ul>
+ <li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax,
+ and .bc format</li>
+ <li><em>for:</em> enables running LLVM optimization passes without a
+ emit/parse overhead</li>
+ <li><em>for:</em> adapts well to a JIT context</li>
+ <li><em>against:</em> lots of ugly glue code to write</li>
+ </ul>
+ </li>
+ <li>
+ <strong>Emit LLVM assembly from your compiler's native language.</strong>
+ <ul>
+ <li><em>for:</em> very straightforward to get started</li>
+ <li><em>against:</em> the .ll parser is slower than the bitcode reader
+ when interfacing to the middle end</li>
+ <li><em>against:</em> you'll have to re-engineer the LLVM IR object
+ model and asm writer in your language</li>
+ <li><em>against:</em> it may be harder to track changes to the IR</li>
+ </ul>
+ </li>
+ <li>
+ <strong>Emit LLVM bitcode from your compiler's native language.</strong>
+ <ul>
+ <li><em>for:</em> can use the more-efficient bitcode reader when
+ interfacing to the middle end</li>
+ <li><em>against:</em> you'll have to re-engineer the LLVM IR object
+ model and bitcode writer in your language</li>
+ <li><em>against:</em> it may be harder to track changes to the IR</li>
+ </ul>
+ </li>
+ </ul>
+ <p>If you go with the first option, the C bindings in include/llvm-c should
+ help a lot, since most languages have strong support for interfacing with
+ C. The most common hurdle with calling C from managed code is interfacing
+ with the garbage collector. The C interface was designed to require very
+ little memory management, and so is straightforward in this regard.</p>
+ </div>
+
+ <div class="question"><p><a name="langhlsupp">
+ What support is there for a higher level source language constructs for
+ building a compiler?</a></p>
+ </div>
+ <div class="answer">
+ <p>Currently, there isn't much. LLVM supports an intermediate representation
+ which is useful for code representation but will not support the high level
+ (abstract syntax tree) representation needed by most compilers. There are no
+ facilities for lexical nor semantic analysis. There is, however, a <i>mostly
+ implemented</i> configuration-driven
+ <a href="CompilerDriver.html">compiler driver</a> which simplifies the task
+ of running optimizations, linking, and executable generation.</p>
+ </div>
+
+ <div class="question"><p><a name="langhlsupp">
+ I don't understand the GetElementPtr instruction. Help!</a></p>
+ </div>
+ <div class="answer">
+ <p>See <a href="GetElementPtr.html">The Often Misunderstood GEP
+ Instruction</a>.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="cfe">Using the GCC Front End</a>
+ </div>
+
+ <div class="question">
+ <p>
+ When I compile software that uses a configure script, the configure script
+ thinks my system has all of the header files and libraries it is testing for.
+ How do I get configure to work correctly?
+ </p>
+ </div>
+
+ <div class="answer">
+ <p>
+ The configure script is getting things wrong because the LLVM linker allows
+ symbols to be undefined at link time (so that they can be resolved during JIT
+ or translation to the C back end). That is why configure thinks your system
+ "has everything."
+ </p>
+ <p>
+ To work around this, perform the following steps:
+ </p>
+ <ol>
+ <li>Make sure the CC and CXX environment variables contains the full path to
+ the LLVM GCC front end.</li>
+
+ <li>Make sure that the regular C compiler is first in your PATH. </li>
+
+ <li>Add the string "-Wl,-native" to your CFLAGS environment variable.</li>
+ </ol>
+
+ <p>
+ This will allow the <tt>llvm-ld</tt> linker to create a native code executable
+ instead of shell script that runs the JIT. Creating native code requires
+ standard linkage, which in turn will allow the configure script to find out if
+ code is not linking on your system because the feature isn't available on your
+ system.</p>
+ </div>
+
+ <div class="question">
+ <p>
+ When I compile code using the LLVM GCC front end, it complains that it cannot
+ find libcrtend.a.
+ </p>
+ </div>
+
+ <div class="answer">
+ <p>
+ The only way this can happen is if you haven't installed the runtime library. To
+ correct this, do:</p>
+
+ <div class="doc_code">
+ <pre>
+ % cd llvm/runtime
+ % make clean ; make install-bytecode
+ </pre>
+ </div>
+ </div>
+
+ <div class="question">
+ <p>
+ How can I disable all optimizations when compiling code using the LLVM GCC front end?
+ </p>
+ </div>
+
+ <div class="answer">
+ <p>
+ Passing "-Wa,-disable-opt -Wl,-disable-opt" will disable *all* cleanup and
+ optimizations done at the llvm level, leaving you with the truly horrible
+ code that you desire.
+ </p>
+ </div>
+
+
+ <div class="question">
+ <p>
+ <a name="translatec++">Can I use LLVM to convert C++ code to C code?</a>
+ </p>
+ </div>
+
+ <div class="answer">
+ <p>Yes, you can use LLVM to convert code from any language LLVM supports to C.
+ Note that the generated C code will be very low level (all loops are lowered
+ to gotos, etc) and not very pretty (comments are stripped, original source
+ formatting is totally lost, variables are renamed, expressions are regrouped),
+ so this may not be what you're looking for. However, this is a good way to add
+ C++ support for a processor that does not otherwise have a C++ compiler.
+ </p>
+
+ <p>Use commands like this:</p>
+
+ <ol>
+ <li><p>Compile your program as normal with llvm-g++:</p>
+
+ <div class="doc_code">
+ <pre>
+ % llvm-g++ x.cpp -o program
+ </pre>
+ </div>
+
+ <p>or:</p>
+
+ <div class="doc_code">
+ <pre>
+ % llvm-g++ a.cpp -c
+ % llvm-g++ b.cpp -c
+ % llvm-g++ a.o b.o -o program
+ </pre>
+ </div>
+
+ <p>With llvm-gcc3, this will generate program and program.bc. The .bc
+ file is the LLVM version of the program all linked together.</p></li>
+
+ <li><p>Convert the LLVM code to C code, using the LLC tool with the C
+ backend:</p>
+
+ <div class="doc_code">
+ <pre>
+ % llc -march=c program.bc -o program.c
+ </pre>
+ </div></li>
+
+ <li><p>Finally, compile the C file:</p>
+
+ <div class="doc_code">
+ <pre>
+ % cc x.c
+ </pre>
+ </div></li>
+
+ </ol>
+
+ <p>Note that, by default, the C backend does not support exception handling. If
+ you want/need it for a certain program, you can enable it by passing
+ "-enable-correct-eh-support" to the llc program. The resultant code will use
+ setjmp/longjmp to implement exception support that is correct but relatively
+ slow.</p>
+
+ <p>Also note: this specific sequence of commands won't work if you use a
+ function defined in the C++ runtime library (or any other C++ library). To
+ access an external C++ library, you must manually compile libstdc++ to LLVM
+ bitcode, statically link it into your program, then use the commands above to
+ convert the whole result into C code. Alternatively, you can compile the
+ libraries and your application into two different chunks of C code and link
+ them.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="cfe_code">Questions about code generated by the GCC front-end</a>
+ </div>
+
+ <div class="question">
+ <a name="iosinit"></a>
+ <p> What is this <tt>llvm.global_ctors</tt> and
+ <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I #include
+ <iostream>?</p>
+ </div>
+
+ <div class="answer">
+
+ <p>If you #include the <iostream> header into a C++ translation unit, the
+ file will probably use the <tt>std::cin</tt>/<tt>std::cout</tt>/... global
+ objects. However, C++ does not guarantee an order of initialization between
+ static objects in different translation units, so if a static ctor/dtor in your
+ .cpp file used <tt>std::cout</tt>, for example, the object would not necessarily
+ be automatically initialized before your use.</p>
+
+ <p>To make <tt>std::cout</tt> and friends work correctly in these scenarios, the
+ STL that we use declares a static object that gets created in every translation
+ unit that includes <tt><iostream></tt>. This object has a static
+ constructor and destructor that initializes and destroys the global iostream
+ objects before they could possibly be used in the file. The code that you see
+ in the .ll file corresponds to the constructor and destructor registration code.
+ </p>
+
+ <p>If you would like to make it easier to <b>understand</b> the LLVM code
+ generated by the compiler in the demo page, consider using <tt>printf()</tt>
+ instead of <tt>iostream</tt>s to print values.</p>
+
+ </div>
+
+ <!--=========================================================================-->
+
+ <div class="question"><p>
+ <a name="codedce"></a>
+ Where did all of my code go??
+ </p></div>
+
+ <div class="answer">
+ <p>
+ If you are using the LLVM demo page, you may often wonder what happened to all
+ of the code that you typed in. Remember that the demo script is running the
+ code through the LLVM optimizers, so if your code doesn't actually do anything
+ useful, it might all be deleted.
+ </p>
+
+ <p>
+ To prevent this, make sure that the code is actually needed. For example, if
+ you are computing some expression, return the value from the function instead of
+ leaving it in a local variable. If you really want to constrain the optimizer,
+ you can read from and assign to <tt>volatile</tt> global variables.
+ </p>
+ </div>
+
+ <!--=========================================================================-->
+
+ <div class="question"><p>
+ <a name="undef"></a>
+ <p>What is this "<tt>undef</tt>" thing that shows up in my code?
+ </p></div>
+
+ <div class="answer">
+ <p>
+ <a href="LangRef.html#undef"><tt>undef</tt></a> is the LLVM way of representing
+ a value that is not defined. You can get these if you do not initialize a
+ variable before you use it. For example, the C function:</p>
+
+ <div class="doc_code">
+ <pre>
+ int X() { int i; return i; }
+ </pre>
+ </div>
+
+ <p>Is compiled to "<tt>ret i32 undef</tt>" because "<tt>i</tt>" never has
+ a value specified for it.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/GCCFEBuildInstrs.html
diff -c /dev/null llvm-www/releases/2.3/docs/GCCFEBuildInstrs.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/GCCFEBuildInstrs.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,284 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="stylesheet" href="llvm.css" type="text/css" media="screen">
+ <title>Building the LLVM GCC Front-End</title>
+ </head>
+ <body>
+
+ <div class="doc_title">
+ Building the LLVM GCC Front-End
+ </div>
+
+ <ol>
+ <li><a href="#instructions">Building llvm-gcc from Source</a></li>
+ <li><a href="#license">License Information</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by the LLVM Team</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="instructions">Building llvm-gcc from Source</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This section describes how to acquire and build llvm-gcc 4.0 and 4.2, which are
+ based on the GCC 4.0.1/4.2.1 front-ends respectively. Both front-ends support C,
+ C++, Objective-C and Objective-C++. The 4.2 front-end also supports Ada and
+ Fortran to some extent. Note that the instructions for building these front-ends
+ are completely different (and much easier!) than those for building llvm-gcc3 in
+ the past.</p>
+
+ <ol>
+ <li><p>Retrieve the appropriate llvm-gcc4.x-y.z.source.tar.gz archive from the
+ <a href="http://llvm.org/releases/">llvm web site</a>.</p>
+
+ <p>It is also possible to download the sources of the llvm-gcc front end
+ from a read-only mirror using subversion. To check out the 4.0 code
+ for first time use:</p>
+
+ <div class="doc_code">
+ <pre>
+ svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk <i>dst-directory</i>
+ </pre>
+ </div>
+
+ <p>To check out the 4.2 code use:</p>
+
+ <div class="doc_code">
+ <pre>
+ svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk <i>dst-directory</i>
+ </pre>
+ </div>
+
+ <p>After that, the code can be be updated in the destination directory
+ using:</p>
+
+ <div class="doc_code">
+ <pre>svn update</pre>
+ </div>
+
+ <p>The mirror is brought up to date every evening.</p></li>
+
+ <li>Follow the directions in the top-level <tt>README.LLVM</tt> file for
+ up-to-date instructions on how to build llvm-gcc. See below for building
+ with support for Ada or Fortran.
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="license">Building the Ada front-end</a>
+ </div>
+
+ <div class="doc_text">
+ <p>Building with support for Ada amounts to following the directions in the
+ top-level <tt>README.LLVM</tt> file, adding ",ada" to EXTRALANGS, for example:
+ <tt>EXTRALANGS=,ada</tt></p>
+
+ <p>There are some complications however:</p>
+
+ <ol>
+ <li><p>The only platform for which the Ada front-end is known to build is
+ 32 bit intel x86 running linux. It is unlikely to build for other
+ systems without some work.</p></li>
+ <li><p>The build requires having a compiler that supports Ada, C and C++.
+ The Ada front-end is written in Ada so an Ada compiler is needed to
+ build it. Compilers known to work with the
+ <a href="http://llvm.org/releases/download.html">LLVM 2.2 release</a>
+ are <a href="http://gcc.gnu.org/releases.html">gcc-4.2</a> and the
+ <a href="http://libre.adacore.com/">2005 GNAT GPL Edition</a>.
+ <a href="GettingStarted.html#checkout">LLVM from subversion</a>
+ also works with the
+ <a href="http://libre.adacore.com/">2006 and 2007 GNAT GPL Editions</a>.
+ The LLVM parts of llvm-gcc are written in C++ so a C++ compiler is
+ needed to build them. The rest of gcc is written in C.
+ Some linux distributions provide a version of gcc that supports all
+ three languages (the Ada part often comes as an add-on package to
+ the rest of gcc). Otherwise it is possible to combine two versions
+ of gcc, one that supports Ada and C (such as the
+ <a href="http://libre.adacore.com/">2005 GNAT GPL Edition</a>)
+ and another which supports C++, see below.</p></li>
+ <li><p>Because the Ada front-end is experimental, it is wise to build the
+ compiler with checking enabled. This causes it to run much slower, but
+ helps catch mistakes in the compiler (please report any problems using
+ <a href="http://llvm.org/bugs">LLVM bugzilla</a>).</p></li>
+ </ol>
+
+ <p>Supposing appropriate compilers are available, llvm-gcc with Ada support can
+ be built on an x86-32 linux box using the following recipe:</p>
+
+ <ol>
+ <li><p>Download the <a href="http://llvm.org/releases/download.html">LLVM source</a>
+ and unpack it:</p>
+
+ <div class="doc_code">
+ <pre>wget http://llvm.org/releases/2.2/llvm-2.2.tar.gz
+ tar xzf llvm-2.2.tar.gz
+ mv llvm-2.2 llvm</pre>
+ </div>
+
+ <p>or <a href="GettingStarted.html#checkout">check out the
+ latest version from subversion</a>:</p>
+
+ <div class="doc_code">
+ <pre>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</pre>
+ </div>
+ </li>
+
+ <li><p>Download the
+ <a href="http://llvm.org/releases/download.html">llvm-gcc-4.2 source</a>
+ and unpack it:</p>
+
+ <div class="doc_code">
+ <pre>wget http://llvm.org/releases/2.2/llvm-gcc4.2-2.2.source.tar.gz
+ tar xzf llvm-gcc4.2-2.2.source.tar.gz
+ mv llvm-gcc4.2-2.2.source llvm-gcc-4.2</pre>
+ </div>
+
+ <p>or <a href="GettingStarted.html#checkout">check out the
+ latest version from subversion</a>:</p>
+
+ <div class="doc_code">
+ <pre>svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk llvm-gcc-4.2</pre>
+ </div>
+ </li>
+
+ <li><p>Make a build directory <tt>llvm-objects</tt> for llvm and make it the
+ current directory:</p>
+
+ <div class="doc_code">
+ <pre>mkdir llvm-objects
+ cd llvm-objects</pre>
+ </div>
+ </li>
+
+ <li><p>Configure LLVM (here it is configured to install into <tt>/usr/local</tt>):</p>
+
+ <div class="doc_code">
+ <pre>../llvm/configure --prefix=<b>/usr/local</b></pre>
+ </div>
+
+ <p>If you have a multi-compiler setup and the C++ compiler is not the
+ default, then you can configure like this:</p>
+
+ <div class="doc_code">
+ <pre>CXX=<b>PATH_TO_C++_COMPILER</b> ../llvm/configure --prefix=<b>/usr/local</b></pre>
+ </div>
+ </li>
+
+ <li><p>Build LLVM with checking enabled (use <tt>ENABLE_OPTIMIZED=1</tt> to
+ build without checking):</p>
+
+ <div class="doc_code">
+ <pre>make ENABLE_OPTIMIZED=0</pre>
+ </div>
+ </li>
+
+ <li><p>Install LLVM (optional):</p>
+
+ <div class="doc_code">
+ <pre>make install</pre>
+ </div>
+ </li>
+
+ <li><p>Make a build directory <tt>llvm-gcc-4.2-objects</tt> for llvm-gcc and make it the
+ current directory:</p>
+
+ <div class="doc_code">
+ <pre>
+ cd ..
+ mkdir llvm-gcc-4.2-objects
+ cd llvm-gcc-4.2-objects</pre>
+ </div>
+ </li>
+
+ <li><p>Configure llvm-gcc (here it is configured to install into <tt>/usr/local</tt>).
+ The <tt>--enable-checking</tt> flag turns on sanity checks inside the compiler.
+ If you omit it then LLVM must be built with <tt>make ENABLE_OPTIMIZED=1</tt>.
+ Additional languages can be appended to the --enable-languages switch,
+ for example <tt>--enable-languages=ada,c,c++</tt>.</p>
+
+ <div class="doc_code">
+ <pre>../llvm-gcc-4.2/configure --prefix=<b>/usr/local</b> --enable-languages=ada,c --enable-checking --enable-llvm=$PWD/../llvm-objects --disable-shared --disable-bootstrap --disable-multilib</pre>
+ </div>
+
+ <p>If you have a multi-compiler setup, then you can configure like this:</p>
+ <div class="doc_code">
+
+ <pre>
+ export CC=<b>PATH_TO_C_AND_ADA_COMPILER</b>
+ export CXX=<b>PATH_TO_C++_COMPILER</b>
+ ../llvm-gcc-4.2/configure --prefix=<b>/usr/local</b> --enable-languages=ada,c --enable-checking --enable-llvm=$PWD/../llvm-objects --disable-shared --disable-bootstrap --disable-multilib</pre>
+ </div>
+ </li>
+
+ <li><p>Build and install the compiler:</p>
+
+ <div class="doc_code">
+ <pre>make
+ make install</pre>
+ </div>
+ </li>
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="license">Building the Fortran front-end</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ To build with support for Fortran, follow the directions in the top-level
+ <tt>README.LLVM</tt> file, adding ",fortran" to EXTRALANGS, for example:</p>
+
+ <div class="doc_code">
+ <pre>
+ EXTRALANGS=,fortran
+ </pre>
+ </div>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="license">License Information</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ The LLVM GCC frontend is licensed to you under the GNU General Public License
+ and the GNU Lesser General Public License. Please see the files COPYING and
+ COPYING.LIB for more details.
+ </p>
+
+ <p>
+ More information is <a href="FAQ.html#license">available in the FAQ</a>.
+ </p>
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/GarbageCollection.html
diff -c /dev/null llvm-www/releases/2.3/docs/GarbageCollection.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/GarbageCollection.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,1419 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" Content="text/html; charset=UTF-8" >
+ <title>Accurate Garbage Collection with LLVM</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ <style type="text/css">
+ .rowhead { text-align: left; background: inherit; }
+ .indent { padding-left: 1em; }
+ .optl { color: #BFBFBF; }
+ </style>
+ </head>
+ <body>
+
+ <div class="doc_title">
+ Accurate Garbage Collection with LLVM
+ </div>
+
+ <ol>
+ <li><a href="#introduction">Introduction</a>
+ <ul>
+ <li><a href="#feature">GC features provided and algorithms
+ supported</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#usage">Using the collectors</a>
+ <ul>
+ <li><a href="#shadow-stack">ShadowStack -
+ A highly portable collector</a></li>
+ <li><a href="#semispace">SemiSpace -
+ A simple copying collector runtime</a></li>
+ <li><a href="#ocaml">Ocaml -
+ An Objective Caml-compatible collector</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#core">Core support</a>
+ <ul>
+ <li><a href="#gcattr">Specifying GC code generation:
+ <tt>gc "..."</tt></a></li>
+ <li><a href="#gcroot">Identifying GC roots on the stack:
+ <tt>llvm.gcroot</tt></a></li>
+ <li><a href="#barriers">Reading and writing references in the heap</a>
+ <ul>
+ <li><a href="#gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a></li>
+ <li><a href="#gcread">Read barrier: <tt>llvm.gcread</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+
+ <li><a href="#runtime">Recommended runtime interface</a>
+ <ul>
+ <li><a href="#initialize">Garbage collector startup and
+ initialization</a></li>
+ <li><a href="#allocate">Allocating memory from the GC</a></li>
+ <li><a href="#explicit">Explicit invocation of the garbage
+ collector</a></li>
+ <li><a href="#traceroots">Tracing GC pointers from the program
+ stack</a></li>
+ <li><a href="#staticroots">Tracing GC pointers from static roots</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#plugin">Implementing a collector plugin</a>
+ <ul>
+ <li><a href="#collector-algos">Overview of available features</a></li>
+ <li><a href="#stack-map">Computing stack maps</a></li>
+ <li><a href="#init-roots">Initializing roots to null:
+ <tt>InitRoots</tt></a></li>
+ <li><a href="#custom">Custom lowering of intrinsics: <tt>CustomRoots</tt>,
+ <tt>CustomReadBarriers</tt>, and <tt>CustomWriteBarriers</tt></a></li>
+ <li><a href="#safe-points">Generating safe points:
+ <tt>NeededSafePoints</tt></a></li>
+ <li><a href="#assembly">Emitting assembly code:
+ <tt>beginAssembly</tt> and <tt>finishAssembly</tt></a></li>
+ </ul>
+ </li>
+
+ <li><a href="#runtime-impl">Implementing a collector runtime</a>
+ <ul>
+ <li><a href="#gcdescriptors">Tracing GC pointers from heap
+ objects</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#references">References</a></li>
+
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a> and
+ Gordon Henriksen</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Garbage collection is a widely used technique that frees the programmer from
+ having to know the lifetimes of heap objects, making software easier to produce
+ and maintain. Many programming languages rely on garbage collection for
+ automatic memory management. There are two primary forms of garbage collection:
+ conservative and accurate.</p>
+
+ <p>Conservative garbage collection often does not require any special support
+ from either the language or the compiler: it can handle non-type-safe
+ programming languages (such as C/C++) and does not require any special
+ information from the compiler. The
+ <a href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm collector</a> is
+ an example of a state-of-the-art conservative collector.</p>
+
+ <p>Accurate garbage collection requires the ability to identify all pointers in
+ the program at run-time (which requires that the source-language be type-safe in
+ most cases). Identifying pointers at run-time requires compiler support to
+ locate all places that hold live pointer variables at run-time, including the
+ <a href="#gcroot">processor stack and registers</a>.</p>
+
+ <p>Conservative garbage collection is attractive because it does not require any
+ special compiler support, but it does have problems. In particular, because the
+ conservative garbage collector cannot <i>know</i> that a particular word in the
+ machine is a pointer, it cannot move live objects in the heap (preventing the
+ use of compacting and generational GC algorithms) and it can occasionally suffer
+ from memory leaks due to integer values that happen to point to objects in the
+ program. In addition, some aggressive compiler transformations can break
+ conservative garbage collectors (though these seem rare in practice).</p>
+
+ <p>Accurate garbage collectors do not suffer from any of these problems, but
+ they can suffer from degraded scalar optimization of the program. In particular,
+ because the runtime must be able to identify and update all pointers active in
+ the program, some optimizations are less effective. In practice, however, the
+ locality and performance benefits of using aggressive garbage allocation
+ techniques dominates any low-level losses.</p>
+
+ <p>This document describes the mechanisms and interfaces provided by LLVM to
+ support accurate garbage collection.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="feature">GC features provided and algorithms supported</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM's intermediate representation provides <a href="#intrinsics">garbage
+ collection intrinsics</a> that offer support for a broad class of
+ collector models. For instance, the intrinsics permit:</p>
+
+ <ul>
+ <li>semi-space collectors</li>
+ <li>mark-sweep collectors</li>
+ <li>generational collectors</li>
+ <li>reference counting</li>
+ <li>incremental collectors</li>
+ <li>concurrent collectors</li>
+ <li>cooperative collectors</li>
+ </ul>
+
+ <p>We hope that the primitive support built into the LLVM IR is sufficient to
+ support a broad class of garbage collected languages including Scheme, ML, Java,
+ C#, Perl, Python, Lua, Ruby, other scripting languages, and more.</p>
+
+ <p>However, LLVM does not itself implement a garbage collector. This is because
+ collectors are tightly coupled to object models, and LLVM is agnostic to object
+ models. Since LLVM is agnostic to object models, it would be inappropriate for
+ LLVM to dictate any particular collector. Instead, LLVM provides a framework for
+ garbage collector implementations in two manners:</p>
+
+ <ul>
+ <li><b>At compile time</b> with <a href="#plugin">collector plugins</a> for
+ the compiler. Collector plugins have ready access to important garbage
+ collector algorithms. Leveraging these tools, it is straightforward to
+ emit type-accurate stack maps for your runtime in as little as ~100 lines of
+ C++ code.</li>
+
+ <li><b>At runtime</b> with <a href="#runtime">suggested runtime
+ interfaces</a>, which allow front-end compilers to support a range of
+ collection runtimes.</li>
+ </ul>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="usage">Using the collectors</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>In general, using a collector implies:</p>
+
+ <ul>
+ <li>Emitting compatible code, including initialization in the main
+ program if necessary.</li>
+ <li>Loading a compiler plugin if the collector is not statically linked with
+ your compiler. For <tt>llc</tt>, use the <tt>-load</tt> option.</li>
+ <li>Selecting the collection algorithm by applying the <tt>gc "..."</tt>
+ attribute to your garbage collected functions, or equivalently with
+ the <tt>setCollector</tt> method.</li>
+ <li>Linking your final executable with the garbage collector runtime.</li>
+ </ul>
+
+ <p>This table summarizes the available runtimes.</p>
+
+ <table>
+ <tr>
+ <th>Collector</th>
+ <th><tt>gc</tt> attribute</th>
+ <th>Linkage</th>
+ <th><tt>gcroot</tt></th>
+ <th><tt>gcread</tt></th>
+ <th><tt>gcwrite</tt></th>
+ </tr>
+ <tr valign="baseline">
+ <td><a href="#semispace">SemiSpace</a></td>
+ <td><tt>gc "shadow-stack"</tt></td>
+ <td>TODO FIXME</td>
+ <td>required</td>
+ <td>optional</td>
+ <td>optional</td>
+ </tr>
+ <tr valign="baseline">
+ <td><a href="#ocaml">Ocaml</a></td>
+ <td><tt>gc "ocaml"</tt></td>
+ <td><i>provided by ocamlopt</i></td>
+ <td>required</td>
+ <td>optional</td>
+ <td>optional</td>
+ </tr>
+ </table>
+
+ <p>The sections for <a href="#intrinsics">Collection intrinsics</a> and
+ <a href="#runtime">Recommended runtime interface</a> detail the interfaces that
+ collectors may require user programs to utilize.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="shadow-stack">ShadowStack - A highly portable collector</a>
+ </div>
+
+ <div class="doc_code"><tt>
+ Collector *llvm::createShadowStackCollector();
+ </tt></div>
+
+ <div class="doc_text">
+
+ <p>The ShadowStack backend is invoked with the <tt>gc "shadow-stack"</tt>
+ function attribute.
+ Unlike many collectors which rely on a cooperative code generator to generate
+ stack maps, this algorithm carefully maintains a linked list of stack root
+ descriptors [<a href="#henderson02">Henderson2002</a>]. This so-called "shadow
+ stack" mirrors the machine stack. Maintaining this data structure is slower
+ than using stack maps, but has a significant portability advantage because it
+ requires no special support from the target code generator.</p>
+
+ <p>The ShadowStack collector does not use read or write barriers, so the user
+ program may use <tt>load</tt> and <tt>store</tt> instead of <tt>llvm.gcread</tt>
+ and <tt>llvm.gcwrite</tt>.</p>
+
+ <p>ShadowStack is a code generator plugin only. It must be paired with a
+ compatible runtime.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="semispace">SemiSpace - A simple copying collector runtime</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The SemiSpace runtime implements the <a href="runtime">suggested
+ runtime interface</a> and is compatible with the ShadowStack backend.</p>
+
+ <p>SemiSpace is a very simple copying collector. When it starts up, it
+ allocates two blocks of memory for the heap. It uses a simple bump-pointer
+ allocator to allocate memory from the first block until it runs out of space.
+ When it runs out of space, it traces through all of the roots of the program,
+ copying blocks to the other half of the memory space.</p>
+
+ <p>This runtime is highly experimental and has not been used in a real project.
+ Enhancements would be welcomed.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="ocaml">Ocaml - An Objective Caml-compatible collector</a>
+ </div>
+
+ <div class="doc_code"><tt>
+ Collector *llvm::createOcamlCollector();
+ </tt></div>
+
+ <div class="doc_text">
+
+ <p>The ocaml backend is invoked with the <tt>gc "ocaml"</tt> function attribute.
+ It supports the
+ <a href="http://caml.inria.fr/">Objective Caml</a> language runtime by emitting
+ a type-accurate stack map in the form of an ocaml 3.10.0-compatible frametable.
+ The linkage requirements are satisfied automatically by the <tt>ocamlopt</tt>
+ compiler when linking an executable.</p>
+
+ <p>The ocaml collector does not use read or write barriers, so the user program
+ may use <tt>load</tt> and <tt>store</tt> instead of <tt>llvm.gcread</tt> and
+ <tt>llvm.gcwrite</tt>.</p>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="core">Core support</a><a name="intrinsics"></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This section describes the garbage collection facilities provided by the
+ <a href="LangRef.html">LLVM intermediate representation</a>.</p>
+
+ <p>These facilities are limited to those strictly necessary for compilation.
+ They are not intended to be a complete interface to any garbage collector.
+ Notably, heap allocation is not among the supplied primitives. A user program
+ will also need to interface with the runtime, using either the
+ <a href="#runtime">suggested runtime interface</a> or another interface
+ specified by the runtime.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a>
+ </div>
+
+ <div class="doc_code"><tt>
+ define <i>ty</i> @<i>name</i>(...) <u>gc "<i>collector</i>"</u> { ...
+ </tt></div>
+
+ <div class="doc_text">
+
+ <p>The <tt>gc</tt> function attribute is used to specify the desired collector
+ algorithm to the compiler. It is equivalent to specifying the collector name
+ programmatically using the <tt>setCollector</tt> method of
+ <tt>Function</tt>.</p>
+
+ <p>Specifying the collector on a per-function basis allows LLVM to link together
+ programs that use different garbage collection algorithms.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="gcroot">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a>
+ </div>
+
+ <div class="doc_code"><tt>
+ void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+ </tt></div>
+
+ <div class="doc_text">
+
+ <p>The <tt>llvm.gcroot</tt> intrinsic is used to inform LLVM of a pointer
+ variable on the stack. The first argument <b>must</b> be a value referring to an alloca instruction
+ or a bitcast of an alloca. The second contains a pointer to metadata that
+ should be associated with the pointer, and <b>must</b> be a constant or global
+ value address. If your target collector uses tags, use a null pointer for
+ metadata.</p>
+
+ <p>Consider the following fragment of Java code:</p>
+
+ <pre>
+ {
+ Object X; // A null-initialized reference to an object
+ ...
+ }
+ </pre>
+
+ <p>This block (which may be located in the middle of a function or in a loop
+ nest), could be compiled to this LLVM code:</p>
+
+ <pre>
+ Entry:
+ ;; In the entry block for the function, allocate the
+ ;; stack space for X, which is an LLVM pointer.
+ %X = alloca %Object*
+
+ ;; Tell LLVM that the stack space is a stack root.
+ ;; Java has type-tags on objects, so we pass null as metadata.
+ %tmp = bitcast %Object** %X to i8**
+ call void @llvm.gcroot(i8** %X, i8* null)
+ ...
+
+ ;; "CodeBlock" is the block corresponding to the start
+ ;; of the scope above.
+ CodeBlock:
+ ;; Java null-initializes pointers.
+ store %Object* null, %Object** %X
+
+ ...
+
+ ;; As the pointer goes out of scope, store a null value into
+ ;; it, to indicate that the value is no longer live.
+ store %Object* null, %Object** %X
+ ...
+ </pre>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="barriers">Reading and writing references in the heap</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Some collectors need to be informed when the mutator (the program that needs
+ garbage collection) either reads a pointer from or writes a pointer to a field
+ of a heap object. The code fragments inserted at these points are called
+ <em>read barriers</em> and <em>write barriers</em>, respectively. The amount of
+ code that needs to be executed is usually quite small and not on the critical
+ path of any computation, so the overall performance impact of the barrier is
+ tolerable.</p>
+
+ <p>Barriers often require access to the <em>object pointer</em> rather than the
+ <em>derived pointer</em> (which is a pointer to the field within the
+ object). Accordingly, these intrinsics take both pointers as separate arguments
+ for completeness. In this snippet, <tt>%object</tt> is the object pointer, and
+ <tt>%derived</tt> is the derived pointer:</p>
+
+ <blockquote><pre>
+ ;; An array type.
+ %class.Array = type { %class.Object, i32, [0 x %class.Object*] }
+ ...
+
+ ;; Load the object pointer from a gcroot.
+ %object = load %class.Array** %object_addr
+
+ ;; Compute the derived pointer.
+ %derived = getelementptr %object, i32 0, i32 2, i32 %n</pre></blockquote>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection">
+ <a name="gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a>
+ </div>
+
+ <div class="doc_code"><tt>
+ void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived)
+ </tt></div>
+
+ <div class="doc_text">
+
+ <p>For write barriers, LLVM provides the <tt>llvm.gcwrite</tt> intrinsic
+ function. It has exactly the same semantics as a non-volatile <tt>store</tt> to
+ the derived pointer (the third argument).</p>
+
+ <p>Many important algorithms require write barriers, including generational
+ and concurrent collectors. Additionally, write barriers could be used to
+ implement reference counting.</p>
+
+ <p>The use of this intrinsic is optional if the target collector does use
+ write barriers. If so, the collector will replace it with the corresponding
+ <tt>store</tt>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection">
+ <a name="gcread">Read barrier: <tt>llvm.gcread</tt></a>
+ </div>
+
+ <div class="doc_code"><tt>
+ i8* @llvm.gcread(i8* %object, i8** %derived)<br>
+ </tt></div>
+
+ <div class="doc_text">
+
+ <p>For read barriers, LLVM provides the <tt>llvm.gcread</tt> intrinsic function.
+ It has exactly the same semantics as a non-volatile <tt>load</tt> from the
+ derived pointer (the second argument).</p>
+
+ <p>Read barriers are needed by fewer algorithms than write barriers, and may
+ have a greater performance impact since pointer reads are more frequent than
+ writes.</p>
+
+ <p>As with <tt>llvm.gcwrite</tt>, a target collector might not require the use
+ of this intrinsic.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="runtime">Recommended runtime interface</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>LLVM specifies the following recommended runtime interface to the garbage
+ collection at runtime. A program should use these interfaces to accomplish the
+ tasks not supported by the intrinsics.</p>
+
+ <p>Unlike the intrinsics, which are integral to LLVM's code generator, there is
+ nothing unique about these interfaces; a front-end compiler and runtime are free
+ to agree to a different specification.</p>
+
+ <p class="doc_warning">Note: This interface is a work in progress.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="initialize">Garbage collector startup and initialization</a>
+ </div>
+
+ <div class="doc_text">
+
+ <div class="doc_code"><tt>
+ void llvm_gc_initialize(unsigned InitialHeapSize);
+ </tt></div>
+
+ <p>
+ The <tt>llvm_gc_initialize</tt> function should be called once before any other
+ garbage collection functions are called. This gives the garbage collector the
+ chance to initialize itself and allocate the heap. The initial heap size to
+ allocate should be specified as an argument.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="allocate">Allocating memory from the GC</a>
+ </div>
+
+ <div class="doc_text">
+
+ <div class="doc_code"><tt>
+ void *llvm_gc_allocate(unsigned Size);
+ </tt></div>
+
+ <p>The <tt>llvm_gc_allocate</tt> function is a global function defined by the
+ garbage collector implementation to allocate memory. It returns a
+ zeroed-out block of memory of the specified size, sufficiently aligned to store
+ any object.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="explicit">Explicit invocation of the garbage collector</a>
+ </div>
+
+ <div class="doc_text">
+
+ <div class="doc_code"><tt>
+ void llvm_gc_collect();
+ </tt></div>
+
+ <p>
+ The <tt>llvm_gc_collect</tt> function is exported by the garbage collector
+ implementations to provide a full collection, even when the heap is not
+ exhausted. This can be used by end-user code as a hint, and may be ignored by
+ the garbage collector.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="traceroots">Tracing GC pointers from the program stack</a>
+ </div>
+
+ <div class="doc_text">
+ <div class="doc_code"><tt>
+ void llvm_cg_walk_gcroots(void (*FP)(void **Root, void *Meta));
+ </tt></div>
+
+ <p>
+ The <tt>llvm_cg_walk_gcroots</tt> function is a function provided by the code
+ generator that iterates through all of the GC roots on the stack, calling the
+ specified function pointer with each record. For each GC root, the address of
+ the pointer and the meta-data (from the <a
+ href="#gcroot"><tt>llvm.gcroot</tt></a> intrinsic) are provided.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="staticroots">Tracing GC pointers from static roots</a>
+ </div>
+
+ <div class="doc_text">
+ TODO
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="plugin">Implementing a collector plugin</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>User code specifies which collector plugin to use with the <tt>gc</tt>
+ function attribute or, equivalently, with the <tt>setCollector</tt> method of
+ <tt>Function</tt>.</p>
+
+ <p>To implement a collector plugin, it is necessary to subclass
+ <tt>llvm::Collector</tt>, which can be accomplished in a few lines of
+ boilerplate code. LLVM's infrastructure provides access to several important
+ algorithms. For an uncontroversial collector, all that remains may be to emit
+ the assembly code for the collector's unique stack map data structure, which
+ might be accomplished in as few as 100 LOC.</p>
+
+ <p>To subclass <tt>llvm::Collector</tt> and register a collector:</p>
+
+ <blockquote><pre>// lib/MyGC/MyGC.cpp - Example LLVM collector plugin
+
+ #include "llvm/CodeGen/Collector.h"
+ #include "llvm/CodeGen/Collectors.h"
+ #include "llvm/CodeGen/CollectorMetadata.h"
+ #include "llvm/Support/Compiler.h"
+
+ using namespace llvm;
+
+ namespace {
+ class VISIBILITY_HIDDEN MyCollector : public Collector {
+ public:
+ MyCollector() {}
+ };
+
+ CollectorRegistry::Add<MyCollector>
+ X("mygc", "My bespoke garbage collector.");
+ }</pre></blockquote>
+
+ <p>Using the LLVM makefiles (like the <a
+ href="http://llvm.org/viewvc/llvm-project/llvm/trunk/projects/sample/">sample
+ project</a>), this can be built into a plugin using a simple makefile:</p>
+
+ <blockquote><pre
+ ># lib/MyGC/Makefile
+
+ LEVEL := ../..
+ LIBRARYNAME = <var>MyGC</var>
+ LOADABLE_MODULE = 1
+
+ include $(LEVEL)/Makefile.common</pre></blockquote>
+
+ <p>Once the plugin is compiled, code using it may be compiled using <tt>llc
+ -load=<var>MyGC.so</var></tt> (though <var>MyGC.so</var> may have some other
+ platform-specific extension):</p>
+
+ <blockquote><pre
+ >$ cat sample.ll
+ define void @f() gc "mygc" {
+ entry:
+ ret void
+ }
+ $ llvm-as < sample.ll | llc -load=MyGC.so</pre></blockquote>
+
+ <p>It is also possible to statically link the collector plugin into tools, such
+ as a language-specific compiler front-end.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="collector-algos">Overview of available features</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The boilerplate collector above does nothing. More specifically:</p>
+
+ <ul>
+ <li><tt>llvm.gcread</tt> calls are replaced with the corresponding
+ <tt>load</tt> instruction.</li>
+ <li><tt>llvm.gcwrite</tt> calls are replaced with the corresponding
+ <tt>store</tt> instruction.</li>
+ <li>No stack map is emitted, and no safe points are added.</li>
+ </ul>
+
+ <p><tt>Collector</tt> provides a range of features through which a plugin
+ collector may do useful work. This matrix summarizes the supported (and planned)
+ features and correlates them with the collection techniques which typically
+ require them.</p>
+
+ <table>
+ <tr>
+ <th>Algorithm</th>
+ <th>Done</th>
+ <th>shadow stack</th>
+ <th>refcount</th>
+ <th>mark-sweep</th>
+ <th>copying</th>
+ <th>incremental</th>
+ <th>threaded</th>
+ <th>concurrent</th>
+ </tr>
+ <tr>
+ <th class="rowhead"><a href="#stack-map">stack map</a></th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead"><a href="#init-roots">initialize roots</a></th>
+ <td>✔</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead">derived pointers</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘*</td>
+ <td>✘*</td>
+ </tr>
+ <tr>
+ <th class="rowhead"><em><a href="#custom">custom lowering</a></em></th>
+ <td>✔</td>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ </tr>
+ <tr>
+ <th class="rowhead indent">gcroot</th>
+ <td>✔</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th class="rowhead indent">gcwrite</th>
+ <td>✔</td>
+ <td></td>
+ <td>✘</td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td></td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead indent">gcread</th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead"><em><a href="#safe-points">safe points</a></em></th>
+ <td></td>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ </tr>
+ <tr>
+ <th class="rowhead indent">in calls</th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead indent">before calls</th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead indent">for loops</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead indent">before escape</th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead">emit code at safe points</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead"><em>output</em></th>
+ <td></td>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ </tr>
+ <tr>
+ <th class="rowhead indent"><a href="#assembly">assembly</a></th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead indent">JIT</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead indent">obj</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead">live analysis</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead">register map</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ </tr>
+ <tr>
+ <td colspan="10">
+ <div><span class="doc_warning">*</span> Derived pointers only pose a
+ hazard to copying collectors.</div>
+ <div><span class="optl">✘</span> in gray denotes a feature which
+ could be utilized if available.</div>
+ </td>
+ </tr>
+ </table>
+
+ <p>To be clear, the collection techniques above are defined as:</p>
+
+ <dl>
+ <dt>Shadow Stack</dt>
+ <dd>The mutator carefully maintains a linked list of stack root
+ descriptors.</dd>
+ <dt>Reference Counting</dt>
+ <dd>The mutator maintains a reference count for each object and frees an
+ object when its count falls to zero.</dd>
+ <dt>Mark-Sweep</dt>
+ <dd>When the heap is exhausted, the collector marks reachable objects starting
+ from the roots, then deallocates unreachable objects in a sweep
+ phase.</dd>
+ <dt>Copying</dt>
+ <dd>As reachability analysis proceeds, the collector copies objects from one
+ heap area to another, compacting them in the process. Copying collectors
+ enable highly efficient "bump pointer" allocation and can improve locality
+ of reference.</dd>
+ <dt>Incremental</dt>
+ <dd>(Including generational collectors.) Incremental collectors generally have
+ all the properties of a copying collector (regardless of whether the
+ mature heap is compacting), but bring the added complexity of requiring
+ write barriers.</dd>
+ <dt>Threaded</dt>
+ <dd>Denotes a multithreaded mutator; the collector must still stop the mutator
+ ("stop the world") before beginning reachability analysis. Stopping a
+ multithreaded mutator is a complicated problem. It generally requires
+ highly platform specific code in the runtime, and the production of
+ carefully designed machine code at safe points.</dd>
+ <dt>Concurrent</dt>
+ <dd>In this technique, the mutator and the collector run concurrently, with
+ the goal of eliminating pause times. In a <em>cooperative</em> collector,
+ the mutator further aids with collection should a pause occur, allowing
+ collection to take advantage of multiprocessor hosts. The "stop the world"
+ problem of threaded collectors is generally still present to a limited
+ extent. Sophisticated marking algorithms are necessary. Read barriers may
+ be necessary.</dd>
+ </dl>
+
+ <p>As the matrix indicates, LLVM's garbage collection infrastructure is already
+ suitable for a wide variety of collectors, but does not currently extend to
+ multithreaded programs. This will be added in the future as there is
+ interest.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="stack-map">Computing stack maps</a>
+ </div>
+
+ <div class="doc_text">
+
+ <blockquote><pre
+ >for (iterator I = begin(), E = end(); I != E; ++I) {
+ CollectorMetadata *MD = *I;
+ unsigned FrameSize = MD->getFrameSize();
+ size_t RootCount = MD->roots_size();
+
+ for (CollectorMetadata::roots_iterator RI = MD->roots_begin(),
+ RE = MD->roots_end();
+ RI != RE; ++RI) {
+ int RootNum = RI->Num;
+ int RootStackOffset = RI->StackOffset;
+ Constant *RootMetadata = RI->Metadata;
+ }
+ }</pre></blockquote>
+
+ <p>LLVM automatically computes a stack map. All a <tt>Collector</tt> needs to do
+ is access it using <tt>CollectorMetadata::roots_begin()</tt> and
+ -<tt>end()</tt>. If the <tt>llvm.gcroot</tt> intrinsic is eliminated before code
+ generation by a custom lowering pass, LLVM's stack map will be empty.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="init-roots">Initializing roots to null: <tt>InitRoots</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <blockquote><pre
+ >MyCollector::MyCollector() {
+ InitRoots = true;
+ }</pre></blockquote>
+
+ <p>When set, LLVM will automatically initialize each root to <tt>null</tt> upon
+ entry to the function. This prevents the reachability analysis from finding
+ uninitialized values in stack roots at runtime, which will almost certainly
+ cause it to segfault. This initialization occurs before custom lowering, so the
+ two may be used together.</p>
+
+ <p>Since LLVM does not yet compute liveness information, this feature should be
+ used by all collectors which do not custom lower <tt>llvm.gcroot</tt>, and even
+ some that do.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="custom">Custom lowering of intrinsics: <tt>CustomRoots</tt>,
+ <tt>CustomReadBarriers</tt>, and <tt>CustomWriteBarriers</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>For collectors with barriers or unusual treatment of stack roots, these
+ flags allow the collector to perform any required transformation on the LLVM
+ IR:</p>
+
+ <blockquote><pre
+ >class MyCollector : public Collector {
+ public:
+ MyCollector() {
+ CustomRoots = true;
+ CustomReadBarriers = true;
+ CustomWriteBarriers = true;
+ }
+
+ virtual bool initializeCustomLowering(Module &M);
+ virtual bool performCustomLowering(Function &F);
+ };</pre></blockquote>
+
+ <p>If any of these flags are set, then LLVM suppresses its default lowering for
+ the corresponding intrinsics and instead passes them on to a custom lowering
+ pass specified by the collector.</p>
+
+ <p>LLVM's default action for each intrinsic is as follows:</p>
+
+ <ul>
+ <li><tt>llvm.gcroot</tt>: Pass through to the code generator to generate a
+ stack map.</li>
+ <li><tt>llvm.gcread</tt>: Substitute a <tt>load</tt> instruction.</li>
+ <li><tt>llvm.gcwrite</tt>: Substitute a <tt>store</tt> instruction.</li>
+ </ul>
+
+ <p>If <tt>CustomReadBarriers</tt> or <tt>CustomWriteBarriers</tt> are specified,
+ then <tt>performCustomLowering</tt> <strong>must</strong> eliminate the
+ corresponding barriers.</p>
+
+ <p><tt>performCustomLowering</tt>, must comply with the same restrictions as <a
+ href="WritingAnLLVMPass.html#runOnFunction"><tt>runOnFunction</tt></a>, and
+ that <tt>initializeCustomLowering</tt> has the same semantics as <a
+ href="WritingAnLLVMPass.html#doInitialization_mod"><tt>doInitialization(Module
+ &)</tt></a>.</p>
+
+ <p>The following can be used as a template:</p>
+
+ <blockquote><pre
+ >#include "llvm/Module.h"
+ #include "llvm/IntrinsicInst.h"
+
+ bool MyCollector::initializeCustomLowering(Module &M) {
+ return false;
+ }
+
+ bool MyCollector::performCustomLowering(Function &F) {
+ bool MadeChange = false;
+
+ for (Function::iterator BB = F.begin(), E = F.end(); BB != E; ++BB)
+ for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; )
+ if (IntrinsicInst *CI = dyn_cast<IntrinsicInst>(II++))
+ if (Function *F = CI->getCalledFunction())
+ switch (F->getIntrinsicID()) {
+ case Intrinsic::gcwrite:
+ // Handle llvm.gcwrite.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ case Intrinsic::gcread:
+ // Handle llvm.gcread.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ case Intrinsic::gcroot:
+ // Handle llvm.gcroot.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ }
+
+ return MadeChange;
+ }</pre></blockquote>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="safe-points">Generating safe points: <tt>NeededSafePoints</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM can compute four kinds of safe points:</p>
+
+ <blockquote><pre
+ >namespace GC {
+ /// PointKind - The type of a collector-safe point.
+ ///
+ enum PointKind {
+ Loop, //< Instr is a loop (backwards branch).
+ Return, //< Instr is a return instruction.
+ PreCall, //< Instr is a call instruction.
+ PostCall //< Instr is the return address of a call.
+ };
+ }</pre></blockquote>
+
+ <p>A collector can request any combination of the four by setting the
+ <tt>NeededSafePoints</tt> mask:</p>
+
+ <blockquote><pre
+ >MyCollector::MyCollector() {
+ NeededSafePoints = 1 << GC::Loop
+ | 1 << GC::Return
+ | 1 << GC::PreCall
+ | 1 << GC::PostCall;
+ }</pre></blockquote>
+
+ <p>It can then use the following routines to access safe points.</p>
+
+ <blockquote><pre
+ >for (iterator I = begin(), E = end(); I != E; ++I) {
+ CollectorMetadata *MD = *I;
+ size_t PointCount = MD->size();
+
+ for (CollectorMetadata::iterator PI = MD->begin(),
+ PE = MD->end(); PI != PE; ++PI) {
+ GC::PointKind PointKind = PI->Kind;
+ unsigned PointNum = PI->Num;
+ }
+ }
+ </pre></blockquote>
+
+ <p>Almost every collector requires <tt>PostCall</tt> safe points, since these
+ correspond to the moments when the function is suspended during a call to a
+ subroutine.</p>
+
+ <p>Threaded programs generally require <tt>Loop</tt> safe points to guarantee
+ that the application will reach a safe point within a bounded amount of time,
+ even if it is executing a long-running loop which contains no function
+ calls.</p>
+
+ <p>Threaded collectors may also require <tt>Return</tt> and <tt>PreCall</tt>
+ safe points to implement "stop the world" techniques using self-modifying code,
+ where it is important that the program not exit the function without reaching a
+ safe point (because only the topmost function has been patched).</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="assembly">Emitting assembly code:
+ <tt>beginAssembly</tt> and <tt>finishAssembly</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM allows a collector to print arbitrary assembly code before and after
+ the rest of a module's assembly code. From the latter callback, the collector
+ can print stack maps built by the code generator.</p>
+
+ <p>Note that LLVM does not currently have analogous APIs to support code
+ generation in the JIT, nor using the object writers.</p>
+
+ <blockquote><pre
+ >class MyCollector : public Collector {
+ public:
+ virtual void beginAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI);
+
+ virtual void finishAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI);
+ }</pre></blockquote>
+
+ <p>The collector should use <tt>AsmPrinter</tt> and <tt>TargetAsmInfo</tt> to
+ print portable assembly code to the <tt>std::ostream</tt>. The collector itself
+ contains the stack map for the entire module, and may access the
+ <tt>CollectorMetadata</tt> using its own <tt>begin()</tt> and <tt>end()</tt>
+ methods. Here's a realistic example:</p>
+
+ <blockquote><pre
+ >#include "llvm/CodeGen/AsmPrinter.h"
+ #include "llvm/Function.h"
+ #include "llvm/Target/TargetMachine.h"
+ #include "llvm/Target/TargetData.h"
+ #include "llvm/Target/TargetAsmInfo.h"
+
+ void MyCollector::beginAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI) {
+ // Nothing to do.
+ }
+
+ void MyCollector::finishAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI) {
+ // Set up for emitting addresses.
+ const char *AddressDirective;
+ int AddressAlignLog;
+ if (AP.TM.getTargetData()->getPointerSize() == sizeof(int32_t)) {
+ AddressDirective = TAI.getData32bitsDirective();
+ AddressAlignLog = 2;
+ } else {
+ AddressDirective = TAI.getData64bitsDirective();
+ AddressAlignLog = 3;
+ }
+
+ // Put this in the data section.
+ AP.SwitchToDataSection(TAI.getDataSection());
+
+ // For each function...
+ for (iterator FI = begin(), FE = end(); FI != FE; ++FI) {
+ CollectorMetadata &MD = **FI;
+
+ // Emit this data structure:
+ //
+ // struct {
+ // int32_t PointCount;
+ // struct {
+ // void *SafePointAddress;
+ // int32_t LiveCount;
+ // int32_t LiveOffsets[LiveCount];
+ // } Points[PointCount];
+ // } __gcmap_<FUNCTIONNAME>;
+
+ // Align to address width.
+ AP.EmitAlignment(AddressAlignLog);
+
+ // Emit the symbol by which the stack map can be found.
+ std::string Symbol;
+ Symbol += TAI.getGlobalPrefix();
+ Symbol += "__gcmap_";
+ Symbol += MD.getFunction().getName();
+ if (const char *GlobalDirective = TAI.getGlobalDirective())
+ OS << GlobalDirective << Symbol << "\n";
+ OS << TAI.getGlobalPrefix() << Symbol << ":\n";
+
+ // Emit PointCount.
+ AP.EmitInt32(MD.size());
+ AP.EOL("safe point count");
+
+ // And each safe point...
+ for (CollectorMetadata::iterator PI = MD.begin(),
+ PE = MD.end(); PI != PE; ++PI) {
+ // Align to address width.
+ AP.EmitAlignment(AddressAlignLog);
+
+ // Emit the address of the safe point.
+ OS << AddressDirective
+ << TAI.getPrivateGlobalPrefix() << "label" << PI->Num;
+ AP.EOL("safe point address");
+
+ // Emit the stack frame size.
+ AP.EmitInt32(MD.getFrameSize());
+ AP.EOL("stack frame size");
+
+ // Emit the number of live roots in the function.
+ AP.EmitInt32(MD.live_size(PI));
+ AP.EOL("live root count");
+
+ // And for each live root...
+ for (CollectorMetadata::live_iterator LI = MD.live_begin(PI),
+ LE = MD.live_end(PI);
+ LI != LE; ++LI) {
+ // Print its offset within the stack frame.
+ AP.EmitInt32(LI->StackOffset);
+ AP.EOL("stack offset");
+ }
+ }
+ }
+ }
+ </pre></blockquote>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="runtime-impl">Implementing a collector runtime</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Implementing a garbage collector for LLVM is fairly straightforward. The
+ LLVM garbage collectors are provided in a form that makes them easy to link into
+ the language-specific runtime that a language front-end would use. They require
+ functionality from the language-specific runtime to get information about <a
+ href="#gcdescriptors">where pointers are located in heap objects</a>.</p>
+
+ <p>The implementation must include the
+ <a href="#allocate"><tt>llvm_gc_allocate</tt></a> and
+ <a href="#explicit"><tt>llvm_gc_collect</tt></a> functions. To do this, it will
+ probably have to <a href="#traceroots">trace through the roots
+ from the stack</a> and understand the <a href="#gcdescriptors">GC descriptors
+ for heap objects</a>. Luckily, there are some <a href="#usage">example
+ implementations</a> available.
+ </p>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="gcdescriptors">Tracing GC pointers from heap objects</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ The three most common ways to keep track of where pointers live in heap objects
+ are (listed in order of space overhead required):</p>
+
+ <ol>
+ <li>In languages with polymorphic objects, pointers from an object header are
+ usually used to identify the GC pointers in the heap object. This is common for
+ object-oriented languages like Self, Smalltalk, Java, or C#.</li>
+
+ <li>If heap objects are not polymorphic, often the "shape" of the heap can be
+ determined from the roots of the heap or from some other meta-data [<a
+ href="#appel89">Appel89</a>, <a href="#goldberg91">Goldberg91</a>, <a
+ href="#tolmach94">Tolmach94</a>]. In this case, the garbage collector can
+ propagate the information around from meta data stored with the roots. This
+ often eliminates the need to have a header on objects in the heap. This is
+ common in the ML family.</li>
+
+ <li>If all heap objects have pointers in the same locations, or pointers can be
+ distinguished just by looking at them (e.g., the low order bit is clear), no
+ book-keeping is needed at all. This is common for Lisp-like languages.</li>
+ </ol>
+
+ <p>The LLVM garbage collectors are capable of supporting all of these styles of
+ language, including ones that mix various implementations. To do this, it
+ allows the source-language to associate meta-data with the <a
+ href="#gcroot">stack roots</a>, and the heap tracing routines can propagate the
+ information. In addition, LLVM allows the front-end to extract GC information
+ in any form from a specific object pointer (this supports situations #1 and #3).
+ </p>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="references">References</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p><a name="appel89">[Appel89]</a> Runtime Tags Aren't Necessary. Andrew
+ W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.</p>
+
+ <p><a name="goldberg91">[Goldberg91]</a> Tag-free garbage collection for
+ strongly typed programming languages. Benjamin Goldberg. ACM SIGPLAN
+ PLDI'91.</p>
+
+ <p><a name="tolmach94">[Tolmach94]</a> Tag-free garbage collection using
+ explicit type parameters. Andrew Tolmach. Proceedings of the 1994 ACM
+ conference on LISP and functional programming.</p>
+
+ <p><a name="henderson02">[Henderson2002]</a> <a
+ href="http://citeseer.ist.psu.edu/henderson02accurate.html">
+ Accurate Garbage Collection in an Uncooperative Environment</a>.
+ Fergus Henderson. International Symposium on Memory Management 2002.</p>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/GetElementPtr.html
diff -c /dev/null llvm-www/releases/2.3/docs/GetElementPtr.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/GetElementPtr.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,370 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>The Often Misunderstood GEP Instruction</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ <style type="text/css">
+ TABLE { text-align: left; border: 1px solid black; border-collapse: collapse; margin: 0 0 0 0; }
+ </style>
+ </head>
+ <body>
+
+ <div class="doc_title">
+ The Often Misunderstood GEP Instruction
+ </div>
+
+ <ol>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#questions">The Questions</a>
+ <ol>
+ <li><a href="#extra_index">Why is the extra 0 index required?</a></li>
+ <li><a href="#deref">What is dereferenced by GEP?</a></li>
+ <li><a href="#firstptr">Why can you index through the first pointer but not
+ subsequent ones?</a></li>
+ <li><a href="#lead0">Why don't GEP x,0,0,1 and GEP x,1 alias? </a></li>
+ <li><a href="#trail0">Why do GEP x,1,0,0 and GEP x,1 alias? </a></li>
+ </ol></li>
+ <li><a href="#summary">Summary</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by: <a href="mailto:rspencer at reidspencer.com">Reid Spencer</a>.</p>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="intro"><b>Introduction</b></a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This document seeks to dispel the mystery and confusion surrounding LLVM's
+ GetElementPtr (GEP) instruction. Questions about the wiley GEP instruction are
+ probably the most frequently occuring questions once a developer gets down to
+ coding with LLVM. Here we lay out the sources of confusion and show that the
+ GEP instruction is really quite simple.
+ </p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="questions"><b>The Questions</b></a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>When people are first confronted with the GEP instruction, they tend to
+ relate it to known concepts from other programming paradigms, most notably C
+ array indexing and field selection. However, GEP is a little different and
+ this leads to the following questions; all of which are answered in the
+ following sections.</p>
+ <ol>
+ <li><a href="#firstptr">What is the first index of the GEP instruction?</a>
+ </li>
+ <li><a href="#extra_index">Why is the extra 0 index required?</a></li>
+ <li><a href="#deref">What is dereferenced by GEP?</a></li>
+ <li><a href="#lead0">Why don't GEP x,0,0,1 and GEP x,1 alias? </a></li>
+ <li><a href="#trail0">Why do GEP x,1,0,0 and GEP x,1 alias? </a></li>
+ </ol>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_subsection">
+ <a name="firstptr"><b>What is the first index of the GEP instruction?</b></a>
+ </div>
+ <div class="doc_text">
+ <p>Quick answer: The index stepping through the first operand.</p>
+ <p>The confusion with the first index usually arises from thinking about
+ the GetElementPtr instruction as if it was a C index operator. They aren't the
+ same. For example, when we write, in "C":</p>
+
+ <div class="doc_code">
+ <pre>
+ AType *Foo;
+ ...
+ X = &Foo->F;
+ </pre>
+ </div>
+
+ <p>it is natural to think that there is only one index, the selection of the
+ field <tt>F</tt>. However, in this example, <tt>Foo</tt> is a pointer. That
+ pointer must be indexed explicitly in LLVM. C, on the other hand, indexs
+ through it transparently. To arrive at the same address location as the C
+ code, you would provide the GEP instruction with two index operands. The
+ first operand indexes through the pointer; the second operand indexes the
+ field <tt>F</tt> of the structure, just as if you wrote:</p>
+
+ <div class="doc_code">
+ <pre>
+ X = &Foo[0].F;
+ </pre>
+ </div>
+
+ <p>Sometimes this question gets rephrased as:</p>
+ <blockquote><p><i>Why is it okay to index through the first pointer, but
+ subsequent pointers won't be dereferenced?</i></p></blockquote>
+ <p>The answer is simply because memory does not have to be accessed to
+ perform the computation. The first operand to the GEP instruction must be a
+ value of a pointer type. The value of the pointer is provided directly to
+ the GEP instruction as an operand without any need for accessing memory. It
+ must, therefore be indexed and requires an index operand. Consider this
+ example:</p>
+
+ <div class="doc_code">
+ <pre>
+ struct munger_struct {
+ int f1;
+ int f2;
+ };
+ void munge(struct munger_struct *P) {
+ P[0].f1 = P[1].f1 + P[2].f2;
+ }
+ ...
+ munger_struct Array[3];
+ ...
+ munge(Array);
+ </pre>
+ </div>
+
+ <p>In this "C" example, the front end compiler (llvm-gcc) will generate three
+ GEP instructions for the three indices through "P" in the assignment
+ statement. The function argument <tt>P</tt> will be the first operand of each
+ of these GEP instructions. The second operand indexes through that pointer.
+ The third operand will be the field offset into the
+ <tt>struct munger_struct</tt> type, for either the <tt>f1</tt> or
+ <tt>f2</tt> field. So, in LLVM assembly the <tt>munge</tt> function looks
+ like:</p>
+
+ <div class="doc_code">
+ <pre>
+ void %munge(%struct.munger_struct* %P) {
+ entry:
+ %tmp = getelementptr %struct.munger_struct* %P, i32 1, i32 0
+ %tmp = load i32* %tmp
+ %tmp6 = getelementptr %struct.munger_struct* %P, i32 2, i32 1
+ %tmp7 = load i32* %tmp6
+ %tmp8 = add i32 %tmp7, %tmp
+ %tmp9 = getelementptr %struct.munger_struct* %P, i32 0, i32 0
+ store i32 %tmp8, i32* %tmp9
+ ret void
+ }
+ </pre>
+ </div>
+
+ <p>In each case the first operand is the pointer through which the GEP
+ instruction starts. The same is true whether the first operand is an
+ argument, allocated memory, or a global variable. </p>
+ <p>To make this clear, let's consider a more obtuse example:</p>
+
+ <div class="doc_code">
+ <pre>
+ %MyVar = unintialized global i32
+ ...
+ %idx1 = getelementptr i32* %MyVar, i64 0
+ %idx2 = getelementptr i32* %MyVar, i64 1
+ %idx3 = getelementptr i32* %MyVar, i64 2
+ </pre>
+ </div>
+
+ <p>These GEP instructions are simply making address computations from the
+ base address of <tt>MyVar</tt>. They compute, as follows (using C syntax):
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ idx1 = (char*) &MyVar + 0
+ idx2 = (char*) &MyVar + 4
+ idx3 = (char*) &MyVar + 8
+ </pre>
+ </div>
+
+ <p>Since the type <tt>i32</tt> is known to be four bytes long, the indices
+ 0, 1 and 2 translate into memory offsets of 0, 4, and 8, respectively. No
+ memory is accessed to make these computations because the address of
+ <tt>%MyVar</tt> is passed directly to the GEP instructions.</p>
+ <p>The obtuse part of this example is in the cases of <tt>%idx2</tt> and
+ <tt>%idx3</tt>. They result in the computation of addresses that point to
+ memory past the end of the <tt>%MyVar</tt> global, which is only one
+ <tt>i32</tt> long, not three <tt>i32</tt>s long. While this is legal in LLVM,
+ it is inadvisable because any load or store with the pointer that results
+ from these GEP instructions would produce undefined results.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_subsection">
+ <a name="extra_index"><b>Why is the extra 0 index required?</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>Quick answer: there are no superfluous indices.</p>
+ <p>This question arises most often when the GEP instruction is applied to a
+ global variable which is always a pointer type. For example, consider
+ this:</p>
+
+ <div class="doc_code">
+ <pre>
+ %MyStruct = uninitialized global { float*, i32 }
+ ...
+ %idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
+ </pre>
+ </div>
+
+ <p>The GEP above yields an <tt>i32*</tt> by indexing the <tt>i32</tt> typed
+ field of the structure <tt>%MyStruct</tt>. When people first look at it, they
+ wonder why the <tt>i64 0</tt> index is needed. However, a closer inspection
+ of how globals and GEPs work reveals the need. Becoming aware of the following
+ facts will dispell the confusion:</p>
+ <ol>
+ <li>The type of <tt>%MyStruct</tt> is <i>not</i> <tt>{ float*, i32 }</tt>
+ but rather <tt>{ float*, i32 }*</tt>. That is, <tt>%MyStruct</tt> is a
+ pointer to a structure containing a pointer to a <tt>float</tt> and an
+ <tt>i32</tt>.</li>
+ <li>Point #1 is evidenced by noticing the type of the first operand of
+ the GEP instruction (<tt>%MyStruct</tt>) which is
+ <tt>{ float*, i32 }*</tt>.</li>
+ <li>The first index, <tt>i64 0</tt> is required to step over the global
+ variable <tt>%MyStruct</tt>. Since the first argument to the GEP
+ instruction must always be a value of pointer type, the first index
+ steps through that pointer. A value of 0 means 0 elements offset from that
+ pointer.</li>
+ <li>The second index, <tt>i32 1</tt> selects the second field of the
+ structure (the <tt>i32</tt>). </li>
+ </ol>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_subsection">
+ <a name="deref"><b>What is dereferenced by GEP?</b></a>
+ </div>
+ <div class="doc_text">
+ <p>Quick answer: nothing.</p>
+ <p>The GetElementPtr instruction dereferences nothing. That is, it doesn't
+ access memory in any way. That's what the Load and Store instructions are for.
+ GEP is only involved in the computation of addresses. For example, consider
+ this:</p>
+
+ <div class="doc_code">
+ <pre>
+ %MyVar = uninitialized global { [40 x i32 ]* }
+ ...
+ %idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+ </pre>
+ </div>
+
+ <p>In this example, we have a global variable, <tt>%MyVar</tt> that is a
+ pointer to a structure containing a pointer to an array of 40 ints. The
+ GEP instruction seems to be accessing the 18th integer of the structure's
+ array of ints. However, this is actually an illegal GEP instruction. It
+ won't compile. The reason is that the pointer in the structure <i>must</i>
+ be dereferenced in order to index into the array of 40 ints. Since the
+ GEP instruction never accesses memory, it is illegal.</p>
+ <p>In order to access the 18th integer in the array, you would need to do the
+ following:</p>
+
+ <div class="doc_code">
+ <pre>
+ %idx = getelementptr { [40 x i32]* }* %, i64 0, i32 0
+ %arr = load [40 x i32]** %idx
+ %idx = getelementptr [40 x i32]* %arr, i64 0, i64 17
+ </pre>
+ </div>
+
+ <p>In this case, we have to load the pointer in the structure with a load
+ instruction before we can index into the array. If the example was changed
+ to:</p>
+
+ <div class="doc_code">
+ <pre>
+ %MyVar = uninitialized global { [40 x i32 ] }
+ ...
+ %idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
+ </pre>
+ </div>
+
+ <p>then everything works fine. In this case, the structure does not contain a
+ pointer and the GEP instruction can index through the global variable,
+ into the first field of the structure and access the 18th <tt>i32</tt> in the
+ array there.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_subsection">
+ <a name="lead0"><b>Why don't GEP x,0,0,1 and GEP x,1 alias?</b></a>
+ </div>
+ <div class="doc_text">
+ <p>Quick Answer: They compute different address locations.</p>
+ <p>If you look at the first indices in these GEP
+ instructions you find that they are different (0 and 1), therefore the address
+ computation diverges with that index. Consider this example:</p>
+
+ <div class="doc_code">
+ <pre>
+ %MyVar = global { [10 x i32 ] }
+ %idx1 = getlementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
+ %idx2 = getlementptr { [10 x i32 ] }* %MyVar, i64 1
+ </pre>
+ </div>
+
+ <p>In this example, <tt>idx1</tt> computes the address of the second integer
+ in the array that is in the structure in %MyVar, that is <tt>MyVar+4</tt>. The
+ type of <tt>idx1</tt> is <tt>i32*</tt>. However, <tt>idx2</tt> computes the
+ address of <i>the next</i> structure after <tt>%MyVar</tt>. The type of
+ <tt>idx2</tt> is <tt>{ [10 x i32] }*</tt> and its value is equivalent
+ to <tt>MyVar + 40</tt> because it indexes past the ten 4-byte integers
+ in <tt>MyVar</tt>. Obviously, in such a situation, the pointers don't
+ alias.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_subsection">
+ <a name="trail0"><b>Why do GEP x,1,0,0 and GEP x,1 alias?</b></a>
+ </div>
+ <div class="doc_text">
+ <p>Quick Answer: They compute the same address location.</p>
+ <p>These two GEP instructions will compute the same address because indexing
+ through the 0th element does not change the address. However, it does change
+ the type. Consider this example:</p>
+
+ <div class="doc_code">
+ <pre>
+ %MyVar = global { [10 x i32 ] }
+ %idx1 = getlementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
+ %idx2 = getlementptr { [10 x i32 ] }* %MyVar, i64 1
+ </pre>
+ </div>
+
+ <p>In this example, the value of <tt>%idx1</tt> is <tt>%MyVar+40</tt> and
+ its type is <tt>i32*</tt>. The value of <tt>%idx2</tt> is also
+ <tt>MyVar+40</tt> but its type is <tt>{ [10 x i32] }*</tt>.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="summary"><b>Summary</b></a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>In summary, here's some things to always remember about the GetElementPtr
+ instruction:</p>
+ <ol>
+ <li>The GEP instruction never accesses memory, it only provides pointer
+ computations.</li>
+ <li>The first operand to the GEP instruction is always a pointer and it must
+ be indexed.</li>
+ <li>There are no superfluous indices for the GEP instruction.</li>
+ <li>Trailing zero indices are superfluous for pointer aliasing, but not for
+ the types of the pointers.</li>
+ <li>Leading zero indices are not superfluous for pointer aliasing nor the
+ types of the pointers.</li>
+ </ol>
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br/>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/GettingStarted.html
diff -c /dev/null llvm-www/releases/2.3/docs/GettingStarted.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/GettingStarted.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,1649 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Getting Started with LLVM System</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">
+ Getting Started with the LLVM System
+ </div>
+
+ <ul>
+ <li><a href="#overview">Overview</a>
+ <li><a href="#quickstart">Getting Started Quickly (A Summary)</a>
+ <li><a href="#requirements">Requirements</a>
+ <ol>
+ <li><a href="#hardware">Hardware</a></li>
+ <li><a href="#software">Software</a></li>
+ <li><a href="#brokengcc">Broken versions of GCC and other tools</a></li>
+ </ol></li>
+
+ <li><a href="#starting">Getting Started with LLVM</a>
+ <ol>
+ <li><a href="#terminology">Terminology and Notation</a></li>
+ <li><a href="#environment">Setting Up Your Environment</a></li>
+ <li><a href="#unpack">Unpacking the LLVM Archives</a></li>
+ <li><a href="#checkout">Checkout LLVM from Subversion</a></li>
+ <li><a href="#installcf">Install the GCC Front End</a></li>
+ <li><a href="#config">Local LLVM Configuration</a></li>
+ <li><a href="#compile">Compiling the LLVM Suite Source Code</a></li>
+ <li><a href="#cross-compile">Cross-Compiling LLVM</a></li>
+ <li><a href="#objfiles">The Location of LLVM Object Files</a></li>
+ <li><a href="#optionalconfig">Optional Configuration Items</a></li>
+ </ol></li>
+
+ <li><a href="#layout">Program layout</a>
+ <ol>
+ <li><a href="#examples"><tt>llvm/examples</tt></a></li>
+ <li><a href="#include"><tt>llvm/include</tt></a></li>
+ <li><a href="#lib"><tt>llvm/lib</tt></a></li>
+ <li><a href="#projects"><tt>llvm/projects</tt></a></li>
+ <li><a href="#runtime"><tt>llvm/runtime</tt></a></li>
+ <li><a href="#test"><tt>llvm/test</tt></a></li>
+ <li><a href="#llvmtest"><tt>llvm-test</tt></a></li>
+ <li><a href="#tools"><tt>llvm/tools</tt></a></li>
+ <li><a href="#utils"><tt>llvm/utils</tt></a></li>
+ <li><a href="#win32"><tt>llvm/win32</tt></a></li>
+ </ol></li>
+
+ <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
+ <ol>
+ <li><a href="#tutorial4">Example with llvm-gcc4</a></li>
+ </ol>
+ <li><a href="#problems">Common Problems</a>
+ <li><a href="#links">Links</a>
+ </ul>
+
+ <div class="doc_author">
+ <p>Written by:
+ <a href="mailto:criswell at uiuc.edu">John Criswell</a>,
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a>,
+ <a href="http://misha.brukman.net">Misha Brukman</a>,
+ <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>, and
+ <a href="mailto:gshi1 at uiuc.edu">Guochun Shi</a>.
+ </p>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="overview"><b>Overview</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Welcome to LLVM! In order to get started, you first need to know some
+ basic information.</p>
+
+ <p>First, LLVM comes in two pieces. The first piece is the LLVM suite. This
+ contains all of the tools, libraries, and header files needed to use the low
+ level virtual machine. It contains an assembler, disassembler, bitcode
+ analyzer and bitcode optimizer. It also contains a test suite that can be
+ used to test the LLVM tools and the GCC front end.</p>
+
+ <p>The second piece is the GCC front end. This component provides a version of
+ GCC that compiles C and C++ code into LLVM bitcode. Currently, the GCC front
+ end uses the GCC parser to convert code to LLVM. Once
+ compiled into LLVM bitcode, a program can be manipulated with the LLVM tools
+ from the LLVM suite.</p>
+
+ <p>
+ There is a third, optional piece called llvm-test. It is a suite of programs
+ with a testing harness that can be used to further test LLVM's functionality
+ and performance.
+ </p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Here's the short story for getting up and running quickly with LLVM:</p>
+
+ <ol>
+ <li>Read the documentation.</li>
+ <li>Read the documentation.</li>
+ <li>Remember that you were warned twice about reading the documentation.</li>
+ <li>Install the llvm-gcc4.2 front end if you intend to compile C or C++:
+ <ol>
+ <li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt></li>
+ <li><tt>gunzip --stdout llvm-gcc.<i>platform</i>.tar.gz | tar -xvf -</tt>
+ </li>
+ <ul><li>If the binary extension is ".bz" use bunzip2 instead of gunzip.</li>
+ </ul>
+ <li>Add llvm-gcc's "bin" directory to your PATH variable.</li>
+ </ol></li>
+
+ <li>Get the LLVM Source Code
+ <ul>
+ <li>With the distributed files (or use <a href="#checkout">SVN</a>):
+ <ol>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
+ <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
+ </ol></li>
+
+ </ul></li>
+
+ <li><b>[Optional]</b> Get the Test Suite Source Code
+ <ul>
+ <li>With the distributed files (or use <a href="#checkout">SVN</a>):
+ <ol>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
+ <li><tt>cd llvm/projects</tt>
+ <li><tt>gunzip --stdout llvm-test-<i>version</i>.tar.gz | tar -xvf -</tt>
+ </ol></li>
+
+ </ul></li>
+
+
+ <li>Configure the LLVM Build Environment
+ <ol>
+ <li><tt>cd <i>where-you-want-to-build-llvm</i></tt></li>
+ <li><tt><i>/path/to/llvm/</i>configure [options]</tt><br>
+ Some common options:
+
+ <ul>
+ <li><tt>--prefix=<i>directory</i></tt>
+ <p>Specify for <i>directory</i> the full pathname of where you
+ want the LLVM tools and libraries to be installed (default
+ <tt>/usr/local</tt>).</p></li>
+ <li><tt>--with-llvmgccdir=<i>directory</i></tt>
+ <p>Optionally, specify for <i>directory</i> the full pathname of the
+ C/C++ front end installation to use with this LLVM configuration. If
+ not specified, the PATH will be searched.</p></li>
+ <li><tt>--enable-spec2000=<i>directory</i></tt>
+ <p>Enable the SPEC2000 benchmarks for testing. The SPEC2000
+ benchmarks should be available in
+ <tt><i>directory</i></tt>.</p></li>
+ </ul>
+ </ol></li>
+
+ <li>Build the LLVM Suite:
+ <ol>
+ <li><tt>gmake -k |& tee gnumake.out
+ # this is csh or tcsh syntax</tt></li>
+ <li>If you get an "internal compiler error (ICE)" or test failures, see
+ <a href="#brokengcc">below</a>.</li>
+ </ol>
+
+ </ol>
+
+ <p>Consult the <a href="#starting">Getting Started with LLVM</a> section for
+ detailed information on configuring and compiling LLVM. See <a
+ href="#environment">Setting Up Your Environment</a> for tips that simplify
+ working with the GCC front end and LLVM tools. Go to <a href="#layout">Program
+ Layout</a> to learn about the layout of the source code tree.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="requirements"><b>Requirements</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Before you begin to use the LLVM system, review the requirements given below.
+ This may save you some trouble by knowing ahead of time what hardware and
+ software you will need.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="hardware"><b>Hardware</b></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM is known to work on the following platforms:</p>
+
+ <table cellpadding="3" summary="Known LLVM platforms">
+ <tr>
+ <th>OS</th>
+ <th>Arch</th>
+ <th>Compilers</th>
+ </tr>
+ <tr>
+ <td>Linux</td>
+ <td>x86<sup><a href="#pf_1">1</a></sup></td>
+ <td>GCC</td>
+ </tr>
+ <tr>
+ <td>Solaris</td>
+ <td>V9 (Ultrasparc)</td>
+ <td>GCC</td>
+ </tr>
+ <tr>
+ <td>FreeBSD</td>
+ <td>x86<sup><a href="#pf_1">1</a></sup></td>
+ <td>GCC</td>
+ </tr>
+ <tr>
+ <td>MacOS X<sup><a href="#pf_2">2</a></sup></td>
+ <td>PowerPC</td>
+ <td>GCC</td>
+ </tr>
+ <tr>
+ <td>MacOS X<sup><a href="#pf_2">2</a>,<a href="#pf_9">9</a></sup></td>
+ <td>x86</td>
+ <td>GCC</td>
+
+ </tr>
+ <tr>
+ <td>Cygwin/Win32</td>
+ <td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_8">8</a></sup></td>
+ <td>GCC 3.4.X, binutils 2.15</td>
+ </tr>
+ <tr>
+ <td>MinGW/Win32</td>
+ <td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_6">6</a>,<a href="#pf_8">8</a></sup></td>
+ <td>GCC 3.4.X, binutils 2.15</td>
+ </tr>
+ <tr>
+ <td>Linux</td>
+ <td>amd64<sup><a href="#pf_3">3</a></sup></td>
+ <td>GCC</td>
+ </tr>
+ </table>
+
+ <p>LLVM has partial support for the following platforms:</p>
+
+ <table summary="LLVM partial platform support">
+ <tr>
+ <th>OS</th>
+ <th>Arch</th>
+ <th>Compilers</th>
+ </tr>
+ <tr>
+ <td>Windows</td>
+ <td>x86<sup><a href="#pf_1">1</a></sup></td>
+ <td>Visual Studio .NET<sup><a href="#pf_4">4</a>,<a href="#pf_5">5</a></sup></td>
+ <tr>
+ <td>AIX<sup><a href="#pf_3">3</a>,<a href="#pf_4">4</a></sup></td>
+ <td>PowerPC</td>
+ <td>GCC</td>
+ </tr>
+ <tr>
+ <td>Linux<sup><a href="#pf_3">3</a>,<a href="#pf_5">5</a></sup></td>
+ <td>PowerPC</td>
+ <td>GCC</td>
+ </tr>
+
+ <tr>
+ <td>Linux<sup><a href="#pf_7">7</a></sup></td>
+ <td>Alpha</td>
+ <td>GCC</td>
+ </tr>
+ <tr>
+ <td>Linux<sup><a href="#pf_7">7</a></sup></td>
+ <td>Itanium (IA-64)</td>
+ <td>GCC</td>
+ </tr>
+ <tr>
+ <td>HP-UX<sup><a href="#pf_7">7</a></sup></td>
+ <td>Itanium (IA-64)</td>
+ <td>HP aCC</td>
+ </tr>
+ </table>
+
+ <p><b>Notes:</b></p>
+
+ <div class="doc_notes">
+ <ol>
+ <li><a name="pf_1">Code generation supported for Pentium processors and
+ up</a></li>
+ <li><a name="pf_2">Code generation supported for 32-bit ABI only</a></li>
+ <li><a name="pf_3">No native code generation</a></li>
+ <li><a name="pf_4">Build is not complete: one or more tools don't link</a></li>
+ <li><a name="pf_5">The GCC-based C/C++ frontend does not build</a></li>
+ <li><a name="pf_6">The port is done using the MSYS shell.</a>
+ <a href="http://www.mingw.org/MinGWiki/">Download</a> and install
+ bison (excl. M4.exe) and flex in that order. Build binutils-2.15 from source,
+ if necessary. Bison & flex can be also grabbed from GNUWin32 sf.net
+ project.</li>
+ <li><a name="pf_7">Native code generation exists but is not complete.</a></li>
+ <li><a name="pf_8">Binutils</a> up to post-2.17 has bug in bfd/cofflink.c
+ preventing LLVM from building correctly. Several workarounds have been
+ introduced into LLVM build system, but the bug can occur anytime in the
+ future. We highly recommend that you rebuild your current binutils with the
+ patch from <a href="http://sourceware.org/bugzilla/show_bug.cgi?id=2659">
+ Binutils bugzilla</a>, if it wasn't already applied.</li>
+ <li><a name="pf_9">XCode 2.5 and gcc 4.0.1 (Apple Build 5370) will trip
+ internal LLVM assert messages when compiled for Release at optimization
+ levels greater than 0 (i.e., <i>“-O1”</i> and higher).
+ Add <i>OPTIMIZE_OPTION="-O0"</i> to the build command line
+ if compiling for LLVM Release or bootstrapping the LLVM toolchain.</li>
+ </ol>
+ </div>
+
+ <p>Note that you will need about 1-3 GB of space for a full LLVM build in Debug
+ mode, depending on the system (it is so large because of all the debugging
+ information and the fact that the libraries are statically linked into multiple
+ tools). If you do not need many of the tools and you are space-conscious,
+ you can disable them individually in <tt>llvm/tools/Makefile</tt>. The Release
+ build requires considerably less space.</p>
+
+ <p>The LLVM suite <i>may</i> compile on other platforms, but it is not
+ guaranteed to do so. If compilation is successful, the LLVM utilities should be
+ able to assemble, disassemble, analyze, and optimize LLVM bitcode. Code
+ generation should work as well, although the generated native code may not work
+ on your platform.</p>
+
+ <p>The GCC front end is not very portable at the moment. If you want to get it
+ to work on another platform, you can download a copy of the source and <a
+ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="software"><b>Software</b></a></div>
+ <div class="doc_text">
+ <p>Compiling LLVM requires that you have several software packages
+ installed. The table below lists those required packages. The Package column
+ is the usual name for the software package that LLVM depends on. The Version
+ column provides "known to work" versions of the package. The Notes column
+ describes how LLVM uses the package and provides other details.</p>
+ <table summary="Packages required to compile LLVM">
+ <tr><th>Package</th><th>Version</th><th>Notes</th></tr>
+
+ <tr>
+ <td><a href="http://savannah.gnu.org/projects/make">GNU Make</a></td>
+ <td>3.79, 3.79.1</td>
+ <td>Makefile/build processor</td>
+ </tr>
+
+ <tr>
+ <td><a href="http://gcc.gnu.org">GCC</a></td>
+ <td>3.4.2</td>
+ <td>C/C++ compiler<sup><a href="#sf1">1</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.gnu.org/software/texinfo">TeXinfo</a></td>
+ <td>4.5</td>
+ <td>For building the CFE</td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.gnu.org/software/flex">Flex</a></td>
+ <td>2.5.4</td>
+ <td>LEX compiler</td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.gnu.org/software/bison/bison.html">Bison</a></td>
+ <td>1.28, 1.35, 1.75, 1.875d, 2.0, or 2.1<br>(not 1.85 or 1.875)</td>
+ <td>YACC compiler</td>
+ </tr>
+
+ <tr>
+ <td><a href="http://subversion.tigris.org/project_packages.html">SVN</a></td>
+ <td>≥1.3</td>
+ <td>Subversion access to LLVM<sup><a href="#sf2">2</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://savannah.gnu.org/projects/dejagnu">DejaGnu</a></td>
+ <td>1.4.2</td>
+ <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.tcl.tk/software/tcltk/">tcl</a></td>
+ <td>8.3, 8.4</td>
+ <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://expect.nist.gov/">expect</a></td>
+ <td>5.38.0</td>
+ <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.perl.com/download.csp">perl</a></td>
+ <td>≥5.6.0</td>
+ <td>Nightly tester, utilities</td>
+ </tr>
+
+ <tr>
+ <td><a href="http://savannah.gnu.org/projects/m4">GNU M4</a>
+ <td>1.4</td>
+ <td>Macro processor for configuration<sup><a href="#sf4">4</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.gnu.org/software/autoconf">GNU Autoconf</a></td>
+ <td>2.59</td>
+ <td>Configuration script builder<sup><a href="#sf4">4</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.gnu.org/software/automake">GNU Automake</a></td>
+ <td>1.9.2</td>
+ <td>aclocal macro generator<sup><a href="#sf4">4</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://savannah.gnu.org/projects/libtool">libtool</a></td>
+ <td>1.5.10</td>
+ <td>Shared library manager<sup><a href="#sf4">4</a></sup></td>
+ </tr>
+
+ </table>
+
+ <p><b>Notes:</b></p>
+ <div class="doc_notes">
+ <ol>
+ <li><a name="sf1">Only the C and C++ languages are needed so there's no
+ need to build the other languages for LLVM's purposes.</a> See
+ <a href="#brokengcc">below</a> for specific version info.</li>
+ <li><a name="sf2">You only need Subversion if you intend to build from the
+ latest LLVM sources. If you're working from a release distribution, you
+ don't need Subversion.</a></li>
+ <li><a name="sf3">Only needed if you want to run the automated test
+ suite in the <tt>llvm/test</tt> directory.</a></li>
+ <li><a name="sf4">If you want to make changes to the configure scripts,
+ you will need GNU autoconf (2.59), and consequently, GNU M4 (version 1.4
+ or higher). You will also need automake (1.9.2). We only use aclocal
+ from that package.</a></li>
+ </ol>
+ </div>
+
+ <p>Additionally, your compilation host is expected to have the usual
+ plethora of Unix utilities. Specifically:</p>
+ <ul>
+ <li><b>ar</b> - archive library builder</li>
+ <li><b>bzip2*</b> - bzip2 command for distribution generation</li>
+ <li><b>bunzip2*</b> - bunzip2 command for distribution checking</li>
+ <li><b>chmod</b> - change permissions on a file</li>
+ <li><b>cat</b> - output concatenation utility</li>
+ <li><b>cp</b> - copy files</li>
+ <li><b>date</b> - print the current date/time </li>
+ <li><b>echo</b> - print to standard output</li>
+ <li><b>egrep</b> - extended regular expression search utility</li>
+ <li><b>find</b> - find files/dirs in a file system</li>
+ <li><b>grep</b> - regular expression search utility</li>
+ <li><b>gzip*</b> - gzip command for distribution generation</li>
+ <li><b>gunzip*</b> - gunzip command for distribution checking</li>
+ <li><b>install</b> - install directories/files </li>
+ <li><b>mkdir</b> - create a directory</li>
+ <li><b>mv</b> - move (rename) files</li>
+ <li><b>ranlib</b> - symbol table builder for archive libraries</li>
+ <li><b>rm</b> - remove (delete) files and directories</li>
+ <li><b>sed</b> - stream editor for transforming output</li>
+ <li><b>sh</b> - Bourne shell for make build scripts</li>
+ <li><b>tar</b> - tape archive for distribution generation</li>
+ <li><b>test</b> - test things in file system</li>
+ <li><b>unzip*</b> - unzip command for distribution checking</li>
+ <li><b>zip*</b> - zip command for distribution generation</li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="brokengcc">Broken versions of GCC and other tools</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM is very demanding of the host C++ compiler, and as such tends to expose
+ bugs in the compiler. In particular, several versions of GCC crash when trying
+ to compile LLVM. We routinely use GCC 3.3.3, 3.4.0, and Apple 4.0.1
+ successfully with them (however, see important notes below). Other versions
+ of GCC will probably work as well. GCC versions listed
+ here are known to not work. If you are using one of these versions, please try
+ to upgrade your GCC to something more recent. If you run into a problem with a
+ version of GCC not listed here, please <a href="mailto:llvmdev at cs.uiuc.edu">let
+ us know</a>. Please use the "<tt>gcc -v</tt>" command to find out which version
+ of GCC you are using.
+ </p>
+
+ <p><b>GCC versions prior to 3.0</b>: GCC 2.96.x and before had several
+ problems in the STL that effectively prevent it from compiling LLVM.
+ </p>
+
+ <p><b>GCC 3.2.2 and 3.2.3</b>: These versions of GCC fails to compile LLVM with
+ a bogus template error. This was fixed in later GCCs.</p>
+
+ <p><b>GCC 3.3.2</b>: This version of GCC suffered from a <a
+ href="http://gcc.gnu.org/PR13392">serious bug</a> which causes it to crash in
+ the "<tt>convert_from_eh_region_ranges_1</tt>" GCC function.</p>
+
+ <p><b>Cygwin GCC 3.3.3</b>: The version of GCC 3.3.3 commonly shipped with
+ Cygwin does not work. Please <a href="GCCFEBuildInstrs.html#cygwin">upgrade
+ to a newer version</a> if possible.</p>
+ <p><b>SuSE GCC 3.3.3</b>: The version of GCC 3.3.3 shipped with SuSE 9.1 (and
+ possibly others) does not compile LLVM correctly (it appears that exception
+ handling is broken in some cases). Please download the FSF 3.3.3 or upgrade
+ to a newer version of GCC.</p>
+ <p><b>GCC 3.4.0 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
+ code generator, causing an infinite loop in the llvm-gcc build when built
+ with optimizations enabled (i.e. a release build).</p>
+ <p><b>GCC 3.4.2 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
+ code generator at -O3, as with 3.4.0. However gcc 3.4.2 (unlike 3.4.0)
+ correctly compiles LLVM at -O2. A work around is to build release LLVM
+ builds with "make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ..."</p>
+ <p><b>GCC 3.4.x on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1056">
+ miscompiles portions of LLVM</a>.</p>
+ <p><b>GCC 3.4.4 (CodeSourcery ARM 2005q3-2)</b>: this compiler miscompiles LLVM
+ when building with optimizations enabled. It appears to work with
+ "<tt>make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1</tt>" or build a debug
+ build.</p>
+ <p><b>IA-64 GCC 4.0.0</b>: The IA-64 version of GCC 4.0.0 is known to
+ miscompile LLVM.</p>
+ <p><b>Apple Xcode 2.3</b>: GCC crashes when compiling LLVM at -O3 (which is the
+ default with ENABLE_OPTIMIZED=1. To work around this, build with
+ "ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2".</p>
+ <p><b>GCC 4.1.1</b>: GCC fails to build LLVM with template concept check errors
+ compiling some files. At the time of this writing, GCC mainline (4.2)
+ did not share the problem.</p>
+ <p><b>GCC 4.1.1 on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1063">
+ miscompiles portions of LLVM</a> when compiling llvm itself into 64-bit
+ code. LLVM will appear to mostly work but will be buggy, e.g. failing
+ portions of its testsuite.</p>
+ <p><b>GCC 4.1.2 on OpenSUSE</b>: Seg faults during libstdc++ build and on x86_64
+ platforms compiling md5.c gets a mangled constant.</p>
+ <p><b>GNU ld 2.16.X</b>. Some 2.16.X versions of the ld linker will produce very
+ long warning messages complaining that some ".gnu.linkonce.t.*" symbol was
+ defined in a discarded section. You can safely ignore these messages as they are
+ erroneous and the linkage is correct. These messages disappear using ld
+ 2.17.</p>
+
+ <p><b>GNU binutils 2.17</b>: Binutils 2.17 contains <a
+ href="http://sourceware.org/bugzilla/show_bug.cgi?id=3111">a bug</a> which
+ causes huge link times (minutes instead of seconds) when building LLVM. We
+ recommend upgrading to a newer version (2.17.50.0.4 or later).</p>
+
+ </div>
+
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="starting"><b>Getting Started with LLVM</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The remainder of this guide is meant to get you up and running with
+ LLVM and to give you some basic information about the LLVM environment.</p>
+
+ <p>The later sections of this guide describe the <a
+ href="#layout">general layout</a> of the the LLVM source tree, a <a
+ href="#tutorial">simple example</a> using the LLVM tool chain, and <a
+ href="#links">links</a> to find more information about LLVM or to get
+ help via e-mail.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="terminology">Terminology and Notation</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Throughout this manual, the following names are used to denote paths
+ specific to the local system and working environment. <i>These are not
+ environment variables you need to set but just strings used in the rest
+ of this document below</i>. In any of the examples below, simply replace
+ each of these names with the appropriate pathname on your local system.
+ All these paths are absolute:</p>
+
+ <dl>
+ <dt>SRC_ROOT
+ <dd>
+ This is the top level directory of the LLVM source tree.
+ <br><br>
+
+ <dt>OBJ_ROOT
+ <dd>
+ This is the top level directory of the LLVM object tree (i.e. the
+ tree where object files and compiled programs will be placed. It
+ can be the same as SRC_ROOT).
+ <br><br>
+
+ <dt>LLVMGCCDIR
+ <dd>
+ This is where the LLVM GCC Front End is installed.
+ <p>
+ For the pre-built GCC front end binaries, the LLVMGCCDIR is
+ <tt>llvm-gcc/<i>platform</i>/llvm-gcc</tt>.
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="environment">Setting Up Your Environment</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ In order to compile and use LLVM, you may need to set some environment
+ variables.
+
+ <dl>
+ <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt>/path/to/your/bitcode/libs</tt></dt>
+ <dd>[Optional] This environment variable helps LLVM linking tools find the
+ locations of your bitcode libraries. It is provided only as a
+ convenience since you can specify the paths using the -L options of the
+ tools and the C/C++ front-end will automatically use the bitcode files
+ installed in its
+ <tt>lib</tt> directory.</dd>
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="unpack">Unpacking the LLVM Archives</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ If you have the LLVM distribution, you will need to unpack it before you
+ can begin to compile it. LLVM is distributed as a set of two files: the LLVM
+ suite and the LLVM GCC front end compiled for your platform. There is an
+ additional test suite that is optional. Each file is a TAR archive that is
+ compressed with the gzip program.
+ </p>
+
+ <p>The files are as follows, with <em>x.y</em> marking the version number:
+ <dl>
+ <dt><tt>llvm-x.y.tar.gz</tt></dt>
+ <dd>Source release for the LLVM libraries and tools.<br/></dd>
+
+ <dt><tt>llvm-test-x.y.tar.gz</tt></dt>
+ <dd>Source release for the LLVM test suite.</dd>
+
+ <dt><tt>llvm-gcc4-x.y.source.tar.gz</tt></dt>
+ <dd>Source release of the llvm-gcc4 front end. See README.LLVM in the root
+ directory for build instructions.<br/></dd>
+
+ <dt><tt>llvm-gcc4-x.y-platform.tar.gz</tt></dt>
+ <dd>Binary release of the llvm-gcc4 front end for a specific platform.<br/></dd>
+
+ </dl>
+
+ <p>It is also possible to download the sources of the llvm-gcc4 front end from a
+ read-only subversion mirror at
+ svn://anonsvn.opensource.apple.com/svn/llvm/trunk. </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="checkout">Checkout LLVM from Subversion</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If you have access to our Subversion repository, you can get a fresh copy of
+ the entire source code. All you need to do is check it out from Subvresion as
+ follows:</p>
+
+ <ul>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
+ <li>Read-Only: <tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
+ <li>Read-Write:<tt>svn co https://user@llvm.org/svn/llvm-project/llvm/trunk
+ llvm</tt></li>
+ </ul>
+
+
+ <p>This will create an '<tt>llvm</tt>' directory in the current
+ directory and fully populate it with the LLVM source code, Makefiles,
+ test directories, and local copies of documentation files.</p>
+
+ <p>If you want to get a specific release (as opposed to the most recent
+ revision), you can checkout it from the '<tt>tags</tt>' directory (instead of
+ '<tt>trunk</tt>'). The following releases are located in the following
+ subdirectories of the '<tt>tags</tt>' directory:</p>
+
+ <ul>
+ <li>Release 2.3: <b>RELEASE_23</b></li>
+ <li>Release 2.2: <b>RELEASE_22</b></li>
+ <li>Release 2.1: <b>RELEASE_21</b></li>
+ <li>Release 2.0: <b>RELEASE_20</b></li>
+ <li>Release 1.9: <b>RELEASE_19</b></li>
+ <li>Release 1.8: <b>RELEASE_18</b></li>
+ <li>Release 1.7: <b>RELEASE_17</b></li>
+ <li>Release 1.6: <b>RELEASE_16</b></li>
+ <li>Release 1.5: <b>RELEASE_15</b></li>
+ <li>Release 1.4: <b>RELEASE_14</b></li>
+ <li>Release 1.3: <b>RELEASE_13</b></li>
+ <li>Release 1.2: <b>RELEASE_12</b></li>
+ <li>Release 1.1: <b>RELEASE_11</b></li>
+ <li>Release 1.0: <b>RELEASE_1</b></li>
+ </ul>
+
+ <p>If you would like to get the LLVM test suite (a separate package as of 1.4),
+ you get it from the Subversion repository:</p>
+
+ <div class="doc_code">
+ <pre>
+ % cd llvm/projects
+ % svn co http://llvm.org/svn/llvm-project/test-suite/trunk llvm-test
+ </pre>
+ </div>
+
+ <p>By placing it in the <tt>llvm/projects</tt>, it will be automatically
+ configured by the LLVM configure script as well as automatically updated when
+ you run <tt>svn update</tt>.</p>
+
+ <p>If you would like to get the GCC front end source code, you can also get it
+ and build it yourself. Please follow <a href="GCCFEBuildInstrs.html">these
+ instructions</a> to successfully get and build the LLVM GCC front-end.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="installcf">Install the GCC Front End</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Before configuring and compiling the LLVM suite, you can optionally extract the
+ LLVM GCC front end from the binary distribution. It is used for running the
+ llvm-test testsuite and for compiling C/C++ programs. Note that you can optionally
+ <a href="GCCFEBuildInstrs.html">build llvm-gcc yourself</a> after building the
+ main LLVM repository.</p>
+
+ <p>To install the GCC front end, do the following:</p>
+
+ <ol>
+ <li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li>
+ <li><tt>gunzip --stdout llvmgcc-<i>version</i>.<i>platform</i>.tar.gz | tar -xvf
+ -</tt></li>
+ </ol>
+
+ <p>Once the binary is uncompressed, you should add a symlink for llvm-gcc and
+ llvm-g++ to some directory in your path. When you configure LLVM, it will
+ automatically detect llvm-gcc's presence (if it is in your path) enabling its
+ use in llvm-test. Note that you can always build or install llvm-gcc at any
+ pointer after building the main LLVM repository: just reconfigure llvm and
+ llvm-test will pick it up.
+ </p>
+
+ <p>The binary versions of the GCC front end may not suit all of your needs. For
+ example, the binary distribution may include an old version of a system header
+ file, not "fix" a header file that needs to be fixed for GCC, or it may be
+ linked with libraries not available on your system.</p>
+
+ <p>In cases like these, you may want to try <a
+ href="GCCFEBuildInstrs.html">building the GCC front end from source.</a> This is
+ much easier now than it was in the past.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="config">Local LLVM Configuration</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Once checked out from the Subversion repository, the LLVM suite source
+ code must be
+ configured via the <tt>configure</tt> script. This script sets variables in the
+ various <tt>*.in</tt> files, most notably <tt>llvm/Makefile.config</tt> and
+ <tt>llvm/include/Config/config.h</tt>. It also populates <i>OBJ_ROOT</i> with
+ the Makefiles needed to begin building LLVM.</p>
+
+ <p>The following environment variables are used by the <tt>configure</tt>
+ script to configure the build system:</p>
+
+ <table summary="LLVM configure script environment variables">
+ <tr><th>Variable</th><th>Purpose</th></tr>
+ <tr>
+ <td>CC</td>
+ <td>Tells <tt>configure</tt> which C compiler to use. By default,
+ <tt>configure</tt> will look for the first GCC C compiler in
+ <tt>PATH</tt>. Use this variable to override
+ <tt>configure</tt>'s default behavior.</td>
+ </tr>
+ <tr>
+ <td>CXX</td>
+ <td>Tells <tt>configure</tt> which C++ compiler to use. By default,
+ <tt>configure</tt> will look for the first GCC C++ compiler in
+ <tt>PATH</tt>. Use this variable to override
+ <tt>configure</tt>'s default behavior.</td>
+ </tr>
+ </table>
+
+ <p>The following options can be used to set or enable LLVM specific options:</p>
+
+ <dl>
+ <dt><i>--with-llvmgccdir</i></dt>
+ <dd>Path to the LLVM C/C++ FrontEnd to be used with this LLVM configuration.
+ The value of this option should specify the full pathname of the C/C++ Front
+ End to be used. If this option is not provided, the PATH will be searched for
+ a program named <i>llvm-gcc</i> and the C/C++ FrontEnd install directory will
+ be inferred from the path found. If the option is not given, and no llvm-gcc
+ can be found in the path then a warning will be produced by
+ <tt>configure</tt> indicating this situation. LLVM may still be built with
+ the <tt>tools-only</tt> target but attempting to build the runtime libraries
+ will fail as these libraries require llvm-gcc and llvm-g++. See
+ <a href="#installcf">Install the GCC Front End</a> for details on installing
+ the C/C++ Front End. See
+ <a href="GCCFEBuildInstrs.html">Bootstrapping the LLVM C/C++ Front-End</a>
+ for details on building the C/C++ Front End.</dd>
+ <dt><i>--with-tclinclude</i></dt>
+ <dd>Path to the tcl include directory under which <tt>tclsh</tt> can be
+ found. Use this if you have multiple tcl installations on your machine and you
+ want to use a specific one (8.x) for LLVM. LLVM only uses tcl for running the
+ dejagnu based test suite in <tt>llvm/test</tt>. If you don't specify this
+ option, the LLVM configure script will search for the tcl 8.4 and 8.3
+ releases.
+ <br><br>
+ </dd>
+ <dt><i>--enable-optimized</i></dt>
+ <dd>
+ Enables optimized compilation by default (debugging symbols are removed
+ and GCC optimization flags are enabled). The default is to use an
+ unoptimized build (also known as a debug build).
+ <br><br>
+ </dd>
+ <dt><i>--enable-debug-runtime</i></dt>
+ <dd>
+ Enables debug symbols in the runtime libraries. The default is to strip
+ debug symbols from the runtime libraries.
+ </dd>
+ <dt><i>--enable-jit</i></dt>
+ <dd>
+ Compile the Just In Time (JIT) compiler functionality. This is not
+ available
+ on all platforms. The default is dependent on platform, so it is best
+ to explicitly enable it if you want it.
+ <br><br>
+ </dd>
+ <dt><i>--enable-targets=</i><tt>target-option</tt></dt>
+ <dd>Controls which targets will be built and linked into llc. The default
+ value for <tt>target_options</tt> is "all" which builds and links all
+ available targets. The value "host-only" can be specified to build only a
+ native compiler (no cross-compiler targets available). The "native" target is
+ selected as the target of the build host. You can also specify a comma
+ separated list of target names that you want available in llc. The target
+ names use all lower case. The current set of targets is: <br/>
+ <tt>alpha, ia64, powerpc, skeleton, sparc, x86</tt>.
+ <br><br></dd>
+ <dt><i>--enable-doxygen</i></dt>
+ <dd>Look for the doxygen program and enable construction of doxygen based
+ documentation from the source code. This is disabled by default because
+ generating the documentation can take a long time and producess 100s of
+ megabytes of output.</dd>
+ <dt><i>--with-udis86</i></dt>
+ <dd>LLVM can use external disassembler library for various purposes (now it's
+ used only for examining code produced by JIT). This option will enable usage
+ of <a href="http://udis86.sourceforge.net/">udis86</a> x86 (both 32 and 64
+ bits) disassembler library.</dd>
+ </dl>
+
+ <p>To configure LLVM, follow these steps:</p>
+
+ <ol>
+ <li><p>Change directory into the object root directory:</p>
+
+ <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li>
+
+ <li><p>Run the <tt>configure</tt> script located in the LLVM source
+ tree:</p>
+
+ <div class="doc_code">
+ <pre>% <i>SRC_ROOT</i>/configure --prefix=/install/path [other options]</pre>
+ </div></li>
+ </ol>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="compile">Compiling the LLVM Suite Source Code</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Once you have configured LLVM, you can build it. There are three types of
+ builds:</p>
+
+ <dl>
+ <dt>Debug Builds
+ <dd>
+ These builds are the default when one types <tt>gmake</tt> (unless the
+ <tt>--enable-optimized</tt> option was used during configuration). The
+ build system will compile the tools and libraries with debugging
+ information.
+ <br><br>
+
+ <dt>Release (Optimized) Builds
+ <dd>
+ These builds are enabled with the <tt>--enable-optimized</tt> option to
+ <tt>configure</tt> or by specifying <tt>ENABLE_OPTIMIZED=1</tt> on the
+ <tt>gmake</tt> command line. For these builds, the build system will
+ compile the tools and libraries with GCC optimizations enabled and strip
+ debugging information from the libraries and executables it generates.
+ <br><br>
+
+ <dt>Profile Builds
+ <dd>
+ These builds are for use with profiling. They compile profiling
+ information into the code for use with programs like <tt>gprof</tt>.
+ Profile builds must be started by specifying <tt>ENABLE_PROFILING=1</tt>
+ on the <tt>gmake</tt> command line.
+ </dl>
+
+ <p>Once you have LLVM configured, you can build it by entering the
+ <i>OBJ_ROOT</i> directory and issuing the following command:</p>
+
+ <div class="doc_code"><pre>% gmake</pre></div>
+
+ <p>If the build fails, please <a href="#brokengcc">check here</a> to see if you
+ are using a version of GCC that is known not to compile LLVM.</p>
+
+ <p>
+ If you have multiple processors in your machine, you may wish to use some of
+ the parallel build options provided by GNU Make. For example, you could use the
+ command:</p>
+
+ <div class="doc_code"><pre>% gmake -j2</pre></div>
+
+ <p>There are several special targets which are useful when working with the LLVM
+ source code:</p>
+
+ <dl>
+ <dt><tt>gmake clean</tt>
+ <dd>
+ Removes all files generated by the build. This includes object files,
+ generated C/C++ files, libraries, and executables.
+ <br><br>
+
+ <dt><tt>gmake dist-clean</tt>
+ <dd>
+ Removes everything that <tt>gmake clean</tt> does, but also removes files
+ generated by <tt>configure</tt>. It attempts to return the source tree to the
+ original state in which it was shipped.
+ <br><br>
+
+ <dt><tt>gmake install</tt>
+ <dd>
+ Installs LLVM header files, libraries, tools, and documentation in a
+ hierarchy
+ under $PREFIX, specified with <tt>./configure --prefix=[dir]</tt>, which
+ defaults to <tt>/usr/local</tt>.
+ <br><br>
+
+ <dt><tt>gmake -C runtime install-bytecode</tt>
+ <dd>
+ Assuming you built LLVM into $OBJDIR, when this command is run, it will
+ install bitcode libraries into the GCC front end's bitcode library
+ directory. If you need to update your bitcode libraries,
+ this is the target to use once you've built them.
+ <br><br>
+ </dl>
+
+ <p>Please see the <a href="MakefileGuide.html">Makefile Guide</a> for further
+ details on these <tt>make</tt> targets and descriptions of other targets
+ available.</p>
+
+ <p>It is also possible to override default values from <tt>configure</tt> by
+ declaring variables on the command line. The following are some examples:</p>
+
+ <dl>
+ <dt><tt>gmake ENABLE_OPTIMIZED=1</tt>
+ <dd>
+ Perform a Release (Optimized) build.
+ <br><br>
+
+ <dt><tt>gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt>
+ <dd>
+ Perform a Release (Optimized) build without assertions enabled.
+ <br><br>
+
+ <dt><tt>gmake ENABLE_PROFILING=1</tt>
+ <dd>
+ Perform a Profiling build.
+ <br><br>
+
+ <dt><tt>gmake VERBOSE=1</tt>
+ <dd>
+ Print what <tt>gmake</tt> is doing on standard output.
+ <br><br>
+
+ <dt><tt>gmake TOOL_VERBOSE=1</tt></dt>
+ <dd>Ask each tool invoked by the makefiles to print out what it is doing on
+ the standard output. This also implies <tt>VERBOSE=1</tt>.
+ <br><br></dd>
+ </dl>
+
+ <p>Every directory in the LLVM object tree includes a <tt>Makefile</tt> to build
+ it and any subdirectories that it contains. Entering any directory inside the
+ LLVM object tree and typing <tt>gmake</tt> should rebuild anything in or below
+ that directory that is out of date.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="cross-compile">Cross-Compiling LLVM</a>
+ </div>
+
+ <div class="doc_text">
+ <p>It is possible to cross-compile LLVM. That is, you can create LLVM
+ executables and libraries for a platform different than the one one which you
+ are compiling. To do this, a few additional steps are
+ required. <sup><a href="#ccn_1">1</a></sup> To cross-compile LLVM, use
+ these instructions:</p>
+ <ol>
+ <li>Configure and build LLVM as a native compiler. You will need
+ just <tt>TableGen</tt> from that build.
+ <ul>
+ <li>If you have <tt>$LLVM_OBJ_ROOT=$LLVM_SRC_ROOT</tt> just execute
+ <tt>make -C utils/TableGen</tt> after configuring.</li>
+ <li>Otherwise you will need to monitor building process and terminate
+ it just after <tt>TableGen</tt> was built.</li>
+ </ul>
+ </li>
+ <li>Copy the TableGen binary to somewhere safe (out of your build tree).
+ </li>
+ <li>Configure LLVM to build with a cross-compiler. To do this, supply the
+ configure script with <tt>--build</tt> and <tt>--host</tt> options that
+ are different. The values of these options must be legal target triples
+ that your GCC compiler supports.</li>
+ <li>Put the saved <tt>TableGen</tt> executable into the
+ into <tt>$LLVM_OBJ_ROOT/{BUILD_TYPE}/bin</tt> directory (e.g. into
+ <tt>.../Release/bin</tt> for a Release build).</li>
+ <li>Build LLVM as usual.</li>
+ </ol>
+ <p>The result of such a build will produce executables that are not executable
+ on your build host (--build option) but can be executed on your compile host
+ (--host option).</p>
+ <p><b>Notes:</b></p>
+ <div class="doc_notes">
+ <ol>
+ <li><a name="ccn_1">Cross-compiling</a> was tested only with Linux as
+ build platform and Windows as host using mingw32 cross-compiler. Other
+ combinations have not been tested.</li>
+ </ol>
+ </div>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="objfiles">The Location of LLVM Object Files</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The LLVM build system is capable of sharing a single LLVM source tree among
+ several LLVM builds. Hence, it is possible to build LLVM for several different
+ platforms or configurations using the same source tree.</p>
+
+ <p>This is accomplished in the typical autoconf manner:</p>
+
+ <ul>
+ <li><p>Change directory to where the LLVM object files should live:</p>
+
+ <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li>
+
+ <li><p>Run the <tt>configure</tt> script found in the LLVM source
+ directory:</p>
+
+ <div class="doc_code"><pre>% <i>SRC_ROOT</i>/configure</pre></div></li>
+ </ul>
+
+ <p>The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories
+ named after the build type:</p>
+
+ <dl>
+ <dt>Debug Builds
+ <dd>
+ <dl>
+ <dt>Tools
+ <dd><tt><i>OBJ_ROOT</i>/Debug/bin</tt>
+ <dt>Libraries
+ <dd><tt><i>OBJ_ROOT</i>/Debug/lib</tt>
+ </dl>
+ <br><br>
+
+ <dt>Release Builds
+ <dd>
+ <dl>
+ <dt>Tools
+ <dd><tt><i>OBJ_ROOT</i>/Release/bin</tt>
+ <dt>Libraries
+ <dd><tt><i>OBJ_ROOT</i>/Release/lib</tt>
+ </dl>
+ <br><br>
+
+ <dt>Profile Builds
+ <dd>
+ <dl>
+ <dt>Tools
+ <dd><tt><i>OBJ_ROOT</i>/Profile/bin</tt>
+ <dt>Libraries
+ <dd><tt><i>OBJ_ROOT</i>/Profile/lib</tt>
+ </dl>
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="optionalconfig">Optional Configuration Items</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ If you're running on a Linux system that supports the "<a
+ href="http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html">binfmt_misc</a>"
+ module, and you have root access on the system, you can set your system up to
+ execute LLVM bitcode files directly. To do this, use commands like this (the
+ first command may not be required if you are already using the module):</p>
+
+ <div class="doc_code">
+ <pre>
+ $ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
+ $ echo ':llvm:M::llvm::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
+ $ chmod u+x hello.bc (if needed)
+ $ ./hello.bc
+ </pre>
+ </div>
+
+ <p>
+ This allows you to execute LLVM bitcode files directly. Thanks to Jack
+ Cummings for pointing this out!
+ </p>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="layout"><b>Program Layout</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>One useful source of information about the LLVM source base is the LLVM <a
+ href="http://www.doxygen.org">doxygen</a> documentation available at <tt><a
+ href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a></tt>.
+ The following is a brief introduction to code layout:</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="examples"><tt>llvm/examples</tt></a></div>
+ <div class="doc_text">
+ <p>This directory contains some simple examples of how to use the LLVM IR and
+ JIT.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="include"><tt>llvm/include</tt></a></div>
+ <div class="doc_text">
+
+ <p>This directory contains public header files exported from the LLVM
+ library. The three main subdirectories of this directory are:</p>
+
+ <dl>
+ <dt><tt><b>llvm/include/llvm</b></tt></dt>
+ <dd>This directory contains all of the LLVM specific header files. This
+ directory also has subdirectories for different portions of LLVM:
+ <tt>Analysis</tt>, <tt>CodeGen</tt>, <tt>Target</tt>, <tt>Transforms</tt>,
+ etc...</dd>
+
+ <dt><tt><b>llvm/include/llvm/Support</b></tt></dt>
+ <dd>This directory contains generic support libraries that are provided with
+ LLVM but not necessarily specific to LLVM. For example, some C++ STL utilities
+ and a Command Line option processing library store their header files here.
+ </dd>
+
+ <dt><tt><b>llvm/include/llvm/Config</b></tt></dt>
+ <dd>This directory contains header files configured by the <tt>configure</tt>
+ script. They wrap "standard" UNIX and C header files. Source code can
+ include these header files which automatically take care of the conditional
+ #includes that the <tt>configure</tt> script generates.</dd>
+ </dl>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="lib"><tt>llvm/lib</tt></a></div>
+ <div class="doc_text">
+
+ <p>This directory contains most of the source files of the LLVM system. In LLVM,
+ almost all code exists in libraries, making it very easy to share code among the
+ different <a href="#tools">tools</a>.</p>
+
+ <dl>
+ <dt><tt><b>llvm/lib/VMCore/</b></tt></dt>
+ <dd> This directory holds the core LLVM source files that implement core
+ classes like Instruction and BasicBlock.</dd>
+
+ <dt><tt><b>llvm/lib/AsmParser/</b></tt></dt>
+ <dd>This directory holds the source code for the LLVM assembly language parser
+ library.</dd>
+
+ <dt><tt><b>llvm/lib/BitCode/</b></tt></dt>
+ <dd>This directory holds code for reading and write LLVM bitcode.</dd>
+
+ <dt><tt><b>llvm/lib/Analysis/</b></tt><dd>This directory contains a variety of
+ different program analyses, such as Dominator Information, Call Graphs,
+ Induction Variables, Interval Identification, Natural Loop Identification,
+ etc.</dd>
+
+ <dt><tt><b>llvm/lib/Transforms/</b></tt></dt>
+ <dd> This directory contains the source code for the LLVM to LLVM program
+ transformations, such as Aggressive Dead Code Elimination, Sparse Conditional
+ Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global
+ Elimination, and many others.</dd>
+
+ <dt><tt><b>llvm/lib/Target/</b></tt></dt>
+ <dd> This directory contains files that describe various target architectures
+ for code generation. For example, the <tt>llvm/lib/Target/X86</tt>
+ directory holds the X86 machine description while
+ <tt>llvm/lib/Target/CBackend</tt> implements the LLVM-to-C converter.</dd>
+
+ <dt><tt><b>llvm/lib/CodeGen/</b></tt></dt>
+ <dd> This directory contains the major parts of the code generator: Instruction
+ Selector, Instruction Scheduling, and Register Allocation.</dd>
+
+ <dt><tt><b>llvm/lib/Debugger/</b></tt></dt>
+ <dd> This directory contains the source level debugger library that makes
+ it possible to instrument LLVM programs so that a debugger could identify
+ source code locations at which the program is executing.</dd>
+
+ <dt><tt><b>llvm/lib/ExecutionEngine/</b></tt></dt>
+ <dd> This directory contains libraries for executing LLVM bitcode directly
+ at runtime in both interpreted and JIT compiled fashions.</dd>
+
+ <dt><tt><b>llvm/lib/Support/</b></tt></dt>
+ <dd> This directory contains the source code that corresponds to the header
+ files located in <tt>llvm/include/Support/</tt>.</dd>
+
+ <dt><tt><b>llvm/lib/System/</b></tt></dt>
+ <dd>This directory contains the operating system abstraction layer that
+ shields LLVM from platform-specific coding.</dd>
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="projects"><tt>llvm/projects</tt></a></div>
+ <div class="doc_text">
+ <p>This directory contains projects that are not strictly part of LLVM but are
+ shipped with LLVM. This is also the directory where you should create your own
+ LLVM-based projects. See <tt>llvm/projects/sample</tt> for an example of how
+ to set up your own project. See <tt>llvm/projects/Stacker</tt> for a fully
+ functional example of a compiler front end.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="runtime"><tt>llvm/runtime</tt></a></div>
+ <div class="doc_text">
+
+ <p>This directory contains libraries which are compiled into LLVM bitcode and
+ used when linking programs with the GCC front end. Most of these libraries are
+ skeleton versions of real libraries; for example, libc is a stripped down
+ version of glibc.</p>
+
+ <p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front
+ end to compile.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="test"><tt>llvm/test</tt></a></div>
+ <div class="doc_text">
+ <p>This directory contains feature and regression tests and other basic sanity
+ checks on the LLVM infrastructure. These are intended to run quickly and cover
+ a lot of territory without being exhaustive.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="llvmtest"><tt>test-suite</tt></a></div>
+ <div class="doc_text">
+ <p>This is not a directory in the normal llvm module; it is a separate
+ Subversion
+ module that must be checked out (usually to <tt>projects/test-suite</tt>).
+ This
+ module contains a comprehensive correctness, performance, and benchmarking
+ test
+ suite for LLVM. It is a separate Subversion module because not every LLVM
+ user is
+ interested in downloading or building such a comprehensive test suite. For
+ further details on this test suite, please see the
+ <a href="TestingGuide.html">Testing Guide</a> document.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="tools"><tt>llvm/tools</tt></a></div>
+ <div class="doc_text">
+
+ <p>The <b>tools</b> directory contains the executables built out of the
+ libraries above, which form the main part of the user interface. You can
+ always get help for a tool by typing <tt>tool_name --help</tt>. The
+ following is a brief introduction to the most important tools. More detailed
+ information is in the <a href="CommandGuide/index.html">Command Guide</a>.</p>
+
+ <dl>
+
+ <dt><tt><b>bugpoint</b></tt></dt>
+ <dd><tt>bugpoint</tt> is used to debug
+ optimization passes or code generation backends by narrowing down the
+ given test case to the minimum number of passes and/or instructions that
+ still cause a problem, whether it is a crash or miscompilation. See <a
+ href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information
+ on using <tt>bugpoint</tt>.</dd>
+
+ <dt><tt><b>llvmc</b></tt></dt>
+ <dd>The LLVM Compiler Driver. This program can
+ be configured to utilize both LLVM and non-LLVM compilation tools to enable
+ pre-processing, translation, optimization, assembly, and linking of programs
+ all from one command line. <tt>llvmc</tt> also takes care of processing the
+ dependent libraries found in bitcode. This reduces the need to get the
+ traditional <tt>-l<name></tt> options right on the command line. Please
+ note that this tool, while functional, is still experimental and not feature
+ complete.</dd>
+
+ <dt><tt><b>llvm-ar</b></tt></dt>
+ <dd>The archiver produces an archive containing
+ the given LLVM bitcode files, optionally with an index for faster
+ lookup.</dd>
+
+ <dt><tt><b>llvm-as</b></tt></dt>
+ <dd>The assembler transforms the human readable LLVM assembly to LLVM
+ bitcode.</dd>
+
+ <dt><tt><b>llvm-dis</b></tt></dt>
+ <dd>The disassembler transforms the LLVM bitcode to human readable
+ LLVM assembly.</dd>
+
+ <dt><tt><b>llvm-ld</b></tt></dt>
+ <dd><tt>llvm-ld</tt> is a general purpose and extensible linker for LLVM.
+ This is the linker invoked by <tt>llvmc</tt>. It performsn standard link time
+ optimizations and allows optimization modules to be loaded and run so that
+ language specific optimizations can be applied at link time.</dd>
+
+ <dt><tt><b>llvm-link</b></tt></dt>
+ <dd><tt>llvm-link</tt>, not surprisingly, links multiple LLVM modules into
+ a single program.</dd>
+
+ <dt><tt><b>lli</b></tt></dt>
+ <dd><tt>lli</tt> is the LLVM interpreter, which
+ can directly execute LLVM bitcode (although very slowly...). For architectures
+ that support it (currently x86, Sparc, and PowerPC), by default, <tt>lli</tt>
+ will function as a Just-In-Time compiler (if the functionality was compiled
+ in), and will execute the code <i>much</i> faster than the interpreter.</dd>
+
+ <dt><tt><b>llc</b></tt></dt>
+ <dd> <tt>llc</tt> is the LLVM backend compiler, which
+ translates LLVM bitcode to a native code assembly file or to C code (with
+ the -march=c option).</dd>
+
+ <dt><tt><b>llvm-gcc</b></tt></dt>
+ <dd><tt>llvm-gcc</tt> is a GCC-based C frontend that has been retargeted to
+ use LLVM as its backend instead of GCC's RTL backend. It can also emit LLVM
+ bitcode or assembly (with the <tt>-emit-llvm</tt> option) instead of the
+ usual machine code output. It works just like any other GCC compiler,
+ taking the typical <tt>-c, -S, -E, -o</tt> options that are typically used.
+ Additionally, the the source code for <tt>llvm-gcc</tt> is available as a
+ separate Subversion module.</dd>
+
+ <dt><tt><b>opt</b></tt></dt>
+ <dd><tt>opt</tt> reads LLVM bitcode, applies a series of LLVM to LLVM
+ transformations (which are specified on the command line), and then outputs
+ the resultant bitcode. The '<tt>opt --help</tt>' command is a good way to
+ get a list of the program transformations available in LLVM.<br/>
+ <dd><tt>opt</tt> can also be used to run a specific analysis on an input
+ LLVM bitcode file and print out the results. It is primarily useful for
+ debugging analyses, or familiarizing yourself with what an analysis does.</dd>
+ </dl>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="utils"><tt>llvm/utils</tt></a></div>
+ <div class="doc_text">
+
+ <p>This directory contains utilities for working with LLVM source code, and some
+ of the utilities are actually required as part of the build process because they
+ are code generators for parts of LLVM infrastructure.</p>
+
+ <dl>
+ <dt><tt><b>codegen-diff</b></tt> <dd><tt>codegen-diff</tt> is a script
+ that finds differences between code that LLC generates and code that LLI
+ generates. This is a useful tool if you are debugging one of them,
+ assuming that the other generates correct output. For the full user
+ manual, run <tt>`perldoc codegen-diff'</tt>.<br><br>
+
+ <dt><tt><b>emacs/</b></tt> <dd>The <tt>emacs</tt> directory contains
+ syntax-highlighting files which will work with Emacs and XEmacs editors,
+ providing syntax highlighting support for LLVM assembly files and TableGen
+ description files. For information on how to use the syntax files, consult
+ the <tt>README</tt> file in that directory.<br><br>
+
+ <dt><tt><b>getsrcs.sh</b></tt> <dd>The <tt>getsrcs.sh</tt> script finds
+ and outputs all non-generated source files, which is useful if one wishes
+ to do a lot of development across directories and does not want to
+ individually find each file. One way to use it is to run, for example:
+ <tt>xemacs `utils/getsources.sh`</tt> from the top of your LLVM source
+ tree.<br><br>
+
+ <dt><tt><b>llvmgrep</b></tt></dt>
+ <dd>This little tool performs an "egrep -H -n" on each source file in LLVM and
+ passes to it a regular expression provided on <tt>llvmgrep</tt>'s command
+ line. This is a very efficient way of searching the source base for a
+ particular regular expression.</dd>
+
+ <dt><tt><b>makellvm</b></tt> <dd>The <tt>makellvm</tt> script compiles all
+ files in the current directory and then compiles and links the tool that
+ is the first argument. For example, assuming you are in the directory
+ <tt>llvm/lib/Target/Sparc</tt>, if <tt>makellvm</tt> is in your path,
+ simply running <tt>makellvm llc</tt> will make a build of the current
+ directory, switch to directory <tt>llvm/tools/llc</tt> and build it,
+ causing a re-linking of LLC.<br><br>
+
+ <dt><tt><b>NewNightlyTest.pl</b></tt> and
+ <tt><b>NightlyTestTemplate.html</b></tt> <dd>These files are used in a
+ cron script to generate nightly status reports of the functionality of
+ tools, and the results can be seen by following the appropriate link on
+ the <a href="http://llvm.org/">LLVM homepage</a>.<br><br>
+
+ <dt><tt><b>TableGen/</b></tt> <dd>The <tt>TableGen</tt> directory contains
+ the tool used to generate register descriptions, instruction set
+ descriptions, and even assemblers from common TableGen description
+ files.<br><br>
+
+ <dt><tt><b>vim/</b></tt> <dd>The <tt>vim</tt> directory contains
+ syntax-highlighting files which will work with the VIM editor, providing
+ syntax highlighting support for LLVM assembly files and TableGen
+ description files. For information on how to use the syntax files, consult
+ the <tt>README</tt> file in that directory.<br><br>
+
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="win32"><tt>llvm/win32</tt></a></div>
+ <div class="doc_text">
+ <p>This directory contains build scripts and project files for use with
+ Visual C++. This allows developers on Windows to build LLVM without the need
+ for Cygwin. The contents of this directory should be considered experimental
+ at this time.
+ </p>
+ </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="tutorial">An Example Using the LLVM Tool Chain</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>This section gives an example of using LLVM. llvm-gcc3 is now obsolete,
+ so we only include instructiosn for llvm-gcc4.
+ </p>
+
+ <p><b>Note:</b> The <i>gcc4</i> frontend's invocation is <b><i>considerably different</i></b>
+ from the previous <i>gcc3</i> frontend. In particular, the <i>gcc4</i> frontend <b><i>does not</i></b>
+ create bitcode by default: <i>gcc4</i> produces native code. As the example below illustrates,
+ the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and
+ <i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode
+ output.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="tutorial4">Example with llvm-gcc4</a></div>
+
+ <div class="doc_text">
+
+ <ol>
+ <li><p>First, create a simple C file, name it 'hello.c':</p>
+
+ <div class="doc_code">
+ <pre>
+ #include <stdio.h>
+
+ int main() {
+ printf("hello world\n");
+ return 0;
+ }
+ </pre></div></li>
+
+ <li><p>Next, compile the C file into a native executable:</p>
+
+ <div class="doc_code"><pre>% llvm-gcc hello.c -o hello</pre></div>
+
+ <p>Note that llvm-gcc works just like GCC by default. The standard -S and
+ -c arguments work as usual (producing a native .s or .o file,
+ respectively).</p></li>
+
+ <li><p>Next, compile the C file into a LLVM bitcode file:</p>
+
+ <div class="doc_code">
+ <pre>% llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc</pre></div>
+
+ <p>The -emit-llvm option can be used with the -S or -c options to emit an
+ LLVM ".ll" or ".bc" file (respectively) for the code. This allows you
+ to use the <a href="CommandGuide/index.html">standard LLVM tools</a> on
+ the bitcode file.</p>
+
+ <p>Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments.
+ </p></li>
+
+ <li><p>Run the program in both forms. To run the program, use:</p>
+
+ <div class="doc_code"><pre>% ./hello</pre></div>
+
+ <p>and</p>
+
+ <div class="doc_code"><pre>% lli hello.bc</pre></div>
+
+ <p>The second examples shows how to invoke the LLVM JIT, <a
+ href="CommandGuide/html/lli.html">lli</a>.</p></li>
+
+ <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
+ code:</p>
+
+ <div class="doc_code">
+ <pre>llvm-dis < hello.bc | less</pre>
+ </div></li>
+
+ <li><p>Compile the program to native assembly using the LLC code
+ generator:</p>
+
+ <div class="doc_code"><pre>% llc hello.bc -o hello.s</pre></div></li>
+
+ <li><p>Assemble the native assembly language file into a program:</p>
+
+ <div class="doc_code">
+ <pre>
+ <b>Solaris:</b> % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native
+
+ <b>Others:</b> % gcc hello.s -o hello.native
+ </pre>
+ </div></li>
+
+ <li><p>Execute the native code program:</p>
+
+ <div class="doc_code"><pre>% ./hello.native</pre></div>
+
+ <p>Note that using llvm-gcc to compile directly to native code (i.e. when
+ the -emit-llvm option is not present) does steps 6/7/8 for you.</p>
+ </li>
+
+ </ol>
+
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="problems">Common Problems</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>If you are having problems building or using LLVM, or if you have any other
+ general questions about LLVM, please consult the <a href="FAQ.html">Frequently
+ Asked Questions</a> page.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="links">Links</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This document is just an <b>introduction</b> to how to use LLVM to do
+ some simple things... there are many more interesting and complicated things
+ that you can do that aren't documented here (but we'll gladly accept a patch
+ if you want to write something up!). For more information about LLVM, check
+ out:</p>
+
+ <ul>
+ <li><a href="http://llvm.org/">LLVM homepage</a></li>
+ <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
+ <li><a href="http://llvm.org/docs/Projects.html">Starting a Project
+ that Uses LLVM</a></li>
+ </ul>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.x10sys.com/rspencer/">Reid Spencer</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/GettingStartedVS.html
diff -c /dev/null llvm-www/releases/2.3/docs/GettingStartedVS.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/GettingStartedVS.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,380 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Getting Started with LLVM System for Microsoft Visual Studio</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">
+ Getting Started with the LLVM System using Microsoft Visual Studio
+ </div>
+
+ <ul>
+ <li><a href="#overview">Overview</a>
+ <li><a href="#quickstart">Getting Started Quickly (A Summary)</a>
+ <li><a href="#requirements">Requirements</a>
+ <ol>
+ <li><a href="#hardware">Hardware</a>
+ <li><a href="#software">Software</a>
+ </ol></li>
+
+ <li><a href="#starting">Getting Started with LLVM</a>
+ <ol>
+ <li><a href="#terminology">Terminology and Notation</a>
+ <li><a href="#objfiles">The Location of LLVM Object Files</a>
+ </ol></li>
+
+ <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
+ <li><a href="#problems">Common Problems</a>
+ <li><a href="#links">Links</a>
+ </ul>
+
+ <div class="doc_author">
+ <p>Written by:
+ <a href="mailto:jeffc at jolt-lang.org">Jeff Cohen</a>
+ </p>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="overview"><b>Overview</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The Visual Studio port at this time is experimental. It is suitable for
+ use only if you are writing your own compiler front end or otherwise have a
+ need to dynamically generate machine code. The JIT and interpreter are
+ functional, but it is currently not possible to generate assembly code which
+ is then assembled into an executable. You can indirectly create executables
+ by using the C back end.</p>
+
+ <p>To emphasize, there is no C/C++ front end currently available.
+ <tt>llvm-gcc</tt> is based on GCC, which cannot be bootstrapped using VC++.
+ Eventually there should be a <tt>llvm-gcc</tt> based on Cygwin or MinGW that
+ is usable. There is also the option of generating bitcode files on Unix and
+ copying them over to Windows. But be aware the odds of linking C++ code
+ compiled with <tt>llvm-gcc</tt> with code compiled with VC++ is essentially
+ zero.</p>
+
+ <p>The LLVM test suite cannot be run on the Visual Studio port at this
+ time.</p>
+
+ <p>Most of the tools build and work. <tt>llvm-db</tt> does not build at this
+ time. <tt>bugpoint</tt> does build, but does not work.
+
+ <p>Additional information about the LLVM directory structure and tool chain
+ can be found on the main <a href="GettingStarted.html">Getting Started</a>
+ page.</P>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Here's the short story for getting up and running quickly with LLVM:</p>
+
+ <ol>
+ <li>Read the documentation.</li>
+ <li>Seriously, read the documentation.</li>
+ <li>Remember that you were warned twice about reading the documentation.</li>
+
+ <li>Get the Source Code
+ <ul>
+ <li>With the distributed files:
+ <ol>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
+ <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
+ <i> or use WinZip</i>
+ <li><tt>cd llvm</tt></li>
+ </ol></li>
+
+ <li>With anonymous Subversion access:
+ <ol>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
+ <li><tt>svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top
+ </tt></li>
+ <li><tt>make checkout MODULE=llvm</tt>
+ <li><tt>cd llvm</tt></li>
+ </ol></li>
+ </ul></li>
+
+ <li>Start Visual Studio
+ <ol>
+ <li>Simply double click on the solution file <tt>llvm/win32/llvm.sln</tt>.
+ </li>
+ </ol></li>
+
+ <li>Build the LLVM Suite:
+ <ol>
+ <li>Simply build the solution.</li>
+ <li>The Fibonacci project is a sample program that uses the JIT. Modify
+ the project's debugging properties to provide a numeric command line
+ argument. The program will print the corresponding fibonacci value.</li>
+ </ol></li>
+
+ </ol>
+
+ <p>It is strongly encouraged that you get the latest version from Subversion as
+ changes are continually making the VS support better.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="requirements"><b>Requirements</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Before you begin to use the LLVM system, review the requirements given
+ below. This may save you some trouble by knowing ahead of time what hardware
+ and software you will need.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="hardware"><b>Hardware</b></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Any system that can adequately run Visual Studio .NET 2003 is fine. The
+ LLVM source tree and object files, libraries and executables will consume
+ approximately 3GB.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="software"><b>Software</b></a></div>
+ <div class="doc_text">
+
+ <p>You will need Visual Studio .NET 2003. Earlier versions cannot open the
+ solution/project files. The VS 2005 beta can, but will migrate these files
+ to its own format in the process. While it should work with the VS 2005
+ beta, there are no guarantees and there is no support for it at this time.
+ It has been reported that VC++ Express also works.</p>
+
+ <p>If you plan to modify any .y or .l files, you will need to have bison
+ and/or flex installed where Visual Studio can find them. Otherwise, you do
+ not need them and the pre-generated files that come with the source tree
+ will be used.</p>
+
+ <p>
+ Do not install the LLVM directory tree into a path containing spaces (e.g.
+ C:\Documents and Settings\...) as the configure step will fail.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="starting"><b>Getting Started with LLVM</b></a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The remainder of this guide is meant to get you up and running with
+ LLVM using Visual Studio and to give you some basic information about the LLVM
+ environment.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="terminology">Terminology and Notation</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Throughout this manual, the following names are used to denote paths
+ specific to the local system and working environment. <i>These are not
+ environment variables you need to set but just strings used in the rest
+ of this document below</i>. In any of the examples below, simply replace
+ each of these names with the appropriate pathname on your local system.
+ All these paths are absolute:</p>
+
+ <dl>
+ <dt>SRC_ROOT</dt>
+ <dd><p>This is the top level directory of the LLVM source tree.</p></dd>
+
+ <dt>OBJ_ROOT</dt>
+ <dd><p>This is the top level directory of the LLVM object tree (i.e. the
+ tree where object files and compiled programs will be placed. It is
+ fixed at SRC_ROOT/win32).</p></dd>
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="objfiles">The Location of LLVM Object Files</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The object files are placed under <tt>OBJ_ROOT/Debug</tt> for debug builds
+ and <tt>OBJ_ROOT/Release</tt> for release (optimized) builds. These include
+ both executables and libararies that your application can link against.</p>
+
+ <p>The files that <tt>configure</tt> would create when building on Unix are
+ created by the <tt>Configure</tt> project and placed in
+ <tt>OBJ_ROOT/llvm</tt>. You application must have OBJ_ROOT in its include
+ search path just before <tt>SRC_ROOT/include</tt>.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="tutorial">An Example Using the LLVM Tool Chain</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <ol>
+ <li><p>First, create a simple C file, name it 'hello.c':</p>
+
+ <div class="doc_code">
+ <pre>
+ #include <stdio.h>
+ int main() {
+ printf("hello world\n");
+ return 0;
+ }
+ </pre></div></li>
+
+ <li><p>Next, compile the C file into a LLVM bitcode file:</p>
+
+ <div class="doc_code">
+ <pre>
+ % llvm-gcc -c hello.c -emit-llvm -o hello.bc
+ </pre>
+ </div>
+
+ <p>This will create the result file <tt>hello.bc</tt> which is the LLVM
+ bitcode that corresponds the the compiled program and the library
+ facilities that it required. You can execute this file directly using
+ <tt>lli</tt> tool, compile it to native assembly with the <tt>llc</tt>,
+ optimize or analyze it further with the <tt>opt</tt> tool, etc.</p>
+
+ <p><b>Note: while you cannot do this step on Windows, you can do it on a
+ Unix system and transfer <tt>hello.bc</tt> to Windows. Important:
+ transfer as a binary file!</b></p></li>
+
+ <li><p>Run the program using the just-in-time compiler:</p>
+
+ <div class="doc_code">
+ <pre>
+ % lli hello.bc
+ </pre>
+ </div>
+
+ <p>Note: this will only work for trivial C programs. Non-trivial programs
+ (and any C++ program) will have dependencies on the GCC runtime that
+ won't be satisfied by the Microsoft runtime libraries.</p></li>
+
+ <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
+ code:</p>
+
+ <div class="doc_code">
+ <pre>
+ % llvm-dis < hello.bc | more
+ </pre>
+ </div></li>
+
+ <li><p>Compile the program to C using the LLC code generator:</p>
+
+ <div class="doc_code">
+ <pre>
+ % llc -march=c hello.bc
+ </pre>
+ </div></li>
+
+ <li><p>Compile to binary using Microsoft C:</p>
+
+ <div class="doc_code">
+ <pre>
+ % cl hello.cbe.c
+ </pre>
+ </div>
+
+ <p>Note: this will only work for trivial C programs. Non-trivial programs
+ (and any C++ program) will have dependencies on the GCC runtime that
+ won't be satisfied by the Microsoft runtime libraries.</p></li>
+
+ <li><p>Execute the native code program:</p>
+
+ <div class="doc_code">
+ <pre>
+ % hello.cbe.exe
+ </pre>
+ </div></li>
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="problems">Common Problems</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>If you are having problems building or using LLVM, or if you have any other
+ general questions about LLVM, please consult the <a href="FAQ.html">Frequently
+ Asked Questions</a> page.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="links">Links</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This document is just an <b>introduction</b> to how to use LLVM to do
+ some simple things... there are many more interesting and complicated things
+ that you can do that aren't documented here (but we'll gladly accept a patch
+ if you want to write something up!). For more information about LLVM, check
+ out:</p>
+
+ <ul>
+ <li><a href="http://llvm.org/">LLVM homepage</a></li>
+ <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
+ <li><a href="http://llvm.org/docs/Projects.html">Starting a Project
+ that Uses LLVM</a></li>
+ </ul>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+
+ <a href="mailto:jeffc at jolt-lang.org">Jeff Cohen</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/HowToReleaseLLVM.html
diff -c /dev/null llvm-www/releases/2.3/docs/HowToReleaseLLVM.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/HowToReleaseLLVM.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,608 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>How To Release LLVM To The Public</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">How To Release LLVM To The Public</div>
+ <ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#introduction">Release Timeline</a></li>
+ <li><a href="#process">Release Process</a></li>
+ <li><a href="#dist_targets">Distribution Targets</a></li>
+ </ol>
+ <div class="doc_author">
+ <p>Written by <a href="mailto:rspencer at x10sys.com">Reid Spencer</a>,
+ <a href="mailto:criswell at cs.uiuc.edu">John Criswell</a>,
+ <a href="mailto:tonic at nondot.org">Tanya Lattner</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="introduction">Introduction</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>
+ This document collects information about successfully releasing LLVM to the
+ public. It is the release manager's guide to ensuring that a high quality
+ build of LLVM is released.
+ </p>
+
+ <p>
+ The following is the basic criteria for releasing LLVM:
+ </p>
+
+ <ol>
+ <li>Successful configure and build.</li>
+ <li>Clean 'make check'.</li>
+ <li>No regressions in the testsuite from the previous release. This may
+ include performance regressions for major benchmarks.</li>
+ </ol>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="process">Release Timeline</a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ The release manager should attempt to have a release every 3-4 months because LLVM
+ does time based releases (instead of feature based). The release schedule should
+ be roughly as follows:
+ <ol>
+ <li>Set code freeze and branch creation date for 3 months after last release
+ date. Announce release schedule to the LLVM community and update the website.</li>
+ <li>Create release branch and begin release process. </li>
+ <li>Send out pre-release for first round of testing. Testing will last 7-10 days.
+ During the first round of testing, regressions should be found and fixed. Patches
+ are merged from mainline to the release branch.</li>
+ <li>Generate and send out second pre-release. Bugs found during this time will
+ not be fixed unless absolutely critical. Bugs introduce by patches merged in
+ will be fixed and if so, a 3rd round of testing is needed.</li>
+ <li>The release notes should be updated during the first and second round of
+ pre-release testing.</li>
+ <li>Finally, release!</li>
+ </ol>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="process">Release Process</a></div>
+ <!-- *********************************************************************** -->
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="overview">Process Overview</a></div>
+ <div class="doc_text">
+ <ol>
+ <li><a href="#branch">Create Release Branch</a></li>
+ <li><a href="#verchanges">Update LLVM Version </a></li>
+ <li><a href="#dist">Build the LLVM Source Distributions</a></li>
+ <li><a href="#build">Build LLVM</a></li>
+ <li><a href="#llvmgccbin">Build the LLVM GCC Binary Distribution</a></li>
+ <li><a href="#rpm">Build RPM Packages (optional)</a></li>
+ <li><a href="#check">Run 'make check'</a></li>
+ <li><a href="#test">Run LLVM Test Suite</a></li>
+ <li><a href="#prerelease">Pre-Release Testing</a></li>
+ <li><a href="#tag">Tag the LLVM Release Branch</a></li>
+ <li><a href="#updocs">Update Documentation</a></li>
+ <li><a href="#updemo">Update the LLVM Demo Page</a></li>
+ <li><a href="#webupdates">Update the LLVM Website</a></li>
+ <li><a href="#announce">Announce the Release</a></li>
+
+ </ol>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="branch">Create Release Branch</a></div>
+ <div class="doc_text">
+ <p>Branch the Subversion HEAD using the following procedure:</p>
+ <ol>
+ <li>
+ <p>Verify that the current Subversion HEAD is in decent shape by examining nightly
+ tester results.</p></li>
+ <li>
+ <p>Request all developers to refrain from committing. Offenders get commit
+ rights taken away (temporarily).</p></li>
+ <li>
+ <p> Create the release branch for <tt>llvm</tt>, <tt>llvm-gcc4.0</tt>,
+ <tt>llvm-gcc4.2</tt>, and the <tt>test-suite</tt>. The
+ branch name will be <tt>release_XX</tt>, where <tt>XX</tt> is the major and
+ minor release numbers. These branches can be created without checking out
+ anything from subversion.
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
+ https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XX</i>
+ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk \
+ https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_<i>XX</i>
+ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk \
+ https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i>
+ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
+ https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i>
+ </pre>
+ </div>
+
+ <li>
+ <p>Advise developers they can work on Subversion HEAD again.</p></li>
+
+ <li>
+ <p>The Release Manager should switch to the release branch (as all changes
+ to the release will now be done in the branch). The easiest way to do this
+ is to grab another working copy using the following commands:</p>
+
+ <div class="doc_code">
+ <pre>
+ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XX</i>
+ svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_<i>XX</i>
+ svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i>
+ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i>
+ </pre>
+ </div></li>
+
+ </div>
+ </ol>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="verchanges">Update LLVM Version</a></div>
+ <div class="doc_text">
+ <p>
+ After creating the LLVM release branch, update the release branches'
+ autoconf/configure.ac version from X.Xsvn to just X.X. Update it on mainline
+ as well to be the next version (X.X+1svn). Regenerated the configure script
+ for both. This must be done for both llvm and the test-suite.
+ </p>
+ <p>In addition, the version number of all the Bugzilla components must be
+ updated for the next release.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="dist">Build the LLVM Source Distributions</a></div>
+ <div class="doc_text">
+ <p>
+ Create source distributions for LLVM, LLVM GCC, and the LLVM Test Suite by
+ exporting the source from Subversion and archiving it. This can be done with
+ the following commands:
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ svn export https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XX</i> llvm-X.X
+ svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_<i>XX</i> llvm-gcc4.0-X.X.source
+ svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i> llvm-gcc4.2-X.X.source
+ svn export https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i> llvm-test-X.X
+ tar -cvf - llvm-X.X | gzip > llvm-X.X.tar.gz
+ tar -cvf - llvm-test-X.X | gzip > llvm-test-X.X.tar.gz
+ tar -cvf - llvm-gcc4.0-X.X.source | gzip > llvm-gcc-4.0-X.X.source.tar.gz
+ tar -cvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz
+ </pre>
+ </div>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="build">Build LLVM</a></div>
+ <div class="doc_text">
+ <p>
+ Build both debug and release (optimized) versions of LLVM on all
+ platforms. Ensure the build is warning and error free on each platform.
+ Note that when building the LLVM GCC Binary, use a release build of LLVM.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="llvmgccbin">Build the LLVM GCC Binary Distribution</a></div>
+ <div class="doc_text">
+ <p>
+ Creating the LLVM GCC binary distribution (release/optimized) requires
+ performing the following steps for each supported platform:
+ </p>
+
+ <ol>
+ <li>
+ Build the LLVM GCC front-end by following the directions in the README.LLVM
+ file. Be sure to build with LLVM_VERSION_INFO=X.X, where X is the major and
+ minor release numbers.
+ </li>
+
+ <li>
+ Copy the installation directory to a directory named for the specific target.
+ For example on Red Hat Enterprise Linux, the directory would be named
+ <tt>llvm-gcc4.0-2.1-x86-linux-RHEL4</tt>. Archive and compress the new directory.
+ </li>
+ </ol>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="check">Run 'make check'</a></div>
+ <div class="doc_text">
+ <p>
+ Using the newly built llvm-gcc and llvm, reconfigure llvm to locate llvm-gcc.
+ Run <tt>make check</tt> and ensure there are no unexpected failures. If there
+ are, resolve the failures or file a bug. If there is a fix commited to mainline,
+ merge back into the release branch, and restart testing by
+ <a href="#build">re-building LLVM</a> and <a href="#build">llvm-gcc</a>. If no
+ fix will be made, XFAIL the test and commit back to the release branch.
+ </p>
+
+ <p>
+ Ensure that '<tt>make check</tt>' passes on all platforms for all targets. The
+ test suite must complete with "0 unexpected failures" before sending out the
+ pre-releases for testing.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="test">LLVM Test Suite</a></div>
+ <div class="doc_text">
+ <p>
+ Run the <tt>llvm-test</tt> suite and ensure there are no unacceptable
+ failures. Unacceptable failures are regression from the previous release
+ and (optionally) major performance regressions from the previous release.
+ If a regression is found a bug is filled, but the pre-releases may still go
+ out.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="rpm">Building RPM packages (optional)</a></div>
+ <div class="doc_text">
+ <p>
+ You can, optionally, create source and binary RPM packages for LLVM. These may
+ make it easier to get LLVM into a distribution. This can be done with the
+ following commands:
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ make dist # Build the distribution source tarball
+ make dist-check # Check that the source tarball can build itself.
+ cp llvm-M.m.tar.gz /usr/src/redhat/SOURCES # Required by rpmbuild
+ make srpm # for source rpm
+ make rpm # for binary rpm
+ </pre>
+ </div>
+
+ <p>
+ First, use <tt>make dist</tt> to simply build the distribution. Any failures
+ need to be corrected (on the branch). Once <tt>make dist</tt> can be
+ successful, do <tt>make dist-check</tt>. This target will do the same thing as
+ the 'dist' target but also test that distribution to make sure it can build
+ itself and runs <tt>make check</tt> as well. This ensures that needed files
+ are not missing and that the src tarball can be successfully unpacked, built,
+ installed, and cleaned. Once you have a reliable tarball, you need to copy it
+ to the <tt>/usr/src/redhat/SOURCES</tt> directory which is a requirement of
+ the rpmbuild tool. The last two <tt>make</tt> invocations just run rpmbuild to
+ build either a source (<tt>srpm</tt>) or binary (<tt>rpm</tt>) RPM package.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="prerelease">Pre-Release Testing</a></div>
+ <div class="doc_text">
+ <p>
+ Once all testing has been completed and appropriate bugs filed, the pre-release
+ tar balls may be put on the website and the LLVM community is notified. Ask that
+ all LLVM developers test the release in 2 ways:</p>
+ <ol>
+ <li>Download llvm-X.X, llvm-test-X.X, and the appropriate llvm-gcc4 binary.
+ Run "make check" and the full llvm-test suite (make TEST=nightly report).<li>
+ <li>Download llvm-X.X, llvm-test-X.X, and the llvm-gcc4 source. Compile
+ everything. Run "make check" and the full llvm-test suite (make TEST=nightly
+ report).</li>
+ </ol>
+ <p>Ask LLVM developers to submit the report and make check results to the list.
+ Verify that there are no regressions from the previous release. For
+ unsupported targets, verify that make check at least is clean.</p>
+
+ <p>The first round of pre-release testing will be the longest. During this time,
+ all regressions must be fixed before the second pre-release is created (repeat
+ steps 4-8).</p>
+
+ <p>If this is the second round of testing, this is only to ensure the bug fixes
+ previously merged in have not created new major problems. This is not the time
+ to solve additional and unrelated bugs. If no patches are merged in, the release
+ is determined to be ready and the release manager may move onto the next step.</p>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="tag">Tag the Release Branch</a></div>
+ <div class="doc_text">
+ <p>Tag the release branch using the following procedure:</p>
+ <div class="doc_code">
+ <pre>
+ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XX \
+ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XX</i>
+ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_XX \
+ https://llvm.org/svn/llvm-project/llvm-gcc-4.0/tags/RELEASE_<i>XX</i>
+ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX \
+ https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_<i>XX</i>
+ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \
+ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XX</i>
+ </pre>
+ </div>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="updocs">Update Documentation</a></div>
+ <div class="doc_text">
+ <p>
+ Review the documentation and ensure that it is up to date. The Release Notes
+ must be updated to reflect bug fixes, new known issues, and changes in the
+ list of supported platforms. The Getting Started Guide should be updated to
+ reflect the new release version number tag avaiable from Subversion and
+ changes in basic system requirements. Merge both changes from mainline into
+ the release branch.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="updemo">Update the LLVM Demo Page</a></div>
+ <div class="doc_text">
+ <p>
+ The LLVM demo page must be updated to use the new release. This consists of
+ using the llvm-gcc binary and building LLVM. Update the website demo page
+ configuration to use the new release.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="webupdates">Update the LLVM Website</a></div>
+ <div class="doc_text">
+ <p>
+ The website must be updated before the release announcement is sent out. Here is
+ what to do:</p>
+ <ol>
+ <li> Check out the <tt>website</tt> module from CVS. </li>
+ <li> Create a new subdirectory X.X in the releases directory. </li>
+ <li> Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>llvm-gcc</tt> source,
+ and <tt>llvm-gcc</tt> binaries in this new directory. </li>
+ <li> Copy and commit the <tt>llvm/docs</tt> and <tt>LICENSE.txt</tt>
+ files into this new directory. The docs should be built with BUILD_FOR_WEBSITE=1.</li>
+ <li> Commit the index.html to the release/X.X directory to redirect (use from previous
+ release. </li>
+ <li> Update the <tt>releases/download.html</tt> file with the new release. </li>
+ <li>Update the <tt>releases/index.html</tt> with the new release and link to
+ release documentation.</li>
+ <li> Finally, update the main page (<tt>index.html</tt> and sidebar) to
+ point to the new release and release announcement. Make sure this all gets
+ commited back into Subversion.</li>
+ </ol>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="announce">Announce the Release</a></div>
+ <div class="doc_text">
+ <p>Have Chris send out the release announcement when everything is finished.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="dist_targets">Distribution Targets</a></div>
+ <!-- *********************************************************************** -->
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">Overview</div>
+ <div class="doc_text">
+ <p>
+ The first thing you need to understand is that there are multiple make targets
+ to support this feature. Here's an overview, we'll delve into the details
+ later.
+ </p>
+
+ <ul>
+ <li><b>distdir</b> - builds the distribution directory from which the
+ distribution will be packaged</li>
+ <li><b>dist</b> - builds each of the distribution tarballs (tar.gz,
+ tar.bzip2, .zip). These can be built individually as well, with separate
+ targets.</li>
+ <li><b>dist-check</b> - this is identical to <tt>dist</tt> but includes a
+ check on the distribution that ensures the tarball can: unpack
+ successfully, compile correctly, pass '<tt>make check</tt>', and pass
+ '<tt>make clean</tt>'.</li>
+ <li><b>dist-clean</b>- this just does a normal clean but also cleans up the
+ stuff generated by the other three <tt>dist</tt> targets (above).</li>
+ </ul>
+
+ <p>
+ Okay, that's the basic functionality. When making a release, we want to ensure
+ that the tree you build the distribution from passes
+ <tt>dist-check</tt>. Beyond fixing the usual bugs, there is generally one
+ impediment to making the release in this fashion: missing files. The
+ <tt>dist-check</tt> process guards against that possibility. It will either
+ fail and that failure will indicate what's missing, or it will succeed meaning
+ that it has proved that the tarballs can actually succeed in building LLVM
+ correctly and that it passes <tt>make check</tt>.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+
+ <div class="doc_subsection">distdir</div>
+ <div class="doc_text">
+ <p>
+ This target builds the distribution directory which is the directory from
+ which the tarballs are generated. The distribution directory has the same
+ name as the release, e.g. LLVM-1.7). This target goes through the following
+ process:
+ </p>
+
+ <ol>
+ <li>First, if there was an old distribution directory (for the current
+ release), it is removed in its entirety and you see <tt>Removing old
+ LLVM-1.7</tt></li>
+ <li>Second, it issues a <tt>make all ENABLE_OPTIMIZED=3D1</tt> to ensure
+ that the everything in your tree can be built in release mode. Often
+ times there are discrepancies in building between debug and release
+ modes so it enforces release mode first. If that fails, the
+ <tt>distdir</tt> target fails too. This is preceded by the message
+ <tt>Making 'all' to verify build</tt>.</li>
+ <li>Next, it traverses your source tree and copies it to a new directory
+ that has the name of the release (<tt>LLVM-M.m</tt> in our current
+ case). This is the directory that will get tar'd. It contains all the
+ software that needs to be in the distribution. During the copying
+ process, it omits generated files, SVN directories, and any other
+ "cruft" that's in your build tree. This is done to eliminate the
+ possibility of huge distribution tarballs that include useless or
+ irrelevant stuff in them. This is the trickiest part of making the
+ distribution. Done manually you will either include stuff that
+ shouldn't be in the distribution or exclude stuff that should. This
+ step is preceded by the message <tt>Building Distribution Directory
+ LLVM-1.7</tt></li>
+ <li>The distribution directory is then traversed and all <tt>CVS</tt> or
+ <tt>.svn</tt> directories are removed. You see: <tt>Eliminating CVS/.svn
+ directories from distribution</tt></li>
+ <li>The recursive <tt>dist-hook</tt> target is executed. This gives each
+ directory a chance to modify the distribution in some way (more on this
+ below).</li>
+ <li>The distribution directory is traversed and the correct file
+ permissions and modes are set based on the type of file.</li>
+ </ol>
+
+ <p>
+ To control the process of making the distribution directory correctly, each
+ Makefile can utilize two features:
+ </p>
+
+ <ol>
+ <li><b><tt>EXTRA_DIST</tt></B> - this make variable specifies which files
+ it should distribute. By default, all source files are automatically
+ included for distribution as well as certain <tt>well known</tt> files
+ (see DistAlways variable in Makefile.rules for details). Each Makefile
+ specifies, via the <tt>EXTRA_DIST</tt> variable, which additional files
+ need to be distributed. Only those files that are needed to build LLVM
+ should be added to <tt>EXTRA_DIST</tt>. <tt>EXTRA_DIST</tt> contains a
+ list of file or directory names that should be distributed. For example,
+ the top level Makefile contains <tt>EXTRA_DIST := test llvm.spec
+ include</tt>. This means that in addition to regular things that are
+ distributed at the top level (<tt>CREDITS.txt, LICENSE.txt</tt>, etc.)
+ the distribution should contain the entire <tt>test</tt> and
+ <tt>include</tt> directories as well as the <tt>llvm.spec</tt> file.</li>
+ <li><b><tt>dist-hook</tt></B> - this make target can be used to alter the
+ content of the distribution directory. For example, in the top level
+ Makefile there is some logic to eliminate files in the <tt>include</tt>
+ subtree that are generated by the configure script. These should not be
+ distributed. Similarly, any <tt>dist-hook</tt> target found in any
+ directory can add or remove or modify things just before it gets
+ packaged. Any transformation is permitted. Generally, not much is
+ needed.</li>
+ </ol>
+
+ <p>
+ You will see various messages if things go wrong:
+ </p>
+
+ <ol>
+ <li>During the copying process, any files that are missing will be flagged
+ with: <tt>===== WARNING: Distribution Source 'dir/file' Not Found!</tt>
+ These must be corrected by either adding the file or removing it from
+ <tt>EXTRA_DIST</tt>.</li>
+ <li>If you build the distribution with <tt>VERBOSE=1</tt>, then you might
+ also see: <tt>Skipping non-existent 'dir/file'</tt> in certain cases
+ where it's okay to skip the file.</li>
+ <li>The target can fail if any of the things it does fail. Error messages
+ should indicate what went wrong.</li>
+ </ol>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">dist</div>
+ <div class="doc_text">
+ <p>
+ This target does exactly what <tt>distdir</tt> target does, but also includes
+ assembling the tarballs. There are actually four related targets here:
+ </p>
+
+ <ul>
+ <li><b><tt>dist-gzip</tt></b>: package the gzipped distribution tar
+ file. The distribution directory is packaged into a single file ending
+ in <tt>.tar.gz</tt> which is gzip compressed.</li>
+ <li><b><tt>dist-bzip2</tt></b>: package the bzip2 distribution tar file.
+ The distribution directory is packaged into a single file ending in
+ <tt>.tar.bzip2</tt> which is bzip2 compressed.</li>
+ <li><b><tt>dist-zip</tt></b>: package the zip distribution file. The
+ distribution directory is packaged into a single file ending in
+ <tt>.zip</tt> which is zip compressed.</li>
+ <li><b><tt>dist</tt></b>: does all three, dist-gzip, dist-bzip2,
+ dist-zip</li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">dist-check</div>
+ <div class="doc_text">
+ <p>
+ This target checks the distribution. The basic idea is that it unpacks the
+ distribution tarball and ensures that it can build. It takes the following
+ actions:
+ </p>
+
+ <ol>
+ <li>It depends on the <tt>dist-gzip</tt> target which, if it hasn't already
+ been built, builds the gzip tar bundle (see dist and distdir
+ above).</li>
+ <li>removes any pre-existing <tt>_distcheckdir</tt> at the top level.</li>
+ <li>creates a new <tt>_distcheckdir</tt> directory at the top level.</li>
+ <li>creates a <tt>build</tt> subdirectory and an <tt>install</tt>
+ subdirectory under <tt>_distcheckdir</tt>.</li>
+ <li>unzips and untars the release tarball into <tt>_distcheckdir</tt>,
+ creating <tt>LLVM-1.7</tt> directory (from the tarball).</li>
+ <li>in the build subdirectory, it configures with appropriate options to
+ build from the unpacked source tarball into the <tt>build</tt> directory
+ with installation in the <tt>install</tt> directory.</li>
+ <li>runs <tt>make all</tt></li>
+ <li>runs <tt>make </tt><tt>check</tt></li>
+ <li>runs <tt>make install</tt></li>
+ <li>runs <tt>make uninstall</tt></li>
+ <li>runs <tt>make dist</tt></li>
+ <li>runs <tt>make clean</tt></li>
+ <li>runs <tt>make dist-clean</tt></li>
+ </ol>
+
+ <p>
+ If it can pass all that, the distribution will be deemed distribution worth y
+ and you will see:
+ </p>
+
+ <pre>===== LLVM-1.7.tar.gz Ready For Distribution =====</pre>
+
+ <p>
+ This means the tarball should then be tested on other platforms and have the
+ nightly test run against it. If those all pass, THEN it is ready for
+ distribution.
+ </p>
+
+ <p>
+ A note about disk space: using <tt>dist-check</tt> will easily triple the
+ amount of disk space your build tree is using. You might want to check
+ available space before you begin.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">dist-clean</div>
+ <div class="doc_text">
+ <p>
+ In addition to doing a normal <tt>clean</tt>, this target will clean up the
+ files and directories created by the distribution targets. In particular the
+ distribution directory (<tt>LLVM-X.X</tt>), check directory
+ (<tt>_distcheckdir</tt>), and the various tarballs will be removed. You do
+ this after the release has shipped and you no longer need this stuff in your
+ build tree.
+ </p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
+ <br/>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/HowToSubmitABug.html
diff -c /dev/null llvm-www/releases/2.3/docs/HowToSubmitABug.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/HowToSubmitABug.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,355 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>How to submit an LLVM bug report</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">
+ How to submit an LLVM bug report
+ </div>
+
+ <table class="layout" style="width: 90%" >
+ <tr class="layout">
+ <td class="left">
+ <ol>
+ <li><a href="#introduction">Introduction - Got bugs?</a></li>
+ <li><a href="#crashers">Crashing Bugs</a>
+ <ul>
+ <li><a href="#front-end">Front-end bugs</a>
+ <li><a href="#ct_optimizer">Compile-time optimization bugs</a>
+ <li><a href="#ct_codegen">Code generator bugs</a>
+ </ul></li>
+ <li><a href="#miscompilations">Miscompilations</a></li>
+ <li><a href="#codegen">Incorrect code generation (JIT and LLC)</a></li>
+ </ol>
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a> and
+ <a href="http://misha.brukman.net">Misha Brukman</a></p>
+ </div>
+ </td>
+ <td class="right">
+ <img src="img/Debugging.gif" alt="Debugging" width="444" height="314">
+ </td>
+ </tr>
+ </table>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction - Got bugs?</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>If you're working with LLVM and run into a bug, we definitely want to know
+ about it. This document describes what you can do to increase the odds of
+ getting it fixed quickly.</p>
+
+ <p>Basically you have to do two things at a minimum. First, decide whether the
+ bug <a href="#crashers">crashes the compiler</a> (or an LLVM pass), or if the
+ compiler is <a href="#miscompilations">miscompiling</a> the program (i.e., the
+ compiler successfully produces an executable, but it doesn't run right). Based
+ on
+ what type of bug it is, follow the instructions in the linked section to narrow
+ down the bug so that the person who fixes it will be able to find the problem
+ more easily.</p>
+
+ <p>Once you have a reduced test-case, go to <a
+ href="http://llvm.org/bugs/enter_bug.cgi">the LLVM Bug Tracking
+ System</a> and fill out the form with the necessary details (note that you don't
+ need to pick a catagory, just use the "new-bugs" catagory if you're not sure).
+ The bug description should contain the following
+ information:</p>
+
+ <ul>
+ <li>All information necessary to reproduce the problem.</li>
+ <li>The reduced test-case that triggers the bug.</li>
+ <li>The location where you obtained LLVM (if not from our Subversion
+ repository).</li>
+ </ul>
+
+ <p>Thanks for helping us make LLVM better!</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="crashers">Crashing Bugs</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>More often than not, bugs in the compiler cause it to crash—often due
+ to an assertion failure of some sort. The most important
+ piece of the puzzle is to figure out if it is crashing in the GCC front-end
+ or if it is one of the LLVM libraries (e.g. the optimizer or code generator)
+ that has problems.</p>
+
+ <p>To figure out which component is crashing (the front-end,
+ optimizer or code generator), run the
+ <tt><b>llvm-gcc</b></tt> command line as you were when the crash occurred, but
+ with the following extra command line options:</p>
+
+ <ul>
+ <li><tt><b>-O0 -emit-llvm</b></tt>: If <tt>llvm-gcc</tt> still crashes when
+ passed these options (which disable the optimizer and code generator), then
+ the crash is in the front-end. Jump ahead to the section on <a
+ href="#front-end">front-end bugs</a>.</li>
+
+ <li><tt><b>-emit-llvm</b></tt>: If <tt>llvm-gcc</tt> crashes with this option
+ (which disables the code generator), you found an optimizer bug. Jump ahead
+ to <a href="#ct_optimizer"> compile-time optimization bugs</a>.</li>
+
+ <li>Otherwise, you have a code generator crash. Jump ahead to <a
+ href="#ct_codegen">code generator bugs</a>.</li>
+
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="front-end">Front-end bugs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If the problem is in the front-end, you should re-run the same
+ <tt>llvm-gcc</tt> command that resulted in the crash, but add the
+ <tt>-save-temps</tt> option. The compiler will crash again, but it will leave
+ behind a <tt><i>foo</i>.i</tt> file (containing preprocessed C source code) and
+ possibly <tt><i>foo</i>.s</tt> for each
+ compiled <tt><i>foo</i>.c</tt> file. Send us the <tt><i>foo</i>.i</tt> file,
+ along with the options you passed to llvm-gcc, and a brief description of the
+ error it caused.</p>
+
+ <p>The <a href="http://delta.tigris.org/">delta</a> tool helps to reduce the
+ preprocessed file down to the smallest amount of code that still replicates the
+ problem. You're encouraged to use delta to reduce the code to make the
+ developers' lives easier. <a
+ href="http://gcc.gnu.org/wiki/A_guide_to_testcase_reduction">This website</a>
+ has instructions on the best way to use delta.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="ct_optimizer">Compile-time optimization bugs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If you find that a bug crashes in the optimizer, compile your test-case to a
+ <tt>.bc</tt> file by passing "<tt><b>-emit-llvm -O0 -c -o foo.bc</b></tt>".
+ Then run:</p>
+
+ <div class="doc_code">
+ <p><tt><b>opt</b> -std-compile-opts -debug-pass=Arguments foo.bc
+ -disable-output</tt></p>
+ </div>
+
+ <p>This command should do two things: it should print out a list of passes, and
+ then it should crash in the same was as llvm-gcc. If it doesn't crash, please
+ follow the instructions for a <a href="#front-end">front-end bug</a>.</p>
+
+ <p>If this does crash, then you should be able to debug this with the following
+ bugpoint command:</p>
+
+ <div class="doc_code">
+ <p><tt><b>bugpoint</b> foo.bc <list of passes printed by
+ <b>opt</b>></tt></p>
+ </div>
+
+ <p>Please run this, then file a bug with the instructions and reduced .bc files
+ that bugpoint emits. If something goes wrong with bugpoint, please submit the
+ "foo.bc" file and the list of passes printed by <b>opt</b>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="ct_codegen">Code generator bugs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If you find a bug that crashes llvm-gcc in the code generator, compile your
+ source file to a .bc file by passing "<tt><b>-emit-llvm -c -o foo.bc</b></tt>"
+ to llvm-gcc (in addition to the options you already pass). Once your have
+ foo.bc, one of the following commands should fail:</p>
+
+ <ol>
+ <li><tt><b>llc</b> foo.bc -f</tt></li>
+ <li><tt><b>llc</b> foo.bc -f -relocation-model=pic</tt></li>
+ <li><tt><b>llc</b> foo.bc -f -relocation-model=static</tt></li>
+ <li><tt><b>llc</b> foo.bc -f -enable-eh</tt></li>
+ <li><tt><b>llc</b> foo.bc -f -relocation-model=pic -enable-eh</tt></li>
+ <li><tt><b>llc</b> foo.bc -f -relocation-model=static -enable-eh</tt></li>
+ </ol>
+
+ <p>If none of these crash, please follow the instructions for a
+ <a href="#front-end">front-end bug</a>. If one of these do crash, you should
+ be able to reduce this with one of the following bugpoint command lines (use
+ the one corresponding to the command above that failed):</p>
+
+ <ol>
+ <li><tt><b>bugpoint</b> -run-llc foo.bc</tt></li>
+ <li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args
+ -relocation-model=pic</tt></li>
+ <li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args
+ -relocation-model=static</tt></li>
+ <li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args -enable-eh</tt></li>
+ <li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args
+ -relocation-model=pic -enable-eh</tt></li>
+ <li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args
+ -relocation-model=static -enable-eh</tt></li>
+ </ol>
+
+ <p>Please run this, then file a bug with the instructions and reduced .bc file
+ that bugpoint emits. If something goes wrong with bugpoint, please submit the
+ "foo.bc" file and the option that llc crashes with.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="miscompilations">Miscompilations</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>If llvm-gcc successfully produces an executable, but that executable doesn't
+ run right, this is either a bug in the code or a bug in the
+ compiler. The first thing to check is to make sure it is not using undefined
+ behavior (e.g. reading a variable before it is defined). In particular, check
+ to see if the program <a href="http://valgrind.org/">valgrind</a>s clean,
+ passes purify, or some other memory checker tool. Many of the "LLVM bugs" that
+ we have chased down ended up being bugs in the program being compiled, not
+ LLVM.</p>
+
+ <p>Once you determine that the program itself is not buggy, you should choose
+ which code generator you wish to compile the program with (e.g. C backend, the
+ JIT, or LLC) and optionally a series of LLVM passes to run. For example:</p>
+
+ <div class="doc_code">
+ <p><tt>
+ <b>bugpoint</b> -run-cbe [... optzn passes ...] file-to-test.bc --args -- [program arguments]</tt></p>
+ </div>
+
+ <p><tt>bugpoint</tt> will try to narrow down your list of passes to the one pass
+ that causes an error, and simplify the bitcode file as much as it can to assist
+ you. It will print a message letting you know how to reproduce the resulting
+ error.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="codegen">Incorrect code generation</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Similarly to debugging incorrect compilation by mis-behaving passes, you can
+ debug incorrect code generation by either LLC or the JIT, using
+ <tt>bugpoint</tt>. The process <tt>bugpoint</tt> follows in this case is to try
+ to narrow the code down to a function that is miscompiled by one or the other
+ method, but since for correctness, the entire program must be run,
+ <tt>bugpoint</tt> will compile the code it deems to not be affected with the C
+ Backend, and then link in the shared object it generates.</p>
+
+ <p>To debug the JIT:</p>
+
+ <div class="doc_code">
+ <pre>
+ bugpoint -run-jit -output=[correct output file] [bitcode file] \
+ --tool-args -- [arguments to pass to lli] \
+ --args -- [program arguments]
+ </pre>
+ </div>
+
+ <p>Similarly, to debug the LLC, one would run:</p>
+
+ <div class="doc_code">
+ <pre>
+ bugpoint -run-llc -output=[correct output file] [bitcode file] \
+ --tool-args -- [arguments to pass to llc] \
+ --args -- [program arguments]
+ </pre>
+ </div>
+
+ <p><b>Special note:</b> if you are debugging MultiSource or SPEC tests that
+ already exist in the <tt>llvm/test</tt> hierarchy, there is an easier way to
+ debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which
+ will pass the program options specified in the Makefiles:</p>
+
+ <div class="doc_code">
+ <p><tt>
+ cd llvm/test/../../program<br>
+ make bugpoint-jit
+ </tt></p>
+ </div>
+
+ <p>At the end of a successful <tt>bugpoint</tt> run, you will be presented
+ with two bitcode files: a <em>safe</em> file which can be compiled with the C
+ backend and the <em>test</em> file which either LLC or the JIT
+ mis-codegenerates, and thus causes the error.</p>
+
+ <p>To reproduce the error that <tt>bugpoint</tt> found, it is sufficient to do
+ the following:</p>
+
+ <ol>
+
+ <li><p>Regenerate the shared object from the safe bitcode file:</p>
+
+ <div class="doc_code">
+ <p><tt>
+ <b>llc</b> -march=c safe.bc -o safe.c<br>
+ <b>gcc</b> -shared safe.c -o safe.so
+ </tt></p>
+ </div></li>
+
+ <li><p>If debugging LLC, compile test bitcode native and link with the shared
+ object:</p>
+
+ <div class="doc_code">
+ <p><tt>
+ <b>llc</b> test.bc -o test.s -f<br>
+ <b>gcc</b> test.s safe.so -o test.llc<br>
+ ./test.llc [program options]
+ </tt></p>
+ </div></li>
+
+ <li><p>If debugging the JIT, load the shared object and supply the test
+ bitcode:</p>
+
+ <div class="doc_code">
+ <p><tt><b>lli</b> -load=safe.so test.bc [program options]</tt></p>
+ </div></li>
+
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <hr>
+ <address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a>
+ <br>
+ Last modified: $Date: 2008/06/09 08:20:32 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/2.3/docs/LangRef.html
diff -c /dev/null llvm-www/releases/2.3/docs/LangRef.html:1.1
*** /dev/null Mon Jun 9 03:21:47 2008
--- llvm-www/releases/2.3/docs/LangRef.html Mon Jun 9 03:20:32 2008
***************
*** 0 ****
--- 1,5745 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>LLVM Assembly Language Reference Manual</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <meta name="author" content="Chris Lattner">
+ <meta name="description"
+ content="LLVM Assembly Language Reference Manual.">
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+
+ <body>
+
+ <div class="doc_title"> LLVM Language Reference Manual </div>
+ <ol>
+ <li><a href="#abstract">Abstract</a></li>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#identifiers">Identifiers</a></li>
+ <li><a href="#highlevel">High Level Structure</a>
+ <ol>
+ <li><a href="#modulestructure">Module Structure</a></li>
+ <li><a href="#linkage">Linkage Types</a></li>
+ <li><a href="#callingconv">Calling Conventions</a></li>
+ <li><a href="#globalvars">Global Variables</a></li>
+ <li><a href="#functionstructure">Functions</a></li>
+ <li><a href="#aliasstructure">Aliases</a>
+ <li><a href="#paramattrs">Parameter Attributes</a></li>
+ <li><a href="#gc">Garbage Collector Names</a></li>
+ <li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
+ <li><a href="#datalayout">Data Layout</a></li>
+ </ol>
+ </li>
+ <li><a href="#typesystem">Type System</a>
+ <ol>
+ <li><a href="#t_classifications">Type Classifications</a></li>
+ <li><a href="#t_primitive">Primitive Types</a>
+ <ol>
+ <li><a href="#t_floating">Floating Point Types</a></li>
+ <li><a href="#t_void">Void Type</a></li>
+ <li><a href="#t_label">Label Type</a></li>
+ </ol>
+ </li>
+ <li><a href="#t_derived">Derived Types</a>
+ <ol>
+ <li><a href="#t_integer">Integer Type</a></li>
+ <li><a href="#t_array">Array Type</a></li>
+ <li><a href="#t_function">Function Type</a></li>
+ <li><a href="#t_pointer">Pointer Type</a></li>
+ <li><a href="#t_struct">Structure Type</a></li>
+ <li><a href="#t_pstruct">Packed Structure Type</a></li>
+ <li><a href="#t_vector">Vector Type</a></li>
+ <li><a href="#t_opaque">Opaque Type</a></li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li><a href="#constants">Constants</a>
+ <ol>
+ <li><a href="#simpleconstants">Simple Constants</a>
+ <li><a href="#aggregateconstants">Aggregate Constants</a>
+ <li><a href="#globalconstants">Global Variable and Function Addresses</a>
+ <li><a href="#undefvalues">Undefined Values</a>
+ <li><a href="#constantexprs">Constant Expressions</a>
+ </ol>
+ </li>
+ <li><a href="#othervalues">Other Values</a>
+ <ol>
+ <li><a href="#inlineasm">Inline Assembler Expressions</a>
+ </ol>
+ </li>
+ <li><a href="#instref">Instruction Reference</a>
+ <ol>
+ <li><a href="#terminators">Terminator Instructions</a>
+ <ol>
+ <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
+ <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
+ <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
+ <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
+ <li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li>
+ <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
+ </ol>
+ </li>
+ <li><a href="#binaryops">Binary Operations</a>
+ <ol>
+ <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
+ <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
+ <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
+ <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li>
+ <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li>
+ <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li>
+ <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li>
+ <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li>
+ <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li>
+ </ol>
+ </li>
+ <li><a href="#bitwiseops">Bitwise Binary Operations</a>
+ <ol>
+ <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
+ <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li>
+ <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li>
+ <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
+ <li><a href="#i_or">'<tt>or</tt>' Instruction</a></li>
+ <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
+ </ol>
+ </li>
+ <li><a href="#vectorops">Vector Operations</a>
+ <ol>
+ <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
+ <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
+ <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
+ </ol>
+ </li>
+ <li><a href="#memoryops">Memory Access and Addressing Operations</a>
+ <ol>
+ <li><a href="#i_malloc">'<tt>malloc</tt>' Instruction</a></li>
+ <li><a href="#i_free">'<tt>free</tt>' Instruction</a></li>
+ <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li>
+ <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li>
+ <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li>
+ <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
+ </ol>
+ </li>
+ <li><a href="#convertops">Conversion Operations</a>
+ <ol>
+ <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
+ <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
+ <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
+ <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
+ <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
+ <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li>
+ <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li>
+ <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li>
+ <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li>
+ <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li>
+ <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li>
+ <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li>
+ </ol>
+ <li><a href="#otherops">Other Operations</a>
+ <ol>
+ <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li>
+ <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li>
+ <li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li>
+ <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
+ <li><a href="#i_call">'<tt>call</tt>' Instruction</a></li>
+ <li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a></li>
+ <li><a href="#i_getresult">'<tt>getresult</tt>' Instruction</a></li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li><a href="#intrinsics">Intrinsic Functions</a>
+ <ol>
+ <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
+ <ol>
+ <li><a href="#int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
+ <li><a href="#int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a></li>
+ <li><a href="#int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
+ <ol>
+ <li><a href="#int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
+ <li><a href="#int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
+ <li><a href="#int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ <li><a href="#int_codegen">Code Generator Intrinsics</a>
+ <ol>
+ <li><a href="#int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
+ <li><a href="#int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li>
+ <li><a href="#int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li>
+ <li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
+ <li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
+ <li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
+ <li><a href="#int_readcyclecounter"><tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ <li><a href="#int_libc">Standard C Library Intrinsics</a>
+ <ol>
+ <li><a href="#int_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ <li><a href="#int_manip">Bit Manipulation Intrinsics</a>
+ <ol>
+ <li><a href="#int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li>
+ <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li>
+ <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li>
+ <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li>
+ <li><a href="#int_part_select">'<tt>llvm.part.select.*</tt>' Intrinsic </a></li>
+ <li><a href="#int_part_set">'<tt>llvm.part.set.*</tt>' Intrinsic </a></li>
+ </ol>
+ </li>
+ <li><a href="#int_debugger">Debugger intrinsics</a></li>
+ <li><a href="#int_eh">Exception Handling intrinsics</a></li>
+ <li><a href="#int_trampoline">Trampoline Intrinsic</a>
+ <ol>
+ <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ <li><a href="#int_atomics">Atomic intrinsics</a>
+ <ol>
+ <li><a href="#int_memory_barrier"><tt>llvm.memory_barrier</tt></a></li>
+ <li><a href="#int_atomic_lcs"><tt>llvm.atomic.lcs</tt></a></li>
+ <li><a href="#int_atomic_las"><tt>llvm.atomic.las</tt></a></li>
+ <li><a href="#int_atomic_swap"><tt>llvm.atomic.swap</tt></a></li>
+ </ol>
+ </li>
+ <li><a href="#int_general">General intrinsics</a>
+ <ol>
+ <li><a href="#int_var_annotation">
+ <tt>llvm.var.annotation</tt>' Intrinsic</a></li>
+ <li><a href="#int_annotation">
+ <tt>llvm.annotation.*</tt>' Intrinsic</a></li>
+ <li><a href="#int_trap">
+ <tt>llvm.trap</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a>
+ and <a href="mailto:vadve at cs.uiuc.edu">Vikram Adve</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="abstract">Abstract </a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>This document is a reference manual for the LLVM assembly language.
+ LLVM is an SSA based representation that provides type safety,
+ low-level operations, flexibility, and the capability of representing
+ 'all' high-level languages cleanly. It is the common code
+ representation used throughout all phases of the LLVM compilation
+ strategy.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="introduction">Introduction</a> </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The LLVM code representation is designed to be used in three
+ different forms: as an in-memory compiler IR, as an on-disk bitcode
+ representation (suitable for fast loading by a Just-In-Time compiler),
+ and as a human readable assembly language representation. This allows
+ LLVM to provide a powerful intermediate representation for efficient
+ compiler transformations and analysis, while providing a natural means
+ to debug and visualize the transformations. The three different forms
+ of LLVM are all equivalent. This document describes the human readable
+ representation and notation.</p>
+
+ <p>The LLVM representation aims to be light-weight and low-level
+ while being expressive, typed, and extensible at the same time. It
+ aims to be a "universal IR" of sorts, by being at a low enough level
+ that high-level ideas may be cleanly mapped to it (similar to how
+ microprocessors are "universal IR's", allowing many source languages to
+ be mapped to them). By providing type information, LLVM can be used as
+ the target of optimizations: for example, through pointer analysis, it
+ can be proven that a C automatic variable is never accessed outside of
+ the current function... allowing it to be promoted to a simple SSA
+ value instead of a memory location.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div>
+
+ <div class="doc_text">
+
+ <p>It is important to note that this document describes 'well formed'
+ LLVM assembly language. There is a difference between what the parser
+ accepts and what is considered 'well formed'. For example, the
+ following instruction is syntactically okay, but not well formed:</p>
+
+ <div class="doc_code">
+ <pre>
+ %x = <a href="#i_add">add</a> i32 1, %x
+ </pre>
+ </div>
+
+ <p>...because the definition of <tt>%x</tt> does not dominate all of
+ its uses. The LLVM infrastructure provides a verification pass that may
+ be used to verify that an LLVM module is well formed. This pass is
+ automatically run by the parser after parsing input assembly and by
+ the optimizer before it outputs bitcode. The violations pointed out
+ by the verifier pass indicate bugs in transformation passes or input to
+ the parser.</p>
+ </div>
+
+ <!-- Describe the typesetting conventions here. -->
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>LLVM identifiers come in two basic types: global and local. Global
+ identifiers (functions, global variables) begin with the @ character. Local
+ identifiers (register names, types) begin with the % character. Additionally,
+ there are three different formats for identifiers, for different purposes:
+
+ <ol>
+ <li>Named values are represented as a string of characters with their prefix.
+ For example, %foo, @DivisionByZero, %a.really.long.identifier. The actual
+ regular expression used is '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
+ Identifiers which require other characters in their names can be surrounded
+ with quotes. In this way, anything except a <tt>"</tt> character can
+ be used in a named value.</li>
+
+ <li>Unnamed values are represented as an unsigned numeric value with their
+ prefix. For example, %12, @2, %44.</li>
+
+ <li>Constants, which are described in a <a href="#constants">section about
+ constants</a>, below.</li>
+ </ol>
+
+ <p>LLVM requires that values start with a prefix for two reasons: Compilers
+ don't need to worry about name clashes with reserved words, and the set of
+ reserved words may be expanded in the future without penalty. Additionally,
+ unnamed identifiers allow a compiler to quickly come up with a temporary
+ variable without having to avoid symbol table conflicts.</p>
+
+ <p>Reserved words in LLVM are very similar to reserved words in other
+ languages. There are keywords for different opcodes
+ ('<tt><a href="#i_add">add</a></tt>',
+ '<tt><a href="#i_bitcast">bitcast</a></tt>',
+ '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names ('<tt><a
+ href="#t_void">void</a></tt>', '<tt><a href="#t_primitive">i32</a></tt>', etc...),
+ and others. These reserved words cannot conflict with variable names, because
+ none of them start with a prefix character ('%' or '@').</p>
+
+ <p>Here is an example of LLVM code to multiply the integer variable
+ '<tt>%X</tt>' by 8:</p>
+
+ <p>The easy way:</p>
+
+ <div class="doc_code">
+ <pre>
+ %result = <a href="#i_mul">mul</a> i32 %X, 8
+ </pre>
+ </div>
+
+ <p>After strength reduction:</p>
+
+ <div class="doc_code">
+ <pre>
+ %result = <a href="#i_shl">shl</a> i32 %X, i8 3
+ </pre>
+ </div>
+
+ <p>And the hard way:</p>
+
+ <div class="doc_code">
+ <pre>
+ <a href="#i_add">add</a> i32 %X, %X <i>; yields {i32}:%0</i>
+ <a href="#i_add">add</a> i32 %0, %0 <i>; yields {i32}:%1</i>
+ %result = <a href="#i_add">add</a> i32 %1, %1
+ </pre>
+ </div>
+
+ <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several
+ important lexical features of LLVM:</p>
+
+ <ol>
+
+ <li>Comments are delimited with a '<tt>;</tt>' and go until the end of
+ line.</li>
+
+ <li>Unnamed temporaries are created when the result of a computation is not
+ assigned to a named value.</li>
+
+ <li>Unnamed temporaries are numbered sequentially</li>
+
+ </ol>
+
+ <p>...and it also shows a convention that we follow in this document. When
+ demonstrating instructions, we will follow an instruction with a comment that
+ defines the type and name of value produced. Comments are shown in italic
+ text.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="highlevel">High Level Structure</a> </div>
+ <!-- *********************************************************************** -->
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="modulestructure">Module Structure</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM programs are composed of "Module"s, each of which is a
+ translation unit of the input programs. Each module consists of
+ functions, global variables, and symbol table entries. Modules may be
+ combined together with the LLVM linker, which merges function (and
+ global variable) definitions, resolves forward declarations, and merges
+ symbol table entries. Here is an example of the "hello world" module:</p>
+
+ <div class="doc_code">
+ <pre><i>; Declare the string constant as a global constant...</i>
+ <a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a
+ href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; [13 x i8]*</i>
+
+ <i>; External declaration of the puts function</i>
+ <a href="#functionstructure">declare</a> i32 @puts(i8 *) <i>; i32(i8 *)* </i>
+
+ <i>; Definition of main function</i>
+ define i32 @main() { <i>; i32()* </i>
+ <i>; Convert [13x i8 ]* to i8 *...</i>
+ %cast210 = <a
+ href="#i_getelementptr">getelementptr</a> [13 x i8 ]* @.LC0, i64 0, i64 0 <i>; i8 *</i>
+
+ <i>; Call puts function to write out the string to stdout...</i>
+ <a
+ href="#i_call">call</a> i32 @puts(i8 * %cast210) <i>; i32</i>
+ <a
+ href="#i_ret">ret</a> i32 0<br>}<br>
+ </pre>
+ </div>
+
+ <p>This example is made up of a <a href="#globalvars">global variable</a>
+ named "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>"
+ function, and a <a href="#functionstructure">function definition</a>
+ for "<tt>main</tt>".</p>
+
+ <p>In general, a module is made up of a list of global values,
+ where both functions and global variables are global values. Global values are
+ represented by a pointer to a memory location (in this case, a pointer to an
+ array of char, and a pointer to a function), and have one of the following <a
+ href="#linkage">linkage types</a>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="linkage">Linkage Types</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ All Global Variables and Functions have one of the following types of linkage:
+ </p>
+
+ <dl>
+
+ <dt><tt><b><a name="linkage_internal">internal</a></b></tt> </dt>
+
+ <dd>Global values with internal linkage are only directly accessible by
+ objects in the current module. In particular, linking code into a module with
+ an internal global value may cause the internal to be renamed as necessary to
+ avoid collisions. Because the symbol is internal to the module, all
+ references can be updated. This corresponds to the notion of the
+ '<tt>static</tt>' keyword in C.
+ </dd>
+
+ <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt>
+
+ <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
+ the same name when linkage occurs. This is typically used to implement
+ inline functions, templates, or other code which must be generated in each
+ translation unit that uses it. Unreferenced <tt>linkonce</tt> globals are
+ allowed to be discarded.
+ </dd>
+
+ <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
+
+ <dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt> linkage,
+ except that unreferenced <tt>weak</tt> globals may not be discarded. This is
+ used for globals that may be emitted in multiple translation units, but that
+ are not guaranteed to be emitted into every translation unit that uses them.
+ One example of this are common globals in C, such as "<tt>int X;</tt>" at
+ global scope.
+ </dd>
+
+ <dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt>
+
+ <dd>"<tt>appending</tt>" linkage may only be applied to global variables of
+ pointer to array type. When two global variables with appending linkage are
+ linked together, the two global arrays are appended together. This is the
+ LLVM, typesafe, equivalent of having the system linker append together
+ "sections" with identical names when .o files are linked.
+ </dd>
+
+ <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt>: </dt>
+ <dd>The semantics of this linkage follow the ELF model: the symbol is weak
+ until linked, if not linked, the symbol becomes null instead of being an
+ undefined reference.
+ </dd>
+
+ <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
+
+ <dd>If none of the above identifiers are used, the global is externally
+ visible, meaning that it participates in linkage and can be used to resolve
+ external symbol references.
+ </dd>
+ </dl>
+
+ <p>
+ The next two types of linkage are targeted for Microsoft Windows platform
+ only. They are designed to support importing (exporting) symbols from (to)
+ DLLs.
+ </p>
+
+ <dl>
+ <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt>: </dt>
+
+ <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
+ or variable via a global pointer to a pointer that is set up by the DLL
+ exporting the symbol. On Microsoft Windows targets, the pointer name is
+ formed by combining <code>_imp__</code> and the function or variable name.
+ </dd>
+
+ <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt>: </dt>
+
+ <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
+ pointer to a pointer in a DLL, so that it can be referenced with the
+ <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
+ name is formed by combining <code>_imp__</code> and the function or variable
+ name.
+ </dd>
+
+ </dl>
+
+ <p><a name="linkage_external"></a>For example, since the "<tt>.LC0</tt>"
+ variable is defined to be internal, if another module defined a "<tt>.LC0</tt>"
+ variable and was linked with this one, one of the two would be renamed,
+ preventing a collision. Since "<tt>main</tt>" and "<tt>puts</tt>" are
+ external (i.e., lacking any linkage declarations), they are accessible
+ outside of the current module.</p>
+ <p>It is illegal for a function <i>declaration</i>
+ to have any linkage type other than "externally visible", <tt>dllimport</tt>,
+ or <tt>extern_weak</tt>.</p>
+ <p>Aliases can have only <tt>external</tt>, <tt>internal</tt> and <tt>weak</tt>
+ linkages.
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="callingconv">Calling Conventions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
+ and <a href="#i_invoke">invokes</a> can all have an optional calling convention
+ specified for the call. The calling convention of any pair of dynamic
+ caller/callee must match, or the behavior of the program is undefined. The
+ following calling conventions are supported by LLVM, and more may be added in
+ the future:</p>
+
+ <dl>
+ <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
+
+ <dd>This calling convention (the default if no other calling convention is
+ specified) matches the target C calling conventions. This calling convention
+ supports varargs function calls and tolerates some mismatch in the declared
+ prototype and implemented declaration of the function (as does normal C).
+ </dd>
+
+ <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
+
+ <dd>This calling convention attempts to make calls as fast as possible
+ (e.g. by passing things in registers). This calling convention allows the
+ target to use whatever tricks it wants to produce fast code for the target,
+ without having to conform to an externally specified ABI. Implementations of
+ this convention should allow arbitrary
+ <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> to be
+ supported. This calling convention does not support varargs and requires the
+ prototype of all callees to exactly match the prototype of the function
+ definition.
+ </dd>
+
+ <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
+
+ <dd>This calling convention attempts to make code in the caller as efficient
+ as possible under the assumption that the call is not commonly executed. As
+ such, these calls often preserve all registers so that the call does not break
+ any live ranges in the caller side. This calling convention does not support
+ varargs and requires the prototype of all callees to exactly match the
+ prototype of the function definition.
+ </dd>
+
+ <dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt>
+
+ <dd>Any calling convention may be specified by number, allowing
+ target-specific calling conventions to be used. Target specific calling
+ conventions start at 64.
+ </dd>
+ </dl>
+
+ <p>More calling conventions can be added/defined on an as-needed basis, to
+ support pascal conventions or any other well-known target-independent
+ convention.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="visibility">Visibility Styles</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ All Global Variables and Functions have one of the following visibility styles:
+ </p>
+
+ <dl>
+ <dt><b>"<tt>default</tt>" - Default style</b>:</dt>
+
+ <dd>On ELF, default visibility means that the declaration is visible to other
+ modules and, in shared libraries, means that the declared entity may be
+ overridden. On Darwin, default visibility means that the declaration is
+ visible to other modules. Default visibility corresponds to "external
+ linkage" in the language.
+ </dd>
+
+ <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt>
+
+ <dd>Two declarations of an object with hidden visibility refer to the same
+ object if they are in the same shared object. Usually, hidden visibility
+ indicates that the symbol will not be placed into the dynamic symbol table,
+ so no other module (executable or shared library) can reference it
+ directly.
+ </dd>
+
+ <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt>
+
+ <dd>On ELF, protected visibility indicates that the symbol will be placed in
+ the dynamic symbol table, but that references within the defining module will
+ bind to the local symbol. That is, the symbol cannot be overridden by another
+ module.
+ </dd>
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="globalvars">Global Variables</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Global variables define regions of memory allocated at compilation time
+ instead of run-time. Global variables may optionally be initialized, may have
+ an explicit section to be placed in, and may have an optional explicit alignment
+ specified. A variable may be defined as "thread_local", which means that it
+ will not be shared by threads (each thread will have a separated copy of the
+ variable). A variable may be defined as a global "constant," which indicates
+ that the contents of the variable will <b>never</b> be modified (enabling better
+ optimization, allowing the global data to be placed in the read-only section of
+ an executable, etc). Note that variables that need runtime initialization
+ cannot be marked "constant" as there is a store to the variable.</p>
+
+ <p>
+ LLVM explicitly allows <em>declarations</em> of global variables to be marked
+ constant, even if the final definition of the global is not. This capability
+ can be used to enable slightly better optimization of the program, but requires
+ the language definition to guarantee that optimizations based on the
+ 'constantness' are valid for the translation units that do not include the
+ definition.
+ </p>
+
+ <p>As SSA values, global variables define pointer values that are in
+ scope (i.e. they dominate) all basic blocks in the program. Global
+ variables always define a pointer to their "content" type because they
+ describe a region of memory, and all memory objects in LLVM are
+ accessed through pointers.</p>
+
+ <p>A global variable may be declared to reside in a target-specifc numbered
+ address space. For targets that support them, address spaces may affect how
+ optimizations are performed and/or what target instructions are used to access
+ the variable. The default address space is zero. The address space qualifier
+ must precede any other attributes.</p>
+
+ <p>LLVM allows an explicit section to be specified for globals. If the target
+ supports it, it will emit globals to the section specified.</p>
+
+ <p>An explicit alignment may be specified for a global. If not present, or if
+ the alignment is set to zero, the alignment of the global is set by the target
+ to whatever it feels convenient. If an explicit alignment is specified, the
+ global is forced to have at least that much alignment. All alignments must be
+ a power of 2.</p>
+
+ <p>For example, the following defines a global in a numbered address space with
+ an initializer, section, and alignment:</p>
+
+ <div class="doc_code">
+ <pre>
+ @G = constant float 1.0 addrspace(5), section "foo", align 4
+ </pre>
+ </div>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="functionstructure">Functions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM function definitions consist of the "<tt>define</tt>" keyord,
+ an optional <a href="#linkage">linkage type</a>, an optional
+ <a href="#visibility">visibility style</a>, an optional
+ <a href="#callingconv">calling convention</a>, a return type, an optional
+ <a href="#paramattrs">parameter attribute</a> for the return type, a function
+ name, a (possibly empty) argument list (each with optional
+ <a href="#paramattrs">parameter attributes</a>), an optional section, an
+ optional alignment, an optional <a href="#gc">garbage collector name</a>, an
+ opening curly brace, a list of basic blocks, and a closing curly brace.
+
+ LLVM function declarations consist of the "<tt>declare</tt>" keyword, an
+ optional <a href="#linkage">linkage type</a>, an optional
+ <a href="#visibility">visibility style</a>, an optional
+ <a href="#callingconv">calling convention</a>, a return type, an optional
+ <a href="#paramattrs">parameter attribute</a> for the return type, a function
+ name, a possibly empty list of arguments, an optional alignment, and an optional
+ <a href="#gc">garbage collector name</a>.</p>
+
+ <p>A function definition contains a list of basic blocks, forming the CFG for
+ the function. Each basic block may optionally start with a label (giving the
+ basic block a symbol table entry), contains a list of instructions, and ends
+ with a <a href="#terminators">terminator</a> instruction (such as a branch or
+ function return).</p>
+
+ <p>The first basic block in a function is special in two ways: it is immediately
+ executed on entrance to the function, and it is not allowed to have predecessor
+ basic blocks (i.e. there can not be any branches to the entry block of a
+ function). Because the block can have no predecessors, it also cannot have any
+ <a href="#i_phi">PHI nodes</a>.</p>
+
+ <p>LLVM allows an explicit section to be specified for functions. If the target
+ supports it, it will emit functions to the section specified.</p>
+
+ <p>An explicit alignment may be specified for a function. If not present, or if
+ the alignment is set to zero, the alignment of the function is set by the target
+ to whatever it feels convenient. If an explicit alignment is specified, the
+ function is forced to have at least that much alignment. All alignments must be
+ a power of 2.</p>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="aliasstructure">Aliases</a>
+ </div>
+ <div class="doc_text">
+ <p>Aliases act as "second name" for the aliasee value (which can be either
+ function, global variable, another alias or bitcast of global value). Aliases
+ may have an optional <a href="#linkage">linkage type</a>, and an
+ optional <a href="#visibility">visibility style</a>.</p>
+
+ <h5>Syntax:</h5>
+
+ <div class="doc_code">
+ <pre>
+ @<Name> = [Linkage] [Visibility] alias <AliaseeTy> @<Aliasee>
+ </pre>
+ </div>
+
+ </div>
+
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div>
+ <div class="doc_text">
+ <p>The return type and each parameter of a function type may have a set of
+ <i>parameter attributes</i> associated with them. Parameter attributes are
+ used to communicate additional information about the result or parameters of
+ a function. Parameter attributes are considered to be part of the function,
+ not of the function type, so functions with different parameter attributes
+ can have the same function type.</p>
+
+ <p>Parameter attributes are simple keywords that follow the type specified. If
+ multiple parameter attributes are needed, they are space separated. For
+ example:</p>
+
+ <div class="doc_code">
+ <pre>
+ declare i32 @printf(i8* noalias , ...) nounwind
+ declare i32 @atoi(i8*) nounwind readonly
+ </pre>
+ </div>
+
+ <p>Note that any attributes for the function result (<tt>nounwind</tt>,
+ <tt>readonly</tt>) come immediately after the argument list.</p>
+
+ <p>Currently, only the following parameter attributes are defined:</p>
+ <dl>
+ <dt><tt>zeroext</tt></dt>
+ <dd>This indicates that the parameter should be zero extended just before
+ a call to this function.</dd>
+
+ <dt><tt>signext</tt></dt>
+ <dd>This indicates that the parameter should be sign extended just before
+ a call to this function.</dd>
+
+ <dt><tt>inreg</tt></dt>
+ <dd>This indicates that the parameter should be placed in register (if
+ possible) during assembling function call. Support for this attribute is
+ target-specific</dd>
+
+ <dt><tt>byval</tt></dt>
+ <dd>This indicates that the pointer parameter should really be passed by
+ value to the function. The attribute implies that a hidden copy of the
+ pointee is made between the caller and the callee, so the callee is unable
+ to modify the value in the callee. This attribute is only valid on llvm
+ pointer arguments. It is generally used to pass structs and arrays by
+ value, but is also valid on scalars (even though this is silly).</dd>
+
+ <dt><tt>sret</tt></dt>
+ <dd>This indicates that the pointer parameter specifies the address of a
+ structure that is the return value of the function in the source program.
+ Loads and stores to the structure are assumed not to trap.
+ May only be applied to the first parameter.</dd>
+
+ <dt><tt>noalias</tt></dt>
+ <dd>This indicates that the parameter does not alias any global or any other
+ parameter. The caller is responsible for ensuring that this is the case,
+ usually by placing the value in a stack allocation.</dd>
+
+ <dt><tt>noreturn</tt></dt>
+ <dd>This function attribute indicates that the function never returns. This
+ indicates to LLVM that every call to this function should be treated as if
+ an <tt>unreachable</tt> instruction immediately followed the call.</dd>
+
+ <dt><tt>nounwind</tt></dt>
+ <dd>This function attribute indicates that no exceptions unwind out of the
+ function. Usually this is because the function makes no use of exceptions,
+ but it may also be that the function catches any exceptions thrown when
+ executing it.</dd>
+
+ <dt><tt>nest</tt></dt>
+ <dd>This indicates that the parameter can be excised using the
+ <a href="#int_trampoline">trampoline intrinsics</a>.</dd>
+ <dt><tt>readonly</tt></dt>
+ <dd>This function attribute indicates that the function has no side-effects
+ except for producing a return value or throwing an exception. The value
+ returned must only depend on the function arguments and/or global variables.
+ It may use values obtained by dereferencing pointers.</dd>
+ <dt><tt>readnone</tt></dt>
+ <dd>A <tt>readnone</tt> function has the same restrictions as a <tt>readonly</tt>
+ function, but in addition it is not allowed to dereference any pointer arguments
+ or global variables.
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="gc">Garbage Collector Names</a>
+ </div>
+
+ <div class="doc_text">
+ <p>Each function may specify a garbage collector name, which is simply a
+ string.</p>
+
+ <div class="doc_code"><pre
+ >define void @f() gc "name" { ...</pre></div>
+
+ <p>The compiler declares the supported values of <i>name</i>. Specifying a
+ collector which will cause the compiler to alter its output in order to support
+ the named garbage collection algorithm.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="moduleasm">Module-Level Inline Assembly</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ Modules may contain "module-level inline asm" blocks, which corresponds to the
+ GCC "file scope inline asm" blocks. These blocks are internally concatenated by
+ LLVM and treated as a single unit, but may be separated in the .ll file if
+ desired. The syntax is very simple:
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ module asm "inline asm code goes here"
+ module asm "more can go here"
+ </pre>
+ </div>
+
+ <p>The strings can contain any character by escaping non-printable characters.
+ The escape sequence used is simply "\xx" where "xx" is the two digit hex code
+ for the number.
+ </p>
+
+ <p>
+ The inline asm code is simply printed to the machine code .s file when
+ assembly code is generated.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="datalayout">Data Layout</a>
+ </div>
+
+ <div class="doc_text">
+ <p>A module may specify a target specific data layout string that specifies how
+ data is to be laid out in memory. The syntax for the data layout is simply:</p>
+ <pre> target datalayout = "<i>layout specification</i>"</pre>
+ <p>The <i>layout specification</i> consists of a list of specifications
+ separated by the minus sign character ('-'). Each specification starts with a
+ letter and may include other information after the letter to define some
+ aspect of the data layout. The specifications accepted are as follows: </p>
+ <dl>
+ <dt><tt>E</tt></dt>
+ <dd>Specifies that the target lays out data in big-endian form. That is, the
+ bits with the most significance have the lowest address location.</dd>
+ <dt><tt>e</tt></dt>
+ <dd>Specifies that hte target lays out data in little-endian form. That is,
+ the bits with the least significance have the lowest address location.</dd>
+ <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
+ <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
+ <i>preferred</i> alignments. All sizes are in bits. Specifying the <i>pref</i>
+ alignment is optional. If omitted, the preceding <tt>:</tt> should be omitted
+ too.</dd>
+ <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
+ <dd>This specifies the alignment for an integer type of a given bit
+ <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd>
+ <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
+ <dd>This specifies the alignment for a vector type of a given bit
+ <i>size</i>.</dd>
+ <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
+ <dd>This specifies the alignment for a floating point type of a given bit
+ <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64
+ (double).</dd>
+ <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
+ <dd>This specifies the alignment for an aggregate type of a given bit
+ <i>size</i>.</dd>
+ </dl>
+ <p>When constructing the data layout for a given target, LLVM starts with a
+ default set of specifications which are then (possibly) overriden by the
+ specifications in the <tt>datalayout</tt> keyword. The default specifications
+ are given in this list:</p>
+ <ul>
+ <li><tt>E</tt> - big endian</li>
+ <li><tt>p:32:64:64</tt> - 32-bit pointers with 64-bit alignment</li>
+ <li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li>
+ <li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li>
+ <li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li>
+ <li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li>
+ <li><tt>i64:32:64</tt> - i64 has abi alignment of 32-bits but preferred
+ alignment of 64-bits</li>
+ <li><tt>f32:32:32</tt> - float is 32-bit aligned</li>
+ <li><tt>f64:64:64</tt> - double is 64-bit aligned</li>
+ <li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li>
+ <li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li>
+ <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li>
+ </ul>
+ <p>When llvm is determining the alignment for a given type, it uses the
+ following rules:
+ <ol>
+ <li>If the type sought is an exact match for one of the specifications, that
+ specification is used.</li>
+ <li>If no match is found, and the type sought is an integer type, then the
+ smallest integer type that is larger than the bitwidth of the sought type is
+ used. If none of the specifications are larger than the bitwidth then the the
+ largest integer type is used. For example, given the default specifications
+ above, the i7 type will use the alignment of i8 (next largest) while both
+ i65 and i256 will use the alignment of i64 (largest specified).</li>
+ <li>If no match is found, and the type sought is a vector type, then the
+ largest vector type that is smaller than the sought vector type will be used
+ as a fall back. This happens because <128 x double> can be implemented in
+ terms of 64 <2 x double>, for example.</li>
+ </ol>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="typesystem">Type System</a> </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The LLVM type system is one of the most important features of the
+ intermediate representation. Being typed enables a number of
+ optimizations to be performed on the IR directly, without having to do
+ extra analyses on the side before the transformation. A strong type
+ system makes it easier to read the generated code and enables novel
+ analyses and transformations that are not feasible to perform on normal
+ three address code representations.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="t_classifications">Type
+ Classifications</a> </div>
+ <div class="doc_text">
+ <p>The types fall into a few useful
+ classifications:</p>
+
+ <table border="1" cellspacing="0" cellpadding="4">
+ <tbody>
+ <tr><th>Classification</th><th>Types</th></tr>
+ <tr>
+ <td><a href="#t_integer">integer</a></td>
+ <td><tt>i1, i2, i3, ... i8, ... i16, ... i32, ... i64, ... </tt></td>
+ </tr>
+ <tr>
+ <td><a href="#t_floating">floating point</a></td>
+ <td><tt>float, double, x86_fp80, fp128, ppc_fp128</tt></td>
+ </tr>
+ <tr>
+ <td><a name="t_firstclass">first class</a></td>
+ <td><a href="#t_integer">integer</a>,
+ <a href="#t_floating">floating point</a>,
+ <a href="#t_pointer">pointer</a>,
+ <a href="#t_vector">vector</a>
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#t_primitive">primitive</a></td>
+ <td><a href="#t_label">label</a>,
+ <a href="#t_void">void</a>,
+ <a href="#t_integer">integer</a>,
+ <a href="#t_floating">floating point</a>.</td>
+ </tr>
+ <tr>
+ <td><a href="#t_derived">derived</a></td>
+ <td><a href="#t_integer">integer</a>,
+ <a href="#t_array">array</a>,
+ <a href="#t_function">function</a>,
+ <a href="#t_pointer">pointer</a>,
+ <a href="#t_struct">structure</a>,
+ <a href="#t_pstruct">packed structure</a>,
+ <a href="#t_vector">vector</a>,
+ <a href="#t_opaque">opaque</a>.
+ </tr>
+ </tbody>
+ </table>
+
+ <p>The <a href="#t_firstclass">first class</a> types are perhaps the
+ most important. Values of these types are the only ones which can be
+ produced by instructions, passed as arguments, or used as operands to
+ instructions. This means that all structures and arrays must be
+ manipulated either by pointer or by component.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
+
+ <div class="doc_text">
+ <p>The primitive types are the fundamental building blocks of the LLVM
+ system.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div>
+
+ <div class="doc_text">
+ <table>
+ <tbody>
+ <tr><th>Type</th><th>Description</th></tr>
+ <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
+ <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
+ <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr>
+ <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr>
+ <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_void">Void Type</a> </div>
+
+ <div class="doc_text">
+ <h5>Overview:</h5>
+ <p>The void type does not represent any value and has no size.</p>
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ void
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_label">Label Type</a> </div>
+
+ <div class="doc_text">
+ <h5>Overview:</h5>
+ <p>The label type represents code labels.</p>
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ label
+ </pre>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
+
+ <div class="doc_text">
+
+ <p>The real power in LLVM comes from the derived types in the system.
+ This is what allows a programmer to represent arrays, functions,
+ pointers, and other useful types. Note that these derived types may be
+ recursive: For example, it is possible to have a two dimensional array.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
+
+ <div class="doc_text">
+
+ <h5>Overview:</h5>
+ <p>The integer type is a very simple derived type that simply specifies an
+ arbitrary bit width for the integer type desired. Any bit width from 1 bit to
+ 2^23-1 (about 8 million) can be specified.</p>
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ iN
+ </pre>
+
+ <p>The number of bits the integer will occupy is specified by the <tt>N</tt>
+ value.</p>
+
+ <h5>Examples:</h5>
+ <table class="layout">
+ <tbody>
+ <tr>
+ <td><tt>i1</tt></td>
+ <td>a single-bit integer.</td>
+ </tr><tr>
+ <td><tt>i32</tt></td>
+ <td>a 32-bit integer.</td>
+ </tr><tr>
+ <td><tt>i1942652</tt></td>
+ <td>a really big integer of over 1 million bits.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
+
+ <div class="doc_text">
+
+ <h5>Overview:</h5>
+
+ <p>The array type is a very simple derived type that arranges elements
+ sequentially in memory. The array type requires a size (number of
+ elements) and an underlying data type.</p>
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ [<# elements> x <elementtype>]
+ </pre>
+
+ <p>The number of elements is a constant integer value; elementtype may
+ be any type with a size.</p>
+
+ <h5>Examples:</h5>
+ <table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>[40 x i32]</tt></td>
+ <td class="left">Array of 40 32-bit integer values.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>[41 x i32]</tt></td>
+ <td class="left">Array of 41 32-bit integer values.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>[4 x i8]</tt></td>
+ <td class="left">Array of 4 8-bit integer values.</td>
+ </tr>
+ </table>
+ <p>Here are some examples of multidimensional arrays:</p>
+ <table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>[3 x [4 x i32]]</tt></td>
+ <td class="left">3x4 array of 32-bit integer values.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>[12 x [10 x float]]</tt></td>
+ <td class="left">12x10 array of single precision floating point values.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>[2 x [3 x [4 x i16]]]</tt></td>
+ <td class="left">2x3x4 array of 16-bit integer values.</td>
+ </tr>
+ </table>
+
+ <p>Note that 'variable sized arrays' can be implemented in LLVM with a zero
+ length array. Normally, accesses past the end of an array are undefined in
+ LLVM (e.g. it is illegal to access the 5th element of a 3 element array).
+ As a special case, however, zero length arrays are recognized to be variable
+ length. This allows implementation of 'pascal style arrays' with the LLVM
+ type "{ i32, [0 x float]}", for example.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div>
+ <div class="doc_text">
+
+ <h5>Overview:</h5>
+
+ <p>The function type can be thought of as a function signature. It
+ consists of a return type and a list of formal parameter types. The
+ return type of a function type is a scalar type, a void type, or a struct type.
+ If the return type is a struct type then all struct elements must be of first
+ class types, and the struct must have at least one element.</p>
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <returntype list> (<parameter list>)
+ </pre>
+
+ <p>...where '<tt><parameter list></tt>' is a comma-separated list of type
+ specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
+ which indicates that the function takes a variable number of arguments.
+ Variable argument functions can access their arguments with the <a
+ href="#int_varargs">variable argument handling intrinsic</a> functions.
+ '<tt><returntype list></tt>' is a comma-separated list of
+ <a href="#t_firstclass">first class</a> type specifiers.</p>
+
+ <h5>Examples:</h5>
+ <table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>i32 (i32)</tt></td>
+ <td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt>
+ </td>
+ </tr><tr class="layout">
+ <td class="left"><tt>float (i16 signext, i32 *) *
+ </tt></td>
+ <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
+ an <tt>i16</tt> that should be sign extended and a
+ <a href="#t_pointer">pointer</a> to <tt>i32</tt>, returning
+ <tt>float</tt>.
+ </td>
+ </tr><tr class="layout">
+ <td class="left"><tt>i32 (i8*, ...)</tt></td>
+ <td class="left">A vararg function that takes at least one
+ <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
+ which returns an integer. This is the signature for <tt>printf</tt> in
+ LLVM.
+ </td>
+ </tr><tr class="layout">
+ <td class="left"><tt>{i32, i32} (i32)</tt></td>
+ <td class="left">A function taking an <tt>i32></tt>, returning two
+ <tt> i32 </tt> values as an aggregate of type <tt>{ i32, i32 }</tt>
+ </td>
+ </tr>
+ </table>
+
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div>
+ <div class="doc_text">
+ <h5>Overview:</h5>
+ <p>The structure type is used to represent a collection of data members
+ together in memory. The packing of the field types is defined to match
+ the ABI of the underlying processor. The elements of a structure may
+ be any type that has a size.</p>
+ <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt>
+ and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a
+ field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>'
+ instruction.</p>
+ <h5>Syntax:</h5>
+ <pre> { <type list> }<br></pre>
+ <h5>Examples:</h5>
+ <table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>{ i32, i32, i32 }</tt></td>
+ <td class="left">A triple of three <tt>i32</tt> values</td>
+ </tr><tr class="layout">
+ <td class="left"><tt>{ float, i32 (i32) * }</tt></td>
+ <td class="left">A pair, where the first element is a <tt>float</tt> and the
+ second element is a <a href="#t_pointer">pointer</a> to a
+ <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
+ an <tt>i32</tt>.</td>
+ </tr>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_pstruct">Packed Structure Type</a>
+ </div>
+ <div class="doc_text">
+ <h5>Overview:</h5>
+ <p>The packed structure type is used to represent a collection of data members
+ together in memory. There is no padding between fields. Further, the alignment
+ of a packed structure is 1 byte. The elements of a packed structure may
+ be any type that has a size.</p>
+ <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt>
+ and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a
+ field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>'
+ instruction.</p>
+ <h5>Syntax:</h5>
+ <pre> < { <type list> } > <br></pre>
+ <h5>Examples:</h5>
+ <table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>< { i32, i32, i32 } ></tt></td>
+ <td class="left">A triple of three <tt>i32</tt> values</td>
+ </tr><tr class="layout">
+ <td class="left"><tt>< { float, i32 (i32)* } ></tt></td>
+ <td class="left">A pair, where the first element is a <tt>float</tt> and the
+ second element is a <a href="#t_pointer">pointer</a> to a
+ <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
+ an <tt>i32</tt>.</td>
+ </tr>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
+ <div class="doc_text">
+ <h5>Overview:</h5>
+ <p>As in many languages, the pointer type represents a pointer or
+ reference to another object, which must live in memory. Pointer types may have
+ an optional address space attribute defining the target-specific numbered
+ address space where the pointed-to object resides. The default address space is
+ zero.</p>
+ <h5>Syntax:</h5>
+ <pre> <type> *<br></pre>
+ <h5>Examples:</h5>
+ <table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>[4x i32]*</tt></td>
+ <td class="left">A <a href="#t_pointer">pointer</a> to <a
+ href="#t_array">array</a> of four <tt>i32</tt> values.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>i32 (i32 *) *</tt></td>
+ <td class="left"> A <a href="#t_pointer">pointer</a> to a <a
+ href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an
+ <tt>i32</tt>.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>i32 addrspace(5)*</tt></td>
+ <td class="left">A <a href="#t_pointer">pointer</a> to an <tt>i32</tt> value
+ that resides in address space #5.</td>
+ </tr>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_vector">Vector Type</a> </div>
+ <div class="doc_text">
+
+ <h5>Overview:</h5>
+
+ <p>A vector type is a simple derived type that represents a vector
+ of elements. Vector types are used when multiple primitive data
+ are operated in parallel using a single instruction (SIMD).
+ A vector type requires a size (number of
+ elements) and an underlying primitive data type. Vectors must have a power
+ of two length (1, 2, 4, 8, 16 ...). Vector types are
+ considered <a href="#t_firstclass">first class</a>.</p>
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ < <# elements> x <elementtype> >
+ </pre>
+
+ <p>The number of elements is a constant integer value; elementtype may
+ be any integer or floating point type.</p>
+
+ <h5>Examples:</h5>
+
+ <table class="layout">
+ <tr class="layout">
+ <td class="left"><tt><4 x i32></tt></td>
+ <td class="left">Vector of 4 32-bit integer values.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt><8 x float></tt></td>
+ <td class="left">Vector of 8 32-bit floating-point values.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt><2 x i64></tt></td>
+ <td class="left">Vector of 2 64-bit integer values.</td>
+ </tr>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_opaque">Opaque Type</a> </div>
+ <div class="doc_text">
+
+ <h5>Overview:</h5>
+
+ <p>Opaque types are used to represent unknown types in the system. This
+ corresponds (for example) to the C notion of a forward declared structure type.
+ In LLVM, opaque types can eventually be resolved to any type (not just a
+ structure type).</p>
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ opaque
+ </pre>
+
+ <h5>Examples:</h5>
+
+ <table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>opaque</tt></td>
+ <td class="left">An opaque type.</td>
+ </tr>
+ </table>
+ </div>
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="constants">Constants</a> </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>LLVM has several different basic types of constants. This section describes
+ them all and their syntax.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="simpleconstants">Simple Constants</a></div>
+
+ <div class="doc_text">
+
+ <dl>
+ <dt><b>Boolean constants</b></dt>
+
+ <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
+ constants of the <tt><a href="#t_primitive">i1</a></tt> type.
+ </dd>
+
+ <dt><b>Integer constants</b></dt>
+
+ <dd>Standard integers (such as '4') are constants of the <a
+ href="#t_integer">integer</a> type. Negative numbers may be used with
+ integer types.
+ </dd>
+
+ <dt><b>Floating point constants</b></dt>
+
+ <dd>Floating point constants use standard decimal notation (e.g. 123.421),
+ exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
+ notation (see below). The assembler requires the exact decimal value of
+ a floating-point constant. For example, the assembler accepts 1.25 but
+ rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point
+ constants must have a <a href="#t_floating">floating point</a> type. </dd>
+
+ <dt><b>Null pointer constants</b></dt>
+
+ <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
+ and must be of <a href="#t_pointer">pointer type</a>.</dd>
+
+ </dl>
+
+ <p>The one non-intuitive notation for constants is the optional hexadecimal form
+ of floating point constants. For example, the form '<tt>double
+ 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
+ 4.5e+15</tt>'. The only time hexadecimal floating point constants are required
+ (and the only time that they are generated by the disassembler) is when a
+ floating point constant must be emitted but it cannot be represented as a
+ decimal floating point number. For example, NaN's, infinities, and other
+ special values are represented in their IEEE hexadecimal format so that
+ assembly and disassembly do not cause any bits to change in the constants.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="aggregateconstants">Aggregate Constants</a>
+ </div>
+
+ <div class="doc_text">
+ <p>Aggregate constants arise from aggregation of simple constants
+ and smaller aggregate constants.</p>
+
+ <dl>
+ <dt><b>Structure constants</b></dt>
+
+ <dd>Structure constants are represented with notation similar to structure
+ type definitions (a comma separated list of elements, surrounded by braces
+ (<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>",
+ where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>". Structure constants
+ must have <a href="#t_struct">structure type</a>, and the number and
+ types of elements must match those specified by the type.
+ </dd>
+
+ <dt><b>Array constants</b></dt>
+
+ <dd>Array constants are represented with notation similar to array type
+ definitions (a comma separated list of elements, surrounded by square brackets
+ (<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74 ]</tt>". Array
+ constants must have <a href="#t_array">array type</a>, and the number and
+ types of elements must match those specified by the type.
+ </dd>
+
+ <dt><b>Vector constants</b></dt>
+
+ <dd>Vector constants are represented with notation similar to vector type
+ definitions (a comma separated list of elements, surrounded by
+ less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32 42,
+ i32 11, i32 74, i32 100 ></tt>". Vector constants must have <a
+ href="#t_vector">vector type</a>, and the number and types of elements must
+ match those specified by the type.
+ </dd>
+
+ <dt><b>Zero initialization</b></dt>
+
+ <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
+ value to zero of <em>any</em> type, including scalar and aggregate types.
+ This is often used to avoid having to print large zero initializers (e.g. for
+ large arrays) and is always exactly equivalent to using explicit zero
+ initializers.
+ </dd>
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="globalconstants">Global Variable and Function Addresses</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The addresses of <a href="#globalvars">global variables</a> and <a
+ href="#functionstructure">functions</a> are always implicitly valid (link-time)
+ constants. These constants are explicitly referenced when the <a
+ href="#identifiers">identifier for the global</a> is used and always have <a
+ href="#t_pointer">pointer</a> type. For example, the following is a legal LLVM
+ file:</p>
+
+ <div class="doc_code">
+ <pre>
+ @X = global i32 17
+ @Y = global i32 42
+ @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
+ </pre>
+ </div>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
+ <div class="doc_text">
+ <p>The string '<tt>undef</tt>' is recognized as a type-less constant that has
+ no specific value. Undefined values may be of any type and be used anywhere
+ a constant is permitted.</p>
+
+ <p>Undefined values indicate to the compiler that the program is well defined
+ no matter what value is used, giving the compiler more freedom to optimize.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="constantexprs">Constant Expressions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Constant expressions are used to allow expressions involving other constants
+ to be used as constants. Constant expressions may be of any <a
+ href="#t_firstclass">first class</a> type and may involve any LLVM operation
+ that does not have side effects (e.g. load and call are not supported). The
+ following is the syntax for constant expressions:</p>
+
+ <dl>
+ <dt><b><tt>trunc ( CST to TYPE )</tt></b></dt>
+ <dd>Truncate a constant to another type. The bit size of CST must be larger
+ than the bit size of TYPE. Both types must be integers.</dd>
+
+ <dt><b><tt>zext ( CST to TYPE )</tt></b></dt>
+ <dd>Zero extend a constant to another type. The bit size of CST must be
+ smaller or equal to the bit size of TYPE. Both types must be integers.</dd>
+
+ <dt><b><tt>sext ( CST to TYPE )</tt></b></dt>
+ <dd>Sign extend a constant to another type. The bit size of CST must be
+ smaller or equal to the bit size of TYPE. Both types must be integers.</dd>
+
+ <dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt>
+ <dd>Truncate a floating point constant to another floating point type. The
+ size of CST must be larger than the size of TYPE. Both types must be
+ floating point.</dd>
+
+ <dt><b><tt>fpext ( CST to TYPE )</tt></b></dt>
+ <dd>Floating point extend a constant to another type. The size of CST must be
+ smaller or equal to the size of TYPE. Both types must be floating point.</dd>
+
+ <dt><b><tt>fptoui ( CST to TYPE )</tt></b></dt>
+ <dd>Convert a floating point constant to the corresponding unsigned integer
+ constant. TYPE must be a scalar or vector integer type. CST must be of scalar
+ or vector floating point type. Both CST and TYPE must be scalars, or vectors
+ of the same number of elements. If the value won't fit in the integer type,
+ the results are undefined.</dd>
+
+ <dt><b><tt>fptosi ( CST to TYPE )</tt></b></dt>
+ <dd>Convert a floating point constant to the corresponding signed integer
+ constant. TYPE must be a scalar or vector integer type. CST must be of scalar
+ or vector floating point type. Both CST and TYPE must be scalars, or vectors
+ of the same number of elements. If the value won't fit in the integer type,
+ the results are undefined.</dd>
+
+ <dt><b><tt>uitofp ( CST to TYPE )</tt></b></dt>
+ <dd>Convert an unsigned integer constant to the corresponding floating point
+ constant. TYPE must be a scalar or vector floating point type. CST must be of
+ scalar or vector integer type. Both CST and TYPE must be scalars, or vectors
+ of the same number of elements. If the value won't fit in the floating point
+ type, the results are undefined.</dd>
+
+ <dt><b><tt>sitofp ( CST to TYPE )</tt></b></dt>
+ <dd>Convert a signed integer constant to the corresponding floating point
+ constant. TYPE must be a scalar or vector floating point type. CST must be of
+ scalar or vector integer type. Both CST and TYPE must be scalars, or vectors
+ of the same number of elements. If the value won't fit in the floating point
+ type, the results are undefined.</dd>
+
+ <dt><b><tt>ptrtoint ( CST to TYPE )</tt></b></dt>
+ <dd>Convert a pointer typed constant to the corresponding integer constant
+ TYPE must be an integer type. CST must be of pointer type. The CST value is
+ zero extended, truncated, or unchanged to make it fit in TYPE.</dd>
+
+ <dt><b><tt>inttoptr ( CST to TYPE )</tt></b></dt>
+ <dd>Convert a integer constant to a pointer constant. TYPE must be a
+ pointer type. CST must be of integer type. The CST value is zero extended,
+ truncated, or unchanged to make it fit in a pointer size. This one is
+ <i>really</i> dangerous!</dd>
+
+ <dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt>
+ <dd>Convert a constant, CST, to another TYPE. The size of CST and TYPE must be
+ identical (same number of bits). The conversion is done as if the CST value
+ was stored to memory and read back as TYPE. In other words, no bits change
+ with this operator, just the type. This can be used for conversion of
+ vector types to any other type, as long as they have the same bit width. For
+ pointers it is only valid to cast to another pointer type.
+ </dd>
+
+ <dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
+
+ <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
+ constants. As with the <a href="#i_getelementptr">getelementptr</a>
+ instruction, the index list may have zero or more indexes, which are required
+ to make sense for the type of "CSTPTR".</dd>
+
+ <dt><b><tt>select ( COND, VAL1, VAL2 )</tt></b></dt>
+
+ <dd>Perform the <a href="#i_select">select operation</a> on
+ constants.</dd>
+
+ <dt><b><tt>icmp COND ( VAL1, VAL2 )</tt></b></dt>
+ <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
+
+ <dt><b><tt>fcmp COND ( VAL1, VAL2 )</tt></b></dt>
+ <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
+
+ <dt><b><tt>extractelement ( VAL, IDX )</tt></b></dt>
+
+ <dd>Perform the <a href="#i_extractelement">extractelement
+ operation</a> on constants.
+
+ <dt><b><tt>insertelement ( VAL, ELT, IDX )</tt></b></dt>
+
+ <dd>Perform the <a href="#i_insertelement">insertelement
+ operation</a> on constants.</dd>
+
+
+ <dt><b><tt>shufflevector ( VEC1, VEC2, IDXMASK )</tt></b></dt>
+
+ <dd>Perform the <a href="#i_shufflevector">shufflevector
+ operation</a> on constants.</dd>
+
+ <dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt>
+
+ <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
+ be any of the <a href="#binaryops">binary</a> or <a href="#bitwiseops">bitwise
+ binary</a> operations. The constraints on operands are the same as those for
+ the corresponding instruction (e.g. no bitwise operations on floating point
+ values are allowed).</dd>
+ </dl>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="othervalues">Other Values</a> </div>
+ <!-- *********************************************************************** -->
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="inlineasm">Inline Assembler Expressions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ LLVM supports inline assembler expressions (as opposed to <a href="#moduleasm">
+ Module-Level Inline Assembly</a>) through the use of a special value. This
+ value represents the inline assembler as a string (containing the instructions
+ to emit), a list of operand constraints (stored as a string), and a flag that
+ indicates whether or not the inline asm expression has side effects. An example
+ inline assembler expression is:
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ i32 (i32) asm "bswap $0", "=r,r"
+ </pre>
+ </div>
+
+ <p>
+ Inline assembler expressions may <b>only</b> be used as the callee operand of
+ a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we have:
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ %X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y)
+ </pre>
+ </div>
+
+ <p>
+ Inline asms with side effects not visible in the constraint list must be marked
+ as having side effects. This is done through the use of the
+ '<tt>sideeffect</tt>' keyword, like so:
+ </p>
+
+ <div class="doc_code">
+ <pre>
+ call void asm sideeffect "eieio", ""()
+ </pre>
+ </div>
+
+ <p>TODO: The format of the asm and constraints string still need to be
+ documented here. Constraints on what can be done (e.g. duplication, moving, etc
+ need to be documented).
+ </p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The LLVM instruction set consists of several different
+ classifications of instructions: <a href="#terminators">terminator
+ instructions</a>, <a href="#binaryops">binary instructions</a>,
+ <a href="#bitwiseops">bitwise binary instructions</a>, <a
+ href="#memoryops">memory instructions</a>, and <a href="#otherops">other
+ instructions</a>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="terminators">Terminator
+ Instructions</a> </div>
+
+ <div class="doc_text">
+
+ <p>As mentioned <a href="#functionstructure">previously</a>, every
+ basic block in a program ends with a "Terminator" instruction, which
+ indicates which block should be executed after the current block is
+ finished. These terminator instructions typically yield a '<tt>void</tt>'
+ value: they produce control flow, not values (the one exception being
+ the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
+ <p>There are six different terminator instructions: the '<a
+ href="#i_ret"><tt>ret</tt></a>' instruction, the '<a href="#i_br"><tt>br</tt></a>'
+ instruction, the '<a href="#i_switch"><tt>switch</tt></a>' instruction,
+ the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the '<a
+ href="#i_unwind"><tt>unwind</tt></a>' instruction, and the '<a
+ href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> ret <type> <value> <i>; Return a value from a non-void function</i>
+ ret void <i>; Return from void function</i>
+ ret <type> <value>, <type> <value> <i>; Return two values from a non-void function </i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>ret</tt>' instruction is used to return control flow (and a
+ value) from a function back to the caller.</p>
+ <p>There are two forms of the '<tt>ret</tt>' instruction: one that
+ returns value(s) and then causes control flow, and one that just causes
+ control flow to occur.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The '<tt>ret</tt>' instruction may return zero, one or multiple values.
+ The type of each return value must be a '<a href="#t_firstclass">first
+ class</a>' type. Note that a function is not <a href="#wellformed">well
+ formed</a> if there exists a '<tt>ret</tt>' instruction inside of the
+ function that returns values that do not match the return type of the
+ function.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>When the '<tt>ret</tt>' instruction is executed, control flow
+ returns back to the calling function's context. If the caller is a "<a
+ href="#i_call"><tt>call</tt></a>" instruction, execution continues at
+ the instruction after the call. If the caller was an "<a
+ href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues
+ at the beginning of the "normal" destination block. If the instruction
+ returns a value, that value shall set the call or invoke instruction's
+ return value. If the instruction returns multiple values then these
+ values can only be accessed through a '<a href="#i_getresult"><tt>getresult</tt>
+ </a>' instruction.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ ret i32 5 <i>; Return an integer value of 5</i>
+ ret void <i>; Return from a void function</i>
+ ret i32 4, i8 2 <i>; Return two values 4 and 2 </i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> br i1 <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>br</tt>' instruction is used to cause control flow to
+ transfer to a different basic block in the current function. There are
+ two forms of this instruction, corresponding to a conditional branch
+ and an unconditional branch.</p>
+ <h5>Arguments:</h5>
+ <p>The conditional branch form of the '<tt>br</tt>' instruction takes a
+ single '<tt>i1</tt>' value and two '<tt>label</tt>' values. The
+ unconditional form of the '<tt>br</tt>' instruction takes a single
+ '<tt>label</tt>' value as a target.</p>
+ <h5>Semantics:</h5>
+ <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>'
+ argument is evaluated. If the value is <tt>true</tt>, control flows
+ to the '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>,
+ control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
+ <h5>Example:</h5>
+ <pre>Test:<br> %cond = <a href="#i_icmp">icmp</a> eq, i32 %a, %b<br> br i1 %cond, label %IfEqual, label %IfUnequal<br>IfEqual:<br> <a
+ href="#i_ret">ret</a> i32 1<br>IfUnequal:<br> <a href="#i_ret">ret</a> i32 0<br></pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_switch">'<tt>switch</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+
+ <pre>
+ switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
+ several different places. It is a generalization of the '<tt>br</tt>'
+ instruction, allowing a branch to occur to one of many possible
+ destinations.</p>
+
+
+ <h5>Arguments:</h5>
+
+ <p>The '<tt>switch</tt>' instruction uses three parameters: an integer
+ comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
+ an array of pairs of comparison value constants and '<tt>label</tt>'s. The
+ table is not allowed to contain duplicate constant entries.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The <tt>switch</tt> instruction specifies a table of values and
+ destinations. When the '<tt>switch</tt>' instruction is executed, this
+ table is searched for the given value. If the value is found, control flow is
+ transfered to the corresponding destination; otherwise, control flow is
+ transfered to the default destination.</p>
+
+ <h5>Implementation:</h5>
+
+ <p>Depending on properties of the target machine and the particular
+ <tt>switch</tt> instruction, this instruction may be code generated in different
+ ways. For example, it could be generated as a series of chained conditional
+ branches or with a lookup table.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ <i>; Emulate a conditional br instruction</i>
+ %Val = <a href="#i_zext">zext</a> i1 %value to i32
+ switch i32 %Val, label %truedest [i32 0, label %falsedest ]
+
+ <i>; Emulate an unconditional br instruction</i>
+ switch i32 0, label %dest [ ]
+
+ <i>; Implement a jump table:</i>
+ switch i32 %val, label %otherwise [ i32 0, label %onzero
+ i32 1, label %onone
+ i32 2, label %ontwo ]
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = invoke [<a href="#callingconv">cconv</a>] <ptr to function ty> <function ptr val>(<function args>)
+ to label <normal label> unwind label <exception label>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
+ function, with the possibility of control flow transfer to either the
+ '<tt>normal</tt>' label or the
+ '<tt>exception</tt>' label. If the callee function returns with the
+ "<tt><a href="#i_ret">ret</a></tt>" instruction, control flow will return to the
+ "normal" label. If the callee (or any indirect callees) returns with the "<a
+ href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted and
+ continued at the dynamically nearest "exception" label. If the callee function
+ returns multiple values then individual return values are only accessible through
+ a '<tt><a href="#i_getresult">getresult</a></tt>' instruction.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>This instruction requires several arguments:</p>
+
+ <ol>
+ <li>
+ The optional "cconv" marker indicates which <a href="#callingconv">calling
+ convention</a> the call should use. If none is specified, the call defaults
+ to using C calling conventions.
+ </li>
+ <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
+ function value being invoked. In most cases, this is a direct function
+ invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
+ an arbitrary pointer to function value.
+ </li>
+
+ <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
+ function to be invoked. </li>
+
+ <li>'<tt>function args</tt>': argument list whose types match the function
+ signature argument types. If the function signature indicates the function
+ accepts a variable number of arguments, the extra arguments can be
+ specified. </li>
+
+ <li>'<tt>normal label</tt>': the label reached when the called function
+ executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
+
+ <li>'<tt>exception label</tt>': the label reached when a callee returns with
+ the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
+
+ </ol>
+
+ <h5>Semantics:</h5>
+
+ <p>This instruction is designed to operate as a standard '<tt><a
+ href="#i_call">call</a></tt>' instruction in most regards. The primary
+ difference is that it establishes an association with a label, which is used by
+ the runtime library to unwind the stack.</p>
+
+ <p>This instruction is used in languages with destructors to ensure that proper
+ cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
+ exception. Additionally, this is important for implementation of
+ '<tt>catch</tt>' clauses in high-level languages that support them.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %retval = invoke i32 @Test(i32 15) to label %Continue
+ unwind label %TestCleanup <i>; {i32}:retval set</i>
+ %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue
+ unwind label %TestCleanup <i>; {i32}:retval set</i>
+ </pre>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+
+ <div class="doc_subsubsection"> <a name="i_unwind">'<tt>unwind</tt>'
+ Instruction</a> </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ unwind
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
+ at the first callee in the dynamic call stack which used an <a
+ href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is
+ primarily used to implement exception handling.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>unwind</tt>' instruction causes execution of the current function to
+ immediately halt. The dynamic call stack is then searched for the first <a
+ href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found,
+ execution continues at the "exceptional" destination block specified by the
+ <tt>invoke</tt> instruction. If there is no <tt>invoke</tt> instruction in the
+ dynamic call chain, undefined behavior results.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+
+ <div class="doc_subsubsection"> <a name="i_unreachable">'<tt>unreachable</tt>'
+ Instruction</a> </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ unreachable
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>unreachable</tt>' instruction has no defined semantics. This
+ instruction is used to inform the optimizer that a particular portion of the
+ code is not reachable. This can be used to indicate that the code after a
+ no-return function cannot be reached, and other facts.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
+ </div>
+
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div>
+ <div class="doc_text">
+ <p>Binary operators are used to do most of the computation in a
+ program. They require two operands of the same type, execute an operation on them, and
+ produce a single value. The operands might represent
+ multiple data, as is the case with the <a href="#t_vector">vector</a> data type.
+ The result value has the same type as its operands.</p>
+ <p>There are several different binary operators:</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_add">'<tt>add</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = add <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>add</tt>' instruction must be either <a
+ href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values.
+ This instruction can also take <a href="#t_vector">vector</a> versions of the values.
+ Both arguments must have identical types.</p>
+ <h5>Semantics:</h5>
+ <p>The value produced is the integer or floating point sum of the two
+ operands.</p>
+ <p>If an integer sum has unsigned overflow, the result returned is the
+ mathematical result modulo 2<sup>n</sup>, where n is the bit width of
+ the result.</p>
+ <p>Because LLVM integers use a two's complement representation, this
+ instruction is appropriate for both signed and unsigned integers.</p>
+ <h5>Example:</h5>
+ <pre> <result> = add i32 4, %var <i>; yields {i32}:result = 4 + %var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_sub">'<tt>sub</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = sub <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>sub</tt>' instruction returns the difference of its two
+ operands.</p>
+ <p>Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
+ instruction present in most other intermediate representations.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>sub</tt>' instruction must be either <a
+ href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
+ values.
+ This instruction can also take <a href="#t_vector">vector</a> versions of the values.
+ Both arguments must have identical types.</p>
+ <h5>Semantics:</h5>
+ <p>The value produced is the integer or floating point difference of
+ the two operands.</p>
+ <p>If an integer difference has unsigned overflow, the result returned is the
+ mathematical result modulo 2<sup>n</sup>, where n is the bit width of
+ the result.</p>
+ <p>Because LLVM integers use a two's complement representation, this
+ instruction is appropriate for both signed and unsigned integers.</p>
+ <h5>Example:</h5>
+ <pre>
+ <result> = sub i32 4, %var <i>; yields {i32}:result = 4 - %var</i>
+ <result> = sub i32 0, %val <i>; yields {i32}:result = -%var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_mul">'<tt>mul</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = mul <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>mul</tt>' instruction returns the product of its two
+ operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>mul</tt>' instruction must be either <a
+ href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
+ values.
+ This instruction can also take <a href="#t_vector">vector</a> versions of the values.
+ Both arguments must have identical types.</p>
+ <h5>Semantics:</h5>
+ <p>The value produced is the integer or floating point product of the
+ two operands.</p>
+ <p>If the result of an integer multiplication has unsigned overflow,
+ the result returned is the mathematical result modulo
+ 2<sup>n</sup>, where n is the bit width of the result.</p>
+ <p>Because LLVM integers use a two's complement representation, and the
+ result is the same width as the operands, this instruction returns the
+ correct result for both signed and unsigned integers. If a full product
+ (e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands
+ should be sign-extended or zero-extended as appropriate to the
+ width of the full product.</p>
+ <h5>Example:</h5>
+ <pre> <result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction
+ </a></div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = udiv <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>udiv</tt>' instruction returns the quotient of its two
+ operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>udiv</tt>' instruction must be
+ <a href="#t_integer">integer</a> values. Both arguments must have identical
+ types. This instruction can also take <a href="#t_vector">vector</a> versions
+ of the values in which case the elements must be integers.</p>
+ <h5>Semantics:</h5>
+ <p>The value produced is the unsigned integer quotient of the two operands.</p>
+ <p>Note that unsigned integer division and signed integer division are distinct
+ operations; for signed integer division, use '<tt>sdiv</tt>'.</p>
+ <p>Division by zero leads to undefined behavior.</p>
+ <h5>Example:</h5>
+ <pre> <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction
+ </a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = sdiv <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>sdiv</tt>' instruction returns the quotient of its two
+ operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>sdiv</tt>' instruction must be
+ <a href="#t_integer">integer</a> values. Both arguments must have identical
+ types. This instruction can also take <a href="#t_vector">vector</a> versions
+ of the values in which case the elements must be integers.</p>
+ <h5>Semantics:</h5>
+ <p>The value produced is the signed integer quotient of the two operands rounded towards zero.</p>
+ <p>Note that signed integer division and unsigned integer division are distinct
+ operations; for unsigned integer division, use '<tt>udiv</tt>'.</p>
+ <p>Division by zero leads to undefined behavior. Overflow also leads to
+ undefined behavior; this is a rare case, but can occur, for example,
+ by doing a 32-bit division of -2147483648 by -1.</p>
+ <h5>Example:</h5>
+ <pre> <result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = fdiv <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>fdiv</tt>' instruction returns the quotient of its two
+ operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>fdiv</tt>' instruction must be
+ <a href="#t_floating">floating point</a> values. Both arguments must have
+ identical types. This instruction can also take <a href="#t_vector">vector</a>
+ versions of floating point values.</p>
+ <h5>Semantics:</h5>
+ <p>The value produced is the floating point quotient of the two operands.</p>
+ <h5>Example:</h5>
+ <pre> <result> = fdiv float 4.0, %var <i>; yields {float}:result = 4.0 / %var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = urem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>urem</tt>' instruction returns the remainder from the
+ unsigned division of its two arguments.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>urem</tt>' instruction must be
+ <a href="#t_integer">integer</a> values. Both arguments must have identical
+ types. This instruction can also take <a href="#t_vector">vector</a> versions
+ of the values in which case the elements must be integers.</p>
+ <h5>Semantics:</h5>
+ <p>This instruction returns the unsigned integer <i>remainder</i> of a division.
+ This instruction always performs an unsigned division to get the remainder.</p>
+ <p>Note that unsigned integer remainder and signed integer remainder are
+ distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p>
+ <p>Taking the remainder of a division by zero leads to undefined behavior.</p>
+ <h5>Example:</h5>
+ <pre> <result> = urem i32 4, %var <i>; yields {i32}:result = 4 % %var</i>
+ </pre>
+
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_srem">'<tt>srem</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = srem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>srem</tt>' instruction returns the remainder from the
+ signed division of its two operands. This instruction can also take
+ <a href="#t_vector">vector</a> versions of the values in which case
+ the elements must be integers.</p>
+
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>srem</tt>' instruction must be
+ <a href="#t_integer">integer</a> values. Both arguments must have identical
+ types.</p>
+ <h5>Semantics:</h5>
+ <p>This instruction returns the <i>remainder</i> of a division (where the result
+ has the same sign as the dividend, <tt>var1</tt>), not the <i>modulo</i>
+ operator (where the result has the same sign as the divisor, <tt>var2</tt>) of
+ a value. For more information about the difference, see <a
+ href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
+ Math Forum</a>. For a table of how this is implemented in various languages,
+ please see <a href="http://en.wikipedia.org/wiki/Modulo_operation">
+ Wikipedia: modulo operation</a>.</p>
+ <p>Note that signed integer remainder and unsigned integer remainder are
+ distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p>
+ <p>Taking the remainder of a division by zero leads to undefined behavior.
+ Overflow also leads to undefined behavior; this is a rare case, but can occur,
+ for example, by taking the remainder of a 32-bit division of -2147483648 by -1.
+ (The remainder doesn't actually overflow, but this rule lets srem be
+ implemented using instructions that return both the result of the division
+ and the remainder.)</p>
+ <h5>Example:</h5>
+ <pre> <result> = srem i32 4, %var <i>; yields {i32}:result = 4 % %var</i>
+ </pre>
+
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_frem">'<tt>frem</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = frem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>frem</tt>' instruction returns the remainder from the
+ division of its two operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>frem</tt>' instruction must be
+ <a href="#t_floating">floating point</a> values. Both arguments must have
+ identical types. This instruction can also take <a href="#t_vector">vector</a>
+ versions of floating point values.</p>
+ <h5>Semantics:</h5>
+ <p>This instruction returns the <i>remainder</i> of a division.
+ The remainder has the same sign as the dividend.</p>
+ <h5>Example:</h5>
+ <pre> <result> = frem float 4.0, %var <i>; yields {float}:result = 4.0 % %var</i>
+ </pre>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
+ Operations</a> </div>
+ <div class="doc_text">
+ <p>Bitwise binary operators are used to do various forms of
+ bit-twiddling in a program. They are generally very efficient
+ instructions and can commonly be strength reduced from other
+ instructions. They require two operands of the same type, execute an operation on them,
+ and produce a single value. The resulting value is the same type as its operands.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = shl <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>shl</tt>' instruction returns the first operand shifted to
+ the left a specified number of bits.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>Both arguments to the '<tt>shl</tt>' instruction must be the same <a
+ href="#t_integer">integer</a> type. '<tt>var2</tt>' is treated as an
+ unsigned value.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup> mod 2<sup>n</sup>,
+ where n is the width of the result. If <tt>var2</tt> is (statically or dynamically) negative or
+ equal to or larger than the number of bits in <tt>var1</tt>, the result is undefined.</p>
+
+ <h5>Example:</h5><pre>
+ <result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i>
+ <result> = shl i32 4, 2 <i>; yields {i32}: 16</i>
+ <result> = shl i32 1, 10 <i>; yields {i32}: 1024</i>
+ <result> = shl i32 1, 32 <i>; undefined</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = lshr <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
+ operand shifted to the right a specified number of bits with zero fill.</p>
+
+ <h5>Arguments:</h5>
+ <p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
+ <a href="#t_integer">integer</a> type. '<tt>var2</tt>' is treated as an
+ unsigned value.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>This instruction always performs a logical shift right operation. The most
+ significant bits of the result will be filled with zero bits after the
+ shift. If <tt>var2</tt> is (statically or dynamically) equal to or larger than
+ the number of bits in <tt>var1</tt>, the result is undefined.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ <result> = lshr i32 4, 1 <i>; yields {i32}:result = 2</i>
+ <result> = lshr i32 4, 2 <i>; yields {i32}:result = 1</i>
+ <result> = lshr i8 4, 3 <i>; yields {i8}:result = 0</i>
+ <result> = lshr i8 -2, 1 <i>; yields {i8}:result = 0x7FFFFFFF </i>
+ <result> = lshr i32 1, 32 <i>; undefined</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_ashr">'<tt>ashr</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre> <result> = ashr <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
+ operand shifted to the right a specified number of bits with sign extension.</p>
+
+ <h5>Arguments:</h5>
+ <p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
+ <a href="#t_integer">integer</a> type. '<tt>var2</tt>' is treated as an
+ unsigned value.</p>
+
+ <h5>Semantics:</h5>
+ <p>This instruction always performs an arithmetic shift right operation,
+ The most significant bits of the result will be filled with the sign bit
+ of <tt>var1</tt>. If <tt>var2</tt> is (statically or dynamically) equal to or
+ larger than the number of bits in <tt>var1</tt>, the result is undefined.
+ </p>
+
+ <h5>Example:</h5>
+ <pre>
+ <result> = ashr i32 4, 1 <i>; yields {i32}:result = 2</i>
+ <result> = ashr i32 4, 2 <i>; yields {i32}:result = 1</i>
+ <result> = ashr i8 4, 3 <i>; yields {i8}:result = 0</i>
+ <result> = ashr i8 -2, 1 <i>; yields {i8}:result = -1</i>
+ <result> = ashr i32 1, 32 <i>; undefined</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = and <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>and</tt>' instruction returns the bitwise logical and of
+ its two operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>and</tt>' instruction must be <a
+ href="#t_integer">integer</a> values. Both arguments must have
+ identical types.</p>
+ <h5>Semantics:</h5>
+ <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
+ <p> </p>
+ <div style="align: center">
+ <table border="1" cellspacing="0" cellpadding="4">
+ <tbody>
+ <tr>
+ <td>In0</td>
+ <td>In1</td>
+ <td>Out</td>
+ </tr>
+ <tr>
+ <td>0</td>
+ <td>0</td>
+ <td>0</td>
+ </tr>
+ <tr>
+ <td>0</td>
+ <td>1</td>
+ <td>0</td>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>0</td>
+ <td>0</td>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>1</td>
+ <td>1</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <h5>Example:</h5>
+ <pre> <result> = and i32 4, %var <i>; yields {i32}:result = 4 & %var</i>
+ <result> = and i32 15, 40 <i>; yields {i32}:result = 8</i>
+ <result> = and i32 4, 8 <i>; yields {i32}:result = 0</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = or <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive
+ or of its two operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>or</tt>' instruction must be <a
+ href="#t_integer">integer</a> values. Both arguments must have
+ identical types.</p>
+ <h5>Semantics:</h5>
+ <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
+ <p> </p>
+ <div style="align: center">
+ <table border="1" cellspacing="0" cellpadding="4">
+ <tbody>
+ <tr>
+ <td>In0</td>
+ <td>In1</td>
+ <td>Out</td>
+ </tr>
+ <tr>
+ <td>0</td>
+ <td>0</td>
+ <td>0</td>
+ </tr>
+ <tr>
+ <td>0</td>
+ <td>1</td>
+ <td>1</td>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>0</td>
+ <td>1</td>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>1</td>
+ <td>1</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <h5>Example:</h5>
+ <pre> <result> = or i32 4, %var <i>; yields {i32}:result = 4 | %var</i>
+ <result> = or i32 15, 40 <i>; yields {i32}:result = 47</i>
+ <result> = or i32 4, 8 <i>; yields {i32}:result = 12</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = xor <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive
+ or of its two operands. The <tt>xor</tt> is used to implement the
+ "one's complement" operation, which is the "~" operator in C.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>xor</tt>' instruction must be <a
+ href="#t_integer">integer</a> values. Both arguments must have
+ identical types.</p>
+ <h5>Semantics:</h5>
+ <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
+ <p> </p>
+ <div style="align: center">
+ <table border="1" cellspacing="0" cellpadding="4">
+ <tbody>
+ <tr>
+ <td>In0</td>
+ <td>In1</td>
+ <td>Out</td>
+ </tr>
+ <tr>
+ <td>0</td>
+ <td>0</td>
+ <td>0</td>
+ </tr>
+ <tr>
+ <td>0</td>
+ <td>1</td>
+ <td>1</td>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>0</td>
+ <td>1</td>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>1</td>
+ <td>0</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <p> </p>
+ <h5>Example:</h5>
+ <pre> <result> = xor i32 4, %var <i>; yields {i32}:result = 4 ^ %var</i>
+ <result> = xor i32 15, 40 <i>; yields {i32}:result = 39</i>
+ <result> = xor i32 4, 8 <i>; yields {i32}:result = 12</i>
+ <result> = xor i32 %V, -1 <i>; yields {i32}:result = ~%V</i>
+ </pre>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="vectorops">Vector Operations</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM supports several instructions to represent vector operations in a
+ target-independent manner. These instructions cover the element-access and
+ vector-specific operations needed to process vectors effectively. While LLVM
+ does directly support these vector operations, many sophisticated algorithms
+ will want to use target-specific intrinsics to take full advantage of a specific
+ target.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = extractelement <n x <ty>> <val>, i32 <idx> <i>; yields <ty></i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>extractelement</tt>' instruction extracts a single scalar
+ element from a vector at a specified index.
+ </p>
+
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The first operand of an '<tt>extractelement</tt>' instruction is a
+ value of <a href="#t_vector">vector</a> type. The second operand is
+ an index indicating the position from which to extract the element.
+ The index may be a variable.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The result is a scalar of the same type as the element type of
+ <tt>val</tt>. Its value is the value at position <tt>idx</tt> of
+ <tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
+ results are undefined.
+ </p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %result = extractelement <4 x i32> %vec, i32 0 <i>; yields i32</i>
+ </pre>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx> <i>; yields <n x <ty>></i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>insertelement</tt>' instruction inserts a scalar
+ element into a vector at a specified index.
+ </p>
+
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The first operand of an '<tt>insertelement</tt>' instruction is a
+ value of <a href="#t_vector">vector</a> type. The second operand is a
+ scalar value whose type must equal the element type of the first
+ operand. The third operand is an index indicating the position at
+ which to insert the value. The index may be a variable.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The result is a vector of the same type as <tt>val</tt>. Its
+ element values are those of <tt>val</tt> except at position
+ <tt>idx</tt>, where it gets the value <tt>elt</tt>. If <tt>idx</tt>
+ exceeds the length of <tt>val</tt>, the results are undefined.
+ </p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %result = insertelement <4 x i32> %vec, i32 1, i32 0 <i>; yields <4 x i32></i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <n x i32> <mask> <i>; yields <n x <ty>></i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
+ from two input vectors, returning a vector of the same type.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
+ with types that match each other and types that match the result of the
+ instruction. The third argument is a shuffle mask, which has the same number
+ of elements as the other vector type, but whose element type is always 'i32'.
+ </p>
+
+ <p>
+ The shuffle mask operand is required to be a constant vector with either
+ constant integer or undef values.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The elements of the two input vectors are numbered from left to right across
+ both of the vectors. The shuffle mask operand specifies, for each element of
+ the result vector, which element of the two input registers the result element
+ gets. The element selector may be undef (meaning "don't care") and the second
+ operand may be undef if performing a shuffle from only one vector.
+ </p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %result = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+ <4 x i32> <i32 0, i32 4, i32 1, i32 5> <i>; yields <4 x i32></i>
+ %result = shufflevector <4 x i32> %v1, <4 x i32> undef,
+ <4 x i32> <i32 0, i32 1, i32 2, i32 3> <i>; yields <4 x i32></i> - Identity shuffle.
+ </pre>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="memoryops">Memory Access and Addressing Operations</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>A key design point of an SSA-based representation is how it
+ represents memory. In LLVM, no memory locations are in SSA form, which
+ makes things very simple. This section describes how to read, write,
+ allocate, and free memory in LLVM.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = malloc <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>malloc</tt>' instruction allocates memory from the system
+ heap and returns a pointer to it. The object is always allocated in the generic
+ address space (address space zero).</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The '<tt>malloc</tt>' instruction allocates
+ <tt>sizeof(<type>)*NumElements</tt>
+ bytes of memory from the operating system and returns a pointer of the
+ appropriate type to the program. If "NumElements" is specified, it is the
+ number of elements allocated, otherwise "NumElements" is defaulted to be one.
+ If a constant alignment is specified, the value result of the allocation is guaranteed to
+ be aligned to at least that boundary. If not specified, or if zero, the target can
+ choose to align the allocation on any convenient boundary.</p>
+
+ <p>'<tt>type</tt>' must be a sized type.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>Memory is allocated using the system "<tt>malloc</tt>" function, and
+ a pointer is returned. The result of a zero byte allocattion is undefined. The
+ result is null if there is insufficient memory available.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %array = malloc [4 x i8 ] <i>; yields {[%4 x i8]*}:array</i>
+
+ %size = <a href="#i_add">add</a> i32 2, 2 <i>; yields {i32}:size = i32 4</i>
+ %array1 = malloc i8, i32 4 <i>; yields {i8*}:array1</i>
+ %array2 = malloc [12 x i8], i32 %size <i>; yields {[12 x i8]*}:array2</i>
+ %array3 = malloc i32, i32 4, align 1024 <i>; yields {i32*}:array3</i>
+ %array4 = malloc i32, align 1024 <i>; yields {i32*}:array4</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_free">'<tt>free</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ free <type> <value> <i>; yields {void}</i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>free</tt>' instruction returns memory back to the unused
+ memory heap to be reallocated in the future.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>'<tt>value</tt>' shall be a pointer value that points to a value
+ that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
+ instruction.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>Access to the memory pointed to by the pointer is no longer defined
+ after this instruction executes. If the pointer is null, the operation
+ is a noop.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %array = <a href="#i_malloc">malloc</a> [4 x i8] <i>; yields {[4 x i8]*}:array</i>
+ free [4 x i8]* %array
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = alloca <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the
+ currently executing function, to be automatically released when this function
+ returns to its caller. The object is always allocated in the generic address
+ space (address space zero).</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
+ bytes of memory on the runtime stack, returning a pointer of the
+ appropriate type to the program. If "NumElements" is specified, it is the
+ number of elements allocated, otherwise "NumElements" is defaulted to be one.
+ If a constant alignment is specified, the value result of the allocation is guaranteed
+ to be aligned to at least that boundary. If not specified, or if zero, the target
+ can choose to align the allocation on any convenient boundary.</p>
+
+ <p>'<tt>type</tt>' may be any sized type.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>Memory is allocated; a pointer is returned. The operation is undefiend if
+ there is insufficient stack space for the allocation. '<tt>alloca</tt>'d
+ memory is automatically released when the function returns. The '<tt>alloca</tt>'
+ instruction is commonly used to represent automatic variables that must
+ have an address available. When the function returns (either with the <tt><a
+ href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
+ instructions), the memory is reclaimed. Allocating zero bytes
+ is legal, but the result is undefined.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %ptr = alloca i32 <i>; yields {i32*}:ptr</i>
+ %ptr = alloca i32, i32 4 <i>; yields {i32*}:ptr</i>
+ %ptr = alloca i32, i32 4, align 1024 <i>; yields {i32*}:ptr</i>
+ %ptr = alloca i32, align 1024 <i>; yields {i32*}:ptr</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = load <ty>* <pointer>[, align <alignment>]<br> <result> = volatile load <ty>* <pointer>[, align <alignment>]<br></pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
+ <h5>Arguments:</h5>
+ <p>The argument to the '<tt>load</tt>' instruction specifies the memory
+ address from which to load. The pointer must point to a <a
+ href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
+ marked as <tt>volatile</tt>, then the optimizer is not allowed to modify
+ the number or order of execution of this <tt>load</tt> with other
+ volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
+ instructions. </p>
+ <p>
+ The optional constant "align" argument specifies the alignment of the operation
+ (that is, the alignment of the memory address). A value of 0 or an
+ omitted "align" argument means that the operation has the preferential
+ alignment for the target. It is the responsibility of the code emitter
+ to ensure that the alignment information is correct. Overestimating
+ the alignment results in an undefined behavior. Underestimating the
+ alignment may produce less efficient code. An alignment of 1 is always
+ safe.
+ </p>
+ <h5>Semantics:</h5>
+ <p>The location of memory pointed to is loaded.</p>
+ <h5>Examples:</h5>
+ <pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i>
+ <a
+ href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i>
+ %val = load i32* %ptr <i>; yields {i32}:val = i32 3</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i>
+ volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
+ <h5>Arguments:</h5>
+ <p>There are two arguments to the '<tt>store</tt>' instruction: a value
+ to store and an address at which to store it. The type of the '<tt><pointer></tt>'
+ operand must be a pointer to the <a href="#t_firstclass">first class</a> type
+ of the '<tt><value></tt>'
+ operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the
+ optimizer is not allowed to modify the number or order of execution of
+ this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
+ href="#i_store">store</a></tt> instructions.</p>
+ <p>
+ The optional constant "align" argument specifies the alignment of the operation
+ (that is, the alignment of the memory address). A value of 0 or an
+ omitted "align" argument means that the operation has the preferential
+ alignment for the target. It is the responsibility of the code emitter
+ to ensure that the alignment information is correct. Overestimating
+ the alignment results in an undefined behavior. Underestimating the
+ alignment may produce less efficient code. An alignment of 1 is always
+ safe.
+ </p>
+ <h5>Semantics:</h5>
+ <p>The contents of memory are updated to contain '<tt><value></tt>'
+ at the location specified by the '<tt><pointer></tt>' operand.</p>
+ <h5>Example:</h5>
+ <pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i>
+ store i32 3, i32* %ptr <i>; yields {void}</i>
+ %val = <a href="#i_load">load</a> i32* %ptr <i>; yields {i32}:val = i32 3</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = getelementptr <ty>* <ptrval>{, <ty> <idx>}*
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>getelementptr</tt>' instruction is used to get the address of a
+ subelement of an aggregate data structure.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>This instruction takes a list of integer operands that indicate what
+ elements of the aggregate object to index to. The actual types of the arguments
+ provided depend on the type of the first pointer argument. The
+ '<tt>getelementptr</tt>' instruction is used to index down through the type
+ levels of a structure or to a specific index in an array. When indexing into a
+ structure, only <tt>i32</tt> integer constants are allowed. When indexing
+ into an array or pointer, only integers of 32 or 64 bits are allowed; 32-bit
+ values will be sign extended to 64-bits if required.</p>
+
+ <p>For example, let's consider a C code fragment and how it gets
+ compiled to LLVM:</p>
+
+ <div class="doc_code">
+ <pre>
+ struct RT {
+ char A;
+ int B[10][20];
+ char C;
+ };
+ struct ST {
+ int X;
+ double Y;
+ struct RT Z;
+ };
+
+ int *foo(struct ST *s) {
+ return &s[1].Z.B[5][13];
+ }
+ </pre>
+ </div>
+
+ <p>The LLVM code generated by the GCC frontend is:</p>
+
+ <div class="doc_code">
+ <pre>
+ %RT = type { i8 , [10 x [20 x i32]], i8 }
+ %ST = type { i32, double, %RT }
+
+ define i32* %foo(%ST* %s) {
+ entry:
+ %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
+ ret i32* %reg
+ }
+ </pre>
+ </div>
+
+ <h5>Semantics:</h5>
+
+ <p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
+ on the pointer type that is being indexed into. <a href="#t_pointer">Pointer</a>
+ and <a href="#t_array">array</a> types can use a 32-bit or 64-bit
+ <a href="#t_integer">integer</a> type but the value will always be sign extended
+ to 64-bits. <a href="#t_struct">Structure</a> and <a href="#t_pstruct">packed
+ structure</a> types require <tt>i32</tt> <b>constants</b>.</p>
+
+ <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
+ type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT
+ }</tt>' type, a structure. The second index indexes into the third element of
+ the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]],
+ i8 }</tt>' type, another structure. The third index indexes into the second
+ element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an
+ array. The two dimensions of the array are subscripted into, yielding an
+ '<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a pointer
+ to this element, thus computing a value of '<tt>i32*</tt>' type.</p>
+
+ <p>Note that it is perfectly legal to index partially through a
+ structure, returning a pointer to an inner element. Because of this,
+ the LLVM code for the given testcase is equivalent to:</p>
+
+ <pre>
+ define i32* %foo(%ST* %s) {
+ %t1 = getelementptr %ST* %s, i32 1 <i>; yields %ST*:%t1</i>
+ %t2 = getelementptr %ST* %t1, i32 0, i32 2 <i>; yields %RT*:%t2</i>
+ %t3 = getelementptr %RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i>
+ %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 <i>; yields [20 x i32]*:%t4</i>
+ %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 <i>; yields i32*:%t5</i>
+ ret i32* %t5
+ }
+ </pre>
+
+ <p>Note that it is undefined to access an array out of bounds: array and
+ pointer indexes must always be within the defined bounds of the array type.
+ The one exception for this rule is zero length arrays. These arrays are
+ defined to be accessible as variable length arrays, which requires access
+ beyond the zero'th element.</p>
+
+ <p>The getelementptr instruction is often confusing. For some more insight
+ into how it works, see <a href="GetElementPtr.html">the getelementptr
+ FAQ</a>.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ <i>; yields [12 x i8]*:aptr</i>
+ %aptr = getelementptr {i32, [12 x i8]}* %sptr, i64 0, i32 1
+ </pre>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="convertops">Conversion Operations</a>
+ </div>
+ <div class="doc_text">
+ <p>The instructions in this category are the conversion instructions (casting)
+ which all take a single operand and a type. They perform various bit conversions
+ on the operand.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = trunc <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>
+ The '<tt>trunc</tt>' instruction truncates its operand to the type <tt>ty2</tt>.
+ </p>
+
+ <h5>Arguments:</h5>
+ <p>
+ The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must
+ be an <a href="#t_integer">integer</a> type, and a type that specifies the size
+ and type of the result, which must be an <a href="#t_integer">integer</a>
+ type. The bit size of <tt>value</tt> must be larger than the bit size of
+ <tt>ty2</tt>. Equal sized types are not allowed.</p>
+
+ <h5>Semantics:</h5>
+ <p>
+ The '<tt>trunc</tt>' instruction truncates the high order bits in <tt>value</tt>
+ and converts the remaining bits to <tt>ty2</tt>. Since the source size must be
+ larger than the destination size, <tt>trunc</tt> cannot be a <i>no-op cast</i>.
+ It will always truncate bits.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = trunc i32 257 to i8 <i>; yields i8:1</i>
+ %Y = trunc i32 123 to i1 <i>; yields i1:true</i>
+ %Y = trunc i32 122 to i1 <i>; yields i1:false</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = zext <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>zext</tt>' instruction zero extends its operand to type
+ <tt>ty2</tt>.</p>
+
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
+ <a href="#t_integer">integer</a> type, and a type to cast it to, which must
+ also be of <a href="#t_integer">integer</a> type. The bit size of the
+ <tt>value</tt> must be smaller than the bit size of the destination type,
+ <tt>ty2</tt>.</p>
+
+ <h5>Semantics:</h5>
+ <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
+ bits until it reaches the size of the destination type, <tt>ty2</tt>.</p>
+
+ <p>When zero extending from i1, the result will always be either 0 or 1.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = zext i32 257 to i64 <i>; yields i64:257</i>
+ %Y = zext i1 true to i32 <i>; yields i32:1</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = sext <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
+
+ <h5>Arguments:</h5>
+ <p>
+ The '<tt>sext</tt>' instruction takes a value to cast, which must be of
+ <a href="#t_integer">integer</a> type, and a type to cast it to, which must
+ also be of <a href="#t_integer">integer</a> type. The bit size of the
+ <tt>value</tt> must be smaller than the bit size of the destination type,
+ <tt>ty2</tt>.</p>
+
+ <h5>Semantics:</h5>
+ <p>
+ The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
+ bit (highest order bit) of the <tt>value</tt> until it reaches the bit size of
+ the type <tt>ty2</tt>.</p>
+
+ <p>When sign extending from i1, the extension always results in -1 or 0.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = sext i8 -1 to i16 <i>; yields i16 :65535</i>
+ %Y = sext i1 true to i32 <i>; yields i32:-1</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = fptrunc <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
+ <tt>ty2</tt>.</p>
+
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
+ point</a> value to cast and a <a href="#t_floating">floating point</a> type to
+ cast it to. The size of <tt>value</tt> must be larger than the size of
+ <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
+ <i>no-op cast</i>.</p>
+
+ <h5>Semantics:</h5>
+ <p> The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
+ <a href="#t_floating">floating point</a> type to a smaller
+ <a href="#t_floating">floating point</a> type. If the value cannot fit within
+ the destination type, <tt>ty2</tt>, then the results are undefined.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = fptrunc double 123.0 to float <i>; yields float:123.0</i>
+ %Y = fptrunc double 1.0E+300 to float <i>; yields undefined</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = fpext <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
+ floating point value.</p>
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>fpext</tt>' instruction takes a
+ <a href="#t_floating">floating point</a> <tt>value</tt> to cast,
+ and a <a href="#t_floating">floating point</a> type to cast it to. The source
+ type must be smaller than the destination type.</p>
+
+ <h5>Semantics:</h5>
+ <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
+ <a href="#t_floating">floating point</a> type to a larger
+ <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
+ used to make a <i>no-op cast</i> because it always changes bits. Use
+ <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = fpext float 3.1415 to double <i>; yields double:3.1415</i>
+ %Y = fpext float 1.0 to float <i>; yields float:1.0 (no-op)</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = fptoui <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its
+ unsigned integer equivalent of type <tt>ty2</tt>.
+ </p>
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a
+ scalar or vector <a href="#t_floating">floating point</a> value, and a type
+ to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
+ type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
+ vector integer type with the same number of elements as <tt>ty</tt></p>
+
+ <h5>Semantics:</h5>
+ <p> The '<tt>fptoui</tt>' instruction converts its
+ <a href="#t_floating">floating point</a> operand into the nearest (rounding
+ towards zero) unsigned integer value. If the value cannot fit in <tt>ty2</tt>,
+ the results are undefined.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = fptoui double 123.0 to i32 <i>; yields i32:123</i>
+ %Y = fptoui float 1.0E+300 to i1 <i>; yields undefined:1</i>
+ %X = fptoui float 1.04E+17 to i8 <i>; yields undefined:1</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = fptosi <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>fptosi</tt>' instruction converts
+ <a href="#t_floating">floating point</a> <tt>value</tt> to type <tt>ty2</tt>.
+ </p>
+
+ <h5>Arguments:</h5>
+ <p> The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
+ scalar or vector <a href="#t_floating">floating point</a> value, and a type
+ to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
+ type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
+ vector integer type with the same number of elements as <tt>ty</tt></p>
+
+ <h5>Semantics:</h5>
+ <p>The '<tt>fptosi</tt>' instruction converts its
+ <a href="#t_floating">floating point</a> operand into the nearest (rounding
+ towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
+ the results are undefined.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = fptosi double -123.0 to i32 <i>; yields i32:-123</i>
+ %Y = fptosi float 1.0E-247 to i1 <i>; yields undefined:1</i>
+ %X = fptosi float 1.04E+17 to i8 <i>; yields undefined:1</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = uitofp <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
+ integer and converts that value to the <tt>ty2</tt> type.</p>
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a
+ scalar or vector <a href="#t_integer">integer</a> value, and a type to cast it
+ to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
+ type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
+ floating point type with the same number of elements as <tt>ty</tt></p>
+
+ <h5>Semantics:</h5>
+ <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
+ integer quantity and converts it to the corresponding floating point value. If
+ the value cannot fit in the floating point value, the results are undefined.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = uitofp i32 257 to float <i>; yields float:257.0</i>
+ %Y = uitofp i8 -1 to double <i>; yields double:255.0</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = sitofp <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed
+ integer and converts that value to the <tt>ty2</tt> type.</p>
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a
+ scalar or vector <a href="#t_integer">integer</a> value, and a type to cast it
+ to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
+ type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
+ floating point type with the same number of elements as <tt>ty</tt></p>
+
+ <h5>Semantics:</h5>
+ <p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed
+ integer quantity and converts it to the corresponding floating point value. If
+ the value cannot fit in the floating point value, the results are undefined.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = sitofp i32 257 to float <i>; yields float:257.0</i>
+ %Y = sitofp i8 -1 to double <i>; yields double:-1.0</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = ptrtoint <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to
+ the integer type <tt>ty2</tt>.</p>
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
+ must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to
+ <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.
+
+ <h5>Semantics:</h5>
+ <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
+ <tt>ty2</tt> by interpreting the pointer value as an integer and either
+ truncating or zero extending that value to the size of the integer type. If
+ <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
+ <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
+ are the same size, then nothing is done (<i>no-op cast</i>) other than a type
+ change.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = ptrtoint i32* %X to i8 <i>; yields truncation on 32-bit architecture</i>
+ %Y = ptrtoint i32* %x to i64 <i>; yields zero extension on 32-bit architecture</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = inttoptr <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to
+ a pointer type, <tt>ty2</tt>.</p>
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a>
+ value to cast, and a type to cast it to, which must be a
+ <a href="#t_pointer">pointer</a> type.
+
+ <h5>Semantics:</h5>
+ <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
+ <tt>ty2</tt> by applying either a zero extension or a truncation depending on
+ the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
+ size of a pointer then a truncation is done. If <tt>value</tt> is smaller than
+ the size of a pointer then a zero extension is done. If they are the same size,
+ nothing is done (<i>no-op cast</i>).</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = inttoptr i32 255 to i32* <i>; yields zero extension on 64-bit architecture</i>
+ %X = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit architecture</i>
+ %Y = inttoptr i64 0 to i32* <i>; yields truncation on 32-bit architecture</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = bitcast <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+ <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
+ <tt>ty2</tt> without changing any bits.</p>
+
+ <h5>Arguments:</h5>
+ <p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be
+ a first class value, and a type to cast it to, which must also be a <a
+ href="#t_firstclass">first class</a> type. The bit sizes of <tt>value</tt>
+ and the destination type, <tt>ty2</tt>, must be identical. If the source
+ type is a pointer, the destination type must also be a pointer.</p>
+
+ <h5>Semantics:</h5>
+ <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
+ <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
+ this conversion. The conversion is done as if the <tt>value</tt> had been
+ stored to memory and read back as type <tt>ty2</tt>. Pointer types may only be
+ converted to other pointer types with this instruction. To convert pointers to
+ other types, use the <a href="#i_inttoptr">inttoptr</a> or
+ <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
+
+ <h5>Example:</h5>
+ <pre>
+ %X = bitcast i8 255 to i8 <i>; yields i8 :-1</i>
+ %Y = bitcast i32* %x to sint* <i>; yields sint*:%x</i>
+ %Z = bitcast <2xint> %V to i64; <i>; yields i64: %V</i>
+ </pre>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
+ <div class="doc_text">
+ <p>The instructions in this category are the "miscellaneous"
+ instructions, which defy better classification.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = icmp <cond> <ty> <var1>, <var2> <i>; yields {i1}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>icmp</tt>' instruction returns a boolean value based on comparison
+ of its two integer or pointer operands.</p>
+ <h5>Arguments:</h5>
+ <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
+ the condition code indicating the kind of comparison to perform. It is not
+ a value, just a keyword. The possible condition code are:
+ <ol>
+ <li><tt>eq</tt>: equal</li>
+ <li><tt>ne</tt>: not equal </li>
+ <li><tt>ugt</tt>: unsigned greater than</li>
+ <li><tt>uge</tt>: unsigned greater or equal</li>
+ <li><tt>ult</tt>: unsigned less than</li>
+ <li><tt>ule</tt>: unsigned less or equal</li>
+ <li><tt>sgt</tt>: signed greater than</li>
+ <li><tt>sge</tt>: signed greater or equal</li>
+ <li><tt>slt</tt>: signed less than</li>
+ <li><tt>sle</tt>: signed less or equal</li>
+ </ol>
+ <p>The remaining two arguments must be <a href="#t_integer">integer</a> or
+ <a href="#t_pointer">pointer</a> typed. They must also be identical types.</p>
+ <h5>Semantics:</h5>
+ <p>The '<tt>icmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
+ the condition code given as <tt>cond</tt>. The comparison performed always
+ yields a <a href="#t_primitive">i1</a> result, as follows:
+ <ol>
+ <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
+ <tt>false</tt> otherwise. No sign interpretation is necessary or performed.
+ </li>
+ <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
+ <tt>false</tt> otherwise. No sign interpretation is necessary or performed.
+ <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
+ <tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
+ <li><tt>uge</tt>: interprets the operands as unsigned values and yields
+ <tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
+ <li><tt>ult</tt>: interprets the operands as unsigned values and yields
+ <tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
+ <li><tt>ule</tt>: interprets the operands as unsigned values and yields
+ <tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
+ <li><tt>sgt</tt>: interprets the operands as signed values and yields
+ <tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
+ <li><tt>sge</tt>: interprets the operands as signed values and yields
+ <tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
+ <li><tt>slt</tt>: interprets the operands as signed values and yields
+ <tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
+ <li><tt>sle</tt>: interprets the operands as signed values and yields
+ <tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
+ </ol>
+ <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
+ values are compared as if they were integers.</p>
+
+ <h5>Example:</h5>
+ <pre> <result> = icmp eq i32 4, 5 <i>; yields: result=false</i>
+ <result> = icmp ne float* %X, %X <i>; yields: result=false</i>
+ <result> = icmp ult i16 4, 5 <i>; yields: result=true</i>
+ <result> = icmp sgt i16 4, 5 <i>; yields: result=false</i>
+ <result> = icmp ule i16 -4, 5 <i>; yields: result=false</i>
+ <result> = icmp sge i16 4, 5 <i>; yields: result=false</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
+ </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = fcmp <cond> <ty> <var1>, <var2> <i>; yields {i1}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>fcmp</tt>' instruction returns a boolean value based on comparison
+ of its floating point operands.</p>
+ <h5>Arguments:</h5>
+ <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
+ the condition code indicating the kind of comparison to perform. It is not
+ a value, just a keyword. The possible condition code are:
+ <ol>
+ <li><tt>false</tt>: no comparison, always returns false</li>
+ <li><tt>oeq</tt>: ordered and equal</li>
+ <li><tt>ogt</tt>: ordered and greater than </li>
+ <li><tt>oge</tt>: ordered and greater than or equal</li>
+ <li><tt>olt</tt>: ordered and less than </li>
+ <li><tt>ole</tt>: ordered and less than or equal</li>
+ <li><tt>one</tt>: ordered and not equal</li>
+ <li><tt>ord</tt>: ordered (no nans)</li>
+ <li><tt>ueq</tt>: unordered or equal</li>
+ <li><tt>ugt</tt>: unordered or greater than </li>
+ <li><tt>uge</tt>: unordered or greater than or equal</li>
+ <li><tt>ult</tt>: unordered or less than </li>
+ <li><tt>ule</tt>: unordered or less than or equal</li>
+ <li><tt>une</tt>: unordered or not equal</li>
+ <li><tt>uno</tt>: unordered (either nans)</li>
+ <li><tt>true</tt>: no comparison, always returns true</li>
+ </ol>
+ <p><i>Ordered</i> means that neither operand is a QNAN while
+ <i>unordered</i> means that either operand may be a QNAN.</p>
+ <p>The <tt>val1</tt> and <tt>val2</tt> arguments must be
+ <a href="#t_floating">floating point</a> typed. They must have identical
+ types.</p>
+ <h5>Semantics:</h5>
+ <p>The '<tt>fcmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
+ the condition code given as <tt>cond</tt>. The comparison performed always
+ yields a <a href="#t_primitive">i1</a> result, as follows:
+ <ol>
+ <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
+ <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <tt>var1</tt> is equal to <tt>var2</tt>.</li>
+ <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <tt>var1</tt> is greather than <tt>var2</tt>.</li>
+ <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
+ <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <tt>var1</tt> is less than <tt>var2</tt>.</li>
+ <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
+ <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
+ <tt>var1</tt> is not equal to <tt>var2</tt>.</li>
+ <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
+ <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <tt>var1</tt> is equal to <tt>var2</tt>.</li>
+ <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <tt>var1</tt> is greater than <tt>var2</tt>.</li>
+ <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
+ <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <tt>var1</tt> is less than <tt>var2</tt>.</li>
+ <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
+ <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
+ <tt>var1</tt> is not equal to <tt>var2</tt>.</li>
+ <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
+ <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
+ </ol>
+
+ <h5>Example:</h5>
+ <pre> <result> = fcmp oeq float 4.0, 5.0 <i>; yields: result=false</i>
+ <result> = icmp one float 4.0, 5.0 <i>; yields: result=true</i>
+ <result> = icmp olt float 4.0, 5.0 <i>; yields: result=true</i>
+ <result> = icmp ueq double 1.0, 2.0 <i>; yields: result=false</i>
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = phi <ty> [ <val0>, <label0>], ...<br></pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>phi</tt>' instruction is used to implement the φ node in
+ the SSA graph representing the function.</p>
+ <h5>Arguments:</h5>
+ <p>The type of the incoming values is specified with the first type
+ field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
+ as arguments, with one pair for each predecessor basic block of the
+ current block. Only values of <a href="#t_firstclass">first class</a>
+ type may be used as the value arguments to the PHI node. Only labels
+ may be used as the label arguments.</p>
+ <p>There must be no non-phi instructions between the start of a basic
+ block and the PHI instructions: i.e. PHI instructions must be first in
+ a basic block.</p>
+ <h5>Semantics:</h5>
+ <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value
+ specified by the pair corresponding to the predecessor basic block that executed
+ just prior to the current block.</p>
+ <h5>Example:</h5>
+ <pre>Loop: ; Infinite loop that counts from 0 on up...<br> %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]<br> %nextindvar = add i32 %indvar, 1<br> br label %Loop<br></pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_select">'<tt>select</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = select i1 <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>select</tt>' instruction is used to choose one value based on a
+ condition, without branching.
+ </p>
+
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The '<tt>select</tt>' instruction requires a boolean value indicating the condition, and two values of the same <a href="#t_firstclass">first class</a> type.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ If the boolean condition evaluates to true, the instruction returns the first
+ value argument; otherwise, it returns the second value argument.
+ </p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i>
+ </pre>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_call">'<tt>call</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <result> = [tail] call [<a href="#callingconv">cconv</a>] <ty> [<fnty>*] <fnptrval>(<param list>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>This instruction requires several arguments:</p>
+
+ <ol>
+ <li>
+ <p>The optional "tail" marker indicates whether the callee function accesses
+ any allocas or varargs in the caller. If the "tail" marker is present, the
+ function call is eligible for tail call optimization. Note that calls may
+ be marked "tail" even if they do not occur before a <a
+ href="#i_ret"><tt>ret</tt></a> instruction.
+ </li>
+ <li>
+ <p>The optional "cconv" marker indicates which <a href="#callingconv">calling
+ convention</a> the call should use. If none is specified, the call defaults
+ to using C calling conventions.
+ </li>
+ <li>
+ <p>'<tt>ty</tt>': the type of the call instruction itself which is also
+ the type of the return value. Functions that return no value are marked
+ <tt><a href="#t_void">void</a></tt>.</p>
+ </li>
+ <li>
+ <p>'<tt>fnty</tt>': shall be the signature of the pointer to function
+ value being invoked. The argument types must match the types implied by
+ this signature. This type can be omitted if the function is not varargs
+ and if the function type does not return a pointer to a function.</p>
+ </li>
+ <li>
+ <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
+ be invoked. In most cases, this is a direct function invocation, but
+ indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
+ to function value.</p>
+ </li>
+ <li>
+ <p>'<tt>function args</tt>': argument list whose types match the
+ function signature argument types. All arguments must be of
+ <a href="#t_firstclass">first class</a> type. If the function signature
+ indicates the function accepts a variable number of arguments, the extra
+ arguments can be specified.</p>
+ </li>
+ </ol>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>call</tt>' instruction is used to cause control flow to
+ transfer to a specified function, with its incoming arguments bound to
+ the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
+ instruction in the called function, control flow continues with the
+ instruction after the function call, and the return value of the
+ function is bound to the result argument. If the callee returns multiple
+ values then the return values of the function are only accessible through
+ the '<tt><a href="#i_getresult">getresult</a></tt>' instruction.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %retval = call i32 @test(i32 %argc)
+ call i32 (i8 *, ...)* @printf(i8 * %msg, i32 12, i8 42) <i>; yields i32</i>
+ %X = tail call i32 @foo() <i>; yields i32</i>
+ %Y = tail call <a href="#callingconv">fastcc</a> i32 @foo() <i>; yields i32</i>
+ call void %foo(i8 97 signext)
+
+ %struct.A = type { i32, i8 }
+ %r = call %struct.A @foo() <i>; yields { 32, i8 }</i>
+ %gr = getresult %struct.A %r, 0 <i>; yields i32</i>
+ %gr1 = getresult %struct.A %r, 1 <i>; yields i8</i>
+ </pre>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <resultval> = va_arg <va_list*> <arglist>, <argty>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
+ the "variable argument" area of a function call. It is used to implement the
+ <tt>va_arg</tt> macro in C.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>This instruction takes a <tt>va_list*</tt> value and the type of
+ the argument. It returns a value of the specified argument type and
+ increments the <tt>va_list</tt> to point to the next argument. The
+ actual type of <tt>va_list</tt> is target specific.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>va_arg</tt>' instruction loads an argument of the specified
+ type from the specified <tt>va_list</tt> and causes the
+ <tt>va_list</tt> to point to the next argument. For more information,
+ see the variable argument handling <a href="#int_varargs">Intrinsic
+ Functions</a>.</p>
+
+ <p>It is legal for this instruction to be called in a function which does not
+ take a variable number of arguments, for example, the <tt>vfprintf</tt>
+ function.</p>
+
+ <p><tt>va_arg</tt> is an LLVM instruction instead of an <a
+ href="#intrinsics">intrinsic function</a> because it takes a type as an
+ argument.</p>
+
+ <h5>Example:</h5>
+
+ <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_getresult">'<tt>getresult</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ <resultval> = getresult <type> <retval>, <index>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p> The '<tt>getresult</tt>' instruction is used to extract individual values
+ from a '<tt><a href="#i_call">call</a></tt>'
+ or '<tt><a href="#i_invoke">invoke</a></tt>' instruction that returns multiple
+ results.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The '<tt>getresult</tt>' instruction takes a call or invoke value as its
+ first argument, or an undef value. The value must have <a
+ href="#t_struct">structure type</a>. The second argument is a constant
+ unsigned index value which must be in range for the number of values returned
+ by the call.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>getresult</tt>' instruction extracts the element identified by
+ '<tt>index</tt>' from the aggregate value.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %struct.A = type { i32, i8 }
+
+ %r = call %struct.A @foo()
+ %gr = getresult %struct.A %r, 0 <i>; yields i32:%gr</i>
+ %gr1 = getresult %struct.A %r, 1 <i>; yields i8:%gr1</i>
+ add i32 %gr, 42
+ add i8 %gr1, 41
+ </pre>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>LLVM supports the notion of an "intrinsic function". These functions have
+ well known names and semantics and are required to follow certain restrictions.
+ Overall, these intrinsics represent an extension mechanism for the LLVM
+ language that does not require changing all of the transformations in LLVM when
+ adding to the language (or the bitcode reader/writer, the parser, etc...).</p>
+
+ <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
+ prefix is reserved in LLVM for intrinsic names; thus, function names may not
+ begin with this prefix. Intrinsic functions must always be external functions:
+ you cannot define the body of intrinsic functions. Intrinsic functions may
+ only be used in call or invoke instructions: it is illegal to take the address
+ of an intrinsic function. Additionally, because intrinsic functions are part
+ of the LLVM language, it is required if any are added that they be documented
+ here.</p>
+
+ <p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents
+ a family of functions that perform the same operation but on different data
+ types. Because LLVM can represent over 8 million different integer types,
+ overloading is used commonly to allow an intrinsic function to operate on any
+ integer type. One or more of the argument types or the result type can be
+ overloaded to accept any integer type. Argument types may also be defined as
+ exactly matching a previous argument's type or the result type. This allows an
+ intrinsic function which accepts multiple arguments, but needs all of them to
+ be of the same type, to only be overloaded with respect to a single argument or
+ the result.</p>
+
+ <p>Overloaded intrinsics will have the names of its overloaded argument types
+ encoded into its function name, each preceded by a period. Only those types
+ which are overloaded result in a name suffix. Arguments whose type is matched
+ against another type do not. For example, the <tt>llvm.ctpop</tt> function can
+ take an integer of any width and returns an integer of exactly the same integer
+ width. This leads to a family of functions such as
+ <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29 %val)</tt>.
+ Only one type, the return type, is overloaded, and only one type suffix is
+ required. Because the argument's type is matched against the return type, it
+ does not require its own name suffix.</p>
+
+ <p>To learn how to add an intrinsic function, please see the
+ <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="int_varargs">Variable Argument Handling Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Variable argument support is defined in LLVM with the <a
+ href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
+ intrinsic functions. These functions are related to the similarly
+ named macros defined in the <tt><stdarg.h></tt> header file.</p>
+
+ <p>All of these functions operate on arguments that use a
+ target-specific value type "<tt>va_list</tt>". The LLVM assembly
+ language reference manual does not define what this type is, so all
+ transformations should be prepared to handle these functions regardless of
+ the type used.</p>
+
+ <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
+ instruction and the variable argument handling intrinsic functions are
+ used.</p>
+
+ <div class="doc_code">
+ <pre>
+ define i32 @test(i32 %X, ...) {
+ ; Initialize variable argument processing
+ %ap = alloca i8*
+ %ap2 = bitcast i8** %ap to i8*
+ call void @llvm.va_start(i8* %ap2)
+
+ ; Read a single integer argument
+ %tmp = va_arg i8** %ap, i32
+
+ ; Demonstrate usage of llvm.va_copy and llvm.va_end
+ %aq = alloca i8*
+ %aq2 = bitcast i8** %aq to i8*
+ call void @llvm.va_copy(i8* %aq2, i8* %ap2)
+ call void @llvm.va_end(i8* %aq2)
+
+ ; Stop processing of arguments.
+ call void @llvm.va_end(i8* %ap2)
+ ret i32 %tmp
+ }
+
+ declare void @llvm.va_start(i8*)
+ declare void @llvm.va_copy(i8*, i8*)
+ declare void @llvm.va_end(i8*)
+ </pre>
+ </div>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
+ </div>
+
+
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> declare void %llvm.va_start(i8* <arglist>)<br></pre>
+ <h5>Overview:</h5>
+ <P>The '<tt>llvm.va_start</tt>' intrinsic initializes
+ <tt>*<arglist></tt> for subsequent use by <tt><a
+ href="#i_va_arg">va_arg</a></tt>.</p>
+
+ <h5>Arguments:</h5>
+
+ <P>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
+
+ <h5>Semantics:</h5>
+
+ <P>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
+ macro available in C. In a target-dependent way, it initializes the
+ <tt>va_list</tt> element to which the argument points, so that the next call to
+ <tt>va_arg</tt> will produce the first variable argument passed to the function.
+ Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
+ last argument of the function as the compiler can figure that out.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> declare void @llvm.va_end(i8* <arglist>)<br></pre>
+ <h5>Overview:</h5>
+
+ <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*<arglist></tt>,
+ which has been initialized previously with <tt><a href="#int_va_start">llvm.va_start</a></tt>
+ or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
+ macro available in C. In a target-dependent way, it destroys the
+ <tt>va_list</tt> element to which the argument points. Calls to <a
+ href="#int_va_start"><tt>llvm.va_start</tt></a> and <a href="#int_va_copy">
+ <tt>llvm.va_copy</tt></a> must be matched exactly with calls to
+ <tt>llvm.va_end</tt>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
+ from the source argument list to the destination argument list.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
+ The second argument is a pointer to a <tt>va_list</tt> element to copy from.</p>
+
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
+ macro available in C. In a target-dependent way, it copies the source
+ <tt>va_list</tt> element into the destination <tt>va_list</tt> element. This
+ intrinsic is necessary because the <tt><a href="#int_va_start">
+ llvm.va_start</a></tt> intrinsic may be arbitrarily complex and require, for
+ example, memory allocation.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ LLVM support for <a href="GarbageCollection.html">Accurate Garbage
+ Collection</a> requires the implementation and generation of these intrinsics.
+ These intrinsics allow identification of <a href="#int_gcroot">GC roots on the
+ stack</a>, as well as garbage collector implementations that require <a
+ href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a> barriers.
+ Front-ends for type-safe garbage collected languages should generate these
+ intrinsics to make use of the LLVM garbage collectors. For more details, see <a
+ href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>.
+ </p>
+
+ <p>The garbage collection intrinsics only operate on objects in the generic
+ address space (address space zero).</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
+ the code generator, and allows some metadata to be associated with it.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The first argument specifies the address of a stack object that contains the
+ root pointer. The second pointer (which must be either a constant or a global
+ value address) contains the meta-data to be associated with the root.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc"
+ location. At compile-time, the code generator generates information to allow
+ the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>'
+ intrinsic may only be used in a function which <a href="#gc">specifies a GC
+ algorithm</a>.</p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
+ locations, allowing garbage collector implementations that require read
+ barriers.</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The second argument is the address to read from, which should be an address
+ allocated from the garbage collector. The first object is a pointer to the
+ start of the referenced object, if needed by the language runtime (otherwise
+ null).</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
+ instruction, but may be replaced with substantially more complex code by the
+ garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic
+ may only be used in a function which <a href="#gc">specifies a GC
+ algorithm</a>.</p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
+ locations, allowing garbage collector implementations that require write
+ barriers (such as generational or reference counting collectors).</p>
+
+ <h5>Arguments:</h5>
+
+ <p>The first argument is the reference to store, the second is the start of the
+ object to store it to, and the third is the address of the field of Obj to
+ store to. If the runtime does not require a pointer to the object, Obj may be
+ null.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
+ instruction, but may be replaced with substantially more complex code by the
+ garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic
+ may only be used in a function which <a href="#gc">specifies a GC
+ algorithm</a>.</p>
+
+ </div>
+
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="int_codegen">Code Generator Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ These intrinsics are provided by LLVM to expose special features that may only
+ be implemented with code generator support.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare i8 *@llvm.returnaddress(i32 <level>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
+ target-specific value indicating the return address of the current function
+ or one of its callers.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The argument to this intrinsic indicates which function to return the address
+ for. Zero indicates the calling function, one indicates its caller, etc. The
+ argument is <b>required</b> to be a constant integer value.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating
+ the return address of the specified call frame, or zero if it cannot be
+ identified. The value returned by this intrinsic is likely to be incorrect or 0
+ for arguments other than zero, so it should only be used for debugging purposes.
+ </p>
+
+ <p>
+ Note that calling this intrinsic does not prevent function inlining or other
+ aggressive transformations, so the value returned may not be that of the obvious
+ source-language caller.
+ </p>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare i8 *@llvm.frameaddress(i32 <level>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
+ target-specific frame pointer value for the specified stack frame.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The argument to this intrinsic indicates which function to return the frame
+ pointer for. Zero indicates the calling function, one indicates its caller,
+ etc. The argument is <b>required</b> to be a constant integer value.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating
+ the frame address of the specified call frame, or zero if it cannot be
+ identified. The value returned by this intrinsic is likely to be incorrect or 0
+ for arguments other than zero, so it should only be used for debugging purposes.
+ </p>
+
+ <p>
+ Note that calling this intrinsic does not prevent function inlining or other
+ aggressive transformations, so the value returned may not be that of the obvious
+ source-language caller.
+ </p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare i8 *@llvm.stacksave()
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state of
+ the function stack, for use with <a href="#int_stackrestore">
+ <tt>llvm.stackrestore</tt></a>. This is useful for implementing language
+ features like scoped automatic variable sized arrays in C99.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This intrinsic returns a opaque pointer value that can be passed to <a
+ href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>. When an
+ <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved from
+ <tt>llvm.stacksave</tt>, it effectively restores the state of the stack to the
+ state it was in when the <tt>llvm.stacksave</tt> intrinsic executed. In
+ practice, this pops any <a href="#i_alloca">alloca</a> blocks from the stack
+ that were allocated after the <tt>llvm.stacksave</tt> was executed.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void @llvm.stackrestore(i8 * %ptr)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
+ the function stack to the state it was in when the corresponding <a
+ href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic executed. This is
+ useful for implementing language features like scoped automatic variable sized
+ arrays in C99.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ See the description for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.
+ </p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+
+ <p>
+ The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to insert
+ a prefetch instruction if supported; otherwise, it is a noop. Prefetches have
+ no
+ effect on the behavior of the program but can change its performance
+ characteristics.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ <tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the specifier
+ determining if the fetch should be for a read (0) or write (1), and
+ <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
+ locality, to (3) - extremely local keep in cache. The <tt>rw</tt> and
+ <tt>locality</tt> arguments must be constant integers.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This intrinsic does not modify the behavior of the program. In particular,
+ prefetches cannot trap and do not produce a value. On targets that support this
+ intrinsic, the prefetch can provide hints to the processor cache for better
+ performance.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void @llvm.pcmarker(i32 <id>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+
+ <p>
+ The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program Counter
+ (PC) in a region of
+ code to simulators and other tools. The method is target specific, but it is
+ expected that the marker will use exported symbols to transmit the PC of the marker.
+ The marker makes no guarantees that it will remain with any specific instruction
+ after optimizations. It is possible that the presence of a marker will inhibit
+ optimizations. The intended use is to be inserted after optimizations to allow
+ correlations of simulation runs.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ <tt>id</tt> is a numerical id identifying the marker.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This intrinsic does not modify the behavior of the program. Backends that do not
+ support this intrinisic may ignore it.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare i64 @llvm.readcyclecounter( )
+ </pre>
+
+ <h5>Overview:</h5>
+
+
+ <p>
+ The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
+ counter register (or similar low latency, high accuracy clocks) on those targets
+ that support it. On X86, it should map to RDTSC. On Alpha, it should map to RPCC.
+ As the backing counters overflow quickly (on the order of 9 seconds on alpha), this
+ should only be used for small timings.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ When directly supported, reading the cycle counter should not modify any memory.
+ Implementations are allowed to either return a application specific value or a
+ system wide value. On backends without support, this is lowered to a constant 0.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="int_libc">Standard C Library Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ LLVM provides intrinsics for a few important standard C library functions.
+ These intrinsics allow source-language front-ends to pass information about the
+ alignment of the pointer arguments to the code generator, providing opportunity
+ for more efficient code generation.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void @llvm.memcpy.i32(i8 * <dest>, i8 * <src>,
+ i32 <len>, i32 <align>)
+ declare void @llvm.memcpy.i64(i8 * <dest>, i8 * <src>,
+ i64 <len>, i32 <align>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
+ location to the destination location.
+ </p>
+
+ <p>
+ Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
+ intrinsics do not return a value, and takes an extra alignment argument.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The first argument is a pointer to the destination, the second is a pointer to
+ the source. The third argument is an integer argument
+ specifying the number of bytes to copy, and the fourth argument is the alignment
+ of the source and destination locations.
+ </p>
+
+ <p>
+ If the call to this intrinisic has an alignment value that is not 0 or 1, then
+ the caller guarantees that both the source and destination pointers are aligned
+ to that boundary.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
+ location to the destination location, which are not allowed to overlap. It
+ copies "len" bytes of memory over. If the argument is known to be aligned to
+ some boundary, this can be specified as the fourth argument, otherwise it should
+ be set to 0 or 1.
+ </p>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void @llvm.memmove.i32(i8 * <dest>, i8 * <src>,
+ i32 <len>, i32 <align>)
+ declare void @llvm.memmove.i64(i8 * <dest>, i8 * <src>,
+ i64 <len>, i32 <align>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the source
+ location to the destination location. It is similar to the
+ '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to overlap.
+ </p>
+
+ <p>
+ Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
+ intrinsics do not return a value, and takes an extra alignment argument.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The first argument is a pointer to the destination, the second is a pointer to
+ the source. The third argument is an integer argument
+ specifying the number of bytes to copy, and the fourth argument is the alignment
+ of the source and destination locations.
+ </p>
+
+ <p>
+ If the call to this intrinisic has an alignment value that is not 0 or 1, then
+ the caller guarantees that the source and destination pointers are aligned to
+ that boundary.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the source
+ location to the destination location, which may overlap. It
+ copies "len" bytes of memory over. If the argument is known to be aligned to
+ some boundary, this can be specified as the fourth argument, otherwise it should
+ be set to 0 or 1.
+ </p>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void @llvm.memset.i32(i8 * <dest>, i8 <val>,
+ i32 <len>, i32 <align>)
+ declare void @llvm.memset.i64(i8 * <dest>, i8 <val>,
+ i64 <len>, i32 <align>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a particular
+ byte value.
+ </p>
+
+ <p>
+ Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic
+ does not return a value, and takes an extra alignment argument.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The first argument is a pointer to the destination to fill, the second is the
+ byte value to fill it with, the third argument is an integer
+ argument specifying the number of bytes to fill, and the fourth argument is the
+ known alignment of destination location.
+ </p>
+
+ <p>
+ If the call to this intrinisic has an alignment value that is not 0 or 1, then
+ the caller guarantees that the destination pointer is aligned to that boundary.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting at
+ the
+ destination location. If the argument is known to be aligned to some boundary,
+ this can be specified as the fourth argument, otherwise it should be set to 0 or
+ 1.
+ </p>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.
+ <pre>
+ declare float @llvm.sqrt.f32(float %Val)
+ declare double @llvm.sqrt.f64(double %Val)
+ declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val)
+ declare fp128 @llvm.sqrt.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
+ returning the same value as the libm '<tt>sqrt</tt>' functions would. Unlike
+ <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined behavior for
+ negative numbers other than -0.0 (which allows for better optimization, because
+ there is no need to worry about errno being set). <tt>llvm.sqrt(-0.0)</tt> is
+ defined to return -0.0 like IEEE sqrt.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The argument and return value are floating point numbers of the same type.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This function returns the sqrt of the specified operand if it is a nonnegative
+ floating point number.
+ </p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.
+ <pre>
+ declare float @llvm.powi.f32(float %Val, i32 %power)
+ declare double @llvm.powi.f64(double %Val, i32 %power)
+ declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power)
+ declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power)
+ declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
+ specified (positive or negative) power. The order of evaluation of
+ multiplications is not defined. When a vector of floating point type is
+ used, the second argument remains a scalar integer value.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The second argument is an integer power, and the first is a value to raise to
+ that power.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This function returns the first value raised to the second power with an
+ unspecified sequence of rounding operations.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.
+ <pre>
+ declare float @llvm.sin.f32(float %Val)
+ declare double @llvm.sin.f64(double %Val)
+ declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val)
+ declare fp128 @llvm.sin.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The argument and return value are floating point numbers of the same type.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This function returns the sine of the specified operand, returning the
+ same values as the libm <tt>sin</tt> functions would, and handles error
+ conditions in the same way.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.
+ <pre>
+ declare float @llvm.cos.f32(float %Val)
+ declare double @llvm.cos.f64(double %Val)
+ declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val)
+ declare fp128 @llvm.cos.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The argument and return value are floating point numbers of the same type.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This function returns the cosine of the specified operand, returning the
+ same values as the libm <tt>cos</tt> functions would, and handles error
+ conditions in the same way.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any
+ floating point or vector of floating point type. Not all targets support all
+ types however.
+ <pre>
+ declare float @llvm.pow.f32(float %Val, float %Power)
+ declare double @llvm.pow.f64(double %Val, double %Power)
+ declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power)
+ declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power)
+ declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the
+ specified (positive or negative) power.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The second argument is a floating point power, and the first is a value to
+ raise to that power.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This function returns the first value raised to the second power,
+ returning the
+ same values as the libm <tt>pow</tt> functions would, and handles error
+ conditions in the same way.</p>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="int_manip">Bit Manipulation Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ LLVM provides intrinsics for a few important bit manipulation operations.
+ These allow efficient code generation for some algorithms.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <p>This is an overloaded intrinsic function. You can use bswap on any integer
+ type that is an even number of bytes (i.e. BitWidth % 16 == 0).
+ <pre>
+ declare i16 @llvm.bswap.i16(i16 <id>)
+ declare i32 @llvm.bswap.i32(i32 <id>)
+ declare i64 @llvm.bswap.i64(i64 <id>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer
+ values with an even number of bytes (positive multiple of 16 bits). These are
+ useful for performing operations on data that is not in the target's native
+ byte order.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high
+ and low byte of the input i16 swapped. Similarly, the <tt>llvm.bswap.i32</tt>
+ intrinsic returns an i32 value that has the four bytes of the input i32
+ swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the returned
+ i32 will have its bytes in 3, 2, 1, 0 order. The <tt>llvm.bswap.i48</tt>,
+ <tt>llvm.bswap.i64</tt> and other intrinsics extend this concept to
+ additional even-byte lengths (6 bytes, 8 bytes and more, respectively).
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
+ width. Not all targets support all bit widths however.
+ <pre>
+ declare i8 @llvm.ctpop.i8 (i8 <src>)
+ declare i16 @llvm.ctpop.i16(i16 <src>)
+ declare i32 @llvm.ctpop.i32(i32 <src>)
+ declare i64 @llvm.ctpop.i64(i64 <src>)
+ declare i256 @llvm.ctpop.i256(i256 <src>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set in a
+ value.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The only argument is the value to be counted. The argument may be of any
+ integer type. The return type must match the argument type.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.
+ </p>
+ </div>
+
+ <!-- _