[llvm-commits] CVS: llvm-www/releases/1.5/docs/.cvsignore AliasAnalysis.html Bugpoint.html BytecodeFormat.html CFEBuildInstrs.html CodeGenerator.html CodingStandards.html CommandLine.html CompilerDriver.html CompilerWriterInfo.html ExtendingLLVM.html FAQ.html GarbageCollection.html GettingStarted.html GettingStartedVS.html HowToSubmitABug.html LLVMVsTheWorld.html LangRef.html Lexicon.html Makefile MakefileGuide.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
John Criswell
criswell at cs.uiuc.edu
Wed May 18 07:34:38 PDT 2005
Changes in directory llvm-www/releases/1.5/docs:
.cvsignore added (r1.1)
AliasAnalysis.html added (r1.1)
Bugpoint.html added (r1.1)
BytecodeFormat.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)
ExtendingLLVM.html added (r1.1)
FAQ.html added (r1.1)
GarbageCollection.html added (r1.1)
GettingStarted.html added (r1.1)
GettingStartedVS.html added (r1.1)
HowToSubmitABug.html added (r1.1)
LLVMVsTheWorld.html added (r1.1)
LangRef.html added (r1.1)
Lexicon.html added (r1.1)
Makefile added (r1.1)
MakefileGuide.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:
Initial commit of LLVM 1.5 documentation.
---
Diffs of the changes: (+28521 -0)
.cvsignore | 2
AliasAnalysis.html | 953 +++++++++++++
Bugpoint.html | 238 +++
BytecodeFormat.html | 1941 ++++++++++++++++++++++++++
CFEBuildInstrs.html | 361 +++++
CodeGenerator.html | 999 +++++++++++++
CodingStandards.html | 646 ++++++++
CommandLine.html | 1821 +++++++++++++++++++++++++
CompilerDriver.html | 823 +++++++++++
CompilerWriterInfo.html | 263 +++
ExtendingLLVM.html | 329 ++++
FAQ.html | 581 ++++++++
GarbageCollection.html | 533 +++++++
GettingStarted.html | 1540 +++++++++++++++++++++
GettingStartedVS.html | 360 +++++
HowToSubmitABug.html | 356 ++++
LLVMVsTheWorld.html | 180 ++
LangRef.html | 3311 ++++++++++++++++++++++++++++++++++++++++++++++
Lexicon.html | 172 ++
Makefile | 66
MakefileGuide.html | 1006 +++++++++++++
ProgrammersManual.html | 2243 +++++++++++++++++++++++++++++++
Projects.html | 454 ++++++
ReleaseNotes.html | 833 +++++++++++
SourceLevelDebugging.html | 1117 +++++++++++++++
Stacker.html | 1412 +++++++++++++++++++
SystemLibrary.html | 344 ++++
TableGenFundamentals.html | 565 +++++++
TestingGuide.html | 528 +++++++
UsingLibraries.html | 504 +++++++
WritingAnLLVMBackend.html | 256 +++
WritingAnLLVMPass.html | 1600 ++++++++++++++++++++++
doxygen.cfg | 863 +++++++++++
doxygen.cfg.in | 863 +++++++++++
doxygen.css | 90 +
doxygen.footer | 10
doxygen.header | 9
doxygen.intro | 18
index.html | 247 +++
llvm.css | 84 +
40 files changed, 28521 insertions(+)
Index: llvm-www/releases/1.5/docs/.cvsignore
diff -c /dev/null llvm-www/releases/1.5/docs/.cvsignore:1.1
*** /dev/null Wed May 18 09:34:07 2005
--- llvm-www/releases/1.5/docs/.cvsignore Wed May 18 09:33:18 2005
***************
*** 0 ****
--- 1,2 ----
+ doxygen.cfg
+
Index: llvm-www/releases/1.5/docs/AliasAnalysis.html
diff -c /dev/null llvm-www/releases/1.5/docs/AliasAnalysis.html:1.1
*** /dev/null Wed May 18 09:34:34 2005
--- llvm-www/releases/1.5/docs/AliasAnalysis.html Wed May 18 09:33:19 2005
***************
*** 0 ****
--- 1,953 ----
+ <!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>
+ </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="#MustNoMay">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.cs.uiuc.edu/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.cs.uiuc.edu/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>
+
+ </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>
+
+ </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>analyze</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.</p>
+
+ </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>
+
+ <!-- *********************************************************************** -->
+
+ <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.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:19 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/Bugpoint.html
diff -c /dev/null llvm-www/releases/1.5/docs/Bugpoint.html:1.1
*** /dev/null Wed May 18 09:34:34 2005
--- llvm-www/releases/1.5/docs/Bugpoint.html Wed May 18 09:33:19 2005
***************
*** 0 ****
--- 1,238 ----
+ <!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>gccas</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>gccas</tt>,
+ <tt>gccld</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>gccas</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 bytecode file, and give you instructions on how to
+ reproduce the failure with <tt>opt</tt>, <tt>analyze</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 bytecode
+ 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.
+
+ </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.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:19 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/BytecodeFormat.html
diff -c /dev/null llvm-www/releases/1.5/docs/BytecodeFormat.html:1.1
*** /dev/null Wed May 18 09:34:34 2005
--- llvm-www/releases/1.5/docs/BytecodeFormat.html Wed May 18 09:33:19 2005
***************
*** 0 ****
--- 1,1941 ----
+ <!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 Bytecode File Format</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ <style type="text/css">
+ TR, TD { border: 2px solid gray; padding-left: 4pt; padding-right: 4pt;
+ padding-top: 2pt; padding-bottom: 2pt; }
+ TH { border: 2px solid gray; font-weight: bold; font-size: 105%; }
+ TABLE { text-align: center; border: 2px solid black;
+ border-collapse: collapse; margin-top: 1em; margin-left: 1em;
+ margin-right: 1em; margin-bottom: 1em; }
+ .td_left { border: 2px solid gray; text-align: left; }
+ </style>
+ </head>
+ <body>
+ <div class="doc_title"> LLVM Bytecode File Format </div>
+ <ol>
+ <li><a href="#abstract">Abstract</a></li>
+ <li><a href="#concepts">Concepts</a>
+ <ol>
+ <li><a href="#blocks">Blocks</a></li>
+ <li><a href="#lists">Lists</a></li>
+ <li><a href="#fields">Fields</a></li>
+ <li><a href="#align">Alignment</a></li>
+ <li><a href="#vbr">Variable Bit-Rate Encoding</a></li>
+ <li><a href="#encoding">Encoding Primitives</a></li>
+ <li><a href="#slots">Slots</a></li>
+ </ol>
+ </li>
+ <li><a href="#general">General Structure</a> </li>
+ <li><a href="#blockdefs">Block Definitions</a>
+ <ol>
+ <li><a href="#signature">Signature Block</a></li>
+ <li><a href="#module">Module Block</a></li>
+ <li><a href="#globaltypes">Global Type Pool</a></li>
+ <li><a href="#globalinfo">Module Info Block</a></li>
+ <li><a href="#constantpool">Global Constant Pool</a></li>
+ <li><a href="#functiondefs">Function Definition</a></li>
+ <li><a href="#compactiontable">Compaction Table</a></li>
+ <li><a href="#instructionlist">Instruction List</a></li>
+ <li><a href="#opcodes">Instruction Opcodes</a></li>
+ <li><a href="#symtab">Symbol Table</a></li>
+ </ol>
+ </li>
+ <li><a href="#versiondiffs">Version Differences</a>
+ <ol>
+ <li><a href="#vers13">Version 1.3 Differences From 1.4</a></li>
+ <li><a href="#vers12">Version 1.2 Differences From 1.3</a></li>
+ <li><a href="#vers11">Version 1.1 Differences From 1.2</a></li>
+ <li><a href="#vers10">Version 1.0 Differences From 1.1</a></li>
+ </ol>
+ </li>
+ </ol>
+ <div class="doc_author">
+ <p>Written by <a href="mailto:rspencer at x10sys.com">Reid Spencer</a>
+ </p>
+ </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="abstract">Abstract </a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This document describes the LLVM bytecode file format. It specifies
+ the binary encoding rules of the bytecode file format so that
+ equivalent systems can encode bytecode files correctly. The LLVM
+ bytecode representation is used to store the intermediate
+ representation on disk in compacted form.</p>
+ <p>The LLVM bytecode format may change in the future, but LLVM will
+ always be backwards compatible with older formats. This document will
+ only describe the most current version of the bytecode format. See <a
+ href="#versiondiffs">Version Differences</a> for the details on how
+ the current version is different from previous versions.</p>
+ </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="concepts">Concepts</a> </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This section describes the general concepts of the bytecode file
+ format without getting into specific layout details. It is recommended
+ that you read this section thoroughly before interpreting the detailed
+ descriptions.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="blocks">Blocks</a> </div>
+ <div class="doc_text">
+ <p>LLVM bytecode files consist simply of a sequence of blocks of bytes
+ using a binary encoding Each block begins with an header of two
+ unsigned integers. The first value identifies the type of block and the
+ second value provides the size of the block in bytes. The block
+ identifier is used because it is possible for entire blocks to be
+ omitted from the file if they are empty. The block identifier helps the
+ reader determine which kind of block is next in the file. Note that
+ blocks can be nested within other blocks.</p>
+ <p> All blocks are variable length, and the block header specifies the
+ size of the block. All blocks begin on a byte index that is aligned to
+ an even 32-bit boundary. That is, the first block is 32-bit aligned
+ because it starts at offset 0. Each block is padded with zero fill
+ bytes to ensure that the next block also starts on a 32-bit boundary.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="lists">Lists</a> </div>
+ <div class="doc_text">
+ <p>LLVM Bytecode blocks often contain lists of things of a similar
+ type. For example, a function contains a list of instructions and a
+ function type contains a list of argument types. There are two basic
+ types of lists: length lists (<a href="#llist">llist</a>), and null
+ terminated lists (<a href="#zlist">zlist</a>), as described below in
+ the <a href="#encoding">Encoding Primitives</a>.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="fields">Fields</a> </div>
+ <div class="doc_text">
+ <p>Fields are units of information that LLVM knows how to write atomically. Most
+ fields have a uniform length or some kind of length indication built into their
+ encoding. For example, a constant string (array of bytes) is written simply as
+ the length followed by the characters. Although this is similar to a list,
+ constant strings are treated atomically and are thus fields.</p>
+ <p>Fields use a condensed bit format specific to the type of information
+ they must contain. As few bits as possible are written for each field. The
+ sections that follow will provide the details on how these fields are
+ written and how the bits are to be interpreted.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="align">Alignment</a> </div>
+ <div class="doc_text">
+ <p>To support cross-platform differences, the bytecode file is aligned on
+ certain boundaries. This means that a small amount of padding (at most 3
+ bytes) will be added to ensure that the next entry is aligned to a 32-bit
+ boundary.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="vbr">Variable Bit-Rate Encoding</a>
+ </div>
+ <div class="doc_text">
+ <p>Most of the values written to LLVM bytecode files are small integers. To
+ minimize the number of bytes written for these quantities, an encoding scheme
+ similar to UTF-8 is used to write integer data. The scheme is known as
+ variable bit rate (vbr) encoding. In this encoding, the high bit of
+ each byte is used to indicate if more bytes follow. If (byte &
+ 0x80) is non-zero in any given byte, it means there is another byte
+ immediately following that also contributes to the value. For the final
+ byte (byte & 0x80) is false (the high bit is not set). In each byte
+ only the low seven bits contribute to the value. Consequently 32-bit
+ quantities can take from one to <em>five</em> bytes to encode. In
+ general, smaller quantities will encode in fewer bytes, as follows:</p>
+ <table>
+ <tbody>
+ <tr>
+ <th>Byte #</th>
+ <th>Significant Bits</th>
+ <th>Maximum Value</th>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>0-6</td>
+ <td>127</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td>7-13</td>
+ <td>16,383</td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td>14-20</td>
+ <td>2,097,151</td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td>21-27</td>
+ <td>268,435,455</td>
+ </tr>
+ <tr>
+ <td>5</td>
+ <td>28-34</td>
+ <td>34,359,738,367</td>
+ </tr>
+ <tr>
+ <td>6</td>
+ <td>35-41</td>
+ <td>4,398,046,511,103</td>
+ </tr>
+ <tr>
+ <td>7</td>
+ <td>42-48</td>
+ <td>562,949,953,421,311</td>
+ </tr>
+ <tr>
+ <td>8</td>
+ <td>49-55</td>
+ <td>72,057,594,037,927,935</td>
+ </tr>
+ <tr>
+ <td>9</td>
+ <td>56-62</td>
+ <td>9,223,372,036,854,775,807</td>
+ </tr>
+ <tr>
+ <td>10</td>
+ <td>63-69</td>
+ <td>1,180,591,620,717,411,303,423</td>
+ </tr>
+ </tbody>
+ </table>
+ <p>Note that in practice, the tenth byte could only encode bit 63 since
+ the maximum quantity to use this encoding is a 64-bit integer.</p>
+ <p><em>Signed</em> VBR values are encoded with the standard vbr
+ encoding, but with the sign bit as the low order bit instead of the
+ high order bit. This allows small negative quantities to be encoded
+ efficiently. For example, -3
+ is encoded as "((3 << 1) | 1)" and 3 is encoded as "(3 <<
+ 1) | 0)", emitted with the standard vbr encoding above.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="encoding">Encoding Primitives</a> </div>
+ <div class="doc_text">
+ <p>Each field in the bytecode format is encoded into the file using a
+ small set of primitive formats. The table below defines the encoding
+ rules for the various primitives used and gives them each a type name.
+ The type names used in the descriptions of blocks and fields in the <a
+ href="#details">Detailed Layout</a>next section. Any type name with
+ the suffix <em>_vbr</em> indicates a quantity that is encoded using
+ variable bit rate encoding as described above.</p>
+ <table class="doc_table">
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Rule</b></th>
+ </tr>
+ <tr>
+ <td><a name="unsigned"><b>unsigned</b></a></td>
+ <td class="td_left">A 32-bit unsigned integer that always occupies four
+ consecutive bytes. The unsigned integer is encoded using LSB first
+ ordering. That is bits 2<sup>0</sup> through 2<sup>7</sup> are in the
+ byte with the lowest file offset (little endian).</td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;"><a name="uint24_vbr">
+ <b>uint24_vbr</b></a></td>
+ <td style="vertical-align: top; text-align: left;">A 24-bit unsigned
+ integer that occupies from one to four bytes using variable bit rate
+ encoding.</td>
+ </tr>
+ <tr>
+ <td><a name="uint32_vbr"><b>uint32_vbr</b></a></td>
+ <td class="td_left">A 32-bit unsigned integer that occupies from one to
+ five bytes using variable bit rate encoding.</td>
+ </tr>
+ <tr>
+ <td><a name="uint64_vbr"><b>uint64_vbr</b></a></td>
+ <td class="td_left">A 64-bit unsigned integer that occupies from one to ten
+ bytes using variable bit rate encoding.</td>
+ </tr>
+ <tr>
+ <td><a name="int64_vbr"><b>int64_vbr</b></a></td>
+ <td class="td_left">A 64-bit signed integer that occupies from one to ten
+ bytes using the signed variable bit rate encoding.</td>
+ </tr>
+ <tr>
+ <td><a name="char"><b>char</b></a></td>
+ <td class="td_left">A single unsigned character encoded into one byte</td>
+ </tr>
+ <tr>
+ <td><a name="bit"><b>bit(n-m)</b></a></td>
+ <td class="td_left">A set of bit within some larger integer field. The values
+ of <code>n</code> and <code>m</code> specify the inclusive range of bits
+ that define the subfield. The value for <code>m</code> may be omitted if
+ its the same as <code>n</code>.</td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;"><b><a name="float"><b>float</b></a></b></td>
+ <td style="vertical-align: top; text-align: left;">A floating point value encoded
+ as a 32-bit IEEE value written in little-endian form.<br>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;"><b><b><a name="double"><b>double</b></a></b></b></td>
+ <td style="vertical-align: top; text-align: left;">A floating point value encoded
+ as a64-bit IEEE value written in little-endian form</td>
+ </tr>
+ <tr>
+ <td><a name="string"><b>string</b></a></td>
+ <td class="td_left">A uint32_vbr indicating the type of the
+ constant string which also includes its length, immediately followed by
+ the characters of the string. There is no terminating null byte in the
+ string.</td>
+ </tr>
+ <tr>
+ <td><a name="data"><b>data</b></a></td>
+ <td class="td_left">An arbitrarily long segment of data to which
+ no interpretation is implied. This is used for constant initializers.<br>
+ </td>
+ </tr>
+ <tr>
+ <td><a name="llist"><b>llist(x)</b></a></td>
+ <td class="td_left">A length list of x. This means the list is
+ encoded as an <a href="#uint32_vbr">uint32_vbr</a> providing the
+ length of the list, followed by a sequence of that many "x" items. This
+ implies that the reader should iterate the number of times provided by
+ the length.</td>
+ </tr>
+ <tr>
+ <td><a name="zlist"><b>zlist(x)</b></a></td>
+ <td class="td_left">A zero-terminated list of x. This means the
+ list is encoded as a sequence of an indeterminate number of "x" items,
+ followed by an <a href="#uint32_vbr">uint32_vbr</a> terminating value.
+ This implies that none of the "x" items can have a zero value (or else
+ the list terminates).</td>
+ </tr>
+ <tr>
+ <td><a name="block"><b>block</b></a></td>
+ <td class="td_left">A block of data that is logically related. A
+ block is an unsigned 32-bit integer that encodes the type of the block
+ in the low 5 bits and the size of the block in the high 27 bits. The
+ length does not include the block header or any alignment bytes at the
+ end of the block. Blocks may compose other blocks. </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="notation">Field Notation</a> </div>
+ <div class="doc_text">
+ <p>In the detailed block and field descriptions that follow, a regex
+ like notation is used to describe optional and repeated fields. A very
+ limited subset of regex is used to describe these, as given in the
+ following table: </p>
+ <table class="doc_table">
+ <tbody>
+ <tr>
+ <th><b>Character</b></th>
+ <th class="td_left"><b>Meaning</b></th>
+ </tr>
+ <tr>
+ <td><b><code>?</code></b></td>
+ <td class="td_left">The question mark indicates 0 or 1
+ occurrences of the thing preceding it.</td>
+ </tr>
+ <tr>
+ <td><b><code>*</code></b></td>
+ <td class="td_left">The asterisk indicates 0 or more occurrences
+ of the thing preceding it.</td>
+ </tr>
+ <tr>
+ <td><b><code>+</code></b></td>
+ <td class="td_left">The plus sign indicates 1 or more occurrences
+ of the thing preceding it.</td>
+ </tr>
+ <tr>
+ <td><b><code>()</code></b></td>
+ <td class="td_left">Parentheses are used for grouping.</td>
+ </tr>
+ <tr>
+ <td><b><code>,</code></b></td>
+ <td class="td_left">The comma separates sequential fields.</td>
+ </tr>
+ </tbody>
+ </table>
+ <p>So, for example, consider the following specifications:</p>
+ <div class="doc_code">
+ <ol>
+ <li><code>string?</code></li>
+ <li><code>(uint32_vbr,uin32_vbr)+</code></li>
+ <li><code>(unsigned?,uint32_vbr)*</code></li>
+ <li><code>(llist(unsigned))?</code></li>
+ </ol>
+ </div>
+ <p>with the following interpretations:</p>
+ <ol>
+ <li>An optional string. Matches either nothing or a single string</li>
+ <li>One or more pairs of uint32_vbr.</li>
+ <li>Zero or more occurrences of either an unsigned followed by a
+ uint32_vbr or just a uint32_vbr.</li>
+ <li>An optional length list of unsigned values.</li>
+ </ol>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="slots">Slots</a> </div>
+ <div class="doc_text">
+ <p>The bytecode format uses the notion of a "slot" to reference Types
+ and Values. Since the bytecode file is a <em>direct</em> representation of
+ LLVM's intermediate representation, there is a need to represent pointers in
+ the file. Slots are used for this purpose. For example, if one has the following
+ assembly:
+ </p>
+ <div class="doc_code"><code> %MyType = type { int, sbyte }<br>
+ %MyVar = external global %MyType
+ </code></div>
+ <p>there are two definitions. The definition of <tt>%MyVar</tt> uses <tt>%MyType</tt>.
+ In the C++ IR this linkage between <tt>%MyVar</tt> and <tt>%MyType</tt>
+ is explicit through the use of C++ pointers. In bytecode, however, there's no
+ ability to store memory addresses. Instead, we compute and write out
+ slot numbers for every Type and Value written to the file.</p>
+ <p>A slot number is simply an unsigned 32-bit integer encoded in the variable
+ bit rate scheme (see <a href="#encoding">encoding</a>). This ensures that
+ low slot numbers are encoded in one byte. Through various bits of magic LLVM
+ attempts to always keep the slot numbers low. The first attempt is to associate
+ slot numbers with their "type plane". That is, Values of the same type
+ are written to the bytecode file in a list (sequentially). Their order in
+ that list determines their slot number. This means that slot #1 doesn't mean
+ anything unless you also specify for which type you want slot #1. Types are
+ always written to the file first (in the <a href="#globaltypes">Global Type
+ Pool</a>) and in such a way that both forward and backward references of the
+ types can often be resolved with a single pass through the type pool. </p>
+ <p>Slot numbers are also kept small by rearranging their order. Because
+ of the structure of LLVM, certain values are much more likely to be used
+ frequently in the body of a function. For this reason, a compaction table is
+ provided in the body of a function if its use would make the function body
+ smaller. Suppose you have a function body that uses just the types "int*" and
+ "{double}" but uses them thousands of time. Its worthwhile to ensure that the
+ slot number for these types are low so they can be encoded in a single byte
+ (via vbr). This is exactly what the compaction table does.</p>
+ <p>In summary then, a slot number can be though of as just a vbr encoded index
+ into a list of Type* or Value*. To keep slot numbers low, Value* are indexed by
+ two slot numbers: the "type plane index" (type slot) and the "value index"
+ (value slot).</p>
+ </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="general">General Structure</a> </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This section provides the general structure of the LLVM bytecode
+ file format. The bytecode file format requires blocks to be in a
+ certain order and nested in a particular way so that an LLVM module can
+ be constructed efficiently from the contents of the file. This ordering
+ defines a general structure for bytecode files as shown below. The
+ table below shows the order in which all block types may appear. Please
+ note that some of the blocks are optional and some may be repeated. The
+ structure is fairly loose because optional blocks, if empty, are
+ completely omitted from the file.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th>ID</th>
+ <th>Parent</th>
+ <th>Optional?</th>
+ <th>Repeated?</th>
+ <th>Level</th>
+ <th>Block Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>N/A</td>
+ <td>File</td>
+ <td>No</td>
+ <td>No</td>
+ <td>0</td>
+ <td class="td_left"><a href="#signature">Signature</a></td>
+ <td class="td_left">This contains the file signature (magic
+ number) that identifies the file as LLVM bytecode.</td>
+ </tr>
+ <tr>
+ <td>0x01</td>
+ <td>File</td>
+ <td>No</td>
+ <td>No</td>
+ <td>0</td>
+ <td class="td_left"><a href="#module">Module</a></td>
+ <td class="td_left">This is the top level block in a bytecode
+ file. It contains all the other blocks. </td>
+ </tr>
+ <tr>
+ <td>0x06</td>
+ <td>Module</td>
+ <td>No</td>
+ <td>No</td>
+ <td>1</td>
+ <td class="td_left"> <a href="#globaltypes">Global Type Pool</a></td>
+ <td class="td_left">This block contains all the global (module)
+ level types.</td>
+ </tr>
+ <tr>
+ <td>0x05</td>
+ <td>Module</td>
+ <td>No</td>
+ <td>No</td>
+ <td>1</td>
+ <td class="td_left"> <a href="#globalinfo">Module Globals Info</a></td>
+ <td class="td_left">This block contains the type, constness, and
+ linkage for each of the global variables in the module. It also
+ contains the type of the functions and the constant initializers.</td>
+ </tr>
+ <tr>
+ <td>0x03</td>
+ <td>Module</td>
+ <td>Yes</td>
+ <td>No</td>
+ <td>1</td>
+ <td class="td_left"> <a href="#constantpool">Module Constant Pool</a></td>
+ <td class="td_left">This block contains all the global constants
+ except function arguments, global values and constant strings.</td>
+ </tr>
+ <tr>
+ <td>0x02</td>
+ <td>Module</td>
+ <td>Yes</td>
+ <td>Yes</td>
+ <td>1</td>
+ <td class="td_left"> <a href="#functiondefs">Function Definitions</a>*</td>
+ <td class="td_left">One function block is written for each
+ function in the module. The function block contains the instructions,
+ compaction table, type constant pool, and symbol table for the function.</td>
+ </tr>
+ <tr>
+ <td>0x03</td>
+ <td>Function</td>
+ <td>Yes</td>
+ <td>No</td>
+ <td>2</td>
+ <td class="td_left"> <a
+ href="#constantpool">Function Constant Pool</a></td>
+ <td class="td_left">Any constants (including types) used solely
+ within the function are emitted here in the function constant pool. </td>
+ </tr>
+ <tr>
+ <td>0x08</td>
+ <td>Function</td>
+ <td>Yes</td>
+ <td>No</td>
+ <td>2</td>
+ <td class="td_left"> <a
+ href="#compactiontable">Compaction Table</a></td>
+ <td class="td_left">This table reduces bytecode size by providing
+ a funtion-local mapping of type and value slot numbers to their global
+ slot numbers</td>
+ </tr>
+ <tr>
+ <td>0x07</td>
+ <td>Function</td>
+ <td>No</td>
+ <td>No</td>
+ <td>2</td>
+ <td class="td_left"> <a
+ href="#instructionlist">Instruction List</a></td>
+ <td class="td_left">This block contains all the instructions of
+ the function. The basic blocks are inferred by terminating
+ instructions. </td>
+ </tr>
+ <tr>
+ <td>0x04</td>
+ <td>Function</td>
+ <td>Yes</td>
+ <td>No</td>
+ <td>2</td>
+ <td class="td_left"> <a
+ href="#symtab">Function Symbol Table</a></td>
+ <td class="td_left">This symbol table provides the names for the
+ function specific values used (basic block labels mostly).</td>
+ </tr>
+ <tr>
+ <td>0x04</td>
+ <td>Module</td>
+ <td>Yes</td>
+ <td>No</td>
+ <td>1</td>
+ <td class="td_left"> <a href="#symtab">Module Symbol Table</a></td>
+ <td class="td_left">This symbol table provides the names for the
+ various entries in the file that are not function specific (global
+ vars, and functions mostly).</td>
+ </tr>
+ </tbody>
+ </table>
+ <p>Use the links in the table for details about the contents of each of
+ the block types.</p>
+ </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="blockdefs">Block Definitions</a> </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This section provides the detailed layout of the individual block
+ types in the LLVM bytecode file format. </p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="signature">Signature Block</a> </div>
+ <div class="doc_text">
+ <p>The signature occurs in every LLVM bytecode file and is always first.
+ It simply provides a few bytes of data to identify the file as being an LLVM
+ bytecode file. This block is always four bytes in length and differs from the
+ other blocks because there is no identifier and no block length at the start
+ of the block. Essentially, this block is just the "magic number" for the file.
+ </p>
+ <p>There are two types of signatures for LLVM bytecode: uncompressed and
+ compressed as shown in the table below. </p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Uncompressed</b></th>
+ <th class="td_left"><b>Compressed</b></th>
+ </tr>
+ <tr>
+ <td><a href="#char">char</a></td>
+ <td class="td_left">Constant "l" (0x6C)</td>
+ <td class="td_left">Constant "l" (0x6C)</td>
+ </tr>
+ <tr>
+ <td><a href="#char">char</a></td>
+ <td class="td_left">Constant "l" (0x6C)</td>
+ <td class="td_left">Constant "l" (0x6C)</td>
+ </tr>
+ <tr>
+ <td><a href="#char">char</a></td>
+ <td class="td_left">Constant "v" (0x76)</td>
+ <td class="td_left">Constant "v" (0x76)</td>
+ </tr>
+ <tr>
+ <td><a href="#char">char</a></td>
+ <td class="td_left">Constant "m" (0x6D)</td>
+ <td class="td_left">Constant "c" (0x63)</td>
+ </tr>
+ <tr>
+ <td><a href="#char">char</a></td>
+ <td class="td_left">N/A</td>
+ <td class="td_left">'0'=null,'1'=gzip,'2'=bzip2</td>
+ </tr>
+ </tbody>
+ </table>
+ <p>In other words, the uncompressed signature is just the characters 'llvm'
+ while the compressed signature is the characters 'llvc' followed by an ascii
+ digit ('0', '1', or '2') that indicates the kind of compression used. A value of
+ '0' indicates that null compression was used. This can happen when compression
+ was requested on a platform that wasn't configured for gzip or bzip2. A value of
+ '1' means that the rest of the file is compressed using the gzip algorithm and
+ should be uncompressed before interpretation. A value of '2' means that the rest
+ of the file is compressed using the bzip2 algorithm and should be uncompressed
+ before interpretation. In all cases, the data resulting from uncompression
+ should be interpreted as if it occurred immediately after the 'llvm'
+ signature (i.e. the uncompressed data begins with the
+ <a href="#module">Module Block</a></p>
+ <p><b>NOTE:</b> As of LLVM 1.4, all bytecode files produced by the LLVM tools
+ are compressed by default. To disable compression, pass the
+ <tt>--disable-compression</tt> option to the tool, if it supports it.
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="module">Module Block</a> </div>
+ <div class="doc_text">
+ <p>The module block contains a small pre-amble and all the other blocks in
+ the file. The table below shows the structure of the module block. Note that it
+ only provides the module identifier, size of the module block, and the format
+ information. Everything else is contained in other blocks, described in other
+ sections.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#unsigned">unsigned</a><br></td>
+ <td class="td_left"><a href="#mod_header">Module Block Identifier
+ (0x01)</a></td>
+ </tr>
+ <tr>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left"><a href="#mod_header">Module Block Size</a></td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left"><a href="#format">Format Information</a></td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left"><a href="#globaltypes">Global Type Pool</a></td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left"><a href="#globalinfo">Module Globals Info</a></td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left"><a href="#constantpool">Module Constant Pool</a></td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a>*</td>
+ <td class="td_left"><a href="#functiondefs">Function Definitions</a></td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left"><a href="#symtab">Module Symbol Table</a></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="mod_header">Module Block Header</a></div>
+ <div class="doc_text">
+ <p>The block header for the module block uses a longer format than the other
+ blocks in a bytecode file. Specifically, instead of encoding the type and size
+ of the block into a 32-bit integer with 5-bits for type and 27-bits for size,
+ the module block header uses two 32-bit unsigned values, one for type, and one
+ for size. While the 2<sup>27</sup> byte limit on block size is sufficient for the blocks
+ contained in the module, it isn't sufficient for the module block itself
+ because we want to ensure that bytecode files as large as 2<sup>32</sup> bytes
+ are possible. For this reason, the module block (and only the module block)
+ uses a long format header.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="format">Format Information</a></div>
+ <div class="doc_text">
+ <p>The format information field is encoded into a <a href="#uint32_vbr">uint32_vbr</a>
+ as shown in the following table.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(0)</a></td>
+ <td class="td_left">Target is big endian?</td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(1)</a></td>
+ <td class="td_left">On target pointers are 64-bit?</td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(2)</a></td>
+ <td class="td_left">Target has no endianess?</td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(3)</a></td>
+ <td class="td_left">Target has no pointer size?</td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(4-31)</a></td>
+ <td class="td_left">Bytecode format version</td>
+ </tr>
+ </tbody>
+ </table>
+ <p>
+ Of particular note, the bytecode format number is simply a 28-bit
+ monotonically increase integer that identifies the version of the bytecode
+ format (which is not directly related to the LLVM release number). The
+ bytecode versions defined so far are (note that this document only
+ describes the latest version, 1.3):</p>
+ <ul>
+ <li>#0: LLVM 1.0 & 1.1</li>
+ <li>#1: LLVM 1.2</li>
+ <li>#2: LLVM 1.2.5 (not released)</li>
+ <li>#3: LLVM 1.3<br>
+ </li>
+ </ul>
+ <p>Note that we plan to eventually expand the target description
+ capabilities
+ of bytecode files to <a href="http://llvm.cs.uiuc.edu/PR263">target
+ triples</a>.
+ </p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="globaltypes">Global Type Pool</a> </div>
+ <div class="doc_text">
+ <p>The global type pool consists of type definitions. Their order of appearance
+ in the file determines their type slot number (0 based). Slot numbers are
+ used to replace pointers in the intermediate representation. Each slot number
+ uniquely identifies one entry in a type plane (a collection of values of the
+ same type). Since all values have types and are associated with the order in
+ which the type pool is written, the global type pool <em>must</em> be written
+ as the first block of a module. If it is not, attempts to read the file will
+ fail because both forward and backward type resolution will not be possible.</p>
+ <p>The type pool is simply a list of type definitions, as shown in the
+ table below.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#unsigned">block</a></td>
+ <td class="td_left">Type Pool Identifier (0x06) + Size<br>
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#llist">llist</a>(<a href="#type">type</a>)</td>
+ <td class="td_left">A length list of type definitions.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="type">Type Definitions</a></div>
+ <div class="doc_text">
+ <p>Types in the type pool are defined using a different format for each kind
+ of type, as given in the following sections.</p>
+ <h3>Primitive Types</h3>
+ <p>The primitive types encompass the basic integer and floating point
+ types. They are encoded simply as their TypeID.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type ID for the primitive types (values 1 to
+ 11) <sup>1</sup></td>
+ </tr>
+ </tbody>
+ </table>
+ Notes:
+ <ol>
+ <li>The values for the Type IDs for the primitive types are provided
+ by the definition of the <code>llvm::Type::TypeID</code> enumeration
+ in <code>include/llvm/Type.h</code>. The enumeration gives the
+ following mapping:
+ <ol>
+ <li>bool</li>
+ <li>ubyte</li>
+ <li>sbyte</li>
+ <li>ushort</li>
+ <li>short</li>
+ <li>uint</li>
+ <li>int</li>
+ <li>ulong</li>
+ <li>long</li>
+ <li>float</li>
+ <li>double</li>
+ </ol>
+ </li>
+ </ol>
+ <h3>Function Types</h3>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type ID for function types (13)</td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type slot number of function's return type.</td>
+ </tr>
+ <tr>
+ <td><a href="#llist">llist</a>(<a href="#uint24_vbr">uint24_vbr</a>)</td>
+ <td class="td_left">Type slot number of each argument's type.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a>?</td>
+ <td class="td_left">Value 0 if this is a varargs function,
+ missing otherwise.</td>
+ </tr>
+ </tbody>
+ </table>
+ <h3>Structure Types</h3>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type ID for structure types (14)</td>
+ </tr>
+ <tr>
+ <td><a href="#zlist">zlist</a>(<a href="#uint24_vbr">uint24_vbr</a>)</td>
+ <td class="td_left">Slot number of each of the element's fields.</td>
+ </tr>
+ </tbody>
+ </table>
+ <h3>Array Types</h3>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type ID for Array Types (15)</td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type slot number of array's element type.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">The number of elements in the array.</td>
+ </tr>
+ </tbody>
+ </table>
+ <h3>Pointer Types</h3>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type ID For Pointer Types (16)</td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type slot number of pointer's element type.</td>
+ </tr>
+ </tbody>
+ </table>
+ <h3>Opaque Types</h3>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type ID For Opaque Types (17)</td>
+ </tr>
+ </tbody>
+ </table>
+ <h3>Packed Types</h3>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type ID for Packed Types (18)</td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Slot number of packed vector's element type.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">The number of elements in the packed vector.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="globalinfo">Module Global Info</a>
+ </div>
+ <div class="doc_text">
+ <p>The module global info block contains the definitions of all global
+ variables including their initializers and the <em>declaration</em> of
+ all functions. The format is shown in the table below:</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left">Module global info identifier (0x05) + size<br>
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#zlist">zlist</a>(<a href="#globalvar">globalvar</a>)</td>
+ <td class="td_left">A zero terminated list of global var
+ definitions occurring in the module.</td>
+ </tr>
+ <tr>
+ <td><a href="#zlist">zlist</a>(<a href="#funcfield">funcfield</a>)</td>
+ <td class="td_left">A zero terminated list of function definitions
+ occurring in the module.</td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;"><a href="#llist">llist</a>(<a
+ href="#string">string</a>)<br>
+ </td>
+ <td style="vertical-align: top; text-align: left;">A length list
+ of strings that specify the names of the libraries that this module
+ depends upon.<br>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;"><a href="#string">string</a><br>
+ </td>
+ <td style="vertical-align: top; text-align: left;">The target
+ triple for the module (blank means no target triple specified, i.e. a
+ platform independent module).<br>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="globalvar">Global Variable Field</a>
+ </div>
+ <div class="doc_text">
+ <p>Global variables are written using an <a href="#uint32_vbr">uint32_vbr</a>
+ that encodes information about the global variable and a list of the
+ constant initializers for the global var, if any.</p>
+ <p>The table below provides the bit layout of the first <a
+ href="#uint32_vbr">uint32_vbr</a> that describes the global variable.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(0)</a></td>
+ <td class="td_left">Is constant?</td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(1)</a></td>
+ <td class="td_left">Has initializer? Note that this bit
+ determines whether the constant initializer field (described below)
+ follows. </td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(2-4)</a></td>
+ <td class="td_left">Linkage type: 0=External, 1=Weak,
+ 2=Appending, 3=Internal, 4=LinkOnce</td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(5-31)</a></td>
+ <td class="td_left">Type slot number of type for the global variable.</td>
+ </tr>
+ </tbody>
+ </table>
+ <p>The table below provides the format of the constant initializers for
+ the global variable field, if it has one.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td>(<a href="#zlist">zlist</a>(<a href="#uint32_vbr">uint32_vbr</a>))?
+ </td>
+ <td class="td_left">An optional zero-terminated list of value slot
+ numbers of the global variable's constant initializer.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="funcfield">Function Field</a>
+ </div>
+ <div class="doc_text">
+ <p>Functions are written using an <a href="#uint32_vbr">uint32_vbr</a>
+ that encodes information about the function and a set of flags.</p>
+
+ <p>The table below provides the bit layout of the <a
+ href="#uint32_vbr">uint32_vbr</a> that describes the function.</p>
+
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(0-3)</a></td>
+ <td class="td_left">
+ Encodes the calling convention number of the function. If this number is
+ zero, this field is followed by a vbr indicating the CC#. Otherwise, the
+ CC number of the function is the value of this field minus one.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(4)</a></td>
+ <td class="td_left">If this bit is set to 1, the indicated function is
+ external, and there is no <a href="#functiondefs">Function Definiton
+ Block</a> in the bytecode file for the function.</td>
+ </tr>
+ <tr>
+ <td><a href="#bit">bit(5-)</a></td>
+ <td class="td_left">Type slot number of type for the function.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="constantpool">Constant Pool</a> </div>
+ <div class="doc_text">
+ <p>A constant pool defines as set of constant values. There are
+ actually two types of constant pool blocks: one for modules and one for
+ functions. For modules, the block begins with the constant strings
+ encountered anywhere in the module. For functions, the block begins
+ with types only encountered in the function. In both cases the header
+ is identical. The tables that follow, show the header, module constant
+ pool preamble, function constant pool preamble, and the part common to
+ both function and module constant pools.</p>
+ <p><b>Common Block Header</b></p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left">Constant pool identifier (0x03) + size<br>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ <p><b>Module Constant Pool Preamble (constant strings)</b></p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">The number of constant strings that follow.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">Zero. This identifies the following "plane"
+ as containing the constant strings. This is needed to identify it
+ uniquely from other constant planes that follow. </td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a>+</td>
+ <td class="td_left">Type slot number of the constant string's type.
+ Note that the constant string's type implicitly defines the length of
+ the string. </td>
+ </tr>
+ </tbody>
+ </table>
+ <p><b>Function Constant Pool Preamble (function types)</b></p>
+ <p>The structure of the types for functions is identical to the <a
+ href="#globaltypes">Global Type Pool</a>. Please refer to that section
+ for the details. </p>
+ <p><b>Common Part (other constants)</b></p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">Number of entries in this type plane.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type slot number of this plane.</td>
+ </tr>
+ <tr>
+ <td><a href="#constant">constant</a>+</td>
+ <td class="td_left">The definition of a constant (see below).</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="constant">Constant Field</a></div>
+ <div class="doc_text">
+ <p>Constants come in many shapes and flavors. The sections that follow
+ define the format for each of them. All constants start with a <a
+ href="#uint32_vbr">uint32_vbr</a> encoded integer that provides the
+ number of operands for the constant. For primitive, structure, and
+ array constants, this will always be zero since those types of
+ constants have no operands. In this case, we have the following field
+ definitions:</p>
+ <ul>
+ <li><b>Bool</b>. This is written as an <a href="#uint32_vbr">uint32_vbr</a>
+ of value 1U or 0U.</li>
+ <li><b>Signed Integers (sbyte,short,int,long)</b>. These are written
+ as an <a href="#int64_vbr">int64_vbr</a> with the corresponding value.</li>
+ <li><b>Unsigned Integers (ubyte,ushort,uint,ulong)</b>. These are
+ written as an <a href="#uint64_vbr">uint64_vbr</a> with the
+ corresponding value. </li>
+ <li><b>Floating Point</b>. Both the float and double types are
+ written literally in binary format.</li>
+ <li><b>Arrays</b>. Arrays are written simply as a list of <a
+ href="#uint32_vbr">uint32_vbr</a> encoded value slot numbers to the constant
+ element values.</li>
+ <li><b>Structures</b>. Structures are written simply as a list of <a
+ href="#uint32_vbr">uint32_vbr</a> encoded value slot numbers to the constant
+ field values of the structure.</li>
+ </ul>
+
+ <p>When the number of operands to the constant is one, we have an 'undef' value
+ of the specified type.</p>
+
+ <p>When the number of operands to the constant is greater than one, we have a
+ constant expression and its field format is provided in the table below, and the
+ number is equal to the number of operands+1.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">Op code of the instruction for the constant
+ expression.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">The value slot number of the constant value for an
+ operand.<sup>1</sup></td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">The type slot number for the type of the constant
+ value for an operand.<sup>1</sup></td>
+ </tr>
+ </tbody>
+ </table>
+ Notes:
+ <ol>
+ <li>Both these fields are repeatable but only in pairs.</li>
+ </ol>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="functiondefs">Function Definition</a></div>
+ <div class="doc_text">
+ <p>Function definitions contain the linkage, constant pool or
+ compaction table, instruction list, and symbol table for a function.
+ The following table shows the structure of a function definition.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a><br>
+ </td>
+ <td class="td_left">Function definition block identifier (0x02) +
+ size<br>
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">The linkage type of the function: 0=External,
+ 1=Weak, 2=Appending, 3=Internal, 4=LinkOnce<sup>1</sup></td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left">The <a href="#constantpool">constant pool</a>
+ block for this function.<sup>2</sup></td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left">The <a href="#compactiontable">compaction
+ table</a> block for the function.<sup>2</sup></td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left">The <a href="#instructionlist">instruction
+ list</a> for the function.</td>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a></td>
+ <td class="td_left">The function's <a href="#symtab">symbol
+ table</a> containing only those symbols pertinent to the function
+ (mostly block labels).</td>
+ </tr>
+ </tbody>
+ </table>
+ Notes:
+ <ol>
+ <li>Note that if the linkage type is "External" then none of the
+ other fields will be present as the function is defined elsewhere.</li>
+ <li>Note that only one of the constant pool or compaction table will
+ be written. Compaction tables are only written if they will actually
+ save bytecode space. If not, then a regular constant pool is written.</li>
+ </ol>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="compactiontable">Compaction Table</a>
+ </div>
+ <div class="doc_text">
+ <p>Compaction tables are part of a function definition. They are merely
+ a device for reducing the size of bytecode files. The size of a
+ bytecode file is dependent on the <em>values</em> of the slot numbers
+ used because larger values use more bytes in the variable bit rate
+ encoding scheme. Furthermore, the compressed instruction format
+ reserves only six bits for the type of the instruction. In large
+ modules, declaring hundreds or thousands of types, the values of the
+ slot numbers can be quite large. However, functions may use only a
+ small fraction of the global types. In such cases a compaction table is
+ created that maps the global type and value slot numbers to smaller
+ values used by a function. Functions will contain either a
+ function-specific constant pool <em>or</em> a compaction table but not
+ both. Compaction tables have the format shown in the table below.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">The number of types that follow</td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a>+</td>
+ <td class="td_left">The type slot number in the global types of
+ the type that will be referenced in the function with the index of this
+ entry in the compaction table.</td>
+ </tr>
+ <tr>
+ <td><a href="#type_len">type_len</a></td>
+ <td class="td_left">An encoding of the type and number of values
+ that follow. This field's encoding varies depending on the size of the
+ type plane. See <a href="#type_len">Type and Length</a> for further
+ details.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a>+</td>
+ <td class="td_left">The value slot number in the global values
+ that will be referenced in the function with the index of this entry in
+ the compaction table.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="type_len">Type and Length</a></div>
+ <div class="doc_text">
+ <p>The type and length of a compaction table type plane is encoded
+ differently depending on the length of the plane. For planes of length
+ 1 or 2, the length is encoded into bits 0 and 1 of a <a
+ href="#uint32_vbr">uint32_vbr</a> and the type is encoded into bits
+ 2-31. Because type numbers are often small, this often saves an extra
+ byte per plane. If the length of the plane is greater than 2 then the
+ encoding uses a <a href="#uint32_vbr">uint32_vbr</a> for each of the
+ length and type, in that order.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="instructionlist">Instruction List</a></div>
+ <div class="doc_text">
+ <p>The instructions in a function are written as a simple list. Basic
+ blocks are inferred by the terminating instruction types. The format of
+ the block is given in the following table.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a><br>
+ </td>
+ <td class="td_left">Instruction list identifier (0x07) + size<br>
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#instruction">instruction</a>+</td>
+ <td class="td_left">An instruction. Instructions have a variety
+ of formats. See <a href="#instruction">Instructions</a> for details.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="instruction">Instructions</a></div>
+ <div class="doc_text">
+ <p>For brevity, instructions are written in one of four formats,
+ depending on the number of operands to the instruction. Each
+ instruction begins with a <a href="#uint32_vbr">uint32_vbr</a> that
+ encodes the type of the instruction as well as other things. The tables
+ that follow describe the format of this first part of each instruction.</p>
+ <p><b>Instruction Format 0</b></p>
+ <p>This format is used for a few instructions that can't easily be
+ shortened because they have large numbers of operands (e.g. PHI Node or
+ getelementptr). Each of the opcode, type, and operand fields is found in
+ successive fields.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">Specifies the opcode of the instruction. Note
+ that for compatibility with the other instruction formats, the opcode
+ is shifted left by 2 bits. Bits 0 and 1 must have value zero for this
+ format.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint24_vbr">uint24_vbr</a></td>
+ <td class="td_left">Provides the type slot number of the result type of
+ the instruction.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">The number of operands that follow.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a>+</td>
+ <td class="td_left">The slot number of the value(s) for the operand(s).
+ <sup>1</sup></td>
+ </tr>
+ </tbody>
+ </table>
+ Notes:
+ <ol>
+ <li>Note that if the instruction is a getelementptr and the type of
+ the operand is a sequential type (array or pointer) then the slot
+ number is shifted up two bits and the low order bits will encode the
+ type of index used, as follows: 0=uint, 1=int, 2=ulong, 3=long.</li>
+ </ol>
+ <p><b>Instruction Format 1</b></p>
+ <p>This format encodes the opcode, type and a single operand into a
+ single <a href="#uint32_vbr">uint32_vbr</a> as follows:</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Bits</b></th>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td>0-1</td>
+ <td>constant "1"</td>
+ <td class="td_left">These two bits must be the value 1 which identifies
+ this as an instruction of format 1.</td>
+ </tr>
+ <tr>
+ <td>2-7</td>
+ <td><a href="#opcode">opcode</a></td>
+ <td class="td_left">Specifies the opcode of the instruction. Note that
+ the maximum opcode value is 63.</td>
+ </tr>
+ <tr>
+ <td>8-19</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the type for this
+ instruction. Maximum slot number is 2<sup>12</sup>-1=4095.</td>
+ </tr>
+ <tr>
+ <td>20-31</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the value for the
+ first operand. Maximum slot number is 2<sup>12</sup>-1=4095. Note that
+ the value 2<sup>12</sup>-1 denotes zero operands.</td>
+ </tr>
+ </tbody>
+ </table>
+ <p><b>Instruction Format 2</b></p>
+ <p>This format encodes the opcode, type and two operands into a single <a
+ href="#uint32_vbr">uint32_vbr</a> as follows:</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Bits</b></th>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td>0-1</td>
+ <td>constant "2"</td>
+ <td class="td_left">These two bits must be the value 2 which identifies
+ this as an instruction of format 2.</td>
+ </tr>
+ <tr>
+ <td>2-7</td>
+ <td><a href="#opcodes">opcode</a></td>
+ <td class="td_left">Specifies the opcode of the instruction. Note that
+ the maximum opcode value is 63.</td>
+ </tr>
+ <tr>
+ <td>8-15</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the type for this
+ instruction. Maximum slot number is 2<sup>8</sup>-1=255.</td>
+ </tr>
+ <tr>
+ <td>16-23</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the value for the first
+ operand. Maximum slot number is 2<sup>8</sup>-1=255.</td>
+ </tr>
+ <tr>
+ <td>24-31</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the value for the second
+ operand. Maximum slot number is 2<sup>8</sup>-1=255.</td>
+ </tr>
+ </tbody>
+ </table>
+ <p><b>Instruction Format 3</b></p>
+ <p>This format encodes the opcode, type and three operands into a
+ single <a href="#uint32_vbr">uint32_vbr</a> as follows:</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Bits</b></th>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td>0-1</td>
+ <td>constant "3"</td>
+ <td class="td_left">These two bits must be the value 3 which identifies
+ this as an instruction of format 3.</td>
+ </tr>
+ <tr>
+ <td>2-7</td>
+ <td><a href="#opcodes">opcode</a></td>
+ <td class="td_left">Specifies the opcode of the instruction. Note that
+ the maximum opcode value is 63.</td>
+ </tr>
+ <tr>
+ <td>8-13</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the type for this
+ instruction. Maximum slot number is 2<sup>6</sup>-1=63.</td>
+ </tr>
+ <tr>
+ <td>14-19</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the value for the first
+ operand. Maximum slot number is 2<sup>6</sup>-1=63.</td>
+ </tr>
+ <tr>
+ <td>20-25</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the value for the second
+ operand. Maximum slot number is 2<sup>6</sup>-1=63.</td>
+ </tr>
+ <tr>
+ <td>26-31</td>
+ <td><a href="#unsigned">unsigned</a></td>
+ <td class="td_left">Specifies the slot number of the value for the third
+ operand. Maximum slot number is 2<sup>6</sup>-1=63.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="opcodes">Instruction Opcodes</a></div>
+ <div class="doc_text">
+ <p>Instructions encode an opcode that identifies the kind of instruction.
+ Opcodes are an enumerated integer value. The specific values used depend on
+ the version of LLVM you're using. The opcode values are defined in the
+ <a href="http://llvm.cs.uiuc.edu/cvsweb/cvsweb.cgi/llvm/include/llvm/Instruction.def">
+ <tt>include/llvm/Instruction.def</tt></a> file. You should check there for the
+ most recent definitions. The table below provides the opcodes defined as of
+ the writing of this document. The table associates each opcode mnemonic with
+ its enumeration value and the bytecode and LLVM version numbers in which the
+ opcode was introduced.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th>Opcode</th>
+ <th>Number</th>
+ <th>Bytecode Version</th>
+ <th>LLVM Version</th>
+ </tr>
+ <tr><td colspan="4"><b>Terminator Instructions</b></td></tr>
+ <tr><td>Ret</td><td>1</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Br</td><td>2</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Switch</td><td>3</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Invoke</td><td>4</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Unwind</td><td>5</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Unreachable</td><td>6</td><td>1</td><td>1.4</td></tr>
+ <tr><td colspan="4"><b>Binary Operators</b></td></tr>
+ <tr><td>Add</td><td>7</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Sub</td><td>8</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Mul</td><td>9</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Div</td><td>10</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Rem</td><td>11</td><td>1</td><td>1.0</td></tr>
+ <tr><td colspan="4"><b>Logical Operators</b></td></tr>
+ <tr><td>And</td><td>12</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Or</td><td>13</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Xor</td><td>14</td><td>1</td><td>1.0</td></tr>
+ <tr><td colspan="4"><b>Binary Comparison Operators</b></td></tr>
+ <tr><td>SetEQ</td><td>15</td><td>1</td><td>1.0</td></tr>
+ <tr><td>SetNE</td><td>16</td><td>1</td><td>1.0</td></tr>
+ <tr><td>SetLE</td><td>17</td><td>1</td><td>1.0</td></tr>
+ <tr><td>SetGE</td><td>18</td><td>1</td><td>1.0</td></tr>
+ <tr><td>SetLT</td><td>19</td><td>1</td><td>1.0</td></tr>
+ <tr><td>SetGT</td><td>20</td><td>1</td><td>1.0</td></tr>
+ <tr><td colspan="4"><b>Memory Operators</b></td></tr>
+ <tr><td>Malloc</td><td>21</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Free</td><td>22</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Alloca</td><td>23</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Load</td><td>24</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Store</td><td>25</td><td>1</td><td>1.0</td></tr>
+ <tr><td>GetElementPtr</td><td>26</td><td>1</td><td>1.0</td></tr>
+ <tr><td colspan="4"><b>Other Operators</b></td></tr>
+ <tr><td>PHI</td><td>27</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Cast</td><td>28</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Call</td><td>29</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Shl</td><td>30</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Shr</td><td>31</td><td>1</td><td>1.0</td></tr>
+ <tr><td>VANext</td><td>32</td><td>1</td><td>1.0</td></tr>
+ <tr><td>VAArg</td><td>33</td><td>1</td><td>1.0</td></tr>
+ <tr><td>Select</td><td>34</td><td>2</td><td>1.2</td></tr>
+ <tr><td colspan="4">
+ <b>Pseudo Instructions<a href="#pi_note">*</a></b>
+ </td></tr>
+ <tr><td>Invoke+CC </td><td>56</td><td>5</td><td>1.5</td></tr>
+ <tr><td>Invoke+FastCC</td><td>57</td><td>5</td><td>1.5</td></tr>
+ <tr><td>Call+CC</td><td>58</td><td>5</td><td>1.5</td></tr>
+ <tr><td>Call+FastCC+TailCall</td><td>59</td><td>5</td><td>1.5</td></tr>
+ <tr><td>Call+FastCC</td><td>60</td><td>5</td><td>1.5</td></tr>
+ <tr><td>Call+CCC+TailCall</td><td>61</td><td>5</td><td>1.5</td></tr>
+ <tr><td>Load+Volatile</td><td>62</td><td>3</td><td>1.3</td></tr>
+ <tr><td>Store+Volatile</td><td>63</td><td>3</td><td>1.3</td></tr>
+ </tbody>
+ </table>
+ </div>
+
+ <p><b><a name="pi_note">* Note: </a></b>
+ These aren't really opcodes from an LLVM language prespeective. They encode
+ information into other opcodes without reserving space for that information.
+ For example, opcode=63 is a Volatile Store. The opcode for this
+ instruction is 25 (Store) but we encode it as 63 to indicate that is a Volatile
+ Store. The same is done for the calling conventions and tail calls.
+ In each of these entries in range 56-63, the opcode is documented as the base
+ opcode (Invoke, Call, Store) plus some set of modifiers, as follows:</p>
+ <dl>
+ <dt>CC</dt>
+ <dd>This means an arbitrary calling convention is specified
+ in a VBR that follows the opcode. This is used when the instruction cannot
+ be encoded with one of the more compact forms.
+ </dd>
+ <dt>FastCC</dt>
+ <dd>This indicates that the Call or Invoke is using the FastCC calling
+ convention.</dd>
+ <dt>CCC</dt>
+ <dd>This indicates that the Call or Invoke is using the native "C" calling
+ convention.</dd>
+ <dt>TailCall</dt>
+ <dd>This indicates that the Call has the 'tail' modifier.</dd>
+ </dl>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="symtab">Symbol Table</a> </div>
+ <div class="doc_text">
+ <p>A symbol table can be put out in conjunction with a module or a function. A
+ symbol table has a list of name/type associations followed by a list of
+ name/value associations. The name/value associations are organized into "type
+ planes" so that all values of a common type are listed together. Each type
+ plane starts with the number of entries in the plane and the type slot number
+ for all the values in that plane (so the type can be looked up in the global
+ type pool). For each entry in a type plane, the slot number of the value and
+ the name associated with that value are written. The format is given in the
+ table below. </p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#block">block</a><br>
+ </td>
+ <td class="td_left">Symbol Table Identifier (0x04)</td>
+ </tr>
+ <tr>
+ <td><a href="#llist">llist</a>(<a href="#symtab_entry">type_entry</a>)</td>
+ <td class="td_left">A length list of symbol table entries for
+ <tt>Type</tt>s
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#zlist">llist</a>(<a href="#symtab_plane">symtab_plane</a>)</td>
+ <td class="td_left">A length list of "type planes" of symbol table
+ entries for <tt>Value</tt>s</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="type_entry">Symbol Table Type
+ Entry</a>
+ </div>
+ <div class="doc_text">
+ <p>A symbol table type entry associates a name with a type. The name is provided
+ simply as an array of chars. The type is provided as a type slot number (index)
+ into the global type pool. The format is given in the following table:</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint24_vbr</a></td>
+ <td class="td_left">Type slot number of the type being given a
+ name relative to the global type pool.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">Length of the character array that follows.</td>
+ </tr>
+ <tr>
+ <td><a href="#char">char</a>+</td>
+ <td class="td_left">The characters of the name.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="symtab_plane">Symbol Table
+ Plane</a>
+ </div>
+ <div class="doc_text">
+ <p>A symbol table plane provides the symbol table entries for all
+ values of a common type. The encoding is given in the following table:</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">Number of entries in this plane.</td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">Type slot number of type for all values in this plane..</td>
+ </tr>
+ <tr>
+ <td><a href="#value_entry">value_entry</a>+</td>
+ <td class="td_left">The symbol table entries for to associate values with
+ names.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="value_entry">Symbol Table Value
+ Entry</a>
+ </div>
+ <div class="doc_text">
+ <p>A symbol table value entry provides the assocation between a value and the
+ name given to the value. The value is referenced by its slot number. The
+ format is given in the following table:</p>
+ <table>
+ <tbody>
+ <tr>
+ <th><b>Type</b></th>
+ <th class="td_left"><b>Field Description</b></th>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint24_vbr</a></td>
+ <td class="td_left">Value slot number of the value being given a name.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#uint32_vbr">uint32_vbr</a></td>
+ <td class="td_left">Length of the character array that follows.</td>
+ </tr>
+ <tr>
+ <td><a href="#char">char</a>+</td>
+ <td class="td_left">The characters of the name.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="versiondiffs">Version Differences</a>
+ </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This section describes the differences in the Bytecode Format across
+ LLVM
+ versions. The versions are listed in reverse order because it assumes
+ the current version is as documented in the previous sections. Each
+ section here
+ describes the differences between that version and the one that <i>follows</i>.
+ </p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="vers13">Version 1.3 Differences From
+ 1.4</a></div>
+ <!-- _______________________________________________________________________ -->
+
+ <div class="doc_subsubsection">Unreachable Instruction</div>
+ <div class="doc_text">
+ <p>The LLVM <a href="LangRef.html#i_unreachable">Unreachable</a> instruction
+ was added in version 1.4 of LLVM. This caused all instruction numbers after
+ it to shift down by one.</p>
+ </div>
+
+ <div class="doc_subsubsection">Function Flags</div>
+ <div class="doc_text">
+ <p>LLVM bytecode versions prior to 1.4 did not include the 5 bit offset
+ in <a href="#funcfield">the function list</a> in the <a
+ href="#globalinfo">Module Global Info</a> block.</p>
+ </div>
+
+ <div class="doc_subsubsection">Function Flags</div>
+ <div class="doc_text">
+ <p>LLVM bytecode versions prior to 1.4 did not include the 'undef' constant
+ value, which affects the encoding of <a href="#constant">Constant
+ Fields</a>.</p>
+ </div>
+
+ <!--
+ <div class="doc_subsubsection">Aligned Data</div>
+ <div class="doc_text">
+ <p>In version 1.3, certain data items were aligned to 32-bit boundaries. In
+ version 1.4, alignment of data was done away with completely. The need for
+ alignment has gone away and the only thing it adds is bytecode file size
+ overhead. In most cases this overhead was small. However, in functions with
+ large numbers of format 0 instructions (GEPs and PHIs with lots of parameters)
+ or regular instructions with large valued operands (e.g. because there's just
+ a lot of instructions in the function) the overhead can be extreme. In one
+ test case, the overhead was 44,000 bytes (34% of the total file size).
+ Consequently in release 1.4, the decision was made to eliminate alignment
+ altogether.</p>
+ <p>In version 1.3 format, the following bytecode constructs were aligned (i.e.
+ they were followed by one to three bytes of padding):</p>
+ <ul>
+ <li>All blocks.</li>
+ <li>Instructions using the long format (format 0).</li>
+ <li>All call instructions that called a var args function.</li>
+ <li>The target triple (a string field at the end of the module block).</li>
+ <li>The version field (immediately following the signature).</li>
+ </ul>
+ <p>None of these constructs are aligned in version 1.4</p>
+ </div>
+ -->
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="vers12">Version 1.2 Differences
+ From 1.3</a></div>
+ <!-- _______________________________________________________________________ -->
+
+ <div class="doc_subsubsection">Type Derives From Value</div>
+ <div class="doc_text">
+ <p>In version 1.2, the Type class in the LLVM IR derives from the Value
+ class. This is not the case in version 1.3. Consequently, in version
+ 1.2 the notion of a "Type Type" was used to write out values that were
+ Types. The types always occuped plane 12 (corresponding to the
+ TypeTyID) of any type planed set of values. In 1.3 this representation
+ is not convenient because the TypeTyID (12) is not present and its
+ value is now used for LabelTyID. Consequently, the data structures
+ written that involve types do so by writing all the types first and
+ then each of the value planes according to those types. In version 1.2,
+ the types would have been written intermingled with the values.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Restricted getelementptr Types</div>
+ <div class="doc_text">
+ <p>In version 1.2, the getelementptr instruction required a ubyte type
+ index for accessing a structure field and a long type index for
+ accessing an array element. Consequently, it was only possible to
+ access structures of 255 or fewer elements. Starting in version 1.3,
+ this restriction was lifted. Structures must now be indexed with uint
+ constants. Arrays may now be indexed with int, uint, long, or ulong
+ typed values. The consequence of this was that the bytecode format had
+ to change in order to accommodate the larger range of structure indices.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Short Block Headers</div>
+ <div class="doc_text">
+ <p>In version 1.2, block headers were always 8 bytes being comprised of
+ both an unsigned integer type and an unsigned integer size. For very
+ small modules, these block headers turn out to be a large fraction of
+ the total bytecode file size. In an attempt to make these small files
+ smaller, the type and size information was encoded into a single
+ unsigned integer (4 bytes) comprised of 5 bits for the block type
+ (maximum 31 block types) and 27 bits for the block size (max
+ ~134MBytes). These limits seemed sufficient for any blocks or sizes
+ forseen in the future. Note that the module block, which encloses all
+ the other blocks is still written as 8 bytes since bytecode files
+ larger than 134MBytes might be possible.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Dependent Libraries and Target Triples</div>
+ <div class="doc_text">
+ <p>In version 1.2, the bytecode format does not store module's target
+ triple or dependent. These fields have been added to the end of the <a
+ href="#globalinfo">module global info block</a>. The purpose of these
+ fields is to allow a front end compiler to specifiy that the generated
+ module is specific to a particular target triple (operating
+ system/manufacturer/processor) which makes it non-portable; and to
+ allow front end compilers to specify the list of libraries that the
+ module depends on for successful linking.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Types Restricted to 24-bits</div>
+ <div class="doc_text">
+ <p>In version 1.2, type slot identifiers were written as 32-bit VBR
+ quantities. In 1.3 this has been reduced to 24-bits in order to ensure
+ that it is not possible to overflow the type field of a global variable
+ definition. 24-bits for type slot numbers is deemed sufficient for any
+ practical use of LLVM.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="vers11">Version 1.1 Differences
+ From 1.2 </a></div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Explicit Primitive Zeros</div>
+ <div class="doc_text">
+ <p>In version 1.1, the zero value for primitives was explicitly encoded
+ into the bytecode format. Since these zero values are constant values
+ in the LLVM IR and never change, there is no reason to explicitly
+ encode them. This explicit encoding was removed in version 1.2.</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Inconsistent Module Global Info</div>
+ <div class="doc_text">
+ <p>In version 1.1, the Module Global Info block was not aligned causing
+ the next block to be read in on an unaligned boundary. This problem was
+ corrected in version 1.2.<br>
+ <br>
+ </p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="vers10">Version 1.0 Differences
+ From 1.1</a></div>
+ <div class="doc_text">
+ <p>None. Version 1.0 and 1.1 bytecode formats are identical.</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:rspencer at x10sys.com">Reid Spencer</a> and <a
+ href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:19 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/CFEBuildInstrs.html
diff -c /dev/null llvm-www/releases/1.5/docs/CFEBuildInstrs.html:1.1
*** /dev/null Wed May 18 09:34:34 2005
--- llvm-www/releases/1.5/docs/CFEBuildInstrs.html Wed May 18 09:33:19 2005
***************
*** 0 ****
--- 1,361 ----
+ <!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>Bootstrapping the LLVM C/C++ Front-End</title>
+ </head>
+ <body>
+
+ <div class="doc_title">
+ Bootstrapping the LLVM C/C++ Front-End
+ </div>
+
+ <ol>
+ <li><a href="#cautionarynote">A Cautionary Note</a>
+ <ul>
+ <li><a href="#cygwin">Building under Cygwin</a></li>
+ <li><a href="#aix">Building under AIX</a></li>
+ </ul>
+ </li>
+ <li><a href="#instructions">Instructions</a></li>
+ <li><a href="#license">License Information</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by Brian R. Gaeke and
+ <a href="http://nondot.org/sabre">Chris Lattner</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="cautionarynote">A Cautionary Note</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>This document is intended to explain the process of building the
+ LLVM C/C++ front-end, based on GCC 3.4, from its source code. You
+ would have to do this, for example, if you are porting LLVM to a new
+ architecture or operating system.</p>
+
+ <p><b>NOTE:</b> This is currently a somewhat fragile, error-prone
+ process, and you should <b>only</b> try to do it if:</p>
+
+ <ol>
+ <li>you really, really, really can't use the binaries we distribute</li>
+ <li>you are an elite GCC hacker.</li>
+ <li>you want to use the latest bits from CVS.</li>
+ </ol>
+
+ <p>We welcome patches to help make this process simpler.</p>
+ </div>
+
+ <!--=========================================================================-->
+ <div class="doc_subsection">
+ <a name="cygwin">Building under Cygwin</a>
+ </div>
+ <!--=========================================================================-->
+
+ <div class="doc_text">
+ <p>If you are building LLVM and the GCC front-end under Cygwin, please note that
+ the LLVM and GCC makefiles do not correctly handle spaces in paths. To deal
+ with this issue, make sure that your LLVM and GCC source and build trees are
+ located in a top-level directory (like <tt>/cygdrive/c/llvm</tt> and
+ <tt>/cygdrive/c/llvm-cfrontend</tt>), not in a directory that contains a space
+ (which includes your "home directory", because it lives under the "Documents
+ and Settings" directory). We welcome patches to fix this issue.
+ </p>
+ <p>It has been found that the GCC 3.3.3 compiler provided with recent Cygwin
+ versions is incapable of compiling the LLVM CFE correctly. If your Cygwin
+ installation includes GCC 3.3.3, we <i>strongly</i> recommend that you download
+ GCC 3.4.3, build it separately, and use it for compiling LLVM CFE. This has been
+ shown to work correctly.</p>
+ <p>Some versions of Cygwin utilize an experimental version of GNU binutils that
+ will cause the GNU <tt>ld</tt> linker to fail an assertion when linking
+ components of the libstdc++. It is recommended that you replace the entire
+ binutils package with version 2.15 such that "<tt>ld --version</tt>" responds
+ with</p>
+ <pre>GNU ld version 2.15</pre>
+ not with:<br/>
+ <pre>GNU ld version 2.15.91 20040725</pre>
+ </div>
+
+ <!--=========================================================================-->
+ <div class="doc_subsection"><a name="aix">Building under AIX</a></div>
+ <div class="doc_text">
+ <p>If you are building LLVM and the GCC front-end under AIX, do NOT use GNU
+ Binutils. They are not stable under AIX and may produce incorrect and/or
+ invalid code. Instead, use the system assembler and linker.
+ </p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="instructions">Instructions</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>
+ <ol>
+ <li><p>Configure and build the LLVM libraries and tools. There are two ways to
+ do this: either with <i>objdir</i> == <i>srcdir</i> or
+ <i>objdir</i> != <i>srcdir</i>. It is recommended
+ that <i>srcdir</i> not be the same as <i>objdir</i>:</p>
+ <ul>
+ <li>With <i>objdir</i> != <i>srcdir</i>:<pre>
+ % cd <i>objdir</i>
+ % <i>srcdir</i>/configure --prefix=/some/path/you/can/install/to [options...]
+ % gmake tools-only
+ </pre></li>
+ <li>With <i>objdir</i> == <i>srcdir</i>:<pre>
+ % cd llvm
+ % ./configure --prefix=/some/path/you/can/install/to [options...]
+ % gmake tools-only
+ </pre></li>
+ </ul>
+ <p>This will build all of the LLVM tools and libraries. The <tt>--prefix</tt>
+ option defaults to /usr/local (per configure standards) but unless you are a
+ system administrator, you probably won't be able to install LLVM there because
+ of permissions. Specify a path into which LLVM can be installed (e.g.
+ <tt>--prefix=/home/user/llvm</tt>).</p>
+ </li>
+
+ <li><p>Add the directory containing the tools to your PATH.</p>
+ <pre>
+ % set path = ( `cd llvm/Debug/bin && pwd` $path )
+ </pre></li>
+
+ <li><p>Unpack the C/C++ front-end source into cfrontend/src, either by
+ untar'ing an llvm-gcc.tar.gz file or checking out CVS into this
+ directory.</p></li>
+
+ <li><p>Make "build" and "install" directories as siblings of the "src" tree:</p>
+ <pre>
+ % pwd
+ /usr/local/example/cfrontend/src
+ % cd ..
+ % mkdir build install
+ % set CFEINSTALL = `pwd`/install
+ </pre></li>
+
+
+ <li><p>Configure, build, and install the GCC front-end:</p>
+
+ <p>
+ <b>Linux/x86:</b><br>
+ <b>MacOS X/PowerPC</b> (requires dlcompat library):<br>
+ <b>AIX/PowerPC:</b>
+ </p>
+
+ <pre>
+ % cd build
+ % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
+ --disable-shared --enable-languages=c,c++ --program-prefix=llvm-
+ % gmake all; gmake install
+ </pre>
+
+ <p><b>Cygwin/x86:</b></p>
+
+ <pre>
+ % cd build
+ % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
+ --disable-shared --enable-languages=c,c++ --disable-c-mbchar \
+ --program-prefix=llvm-
+ % gmake all; gmake install
+ </pre>
+
+ <p><b>Solaris/SPARC:</b></p>
+
+ <p>
+ The GCC front-end can be configured for either SPARC V8 (32 bit) or SPARC V9 (64
+ bit). This changes, among other things, the sizes of integer types and the
+ macros defined for conditional compilation.
+ </p>
+
+ <p>
+ The SPARC V8 backend is still beta quality software. Unless you are working on
+ the SPARC V8 backend, you should specify sparcv9 on the configure command line,
+ as shown below. Also,
+ note that Solaris has trouble with various wide (multibyte) character
+ functions from C as referenced from C++, so we typically configure with
+ --disable-c-mbchar (cf. <a href="http://llvm.cs.uiuc.edu/PR206">Bug 206</a>).
+ </p>
+
+ <pre>
+ % cd build
+ % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
+ --disable-shared --enable-languages=c,c++ --host=sparcv9-sun-solaris2.8 \
+ --disable-c-mbchar --program-prefix=llvm-
+ % gmake all; gmake install
+ </pre>
+
+ <p><b>Common Problem:</b> You may get error messages regarding the fact
+ that LLVM does not support inline assembly. Here are two common
+ fixes:</p>
+
+ <ul>
+ <li><p><b>Fix 1:</b> If you have system header files that include
+ inline assembly, you may have to modify them to remove the inline
+ assembly and install the modified versions in
+ <code>$CFEINSTALL/lib/gcc/<i>target-triplet</i>/3.4-llvm/include</code>.</li>
+
+ <li><b>Fix 2:</b> If you are building the C++ front-end on a CPU we
+ haven't tried yet, you will probably have to edit the appropriate
+ version of atomicity.h under
+ <code>src/libstdc++-v3/config/cpu/<i>name-of-cpu</i>/atomicity.h</code>
+ and apply a patch so that it does not use inline assembly.</li>
+ </ul>
+
+ <p><b>Porting to a new architecture:</b> If you are porting the front-end
+ to a new architecture or compiling in a configuration that we have
+ not tried previously, there are probably several changes you will have to make
+ to the GCC target to get it to work correctly. These include:<p>
+
+ <ul>
+ <li>Often targets include special assembler or linker flags which
+ <tt>gccas</tt>/<tt>gccld</tt> does not understand. In general, these can
+ just be removed.</li>
+ <li>LLVM currently does not support any floating point values other than
+ 32-bit and 64-bit IEEE floating point. The primary effect of this is
+ that you may have to map "long double" onto "double".</li>
+ <li>The profiling hooks in GCC do not apply at all to the LLVM front-end.
+ These may need to be disabled.</li>
+ <li>No inline assembly for position independent code. At the LLVM level,
+ everything is position independent.</li>
+ <li>We handle <tt>.init</tt> and <tt>.fini</tt> differently.</li>
+ <li>You may have to disable multilib support in your target. Using multilib
+ support causes the GCC compiler driver to add a lot of "<tt>-L</tt>"
+ options to the link line, which do not relate to LLVM and confuse
+ <tt>gccld</tt>. To disable multilibs, delete any
+ <tt>MULTILIB_OPTIONS</tt> lines from your target files.</li>
+ <li>Did we mention that we don't support inline assembly? You'll probably
+ have to add some fixinclude hacks to disable it in the system
+ headers.</li>
+ </ul>
+ </li>
+
+ <li><p>Put <tt>$CFEINSTALL/bin</tt> into your <tt>PATH</tt> environment
+ variable.</p>
+ <ul>
+ <li>sh: <tt>export PATH=$CFEINSTALL/bin:$PATH</tt></li>
+ <li>csh: <tt>setenv PATH $CFEINSTALL/bin:$PATH</tt></li>
+ </ul>
+ </li>
+
+ <li><p>Go back into the LLVM source tree proper. Rerun configure, using
+ the same options as the last time. This will cause the configuration to now find
+ the newly built llvm-gcc and llvm-g++ executables. </p></li>
+
+ <li><p>Rebuild your CVS tree. This shouldn't cause the whole thing to be
+ rebuilt, but it should build the runtime libraries. After the tree is
+ built, install the runtime libraries into your GCC front-end build tree.
+ These are the commands you need:</p>
+ <pre>
+ % gmake
+ % gmake -C runtime install-bytecode
+ </pre></li>
+
+ <li><p>Optionally, build a symbol table for the newly installed runtime
+ libraries. Although this step is optional, you are strongly encouraged to
+ do this as the symbol tables will make a significant difference in your
+ link times. Use the <tt>llvm-ranlib</tt> tool to do this, as follows:</p>
+ <pre>
+ % cd $CFEINSTALL/lib
+ % llvm-ranlib libiberty.a
+ % llvm-ranlib libstdc++.a
+ % llvm-ranlib libsupc++.a
+ % cd $CFEINSTALL/lib/gcc/<i>target-triplet</i>/3.4-llvm
+ % llvm-ranlib libgcc.a
+ % llvm-ranlib libgcov.a
+ </pre>
+
+ <li><p>Test the newly-installed C frontend by one or more of the
+ following means:</p>
+ <ul>
+ <li> running the feature & regression tests via <tt>make check</tt></li>
+ <li> compiling and running a "hello, LLVM" program in C and C++.</li>
+ <li> running the tests found in the <tt>llvm-test</tt> CVS module</li>
+ </ul></li>
+ </ol>
+ </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>
+ The software also has the following additional copyrights:
+ </p>
+
+ <pre>
+
+ Copyright (c) 2003, 2004, 2005 University of Illinois at Urbana-Champaign.
+ All rights reserved.
+
+ Developed by:
+
+ LLVM Team
+
+ University of Illinois at Urbana-Champaign
+
+ http://llvm.cs.uiuc.edu
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE
+ SOFTWARE.
+
+ Copyright (c) 1994
+ Hewlett-Packard Company
+
+ Permission to use, copy, modify, distribute and sell this software
+ and its documentation for any purpose is hereby granted without fee,
+ provided that the above copyright notice appear in all copies and
+ that both that copyright notice and this permission notice appear
+ in supporting documentation. Hewlett-Packard Company makes no
+ representations about the suitability of this software for any
+ purpose. It is provided "as is" without express or implied warranty.
+
+ Copyright (c) 1996, 1997, 1998, 1999
+ Silicon Graphics Computer Systems, Inc.
+
+ Permission to use, copy, modify, distribute and sell this software
+ and its documentation for any purpose is hereby granted without fee,
+ provided that the above copyright notice appear in all copies and
+ that both that copyright notice and this permission notice appear
+ in supporting documentation. Silicon Graphics makes no
+ representations about the suitability of this software for any
+ purpose. It is provided "as is" without express or implied warranty.
+ </pre>
+ </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>
+
+ Brian Gaeke<br>
+ <a href="http://llvm.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:19 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/CodeGenerator.html
diff -c /dev/null llvm-www/releases/1.5/docs/CodeGenerator.html:1.1
*** /dev/null Wed May 18 09:34:34 2005
--- llvm-www/releases/1.5/docs/CodeGenerator.html Wed May 18 09:33:19 2005
***************
*** 0 ****
--- 1,999 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <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="#mregisterinfo">The <tt>MRegisterInfo</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="#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>
+ </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</a></li>
+ <li><a href="#selectiondag_select">SelectionDAG Select Phase</a></li>
+ <li><a href="#selectiondag_future">Future directions for the
+ SelectionDAG</a></li>
+ </ul></li>
+ </ul>
+ </li>
+ <li><a href="#targetimpls">Target description implementations</a>
+ <ul>
+ <li><a href="#x86">The X86 backend</a></li>
+ </ul>
+ </li>
+
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</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: programmable FPGAs for example.</p>
+
+ <p><b>Important Note:</b> For historical reasons, the LLVM SparcV9 code
+ generator uses almost entirely different code paths than described in this
+ document. For this reason, there are some deprecated interfaces (such as
+ <tt>TargetRegInfo</tt> and <tt>TargetSchedInfo</tt>), which are only used by the
+ V9 backend and should not be used by any other targets. Also, all code in the
+ <tt>lib/Target/SparcV9</tt> directory and subdirectories should be considered
+ deprecated, and should not be used as the basis for future code generator work.
+ The SparcV9 backend is slowly being merged into the rest of the
+ target-independent code generators, but this is a low-priority process with no
+ predictable completion date.</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> - Determining an
+ efficient implementation of 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.</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, normal scheduling, or peephole optimization work here.
+ </li>
+
+ <li><b><a name="#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 name="#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 name="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 name="codemission">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>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="targetdesc">Target description classes</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The LLVM target description classes (which are 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. These interfaces do not take interference graphs
+ as inputs or other algorithm-specific data structures.</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:
+ <ul><li>an initial register class to use for various ValueTypes,</li>
+ <li>which operations are natively supported by the target machine,</li>
+ <li>the return type of setcc operations, and</li>
+ <li>the type to use for shift amounts, etc</li>.
+ </ol></p>
+
+ </div>
+
+
+
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="mregisterinfo">The <tt>MRegisterInfo</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>MRegisterInfo</tt> class (which will eventually be renamed to
+ <tt>TargetRegisterInfo</tt>) 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 numbers. Physical registers (those that actually exist in the target
+ description) are unique small numbers, and virtual registers are generally
+ large.</p>
+
+ <p>Each register in the processor description has an associated
+ <tt>MRegisterDesc</tt> entry, which provides a textual name for the register
+ (used for assembly output and debugging dumps), a set of aliases (used to
+ indicate that one register overlaps with another), and some flag bits.
+ </p>
+
+ <p>In addition to the per-register description, the <tt>MRegisterInfo</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_subsection">
+ <a name="targetframeinfo">The <tt>TargetFrameInfo</tt> class</a>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="targetjitinfo">The <tt>TargetJITInfo</tt> class</a>
+ </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 MachineFunction, MachineBasicBlock, and <a
+ href="#machineinstr"><tt>MachineInstr</tt></a> instances
+ (defined in include/llvm/CodeGen). This representation is completely target
+ agnostic, representing instructions in their most abstract form: an opcode and a
+ series of operands. This representation is designed to support both 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 number 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:
+ they can be a register reference, constant integer, 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>
+
+ <pre>
+ %r3 = add %i1, %i2
+ </pre>
+
+ <p>If the first operand is a def, and it is also 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>
+
+ <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>
+
+ <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>
+
+ <!-- _______________________________________________________________________ -->
+ <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>
+
+ <pre>
+ int %test(int %X, int %Y) {
+ %Z = div int %X, %Y
+ ret int %Z
+ }
+ </pre>
+
+ <p>The X86 instruction selector produces this machine code for the div
+ and ret (use
+ "<tt>llc X.bc -march=x86 -print-machineinstrs</tt>" to get this):</p>
+
+ <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>
+
+ <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>
+
+ <pre>
+ ;; X is in EAX, Y is in ECX
+ mov %EAX, %EDX
+ sar %EDX, 31
+ idiv %ECX
+ ret
+ </pre>
+
+ <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 and
+ exit of 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 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, as there
+ are no virtual registers left in the code.</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. In LLVM there are two main forms:
+ the old-style 'simple' instruction selector (which effectively peephole selects
+ each LLVM instruction into a series of machine instructions), and the new
+ SelectionDAG based instruction selector.
+ </p>
+
+ <p>The 'simple' instruction selectors are tedious to write, require a lot of
+ boiler plate code, and are difficult to get correct. Additionally, any
+ optimizations written for a simple instruction selector cannot be used by other
+ targets. For this reason, LLVM is moving to a new SelectionDAG based
+ instruction selector, which is described in this section. If you are starting a
+ new port, we recommend that you write the instruction selector using the
+ SelectionDAG infrastructure.</p>
+
+ <p>In time, most of the target-specific code for instruction selection will be
+ auto-generated from the target description (<tt>*.td</tt>) files. For now,
+ however, the <a href="#selectiondag_select">Select Phase</a> must still be
+ written by hand.</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. 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.
+ The various operation node types are described at the top of the
+ <tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt> file. Depending on the
+ operation, nodes may contain additional information (e.g. the condition code
+ for a SETCC node) contained in a derived class.</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 <SDNode, unsigned> pair, indicating the node and result
+ value being used, respectively. Each value produced by an SDNode has an
+ associated MVT::ValueType, 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 MVT::Other. These edges provide
+ an ordering between nodes that have side effects (such as
+ loads/stores/calls/return/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 ISD::EntryToken. The Root node is the
+ final side-effecting node in the token chain. For example, in a single basic
+ block function, this 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 PowerPC, for example, a DAG with any values of i1, i8, i16,
+ or i64 type would be illegal. 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 div/rem pairs) for
+ targets that support these meta operations. This makes the resultant code
+ more efficient and the 'select instructions from DAG' phase (below) simpler.
+ </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 optimized 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, emitting them and building the MachineFunction being
+ compiled.</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>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_build">Initial SelectionDAG Construction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ The initial SelectionDAG is naively peephole expanded from the LLVM input by
+ the <tt>SelectionDAGLowering</tt> class in the SelectionDAGISel.cpp 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
+ add turns into an SDNode add while a geteelementptr is expanded into the obvious
+ arithmetic). This pass requires target-specific hooks to lower calls and
+ returns, varargs, etc. For these features, the TargetLowering 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: promoting a small type to a larger
+ type (e.g. f32 -> f64, or i16 -> i32), and breaking up large
+ integer types
+ to smaller ones (e.g. implementing i64 with i32 operations where
+ possible). Type conversions can insert sign and zero extensions as
+ needed to make sure that the final code has the same behavior as the
+ input.</p>
+ </li>
+
+ <li><p>Eliminate operations that are not supported by the target in a supported
+ type.</p>
+ <p>Targets often have wierd constraints, such as not supporting every
+ operation on every supported datatype (e.g. X86 does not support byte
+ conditional moves). Legalize takes care of either open-coding another
+ sequence of operations to emulate the operation (this is known as
+ expansion), promoting to a larger type that supports the operation
+ (promotion), or using a target-specific hook to implement the
+ legalization.</p>
+ </li>
+ </ol>
+
+ <p>
+ Instead of using a Legalize pass, we could require that every target-specific
+ <a href="#selectiondag_optimize">selector</a> supports and expands every
+ operator and type even if they are not supported and may require many
+ instructions to implement (in fact, this is the approach taken by the
+ "simple" selectors). However, using a Legalize pass allows all of the
+ cannonicalization patterns to be shared across targets which 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</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, allowing Legalize to be very simple since it can ignore many
+ special cases.
+ </p>
+
+ <p>
+ One important class of optimizations that this pass will do in the future is
+ optimizing inserted sign and zero extension instructions. 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, and does simple
+ pattern matching on the DAG to generate code. In time, the Select phase will
+ be automatically generated from the target's InstrInfo.td file, which is why we
+ want to make the Select phase as simple and mechanical as possible.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="selectiondag_future">Future directions for the SelectionDAG</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ol>
+ <li>Optional whole-function selection.</li>
+ <li>Select is a graph translation phase.</li>
+ <li>Place the machine instructions resulting from Select according to register
+ pressure or a schedule.</li>
+ <li>DAG Scheduling.</li>
+ <li>Auto-generate the Select phase from the target description (*.td) files.
+ </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="regalloc">Register Allocation</a>
+ </div>
+ <div class="doc_text"><p>To Be Written</p></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="codemission">Code Emission</a>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="targetimpls">Target description implementations</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="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 currently targets a generic P6-like processor. As such, it
+ produces a few P6-and-above instructions (like conditional moves), but it does
+ not make use of newer features like MMX or SSE. In the future, the X86 backend
+ will have sub-target support added for specific processor families and
+ implementations.</p>
+
+ </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>
+
+ <pre>
+ Base+[1,2,4,8]*IndexReg+Disp32
+ </pre>
+
+ <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 'mov' 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, 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>
+
+ <!-- *********************************************************************** -->
+ <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.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:19 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/CodingStandards.html
diff -c /dev/null llvm-www/releases/1.5/docs/CodingStandards.html:1.1
*** /dev/null Wed May 18 09:34:34 2005
--- llvm-www/releases/1.5/docs/CodingStandards.html Wed May 18 09:33:20 2005
***************
*** 0 ****
--- 1,646 ----
+ <!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>
+ </ol></li>
+ <li><a href="#micro">The Low Level Issues</a>
+ <ol>
+ <li><a href="#hl_assert">Assert Liberally</a></li>
+ <li><a href="#hl_preincrement">Prefer Preincrement</a></li>
+ <li><a href="#hl_avoidendl">Avoid <tt>std::endl</tt></a></li>
+ <li><a href="#hl_exploitcpp">Exploit C++ to its Fullest</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></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 CVS. 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 was developed by the LLVM research group and 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.</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 fundemental 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, 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_subsection">
+ <a name="micro">The Low Level Issues</a>
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="hl_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="hl_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="hl_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_subsubsection">
+ <a name="hl_exploitcpp">Exploit C++ to its Fullest</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>C++ is a powerful language. With a firm grasp on its capabilities, you can
+ make write effective, consise, readable and maintainable code all at the same
+ time. By staying consistent, you reduce the amount of special cases that need
+ to be remembered. Reducing the total number of lines of code you write is a
+ good way to avoid documentation, and avoid giving bugs a place to hide.</p>
+
+ <p>For these reasons, come to know and love the contents of your local
+ <tt><algorithm></tt> header file. Know about <tt><functional></tt>
+ and what it can do for you. C++ is just a tool that wants you to master it.</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.aw-bc.com/catalog/academic/product/0,1144,0201310155,00.html">Effective
+ C++</a> by Scott Meyers. There is an online version of the book (only some
+ chapters though) <a
+ href="http://www.awlonline.com/cseng/meyerscddemo/">available as well</a>. Also
+ interesting and useful are "More Effective C++" and "Effective STL" by the same
+ author.</li>
+
+ <li><a href="http://cseng.aw.com/book/0,3828,0201633620,00.html">Large-Scale C++
+ Software Design</a> 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.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:20 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/CommandLine.html
diff -c /dev/null llvm-www/releases/1.5/docs/CommandLine.html:1.1
*** /dev/null Wed May 18 09:34:34 2005
--- llvm-www/releases/1.5/docs/CommandLine.html Wed May 18 09:33:20 2005
***************
*** 0 ****
--- 1,1821 ----
+ <!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="#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>
+ </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::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::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="#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 "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 argument 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>
+ ...
+ ofstream Output(OutputFilename.c_str());
+ if (Out.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>opt --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>Lets 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>opt -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="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::listlt;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. Example:
+ //
+ // DEBUG(std::cerr << "Bitset contains: " << Bitset << "\n");
+ //</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 additial 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 at most one of these arguments.</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>
+
+ </ul>
+
+ <p>So far, these are the only two miscellaneous option modifiers.</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.</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
+ not 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 three parameters: first, the name of the program (since
+ <tt>argv</tt> may not be available, it can't just look in <tt>argv[0]</tt>),
+ second, the name of the environment variable to examine, and third, the optional
+ <a href="#description">additional extra text</a> to emit when the
+ <tt>--help</tt> option is invoked.</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::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::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="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 fundemental 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.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:20 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/CompilerDriver.html
diff -c /dev/null llvm-www/releases/1.5/docs/CompilerDriver.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/CompilerDriver.html Wed May 18 09:33:20 2005
***************
*** 0 ****
--- 1,823 ----
+ <!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 Compiler Driver (llvmc)</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ <meta name="author" content="Reid Spencer">
+ <meta name="description"
+ content="A description of the use and design of the LLVM Compiler Driver.">
+ </head>
+ <body>
+ <div class="doc_title">The LLVM Compiler Driver (llvmc)</div>
+ <p class="doc_warning">NOTE: This document is a work in progress!</p>
+ <ol>
+ <li><a href="#abstract">Abstract</a></li>
+ <li><a href="#introduction">Introduction</a>
+ <ol>
+ <li><a href="#purpose">Purpose</a></li>
+ <li><a href="#operation">Operation</a></li>
+ <li><a href="#phases">Phases</a></li>
+ <li><a href="#actions">Actions</a></li>
+ </ol>
+ </li>
+ <li><a href="#configuration">Configuration</a>
+ <ol>
+ <li><a href="#overview">Overview</a></li>
+ <li><a href="#filetypes">Configuration Files</a></li>
+ <li><a href="#syntax">Syntax</a></li>
+ <li><a href="#substitutions">Substitutions</a></li>
+ <li><a href="#sample">Sample Config File</a></li>
+ </ol>
+ <li><a href="#glossary">Glossary</a>
+ </ol>
+ <div class="doc_author">
+ <p>Written by <a href="mailto:rspencer at x10sys.com">Reid Spencer</a>
+ </p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="abstract">Abstract</a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This document describes the requirements, design, and configuration of the
+ LLVM compiler driver, <tt>llvmc</tt>. The compiler driver knows about LLVM's
+ tool set and can be configured to know about a variety of compilers for
+ source languages. It uses this knowledge to execute the tools necessary
+ to accomplish general compilation, optimization, and linking tasks. The main
+ purpose of <tt>llvmc</tt> is to provide a simple and consistent interface to
+ all compilation tasks. This reduces the burden on the end user who can just
+ learn to use <tt>llvmc</tt> instead of the entire LLVM tool set and all the
+ source language compilers compatible with LLVM.</p>
+ </div>
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="introduction">Introduction</a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>The <tt>llvmc</tt> <a href="#def_tool">tool</a> is a configurable compiler
+ <a href="#def_driver">driver</a>. As such, it isn't a compiler, optimizer,
+ or a linker itself but it drives (invokes) other software that perform those
+ tasks. If you are familiar with the GNU Compiler Collection's <tt>gcc</tt>
+ tool, <tt>llvmc</tt> is very similar.</p>
+ <p>The following introductory sections will help you understand why this tool
+ is necessary and what it does.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="purpose">Purpose</a></div>
+ <div class="doc_text">
+ <p><tt>llvmc</tt> was invented to make compilation of user programs with
+ LLVM-based tools easier. To accomplish this, <tt>llvmc</tt> strives to:</p>
+ <ul>
+ <li>Be the single point of access to most of the LLVM tool set.</li>
+ <li>Hide the complexities of the LLVM tools through a single interface.</li>
+ <li>Provide a consistent interface for compiling all languages.</li>
+ </ul>
+ <p>Additionally, <tt>llvmc</tt> makes it easier to write a compiler for use
+ with LLVM, because it:</p>
+ <ul>
+ <li>Makes integration of existing non-LLVM tools simple.</li>
+ <li>Extends the capabilities of minimal compiler tools by optimizing their
+ output.</li>
+ <li>Reduces the number of interfaces a compiler writer must know about
+ before a working compiler can be completed (essentially only the VMCore
+ interfaces need to be understood).</li>
+ <li>Supports source language translator invocation via both dynamically
+ loadable shared objects and invocation of an executable.</li>
+ </ul>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="operation">Operation</a></div>
+ <div class="doc_text">
+ <p>At a high level, <tt>llvmc</tt> operation is very simple. The basic action
+ taken by <tt>llvmc</tt> is to simply invoke some tool or set of tools to fill
+ the user's request for compilation. Every execution of <tt>llvmc</tt>takes the
+ following sequence of steps:</p>
+ <dl>
+ <dt><b>Collect Command Line Options</b></dt>
+ <dd>The command line options provide the marching orders to <tt>llvmc</tt>
+ on what actions it should perform. This is the request the user is making
+ of <tt>llvmc</tt> and it is interpreted first. See the <tt>llvmc</tt>
+ <a href="CommandGuide/html/llvmc.html">manual page</a> for details on the
+ options.</dd>
+ <dt><b>Read Configuration Files</b></dt>
+ <dd>Based on the options and the suffixes of the filenames presented, a set
+ of configuration files are read to configure the actions <tt>llvmc</tt> will
+ take. Configuration files are provided by either LLVM or the
+ compiler tools that <tt>llvmc</tt> invokes. These files determine what
+ actions <tt>llvmc</tt> will take in response to the user's request. See
+ the section on <a href="#configuration">configuration</a> for more details.
+ </dd>
+ <dt><b>Determine Phases To Execute</b></dt>
+ <dd>Based on the command line options and configuration files,
+ <tt>llvmc</tt> determines the compilation <a href="#phases">phases</a> that
+ must be executed by the user's request. This is the primary work of
+ <tt>llvmc</tt>.</dd>
+ <dt><b>Determine Actions To Execute</b></dt>
+ <dd>Each <a href="#phases">phase</a> to be executed can result in the
+ invocation of one or more <a href="#actions">actions</a>. An action is
+ either a whole program or a function in a dynamically linked shared library.
+ In this step, <tt>llvmc</tt> determines the sequence of actions that must be
+ executed. Actions will always be executed in a deterministic order.</dd>
+ <dt><b>Execute Actions</b></dt>
+ <dd>The <a href="#actions">actions</a> necessary to support the user's
+ original request are executed sequentially and deterministically. All
+ actions result in either the invocation of a whole program to perform the
+ action or the loading of a dynamically linkable shared library and invocation
+ of a standard interface function within that library.</dd>
+ <dt><b>Termination</b></dt>
+ <dd>If any action fails (returns a non-zero result code), <tt>llvmc</tt>
+ also fails and returns the result code from the failing action. If
+ everything succeeds, <tt>llvmc</tt> will return a zero result code.</dd>
+ </dl>
+ <p><tt>llvmc</tt>'s operation must be simple, regular and predictable.
+ Developers need to be able to rely on it to take a consistent approach to
+ compilation. For example, the invocation:</p>
+ <code>
+ llvmc -O2 x.c y.c z.c -o xyz</code>
+ <p>must produce <i>exactly</i> the same results as:</p>
+ <pre><tt>
+ llvmc -O2 x.c -o x.o
+ llvmc -O2 y.c -o y.o
+ llvmc -O2 z.c -o z.o
+ llvmc -O2 x.o y.o z.o -o xyz</tt></pre>
+ <p>To accomplish this, <tt>llvmc</tt> uses a very simple goal oriented
+ procedure to do its work. The overall goal is to produce a functioning
+ executable. To accomplish this, <tt>llvmc</tt> always attempts to execute a
+ series of compilation <a href="#def_phase">phases</a> in the same sequence.
+ However, the user's options to <tt>llvmc</tt> can cause the sequence of phases
+ to start in the middle or finish early.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="phases"></a>Phases </div>
+ <div class="doc_text">
+ <p><tt>llvmc</tt> breaks every compilation task into the following five
+ distinct phases:</p>
+ <dl><dt><b>Preprocessing</b></dt><dd>Not all languages support preprocessing;
+ but for those that do, this phase can be invoked. This phase is for
+ languages that provide combining, filtering, or otherwise altering with the
+ source language input before the translator parses it. Although C and C++
+ are the most common users of this phase, other languages may provide their
+ own preprocessor (whether its the C pre-processor or not).</dd>
+ </dl>
+ <dl><dt><b>Translation</b></dt><dd>The translation phase converts the source
+ language input into something that LLVM can interpret and use for
+ downstream phases. The translation is essentially from "non-LLVM form" to
+ "LLVM form".</dd>
+ </dl>
+ <dl><dt><b>Optimization</b></dt><dd>Once an LLVM Module has been obtained from
+ the translation phase, the program enters the optimization phase. This phase
+ attempts to optimize all of the input provided on the command line according
+ to the options provided.</dd>
+ </dl>
+ <dl><dt><b>Linking</b></dt><dd>The inputs are combined to form a complete
+ program.</dd>
+ </dl>
+ <p>The following table shows the inputs, outputs, and command line options
+ applicable to each phase.</p>
+ <table>
+ <tr>
+ <th style="width: 10%">Phase</th>
+ <th style="width: 25%">Inputs</th>
+ <th style="width: 25%">Outputs</th>
+ <th style="width: 40%">Options</th>
+ </tr>
+ <tr><td><b>Preprocessing</b></td>
+ <td class="td_left"><ul><li>Source Language File</li></ul></td>
+ <td class="td_left"><ul><li>Source Language File</li></ul></td>
+ <td class="td_left"><dl>
+ <dt><tt>-E</tt></dt>
+ <dd>Stops the compilation after preprocessing</dd>
+ </dl></td>
+ </tr>
+ <tr>
+ <td><b>Translation</b></td>
+ <td class="td_left"><ul>
+ <li>Source Language File</li>
+ </ul></td>
+ <td class="td_left"><ul>
+ <li>LLVM Assembly</li>
+ <li>LLVM Bytecode</li>
+ <li>LLVM C++ IR</li>
+ </ul></td>
+ <td class="td_left"><dl>
+ <dt><tt>-c</tt></dt>
+ <dd>Stops the compilation after translation so that optimization and
+ linking are not done.</dd>
+ <dt><tt>-S</tt></dt>
+ <dd>Stops the compilation before object code is written so that only
+ assembly code remains.</dd>
+ </dl></td>
+ </tr>
+ <tr>
+ <td><b>Optimization</b></td>
+ <td class="td_left"><ul>
+ <li>LLVM Assembly</li>
+ <li>LLVM Bytecode</li>
+ </ul></td>
+ <td class="td_left"><ul>
+ <li>LLVM Bytecode</li>
+ </ul></td>
+ <td class="td_left"><dl>
+ <dt><tt>-Ox</tt>
+ <dd>This group of options controls the amount of optimization
+ performed.</dd>
+ </dl></td>
+ </tr>
+ <tr>
+ <td><b>Linking</b></td>
+ <td class="td_left"><ul>
+ <li>LLVM Bytecode</li>
+ <li>Native Object Code</li>
+ <li>LLVM Library</li>
+ <li>Native Library</li>
+ </ul></td>
+ <td class="td_left"><ul>
+ <li>LLVM Bytecode Executable</li>
+ <li>Native Executable</li>
+ </ul></td>
+ <td class="td_left"><dl>
+ <dt><tt>-L</tt></dt><dd>Specifies a path for library search.</dd>
+ <dt><tt>-l</tt></dt><dd>Specifies a library to link in.</dd>
+ </dl></td>
+ </tr>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="actions"></a>Actions</div>
+ <div class="doc_text">
+ <p>An action, with regard to <tt>llvmc</tt> is a basic operation that it takes
+ in order to fulfill the user's request. Each phase of compilation will invoke
+ zero or more actions in order to accomplish that phase.</p>
+ <p>Actions come in two forms:</p>
+ <ul>
+ <li>Invokable Executables</li>
+ <li>Functions in a shared library</li>
+ </ul>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="configuration">Configuration</a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This section of the document describes the configuration files used by
+ <tt>llvmc</tt>. Configuration information is relatively static for a
+ given release of LLVM and a compiler tool. However, the details may
+ change from release to release of either. Users are encouraged to simply use
+ the various options of the <tt>llvmc</tt> command and ignore the configuration
+ of the tool. These configuration files are for compiler writers and LLVM
+ developers. Those wishing to simply use <tt>llvmc</tt> don't need to understand
+ this section but it may be instructive on how the tool works.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="overview"></a>Overview</div>
+ <div class="doc_text">
+ <p><tt>llvmc</tt> is highly configurable both on the command line and in
+ configuration files. The options it understands are generic, consistent and
+ simple by design. Furthermore, the <tt>llvmc</tt> options apply to the
+ compilation of any LLVM enabled programming language. To be enabled as a
+ supported source language compiler, a compiler writer must provide a
+ configuration file that tells <tt>llvmc</tt> how to invoke the compiler
+ and what its capabilities are. The purpose of the configuration files then
+ is to allow compiler writers to specify to <tt>llvmc</tt> how the compiler
+ should be invoked. Users may but are not advised to alter the compiler's
+ <tt>llvmc</tt> configuration.</p>
+
+ <p>Because <tt>llvmc</tt> just invokes other programs, it must deal with the
+ available command line options for those programs regardless of whether they
+ were written for LLVM or not. Furthermore, not all compiler tools will
+ have the same capabilities. Some compiler tools will simply generate LLVM assembly
+ code, others will be able to generate fully optimized byte code. In general,
+ <tt>llvmc</tt> doesn't make any assumptions about the capabilities or command
+ line options of a sub-tool. It simply uses the details found in the
+ configuration files and leaves it to the compiler writer to specify the
+ configuration correctly.</p>
+
+ <p>This approach means that new compiler tools can be up and working very
+ quickly. As a first cut, a tool can simply compile its source to raw
+ (unoptimized) bytecode or LLVM assembly and <tt>llvmc</tt> can be configured
+ to pick up the slack (translate LLVM assembly to bytecode, optimize the
+ bytecode, generate native assembly, link, etc.). In fact, the compiler tools
+ need not use any LLVM libraries, and it could be written in any language
+ (instead of C++). The configuration data will allow the full range of
+ optimization, assembly, and linking capabilities that LLVM provides to be added
+ to these kinds of tools. Enabling the rapid development of front-ends is one
+ of the primary goals of <tt>llvmc</tt>.</p>
+
+ <p>As a compiler tool matures, it may utilize the LLVM libraries and tools
+ to more efficiently produce optimized bytecode directly in a single compilation
+ and optimization program. In these cases, multiple tools would not be needed
+ and the configuration data for the compiler would change.</p>
+
+ <p>Configuring <tt>llvmc</tt> to the needs and capabilities of a source language
+ compiler is relatively straight-forward. A compiler writer must provide a
+ definition of what to do for each of the five compilation phases for each of
+ the optimization levels. The specification consists simply of prototypical
+ command lines into which <tt>llvmc</tt> can substitute command line
+ arguments and file names. Note that any given phase can be completely blank if
+ the source language's compiler combines multiple phases into a single program.
+ For example, quite often pre-processing, translation, and optimization are
+ combined into a single program. The specification for such a compiler would have
+ blank entries for pre-processing and translation but a full command line for
+ optimization.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="filetypes">Configuration Files</a></div>
+ <div class="doc_subsubsection"><a name="filecontents">File Contents</a></div>
+ <div class="doc_text">
+ <p>Each configuration file provides the details for a single source language
+ that is to be compiled. This configuration information tells <tt>llvmc</tt>
+ how to invoke the language's pre-processor, translator, optimizer, assembler
+ and linker. Note that a given source language needn't provide all these tools
+ as many of them exist in llvm currently.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"><a name="dirsearch">Directory Search</a></div>
+ <div class="doc_text">
+ <p><tt>llvmc</tt> always looks for files of a specific name. It uses the
+ first file with the name its looking for by searching directories in the
+ following order:<br/>
+ <ol>
+ <li>Any directory specified by the <tt>-config-dir</tt> option will be
+ checked first.</li>
+ <li>If the environment variable LLVM_CONFIG_DIR is set, and it contains
+ the name of a valid directory, that directory will be searched next.</li>
+ <li>If the user's home directory (typically <tt>/home/user</tt> contains
+ a sub-directory named <tt>.llvm</tt> and that directory contains a
+ sub-directory named <tt>etc</tt> then that directory will be tried
+ next.</li>
+ <li>If the LLVM installation directory (typically <tt>/usr/local/llvm</tt>
+ contains a sub-directory named <tt>etc</tt> then that directory will be
+ tried last.</li>
+ <li>A standard "system" directory will be searched next. This is typically
+ <tt>/etc/llvm</tt> on UNIX™ and <tt>C:\WINNT</tt> on Microsoft
+ Windows™.</li>
+ <li>If the configuration file sought still can't be found, <tt>llvmc</tt>
+ will print an error message and exit.</li>
+ </ol>
+ <p>The first file found in this search will be used. Other files with the
+ same name will be ignored even if they exist in one of the subsequent search
+ locations.</p>
+ </div>
+
+ <div class="doc_subsubsection"><a name="filenames">File Names</a></div>
+ <div class="doc_text">
+ <p>In the directories searched, each configuration file is given a specific
+ name to foster faster lookup (so llvmc doesn't have to do directory searches).
+ The name of a given language specific configuration file is simply the same
+ as the suffix used to identify files containing source in that language.
+ For example, a configuration file for C++ source might be named
+ <tt>cpp</tt>, <tt>C</tt>, or <tt>cxx</tt>. For languages that support multiple
+ file suffixes, multiple (probably identical) files (or symbolic links) will
+ need to be provided.</p>
+ </div>
+
+ <div class="doc_subsubsection"><a name="whatgetsread">What Gets Read</a></div>
+ <div class="doc_text">
+ <p>Which configuration files are read depends on the command line options and
+ the suffixes of the file names provided on <tt>llvmc</tt>'s command line. Note
+ that the <tt>-x LANGUAGE</tt> option alters the language that <tt>llvmc</tt>
+ uses for the subsequent files on the command line. Only the configuration
+ files actually needed to complete <tt>llvmc</tt>'s task are read. Other
+ language specific files will be ignored.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="syntax"></a>Syntax</div>
+ <div class="doc_text">
+ <p>The syntax of the configuration files is very simple and somewhat
+ compatible with Java's property files. Here are the syntax rules:</p>
+ <ul>
+ <li>The file encoding is ASCII.</li>
+ <li>The file is line oriented. There should be one configuration definition
+ per line. Lines are terminated by the newline (0x0A) and/or carriage return
+ characters (0x0D)</li>
+ <li>A backslash (<tt>\</tt>) before a newline causes the newline to be
+ ignored. This is useful for line continuation of long definitions. A
+ backslash anywhere else is recognized as a backslash.</li>
+ <li>A configuration item consists of a name, an <tt>=</tt> and a value.</li>
+ <li>A name consists of a sequence of identifiers separated by period.</li>
+ <li>An identifier consists of specific keywords made up of only lower case
+ and upper case letters (e.g. <tt>lang.name</tt>).</li>
+ <li>Values come in four flavors: booleans, integers, commands and
+ strings.</li>
+ <li>Valid "false" boolean values are <tt>false False FALSE no No NO
+ off Off</tt> and <tt>OFF</tt>.</li>
+ <li>Valid "true" boolean values are <tt>true True TRUE yes Yes YES
+ on On</tt> and <tt>ON</tt>.</li>
+ <li>Integers are simply sequences of digits.</li>
+ <li>Commands start with a program name and are followed by a sequence of
+ words that are passed to that program as command line arguments. Program
+ arguments that begin and end with the <tt>%</tt> sign will have their value
+ substituted. Program names beginning with <tt>/</tt> are considered to be
+ absolute. Otherwise the <tt>PATH</tt> will be applied to find the program to
+ execute.</li>
+ <li>Strings are composed of multiple sequences of characters from the
+ character class <tt>[-A-Za-z0-9_:%+/\\|,]</tt> separated by white
+ space.</li>
+ <li>White space on a line is folded. Multiple blanks or tabs will be
+ reduced to a single blank.</li>
+ <li>White space before the configuration item's name is ignored.</li>
+ <li>White space on either side of the <tt>=</tt> is ignored.</li>
+ <li>White space in a string value is used to separate the individual
+ components of the string value but otherwise ignored.</li>
+ <li>Comments are introduced by the <tt>#</tt> character. Everything after a
+ <tt>#</tt> and before the end of line is ignored.</li>
+ </ul>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="items">Configuration Items</a></div>
+ <div class="doc_text">
+ <p>The table below provides definitions of the allowed configuration items
+ that may appear in a configuration file. Every item has a default value and
+ does not need to appear in the configuration file. Missing items will have the
+ default value. Each identifier may appear as all lower case, first letter
+ capitalized or all upper case.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th>Name</th>
+ <th>Value Type</th>
+ <th>Description</th>
+ <th>Default</th>
+ </tr>
+ <tr><td colspan="4"><h4>LLVMC ITEMS</h4></td></tr>
+ <tr>
+ <td><b>version</b></td>
+ <td>string</td>
+ <td class="td_left">Provides the version string for the contents of this
+ configuration file. What is accepted as a legal configuration file
+ will change over time and this item tells <tt>llvmc</tt> which version
+ should be expected.</td>
+ <td><i>b</i></td>
+ </tr>
+ <tr><td colspan="4"><h4>LANG ITEMS</h4></td></tr>
+ <tr>
+ <td><b>lang.name</b></td>
+ <td>string</td>
+ <td class="td_left">Provides the common name for a language definition.
+ For example "C++", "Pascal", "FORTRAN", etc.</td>
+ <td><i>blank</i></td>
+ </tr>
+ <tr>
+ <td><b>lang.opt1</b></td>
+ <td>string</td>
+ <td class="td_left">Specifies the parameters to give the optimizer when
+ <tt>-O1</tt> is specified on the <tt>llvmc</tt> command line.</td>
+ <td><tt>-simplifycfg -instcombine -mem2reg</tt></td>
+ </tr>
+ <tr>
+ <td><b>lang.opt2</b></td>
+ <td>string</td>
+ <td class="td_left">Specifies the parameters to give the optimizer when
+ <tt>-O2</tt> is specified on the <tt>llvmc</tt> command line.</td>
+ <td><i>TBD</i></td>
+ </tr>
+ <tr>
+ <td><b>lang.opt3</b></td>
+ <td>string</td>
+ <td class="td_left">Specifies the parameters to give the optimizer when
+ <tt>-O3</tt> is specified on the <tt>llvmc</tt> command line.</td>
+ <td><i>TBD</i></td>
+ </tr>
+ <tr>
+ <td><b>lang.opt4</b></td>
+ <td>string</td>
+ <td class="td_left">Specifies the parameters to give the optimizer when
+ <tt>-O4</tt> is specified on the <tt>llvmc</tt> command line.</td>
+ <td><i>TBD</i></td>
+ </tr>
+ <tr>
+ <td><b>lang.opt5</b></td>
+ <td>string</td>
+ <td class="td_left">Specifies the parameters to give the optimizer when
+ <tt>-O5</tt> is specified on the <tt>llvmc</tt> command line.</td>
+ <td><i>TBD</i></td>
+ </tr>
+ <tr><td colspan="4"><h4>PREPROCESSOR ITEMS</h4></td></tr>
+ <tr>
+ <td><b>preprocessor.command</b></td>
+ <td>command</td>
+ <td class="td_left">This provides the command prototype that will be used
+ to run the preprocessor. This is generally only used with the
+ <tt>-E</tt> option.</td>
+ <td><blank></td>
+ </tr>
+ <tr>
+ <td><b>preprocessor.required</b></td>
+ <td>boolean</td>
+ <td class="td_left">This item specifies whether the pre-processing phase
+ is required by the language. If the value is true, then the
+ <tt>preprocessor.command</tt> value must not be blank. With this option,
+ <tt>llvmc</tt> will always run the preprocessor as it assumes that the
+ translation and optimization phases don't know how to pre-process their
+ input.</td>
+ <td>false</td>
+ </tr>
+ <tr><td colspan="4"><h4>TRANSLATOR ITEMS</h4></td></tr>
+ <tr>
+ <td><b>translator.command</b></td>
+ <td>command</td>
+ <td class="td_left">This provides the command prototype that will be used
+ to run the translator. Valid substitutions are <tt>%in%</tt> for the
+ input file and <tt>%out%</tt> for the output file.</td>
+ <td><blank></td>
+ </tr>
+ <tr>
+ <td><b>translator.output</b></td>
+ <td><tt>bytecode</tt> or <tt>assembly</tt></td>
+ <td class="td_left">This item specifies the kind of output the language's
+ translator generates.</td>
+ <td><tt>bytecode</tt></td>
+ </tr>
+ <tr>
+ <td><b>translator.preprocesses</b></td>
+ <td>boolean</td>
+ <td class="td_left">Indicates that the translator also preprocesses. If
+ this is true, then <tt>llvmc</tt> will skip the pre-processing phase
+ whenever the final phase is not pre-processing.</td>
+ <td><tt>false</tt></td>
+ </tr>
+ <tr><td colspan="4"><h4>OPTIMIZER ITEMS</h4></td></tr>
+ <tr>
+ <td><b>optimizer.command</b></td>
+ <td>command</td>
+ <td class="td_left">This provides the command prototype that will be used
+ to run the optimizer. Valid substitutions are <tt>%in%</tt> for the
+ input file and <tt>%out%</tt> for the output file.</td>
+ <td><blank></td>
+ </tr>
+ <tr>
+ <td><b>optimizer.output</b></td>
+ <td><tt>bytecode</tt> or <tt>assembly</tt></td>
+ <td class="td_left">This item specifies the kind of output the language's
+ optimizer generates. Valid values are "assembly" and "bytecode"</td>
+ <td><tt>bytecode</tt></td>
+ </tr>
+ <tr>
+ <td><b>optimizer.preprocesses</b></td>
+ <td>boolean</td>
+ <td class="td_left">Indicates that the optimizer also preprocesses. If
+ this is true, then <tt>llvmc</tt> will skip the pre-processing phase
+ whenever the final phase is optimization or later.</td>
+ <td><tt>false</tt></td>
+ </tr>
+ <tr>
+ <td><b>optimizer.translates</b></td>
+ <td>boolean</td>
+ <td class="td_left">Indicates that the optimizer also translates. If
+ this is true, then <tt>llvmc</tt> will skip the translation phase
+ whenever the final phase is optimization or later.</td>
+ <td><tt>false</tt></td>
+ </tr>
+ <tr><td colspan="4"><h4>ASSEMBLER ITEMS</h4></td></tr>
+ <tr>
+ <td><b>assembler.command</b></td>
+ <td>command</td>
+ <td class="td_left">This provides the command prototype that will be used
+ to run the assembler. Valid substitutions are <tt>%in%</tt> for the
+ input file and <tt>%out%</tt> for the output file.</td>
+ <td><blank></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="substitutions">Substitutions</a></div>
+ <div class="doc_text">
+ <p>On any configuration item that ends in <tt>command</tt>, you must
+ specify substitution tokens. Substitution tokens begin and end with a percent
+ sign (<tt>%</tt>) and are replaced by the corresponding text. Any substitution
+ token may be given on any <tt>command</tt> line but some are more useful than
+ others. In particular each command <em>should</em> have both an <tt>%in%</tt>
+ and an <tt>%out%</tt> substitution. The table below provides definitions of
+ each of the allowed substitution tokens.</p>
+ <table>
+ <tbody>
+ <tr>
+ <th>Substitution Token</th>
+ <th>Replacement Description</th>
+ </tr>
+ <tr>
+ <td><tt>%args%</tt></td>
+ <td class="td_left">Replaced with all the tool-specific arguments given
+ to <tt>llvmc</tt> via the <tt>-T</tt> set of options. This just allows
+ you to place these arguments in the correct place on the command line.
+ If the <tt>%args%</tt> option does not appear on your command line,
+ then you are explicitly disallowing the <tt>-T</tt> option for your
+ tool.
+ </td>
+ <tr>
+ <td><tt>%force%</tt></td>
+ <td class="td_left">Replaced with the <tt>-f</tt> option if it was
+ specified on the <tt>llvmc</tt> command line. This is intended to tell
+ the compiler tool to force the overwrite of output files.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>%in%</tt></td>
+ <td class="td_left">Replaced with the full path of the input file. You
+ needn't worry about the cascading of file names. <tt>llvmc</tt> will
+ create temporary files and ensure that the output of one phase is the
+ input to the next phase.</td>
+ </tr>
+ <tr>
+ <td><tt>%opt%</tt></td>
+ <td class="td_left">Replaced with the optimization options for the
+ tool. If the tool understands the <tt>-O</tt> options then that will
+ be passed. Otherwise, the <tt>lang.optN</tt> series of configuration
+ items will specify which arguments are to be given.</td>
+ </tr>
+ <tr>
+ <td><tt>%out%</tt></td>
+ <td class="td_left">Replaced with the full path of the output file.
+ Note that this is not necessarily the output file specified with the
+ <tt>-o</tt> option on <tt>llvmc</tt>'s command line. It might be a
+ temporary file that will be passed to a subsequent phase's input.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>%stats%</tt></td>
+ <td class="td_left">If your command accepts the <tt>-stats</tt> option,
+ use this substitution token. If the user requested <tt>-stats</tt>
+ from the <tt>llvmc</tt> command line then this token will be replaced
+ with <tt>-stats</tt>, otherwise it will be ignored.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>%target%</tt></td>
+ <td class="td_left">Replaced with the name of the target "machine" for
+ which code should be generated. The value used here is taken from the
+ <tt>llvmc</tt> option <tt>-march</tt>.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>%time%</tt></td>
+ <td class="td_left">If your command accepts the <tt>-time-passes</tt>
+ option, use this substitution token. If the user requested
+ <tt>-time-passes</tt> from the <tt>llvmc</tt> command line then this
+ token will be replaced with <tt>-time-passes</tt>, otherwise it will
+ be ignored.
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="sample">Sample Config File</a></div>
+ <div class="doc_text">
+ <p>Since an example is always instructive, here's how the Stacker language
+ configuration file looks.</p>
+ <pre><tt>
+ # Stacker Configuration File For llvmc
+
+ ##########################################################
+ # Language definitions
+ ##########################################################
+ lang.name=Stacker
+ lang.opt1=-simplifycfg -instcombine -mem2reg
+ lang.opt2=-simplifycfg -instcombine -mem2reg -load-vn \
+ -gcse -dse -scalarrepl -sccp
+ lang.opt3=-simplifycfg -instcombine -mem2reg -load-vn \
+ -gcse -dse -scalarrepl -sccp -branch-combine -adce \
+ -globaldce -inline -licm
+ lang.opt4=-simplifycfg -instcombine -mem2reg -load-vn \
+ -gcse -dse -scalarrepl -sccp -ipconstprop \
+ -branch-combine -adce -globaldce -inline -licm
+ lang.opt5=-simplifycfg -instcombine -mem2reg --load-vn \
+ -gcse -dse scalarrepl -sccp -ipconstprop \
+ -branch-combine -adce -globaldce -inline -licm \
+ -block-placement
+
+ ##########################################################
+ # Pre-processor definitions
+ ##########################################################
+
+ # Stacker doesn't have a preprocessor but the following
+ # allows the -E option to be supported
+ preprocessor.command=cp %in% %out%
+ preprocessor.required=false
+
+ ##########################################################
+ # Translator definitions
+ ##########################################################
+
+ # To compile stacker source, we just run the stacker
+ # compiler with a default stack size of 2048 entries.
+ translator.command=stkrc -s 2048 %in% -o %out% %time% \
+ %stats% %force% %args%
+
+ # stkrc doesn't preprocess but we set this to true so
+ # that we don't run the cp command by default.
+ translator.preprocesses=true
+
+ # The translator is required to run.
+ translator.required=true
+
+ # stkrc doesn't handle the -On options
+ translator.output=bytecode
+
+ ##########################################################
+ # Optimizer definitions
+ ##########################################################
+
+ # For optimization, we use the LLVM "opt" program
+ optimizer.command=opt %in% -o %out% %opt% %time% %stats% \
+ %force% %args%
+
+ optimizer.required = true
+
+ # opt doesn't translate
+ optimizer.translates = no
+
+ # opt doesn't preprocess
+ optimizer.preprocesses=no
+
+ # opt produces bytecode
+ optimizer.output = bc
+
+ ##########################################################
+ # Assembler definitions
+ ##########################################################
+ assembler.command=llc %in% -o %out% %target% %time% %stats%
+ </tt></pre>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="glossary">Glossary</a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This document uses precise terms in reference to the various artifacts and
+ concepts related to compilation. The terms used throughout this document are
+ defined below.</p>
+ <dl>
+ <dt><a name="def_assembly"><b>assembly</b></a></dt>
+ <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode or
+ LLVM assembly code is assembled to a native code format (either target
+ specific aseembly language or the platform's native object file format).
+ </dd>
+
+ <dt><a name="def_compiler"><b>compiler</b></a></dt>
+ <dd>Refers to any program that can be invoked by <tt>llvmc</tt> to accomplish
+ the work of one or more compilation <a href="#def_phase">phases</a>.</dd>
+
+ <dt><a name="def_driver"><b>driver</b></a></dt>
+ <dd>Refers to <tt>llvmc</tt> itself.</dd>
+
+ <dt><a name="def_linking"><b>linking</b></a></dt>
+ <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode files
+ and (optionally) native system libraries are combined to form a complete
+ executable program.</dd>
+
+ <dt><a name="def_optimization"><b>optimization</b></a></dt>
+ <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode is
+ optimized.</dd>
+
+ <dt><a name="def_phase"><b>phase</b></a></dt>
+ <dd>Refers to any one of the five compilation phases that that
+ <tt>llvmc</tt> supports. The five phases are:
+ <a href="#def_preprocessing">preprocessing</a>,
+ <a href="#def_translation">translation</a>,
+ <a href="#def_optimization">optimization</a>,
+ <a href="#def_assembly">assembly</a>,
+ <a href="#def_linking">linking</a>.</dd>
+
+ <dt><a name="def_sourcelanguage"><b>source language</b></a></dt>
+ <dd>Any common programming language (e.g. C, C++, Java, Stacker, ML,
+ FORTRAN). These languages are distinguished from any of the lower level
+ languages (such as LLVM or native assembly), by the fact that a
+ <a href="#def_translation">translation</a> <a href="#def_phase">phase</a>
+ is required before LLVM can be applied.</dd>
+
+ <dt><a name="def_tool"><b>tool</b></a></dt>
+ <dd>Refers to any program in the LLVM tool set.</dd>
+
+ <dt><a name="def_translation"><b>translation</b></a></dt>
+ <dd>A compilation <a href="#def_phase">phase</a> in which
+ <a href="#def_sourcelanguage">source language</a> code is translated into
+ either LLVM assembly language or LLVM bytecode.</dd>
+ </dl>
+ </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:rspencer at x10sys.com">Reid Spencer</a><br>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:20 $
+ </address>
+ <!-- vim: sw=2
+ -->
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/CompilerWriterInfo.html
diff -c /dev/null llvm-www/releases/1.5/docs/CompilerWriterInfo.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/CompilerWriterInfo.html Wed May 18 09:33:20 2005
***************
*** 0 ****
--- 1,263 ----
+ <!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>
+ </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_subsubsection">Official manuals and docs</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.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:20 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/ExtendingLLVM.html
diff -c /dev/null llvm-www/releases/1.5/docs/ExtendingLLVM.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/ExtendingLLVM.html Wed May 18 09:33:20 2005
***************
*** 0 ****
--- 1,329 ----
+ <!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="#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, 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 easier than adding
+ an instruction, and is transparent to optimization passes which treat it as an
+ unanalyzable function. 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.h</tt>:
+ add an enum in the <tt>llvm::Intrinsic</tt> namespace</li>
+
+ <li><tt>llvm/lib/VMCore/Verifier.cpp</tt>:
+ Add code to check the invariants of the intrinsic are respected.</li>
+
+ <li><tt>llvm/lib/VMCore/Function.cpp (<tt>Function::getIntrinsicID()</tt>)</tt>:
+ Identify the new intrinsic function, returning the enum for the intrinsic
+ that you added.</li>
+
+ <li><tt>llvm/lib/Analysis/BasicAliasAnalysis.cpp</tt>: If the new intrinsic does
+ not access memory or does not write to memory, add it to the relevant list
+ of functions.</li>
+
+ <li><tt>llvm/lib/Transforms/Utils/Local.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>Test your intrinsic</li>
+
+ <li><tt>llvm/test/Regression/*</tt>: add 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. First,
+ 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>. Second, 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 llvm.prefetch 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 a enum value for the SelectionDAG node in
+ <tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt></dt>
+
+ <dd>Also, add code to <tt>lib/CodeGen/SelectionDAG/SelectionDAG.cpp</tt> (and
+ <tt>SelectionDAGPrinter.cpp</tt>) to print the node.</dd>
+
+ <dt>Add code to <tt>SelectionDAG/SelectionDAGISel.cpp</tt> to recognize the
+ intrinsic.</dt>
+
+ <dd>Presumably the intrinsic should be recognized and turned into the node you
+ added above.</dd>
+
+ <dt>Add code to <tt>SelectionDAG/LegalizeDAG.cpp</tt> to <a
+ href="CodeGenerator.html#selectiondag_legalize">legalize, promote, and
+ expand</a> the node as necessary.</dt>
+
+ <dd>If the intrinsic can be expanded to primitive operations, legalize can break
+ the node down into other elementary operations that are be supported.</dd>
+
+ <dt>Add target-specific support to specific code generators.</dt>
+
+ <dd>Extend the code generators you are interested in to recognize and support
+ the node, emitting the code you want.</dd>
+ </dl>
+
+ <p>
+ Unfortunately, the process of extending the code generator to support a new node
+ is not extremely well documented. As such, it is often helpful to look at other
+ intrinsics (e.g. <tt>llvm.ctpop</tt>) to see how they are recognized and turned
+ into a node by <tt>SelectionDAGISel.cpp</tt>, legalized by
+ <tt>LegalizeDAG.cpp</tt>, then finally emitted by the various code generators.
+ </p>
+
+ </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 bytecode
+ 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/Bytecode/Reader/Reader.cpp</tt>:
+ add a case for your instruction and how it will be parsed from bytecode</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 bytecode
+ 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/DerivedType.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/ByteCode/Writer/Writer.cpp</tt>:
+ modify <tt>void BytecodeWriter::outputType(const Type *T)</tt> to serialize
+ your type</li>
+
+ <li><tt>llvm/lib/ByteCode/Reader/Reader.cpp</tt>:
+ modify <tt>const Type *BytecodeReader::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.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
+ <br>
+ Last modified: $Date: 2005/05/18 14:33:20 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/FAQ.html
diff -c /dev/null llvm-www/releases/1.5/docs/FAQ.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/FAQ.html Wed May 18 09:33:20 2005
***************
*** 0 ****
--- 1,581 ----
+ <!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>I compile the code, and I get some error about <tt>/localhome</tt>.</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 CVS, 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 CVS update, rebuilding gives the error "No rule to make
+ target".</li>
+ </ol></li>
+
+ <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>
+
+ </ol>
+ </li>
+
+ <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
+ <ol>
+ <li><a href="#__main">What is this <tt>__main()</tt> call that gets inserted into
+ <tt>main()</tt>?</a></li>
+ <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.cs.uiuc.edu">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.cs.uiuc.edu/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>I compile the code, and I get some error about <tt>/localhome</tt>.</p>
+ </div>
+
+ <div class="answer">
+
+ <p>There are several possible causes for this. The first is that you didn't set
+ a pathname properly when using <tt>configure</tt>, and it defaulted to a
+ pathname that we use on our research machines.</p>
+
+ <p>Another possibility is that we hardcoded a path in our Makefiles. If you see
+ this, please email the LLVM bug mailing list with the name of the offending
+ Makefile and a description of what is wrong with it.</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>
+
+ <p><tt>PATH=[the path without the bad program] ./configure ...</tt></p>
+
+ <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 CVS, 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>
+
+ <p><tt>./config.status <relative path to Makefile></tt><p>
+
+ <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>
+
+ <p><tt>gmake ENABLE_PROFILING=1</tt>
+
+ <p>...then you must run the tests with the following commands:</p>
+
+ <p><tt>cd llvm/test<br>gmake ENABLE_PROFILING=1</tt></p>
+
+ </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 CVS 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">
+ <tt>
+ gmake[2]: *** No rule to make target `/path/to/somefile', needed by
+ `/path/to/another/file.d'.<br>
+ Stop.
+ </tt>
+ </div>
+
+ <p>This may occur anytime files are moved within the CVS 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="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 gccld linker to create a native code executable instead of
+ a 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>
+ <pre>
+ % cd llvm/runtime
+ % make clean ; make install-bytecode
+ </pre>
+ </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="doc_section">
+ <a name="cfe_code">Questions about code generated by the GCC front-end</a>
+ </div>
+
+ <div class="question"><p>
+ <a name="__main"></a>
+ What is this <tt>__main()</tt> call that gets inserted into <tt>main()</tt>?
+ </p></div>
+
+ <div class="answer">
+ <p>
+ The <tt>__main</tt> call is inserted by the C/C++ compiler in order to guarantee
+ that static constructors and destructors are called when the program starts up
+ and shuts down. In C, you can create static constructors and destructors by
+ using GCC extensions, and in C++ you can do so by creating a global variable
+ whose class has a ctor or dtor.
+ </p>
+
+ <p>
+ The actual implementation of <tt>__main</tt> lives in the
+ <tt>llvm/runtime/GCCLibraries/crtend/</tt> directory in the source-base, and is
+ linked in automatically when you link the program.
+ </p>
+ </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">
+ <tt>int X() { int i; return i; }</tt>
+ </div>
+
+ <p>Is compiled to "<tt>ret int undef</tt>" because "i" 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.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:20 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/GarbageCollection.html
diff -c /dev/null llvm-www/releases/1.5/docs/GarbageCollection.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/GarbageCollection.html Wed May 18 09:33:21 2005
***************
*** 0 ****
--- 1,533 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>Accurate Garbage Collection with LLVM</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </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="#interfaces">Interfaces for user programs</a>
+ <ul>
+ <li><a href="#roots">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a></li>
+ <li><a href="#allocate">Allocating memory from the GC</a></li>
+ <li><a href="#barriers">Reading and writing references to the heap</a></li>
+ <li><a href="#explicit">Explicit invocation of the garbage collector</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#gcimpl">Implementing a garbage collector</a>
+ <ul>
+ <li><a href="#llvm_gc_readwrite">Implementing <tt>llvm_gc_read</tt> and <tt>llvm_gc_write</tt></a></li>
+ <li><a href="#callbacks">Callback functions used to implement the garbage collector</a></li>
+ </ul>
+ </li>
+ <li><a href="#gcimpls">GC implementations available</a>
+ <ul>
+ <li><a href="#semispace">SemiSpace - A simple copying garbage collector</a></li>
+ </ul>
+ </li>
+
+ <!--
+ <li><a href="#codegen">Implementing GC support in a code generator</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>Garbage collection is a widely used technique that frees the programmer from
+ having to know the life-times 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 [LINK] Boehm collector 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="#roots">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 provides support for a broad class of garbage collection algorithms,
+ including compacting semi-space collectors, mark-sweep collectors, generational
+ collectors, and even reference counting implementations. It includes support
+ for <a href="#barriers">read and write barriers</a>, and associating <a
+ href="#roots">meta-data with stack objects</a> (used for tagless garbage
+ collection). All LLVM code generators support garbage collection, including the
+ C backend.
+ </p>
+
+ <p>
+ We hope that the primitive support built into LLVM is sufficient to support a
+ broad class of garbage collected languages, including Scheme, ML, scripting
+ languages, Java, C#, etc. That said, the implemented garbage collectors may
+ need to be extended to support language-specific features such as finalization,
+ weak references, or other features. As these needs are identified and
+ implemented, they should be added to this specification.
+ </p>
+
+ <p>
+ LLVM does not currently support garbage collection of multi-threaded programs or
+ GC-safe points other than function calls, but these will be added in the future
+ as there is interest.
+ </p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="interfaces">Interfaces for user programs</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This section describes the interfaces provided by LLVM and by the garbage
+ collector run-time that should be used by user programs. As such, this is the
+ interface that front-end authors should generate code for.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="roots">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <div class="doc_code"><tt>
+ void %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata)
+ </tt></div>
+
+ <p>
+ The <tt>llvm.gcroot</tt> intrinsic is used to inform LLVM of a pointer variable
+ on the stack. The first argument contains the address of the variable on the
+ stack, and the second contains a pointer to metadata that should be associated
+ with the pointer (which <b>must</b> be a constant or global value address). At
+ runtime, the <tt>llvm.gcroot</tt> intrinsic stores a null pointer into the
+ specified location to initialize the pointer.</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*
+ ...
+
+ ;; "CodeBlock" is the block corresponding to the start
+ ;; of the scope above.
+ CodeBlock:
+ ;; Initialize the object, telling LLVM that it is now live.
+ ;; Java has type-tags on objects, so it doesn't need any
+ ;; metadata.
+ call void %llvm.gcroot(%Object** %X, sbyte* null)
+ ...
+
+ ;; 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="allocate">Allocating memory from the GC</a>
+ </div>
+
+ <div class="doc_text">
+
+ <div class="doc_code"><tt>
+ sbyte *%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 appropriate size.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="barriers">Reading and writing references to the heap</a>
+ </div>
+
+ <div class="doc_text">
+
+ <div class="doc_code"><tt>
+ sbyte *%llvm.gcread(sbyte *, sbyte **)<br>
+ void %llvm.gcwrite(sbyte*, sbyte*, sbyte**)
+ </tt></div>
+
+ <p>Several of the more interesting garbage collectors (e.g., generational
+ collectors) need to be informed when the mutator (the program that needs garbage
+ collection) reads or writes object references into the heap. In the case of a
+ generational collector, it needs to keep track of which "old" generation objects
+ have references stored into them. The amount of code that typically needs to be
+ executed is usually quite small (and not on the critical path of any
+ computation), so the overall performance impact of the inserted code is
+ tolerable.</p>
+
+ <p>To support garbage collectors that use read or write barriers, LLVM provides
+ the <tt>llvm.gcread</tt> and <tt>llvm.gcwrite</tt> intrinsics. The first
+ intrinsic has exactly the same semantics as a non-volatile LLVM load and the
+ second has the same semantics as a non-volatile LLVM store, with the
+ additions that they also take a pointer to the start of the memory
+ object as an argument. At code generation
+ time, these intrinsics are replaced with calls into the garbage collector
+ (<tt><a href="#llvm_gc_readwrite">llvm_gc_read</a></tt> and <tt><a
+ href="#llvm_gc_readwrite">llvm_gc_write</a></tt> respectively), which are then
+ inlined into the code.
+ </p>
+
+ <p>
+ If you are writing a front-end for a garbage collected language, every load or
+ store of a reference from or to the heap should use these intrinsics instead of
+ normal LLVM loads/stores.</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 spaces. The initial heap size
+ to allocate should be specified as an argument.
+ </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_section">
+ <a name="gcimpl">Implementing a garbage collector</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>
+ Implementing a garbage collector for LLVM is fairly straight-forward. 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, and it must implement
+ the <a href="#llvm_gc_readwrite">read/write barrier</a> functions as well. 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="#gcimpls">example
+ implementations</a> available.
+ </p>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="llvm_gc_readwrite">Implementing <tt>llvm_gc_read</tt> and <tt>llvm_gc_write</tt></a>
+ </div>
+
+ <div class="doc_text">
+ <div class="doc_code"><tt>
+ void *llvm_gc_read(void*, void **)<br>
+ void llvm_gc_write(void*, void *, void**)
+ </tt></div>
+
+ <p>
+ These functions <i>must</i> be implemented in every garbage collector, even if
+ they do not need read/write barriers. In this case, just load or store the
+ pointer, then return.
+ </p>
+
+ <p>
+ If an actual read or write barrier is needed, it should be straight-forward to
+ implement it.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="callbacks">Callback functions used to implement the garbage collector</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ Garbage collector implementations make use of call-back functions that are
+ implemented by other parts of the LLVM system.
+ </p>
+ </div>
+
+ <!--_________________________________________________________________________-->
+ <div class="doc_subsubsection">
+ <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_subsubsection">
+ <a name="staticroots">Tracing GC pointers from static roots</a>
+ </div>
+
+ <div class="doc_text">
+ TODO
+ </div>
+
+
+ <!--_________________________________________________________________________-->
+ <div class="doc_subsubsection">
+ <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="#roots">stack roots</a>, and the heap tracing routines can propagate the
+ information. In addition, LLVM allows the front-end to extract GC information
+ from in any form from a specific object pointer (this supports situations #1 and
+ #3).
+ </p>
+
+ <p><b>Making this efficient</b></p>
+
+
+
+ </div>
+
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="gcimpls">GC implementations available</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>
+ To make this more concrete, the currently implemented LLVM garbage collectors
+ all live in the <tt>llvm/runtime/GC/*</tt> directories in the LLVM source-base.
+ If you are interested in implementing an algorithm, there are many interesting
+ possibilities (mark/sweep, a generational collector, a reference counting
+ collector, etc), or you could choose to improve one of the existing algorithms.
+ </p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="semispace">SemiSpace - A simple copying garbage collector</a>
+ </div>
+
+ <div class="doc_text">
+ <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>
+
+ </div>
+
+ <!--_________________________________________________________________________-->
+ <div class="doc_subsubsection">
+ Possible Improvements
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ If a collection cycle happens and the heap is not compacted very much (say less
+ than 25% of the allocated memory was freed), the memory regions should be
+ doubled in size.</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>
+
+ </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.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:21 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/GettingStarted.html
diff -c /dev/null llvm-www/releases/1.5/docs/GettingStarted.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/GettingStarted.html Wed May 18 09:33:21 2005
***************
*** 0 ****
--- 1,1540 ----
+ <!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><a href="#software">Software</a>
+ <li><a href="#brokengcc">Broken versions of GCC</a>
+ </ol></li>
+
+ <li><a href="#starting">Getting Started with LLVM</a>
+ <ol>
+ <li><a href="#terminology">Terminology and Notation</a>
+ <li><a href="#environment">Setting Up Your Environment</a>
+ <li><a href="#unpack">Unpacking the LLVM Archives</a>
+ <li><a href="#checkout">Checkout LLVM from CVS</a>
+ <li><a href="#installcf">Install the GCC Front End</a>
+ <li><a href="#config">Local LLVM Configuration</a>
+ <li><a href="#compile">Compiling the LLVM Suite Source Code</a>
+ <li><a href="#objfiles">The Location of LLVM Object Files</a>
+ <li><a href="#optionalconfig">Optional Configuration Items</a>
+ </ol></li>
+
+ <li><a href="#layout">Program layout</a>
+ <ol>
+ <li><a href="#cvsdir"><tt>CVS</tt> directories</a>
+ <li><a href="#examples"><tt>llvm/examples</tt></a>
+ <li><a href="#include"><tt>llvm/include</tt></a>
+ <li><a href="#lib"><tt>llvm/lib</tt></a>
+ <li><a href="#projects"><tt>llvm/projects</tt></a>
+ <li><a href="#runtime"><tt>llvm/runtime</tt></a>
+ <li><a href="#test"><tt>llvm/test</tt></a>
+ <li><a href="#llvmtest"><tt>llvm-test</tt></a>
+ <li><a href="#tools"><tt>llvm/tools</tt></a>
+ <li><a href="#utils"><tt>llvm/utils</tt></a>
+ <li><a href="#win32"><tt>llvm/win32</tt></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: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, bytecode
+ analyzer, and bytecode 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 bytecode. Currently, the GCC front
+ end is a modified version of GCC 3.4 (we track the GCC 3.4 development). Once
+ compiled into LLVM bytecode, 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 GCC 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 cfrontend.<i>platform</i>.tar.gz | tar -xvf -</tt>
+ </li>
+ <li><tt>cd cfrontend/<i>platform</i><br>
+ ./fixheaders</tt></li>
+ <li>Add the cfrontend'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">CVS</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">CVS</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)" 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">
+ <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>Cygwin/Win32</td>
+ <td>x86<sup><a href="#pf_1">1</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></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>
+ <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 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.</li>
+ <li><a name="pf_7">Native code generation exists but is not complete.</a></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 (because of all the debug info), and the libraries
+ appear in more than one of the tools that get linked, so there is some
+ duplication. 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 bytecode. 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="CFEBuildInstrs.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>
+ <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/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.35</td>
+ <td>YACC compiler</td>
+ </tr>
+
+ <tr>
+ <td><a href="https://www.cvshome.org/downloads.html">CVS</a></td>
+ <td>≥1.11</td>
+ <td>CVS 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="sf3">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 CVS if you intend to build from the
+ latest LLVM sources. If you're working from a release distribution, you
+ don't need CVS.</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>etags</b> - C/C++ tag file creator for vim/emacs</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</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 and GCC 3.4.0 and have had success
+ with them (however, see 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</b>: This version of GCC fails to compile LLVM.</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="CFEBuildInstrs.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>IA-64 GCC 4.0.0</b>: The IA-64 version of GCC 4.0.0 is known to
+ miscompile LLVM.</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.
+ <p>
+
+ <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).
+ <p>
+
+ <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>cfrontend/<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/bytecode/libs</tt></dt>
+ <dd>[Optional] This environment variable helps LLVM linking tools find the
+ locations of your bytecode libraries. It is provided only a
+ convenience since you can specify the paths using the -L options of the
+ tools and the C/C++ front-end will use the bytecode 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>cfrontend-x.y.source.tar.gz</tt></dt>
+ <dd>Source release of the GCC front end.<br/></dd>
+
+ <dt><tt>cfrontend-x.y.sparc-sun-solaris2.8.tar.gz</tt></dt>
+ <dd>Binary release of the GCC front end for Solaris/Sparc.
+ <br/></dd>
+
+ <dt><tt>cfrontend-x.y.i686-redhat-linux-gnu.tar.gz</tt></dt>
+ <dd>Binary release of the GCC front end for Linux/x86.<br/></dd>
+
+ <dt><tt>cfrontend-x.y.i386-unknown-freebsd5.1.tar.gz</tt></dt>
+ <dd>Binary release of the GCC front end for FreeBSD/x86.<br/></dd>
+
+ <dt><tt>cfrontend-x.y.powerpc-apple-darwin7.6.0.tar.gz</tt></dt>
+ <dd>Binary release of the GCC front end for MacOS X/PPC.<br/></dd>
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="checkout">Checkout LLVM from CVS</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If you have access to our CVS repository, you can get a fresh copy of
+ the entire source code. All you need to do is check it out from CVS as
+ follows:</p>
+
+ <ul>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
+ <li><tt>cvs -d :pserver:anon at llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt>
+ <li>Hit the return key when prompted for the password.
+ <li><tt>cvs -z3 -d :pserver:anon at llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co
+ llvm</tt>
+ </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 specify a label. The following releases have the following
+ labels:</p>
+
+ <ul>
+ <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 CVS repository:</p>
+ <pre>
+ cd llvm/projects
+ cvs -z3 -d :pserver:anon at llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co llvm-test
+ </pre>
+ <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>cvs update</tt>.</p>
+
+ <p>If you would like to get the GCC front end source code, you can also get it
+ from the CVS repository:</p>
+
+ <pre>
+ cvs -z3 -d :pserver:anon at llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co llvm-gcc
+ </pre>
+
+ <p>Please note that you must follow <a href="CFEBuildInstrs.html">these
+ instructions</a> to successfully build the LLVM GCC front-end.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection">
+ <a name="mirrors">LLVM CVS Mirrors</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If the main CVS server is overloaded or inaccessible, you can try one of
+ these user-hosted mirrors:</p>
+
+ <ul>
+ <li><a href="http://llvm.x10sys.com/">Mirror hosted by eXtensible Systems
+ Inc.</a></li>
+ </ul>
+ </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 need to extract the LLVM
+ GCC front end from the binary distribution. It is used for building the
+ bytecode libraries later used by the GCC front end for linking programs, and its
+ location must be specified when the LLVM suite is configured.</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 cfrontend-<i>version</i>.<i>platform</i>.tar.gz | tar -xvf
+ -</tt></li>
+ </ol>
+
+ <p>Next, you will need to fix your system header files:</p>
+
+ <p><tt>cd cfrontend/<i>platform</i><br>
+ ./fixheaders</tt></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="CFEBuildInstrs.html">building the GCC front end from source.</a> This is
+ not for the faint of heart, so be forewarned.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="config">Local LLVM Configuration</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Once checked out from the CVS 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>
+ <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="CFEBuildInstrs.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 the <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 tcl 8.4 and 8.3 releases.
+ <p></p>
+ </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).
+ <p></p>
+ </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.
+ <p></p>
+ </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 is of targets is: <br/>
+ <tt>alpha, ia64, powerpc, skeleton, sparc, x86</tt>.
+ <p></p></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>
+ </dl>
+
+ <p>To configure LLVM, follow these steps:</p>
+
+ <ol>
+ <li>Change directory into the object root directory:
+ <br>
+ <tt>cd <i>OBJ_ROOT</i></tt>
+ <p>
+
+ <li>Run the <tt>configure</tt> script located in the LLVM source tree:
+ <br>
+ <tt><i>SRC_ROOT</i>/configure --prefix=/install/path [other options]</tt>
+ <p>
+ </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.
+ <p>
+
+ <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.
+ <p>
+
+ <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>
+
+ <p><tt>gmake</tt></p>
+
+ <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>
+
+ <p><tt>gmake -j2</tt></p>
+
+ <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.
+ <p>
+
+ <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.
+ <p>
+
+ <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>.
+ <p>
+
+ <dt><tt>gmake -C runtime install-bytecode</tt>
+ <dd>
+ Assuming you built LLVM into $OBJDIR, when this command is run, it will
+ install bytecode libraries into the GCC front end's bytecode library
+ directory. If you need to update your bytecode libraries,
+ this is the target to use once you've built them.
+ <p>
+ </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.
+ <p>
+
+ <dt><tt>gmake ENABLE_PROFILING=1</tt>
+ <dd>
+ Perform a Profiling build.
+ <p>
+
+ <dt><tt>gmake VERBOSE=1</tt>
+ <dd>
+ Print what <tt>gmake</tt> is doing on standard output.
+ <p>
+
+ <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>.
+ <p></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="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>
+
+ <p><tt>cd <i>OBJ_ROOT</i></tt></p></li>
+
+ <li><p>Run the <tt>configure</tt> script found in the LLVM source
+ directory:</p>
+
+ <p><tt><i>SRC_ROOT</i>/configure</tt></p></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>
+ <p>
+
+ <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>
+ <p>
+
+ <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 bytecode 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 bytecode 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.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>.
+ The following is a brief introduction to code layout:</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="cvsdir"><tt>CVS</tt> directories</a></div>
+ <div class="doc_text">
+ <p>Every directory checked out of CVS will contain a <tt>CVS</tt> directory; for
+ the most part these can just be ignored.</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/ByteCode/</b></tt></dt>
+ <dd>This directory holds code for reading and write LLVM bytecode.</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/SparcV9</tt>
+ directory holds the Sparc 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 bytecode 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 bytecode 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>llvm-test</tt></a></div>
+ <div class="doc_text">
+ <p>This is not a directory in the normal llvm module; it is a separate CVS
+ module that must be checked out (usually to <tt>projects/llvm-test</tt>). This
+ module contains a comprehensive correctness, performance, and benchmarking
+ test
+ suite for LLVM. It is a separate CVS 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>analyze</b></tt></dt>
+ <dd><tt>analyze</tt> is used to run a specific
+ analysis on an input LLVM bytecode file and print out the results. It is
+ primarily useful for debugging analyses, or familiarizing yourself with
+ what an analysis does.</dd>
+
+ <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 bytecode. This reduces the need to get the
+ traditional <tt>-l<name></tt> options right on the command line. Please
+ note that this tool is new in 1.4 and considered experimental. It will be
+ fully supported in 1.5.</dd>
+
+ <dt><tt><b>llvm-ar</b></tt></dt>
+ <dd>The archiver produces an archive containing
+ the given LLVM bytecode 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
+ bytecode.</dd>
+
+ <dt><tt><b>llvm-dis</b></tt></dt>
+ <dd>The disassembler transforms the LLVM bytecode to human readable
+ LLVM assembly.</dd>
+
+ <dt><tt><b>llvm-ld</b></tt></dt>
+ <dd><tt>llvm-ld</tt> is very similar to gccld and provides a general purpose
+ and extensible linker for LLVM. This is the linker invoked by <tt>llvmc</tt>.
+ It allows optimization modules to be loaded so that language specific
+ optimizations can be applied at link time. Please note that this tool is new
+ in LLVM 1.4 and still considered experimental. It will be fully supported in
+ LLVM 1.5.</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 bytecode (although very slowly...). In addition
+ to a simple interpreter, <tt>lli</tt> also has a tracing mode (entered by
+ specifying <tt>-trace</tt> on the command line). Finally, 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 bytecode to a SPARC or x86 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 emit LLVM code as the 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. The source code for the
+ <tt>llvm-gcc</tt> tool is currently not included in the LLVM CVS tree
+ because it is quite large and not very interesting.
+ <blockquote>
+ <dl>
+ <dt><tt><b>gccas</b></tt></dt>
+ <dd>This tool is invoked by the <tt>llvm-gcc</tt> frontend as the
+ "assembler" part of the compiler. This tool actually assembles LLVM
+ assembly to LLVM bytecode, performs a variety of optimizations, and
+ outputs LLVM bytecode. Thus when you invoke
+ <tt>llvm-gcc -c x.c -o x.o</tt>, you are causing <tt>gccas</tt> to be
+ run, which writes the <tt>x.o</tt> file (which is an LLVM bytecode file
+ that can be disassembled or manipulated just like any other bytecode
+ file). The command line interface to <tt>gccas</tt> is designed to be
+ as close as possible to the <b>system</b> `<tt>as</tt>' utility so that
+ the gcc frontend itself did not have to be modified to interface to
+ a "weird" assembler.</dd>
+
+ <dt><tt><b>gccld</b></tt></dt>
+ <dd><tt>gccld</tt> links together several LLVM bytecode files into one
+ bytecode file and does some optimization. It is the linker invoked by
+ the GCC frontend when multiple .o files need to be linked together.
+ Like <tt>gccas</tt>, the command line interface of <tt>gccld</tt> is
+ designed to match the system linker, to aid interfacing with the GCC
+ frontend.</dd>
+ </dl>
+ </blockquote>
+ </dd>
+
+ <dt><tt><b>opt</b></tt></dt>
+ <dd><tt>opt</tt> reads LLVM bytecode, applies a
+ series of LLVM to LLVM transformations (which are specified on the command
+ line), and then outputs the resultant bytecode. The '<tt>opt --help</tt>'
+ command is a good way to get a list of the program transformations
+ available in LLVM.</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>Burg/</b></tt> <dd><tt>Burg</tt> is an instruction selector
+ generator -- it builds trees on which it then performs pattern-matching to
+ select instructions according to the patterns the user has specified. Burg
+ is currently used in the Sparc V9 backend.<p>
+
+ <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>.<p>
+
+ <dt><tt><b>cvsupdate</b></tt> <dd><tt>cvsupdate</tt> is a script that will
+ update your CVS tree, but produce a much cleaner and more organized output
+ than simply running <tt>`cvs -z3 up -dP'</tt> will. For example, it will group
+ together all the new and updated files and modified files in separate
+ sections, so you can see at a glance what has changed. If you are at the
+ top of your LLVM CVS tree, running <tt>utils/cvsupdate</tt> is the
+ preferred way of updating the tree.<p>
+
+ <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.<p>
+
+ <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.<p>
+
+ <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.<p>
+
+ <dt><tt><b>NightlyTest.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.cs.uiuc.edu/">LLVM homepage</a>.<p>
+
+ <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.<p>
+
+ <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.<p>
+
+ </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">
+
+ <ol>
+ <li>First, create a simple C file, name it 'hello.c':
+ <pre>
+ #include <stdio.h>
+ int main() {
+ printf("hello world\n");
+ return 0;
+ }
+ </pre></li>
+
+ <li><p>Next, compile the C file into a LLVM bytecode file:</p>
+ <p><tt>% llvm-gcc hello.c -o hello</tt></p>
+
+ <p>Note that you should have already built the tools and they have to be
+ in your path, at least <tt>gccas</tt> and <tt>gccld</tt>.</p>
+
+ <p>This will create two result files: <tt>hello</tt> and
+ <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
+ corresponds the the compiled program and the library facilities that it
+ required. <tt>hello</tt> is a simple shell script that runs the bytecode
+ file with <tt>lli</tt>, making the result directly executable. Note that
+ all LLVM optimizations are enabled by default, so there is no need for a
+ "-O3" switch.</p></li>
+
+ <li><p>Run the program. To make sure the program ran, execute one of the
+ following commands:</p>
+
+ <p><tt>% ./hello</tt></p>
+
+ <p>or</p>
+
+ <p><tt>% lli hello.bc</tt></p></li>
+
+ <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
+ code:</p>
+
+ <p><tt>% llvm-dis < hello.bc | less</tt><p></li>
+
+ <li><p>Compile the program to native assembly using the LLC code
+ generator:</p>
+
+ <p><tt>% llc hello.bc -o hello.s</tt></p>
+
+ <li><p>Assemble the native assembly language file into a program:</p>
+
+ <p><b>Solaris:</b><tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native</tt></p>
+ <p><b>Others:</b><tt>% gcc hello.s -o hello.native</tt></p>
+
+ <li><p>Execute the native code program:</p>
+
+ <p><tt>% ./hello.native</tt></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.cs.uiuc.edu/">LLVM homepage</a></li>
+ <li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
+ <li><a href="http://llvm.cs.uiuc.edu/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.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:21 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/GettingStartedVS.html
diff -c /dev/null llvm-www/releases/1.5/docs/GettingStartedVS.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/GettingStartedVS.html Wed May 18 09:33:21 2005
***************
*** 0 ****
--- 1,360 ----
+ <!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 bytecode 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>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 CVS access (or use a <a href="#mirror">mirror</a>):
+ <ol>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
+ <li><tt>cvs -d
+ :pserver:anon at llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt></li>
+ <li>Hit the return key when prompted for the password.
+ <li><tt>cvs -z3 -d :pserver:anon at llvm-cvs.cs.uiuc.edu:/var/cvs/llvm
+ co llvm</tt></li>
+ <li><tt>cd llvm</tt></li>
+ <li><tt>cvs up -P -d</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 CVS. Much
+ progress has been made since the 1.4 release.</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>You will also need several open source packages: bison, flex, and sed.
+ These must be installed in <tt>llvm/win32/tools</tt>. These can be found at
+ <a href="http://gnuwin32.sourceforge.net">http://gnuwin32.sourceforge.net</a>
+ or
+ <a href="http://unxutils.sourceforge.net">http://unxutils.sourceforge.net</a>.
+ Bison prefers that m4 be in the path. You must add it to the Visual Studio
+ configuration under the menu Options -> Projects -> VC++ Directories.
+ Alternatively, you can set the environment variable <tt>M4</tt> to point to
+ <tt>m4</tt> executable.</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
+ <dd>
+ This is the top level directory of the LLVM source tree.
+ <p>
+
+ <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
+ is fixed at SRC_ROOT/win32).
+ <p>
+ </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>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>.
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="tutorial">An Example Using the LLVM Tool Chain</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <ol>
+ <li>First, create a simple C file, name it 'hello.c':
+ <pre>
+ #include <stdio.h>
+ int main() {
+ printf("hello world\n");
+ return 0;
+ }
+ </pre></li>
+
+ <li><p>Next, compile the C file into a LLVM bytecode file:</p>
+ <p><tt>% llvm-gcc hello.c -o hello</tt></p>
+
+ <p>Note that you should have already built the tools and they have to be
+ in your path, at least <tt>gccas</tt> and <tt>gccld</tt>.</p>
+
+ <p>This will create two result files: <tt>hello</tt> and
+ <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
+ corresponds the the compiled program and the library facilities that it
+ required. <tt>hello</tt> is a simple shell script that runs the bytecode
+ file with <tt>lli</tt>, making the result directly executable. Note that
+ all LLVM optimizations are enabled by default, so there is no need for a
+ "-O3" switch.</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.</b></p></li>
+
+ <li><p>Run the program. To make sure the program ran, execute the
+ following command:</p>
+
+ <p><tt>% lli hello.bc</tt></p></li>
+
+ <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
+ code:</p>
+
+ <p><tt>% llvm-dis < hello.bc | less</tt><p></li>
+
+ <li><p>Compile the program to native assembly using the LLC code
+ generator:</p>
+
+ <p><tt>% llc hello.bc -o hello.s</tt></p>
+
+ <li><p>Assemble the native assembly language file into a program:</p>
+
+ <p><b>Not currently possible, but eventually will use <tt>NASMW</tt>.</b></p>
+
+ <li><p>Execute the native code program:</p>
+
+ <p><tt>% ./hello.native</tt></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.cs.uiuc.edu/">LLVM homepage</a></li>
+ <li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
+ <li><a href="http://llvm.cs.uiuc.edu/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.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:21 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/HowToSubmitABug.html
diff -c /dev/null llvm-www/releases/1.5/docs/HowToSubmitABug.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/HowToSubmitABug.html Wed May 18 09:33:21 2005
***************
*** 0 ****
--- 1,356 ----
+ <!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="#gccas">GCCAS bugs</a>
+ <li><a href="#gccld">GCCLD bugs</a>
+ <li><a href="#passes">Bugs in LLVM passes</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. 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.cs.uiuc.edu/bugs/enter_bug.cgi">the LLVM Bug Tracking
+ System</a>, select the category in which the bug falls, and fill out the form
+ with the necessary details. 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 CVS
+ 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. If you are running <tt><b>opt</b></tt> or
+ <tt><b>analyze</b></tt> directly, and something crashes, jump to the section on
+ <a href="#passes">bugs in LLVM passes</a>. Otherwise, the most important
+ piece of the puzzle is to figure out if it is the GCC-based front-end that is
+ buggy or if it's one of the LLVM tools that has problems.</p>
+
+ <p>To figure out which program is crashing (the front-end,
+ <tt><b>gccas</b></tt>, or <tt><b>gccld</b></tt>), run the
+ <tt><b>llvm-gcc</b></tt> command line as you were when the crash occurred, but
+ add a <tt>-v</tt> option to the command line. The compiler will print out a
+ bunch of stuff, and should end with telling you that one of
+ <tt><b>cc1</b>/<b>cc1plus</b></tt>, <tt><b>gccas</b></tt>, or
+ <tt><b>gccld</b></tt> crashed.</p>
+
+ <ul>
+
+ <li>If <tt><b>cc1</b></tt> or <tt><b>cc1plus</b></tt> crashed, you found a
+ problem with the front-end.
+ Jump ahead to the section on <a href="#front-end">front-end bugs</a>.</li>
+
+ <li>If <tt><b>gccas</b></tt> crashed, you found a bug in <a href="#gccas">one
+ of the passes in <tt><b>gccas</b></tt></a>.</li>
+
+ <li>If <tt><b>gccld</b></tt> crashed, you found a bug in <a href="#gccld">one
+ of the passes in <tt><b>gccld</b></tt></a>.</li>
+
+ <li>Otherwise, something really weird happened. Email the list with what you
+ have at this point.</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> (containing LLVM assembly code), for each
+ compiled <tt><i>foo</i>.c</tt> file. Send us the <tt><i>foo</i>.i</tt> file,
+ along with a brief description of the error it caused.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="gccas">GCCAS bugs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If you find that a bug crashes in the <tt><b>gccas</b></tt> stage of
+ compilation, compile your test-case to a <tt>.s</tt> file with the
+ <tt>-save-temps</tt> option to <tt><b>llvm-gcc</b></tt>. Then run:</p>
+
+ <div class="doc_code">
+ <p><tt><b>gccas</b> -debug-pass=Arguments < /dev/null -o - > /dev/null</tt></p>
+ </div>
+
+ <p>... which will print a list of arguments, indicating the list of passes that
+ <tt><b>gccas</b></tt> runs. Once you have the input file and the list of
+ passes, go to the section on <a href="#passes">debugging bugs in LLVM
+ passes</a>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="gccld">GCCLD bugs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If you find that a bug crashes in the <tt><b>gccld</b></tt> stage of
+ compilation, gather all of the <tt>.o</tt> bytecode files and libraries that are
+ being linked together (the "<tt><b>llvm-gcc</b> -v</tt>" output should include
+ the full list of objects linked). Then run:</p>
+
+ <div class="doc_code">
+ <p><tt><b>llvm-as</b> < /dev/null > null.bc<br>
+ <b>gccld</b> -debug-pass=Arguments null.bc</tt>
+ </p>
+ </div>
+
+ <p>... which will print a list of arguments, indicating the list of passes that
+ <tt><b>gccld</b></tt> runs. Once you have the input files and the list of
+ passes, go to the section on <a href="#passes">debugging bugs in LLVM
+ passes</a>.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="passes">Bugs in LLVM passes</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>At this point, you should have some number of LLVM assembly files or bytecode
+ files and a list of passes which crash when run on the specified input. In
+ order to reduce the list of passes (which is probably large) and the input to
+ something tractable, use the <tt><b>bugpoint</b></tt> tool as follows:</p>
+
+ <div class="doc_code">
+ <p><tt><b>bugpoint</b> <input files> <list of passes></tt></p>
+ </div>
+
+ <p><tt><b>bugpoint</b></tt> will print a bunch of output as it reduces the
+ test-case, but it should eventually print something like this:</p>
+
+ <div class="doc_code">
+ <p><tt>
+ ...<br>
+ Emitted bytecode to 'bugpoint-reduced-simplified.bc'<br>
+ <br>
+ *** You can reproduce the problem with: opt bugpoint-reduced-simplified.bc -licm<br>
+ </tt></p>
+ </div>
+
+ <p>Once you complete this, please send the LLVM bytecode file and the command
+ line to reproduce the problem to the llvmbugs mailing list.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="miscompilations">Miscompilations</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>A miscompilation occurs when a pass does not correctly transform a program,
+ thus producing errors that are only noticed during execution. This is different
+ from producing invalid LLVM code (i.e., code not in SSA form, using values
+ before defining them, etc.) which the verifier will check for after a pass
+ finishes its run.</p>
+
+ <p>If it looks like the LLVM compiler is miscompiling a program, the very first
+ thing to check is to make sure it is not using undefined behavior. In
+ particular, check to see if the program <a
+ href="http://valgrind.kde.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 bytecode 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] [bytecode 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] [bytecode 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 bytecode 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 bytecode 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 bytecode 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
+ bytecode:</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.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
+ <br>
+ Last modified: $Date: 2005/05/18 14:33:21 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/LLVMVsTheWorld.html
diff -c /dev/null llvm-www/releases/1.5/docs/LLVMVsTheWorld.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/LLVMVsTheWorld.html Wed May 18 09:33:21 2005
***************
*** 0 ****
--- 1,180 ----
+ <!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>LLVM vs. the World - Comparing Compilers to Compilers</title>
+ </head>
+
+ <body>
+
+ <div class="doc_title">
+ LLVM vs. the World - Comparing Compilers to Compilers
+ </div>
+
+ <ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#generalapplicability">General Applicability</a></li>
+ <li><a href="#typesystem">Type System</a></li>
+ <li><a href="#dataflowinformation">Control-flow and Data-flow Information</a></li>
+ <li><a href="#registers">Registers</a></li>
+ <li><a href="#programmerinterface">Programmer Interface</a></li>
+ <li><a href="#codeemission">Machine Code Emission</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by Brian R. Gaeke</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>Whether you are a stranger to LLVM or not, and whether you are considering
+ using it for your projects or not, you may find it useful to understand how we
+ compare ourselves to other well-known compilers. The following list of points
+ should help you understand -- from our point of view -- some of the important
+ ways in which we see LLVM as different from other selected compilers and
+ code generation systems.</p>
+
+ <p>At the moment, we only compare ourselves below to <a
+ href="http://gcc.gnu.org/">GCC</a> and <a
+ href="http://www.gnu.org/software/lightning/">GNU lightning</a>, but we will try
+ to revise and expand it as our knowledge and experience permit. Contributions are
+ welcome.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="generalapplicability">General Applicability</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>GNU lightning: Only currently usable for dynamic runtime emission of binary
+ machine code to memory. Supports one backend at a time.</p>
+
+ <p>LLVM: Supports compilation of C and C++ (with more languages coming soon),
+ strong SSA-based optimization at compile-time, link-time, run-time, and
+ off-line, and multiple platform backends with Just-in-Time and ahead-of-time
+ compilation frameworks. (See our document on <a
+ href="http://llvm.cs.uiuc.edu/pubs/2004-01-30-CGO-LLVM.html">Lifelong
+ Code Optimization</a> for more.)</p>
+
+ <p>GCC: Many relatively mature platform backends support assembly-language code
+ generation from many source languages. No run-time compilation
+ support.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="typesystem">Type System</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>GNU lightning: C integer types and "void *" are supported. No type checking
+ is performed. Explicit type casts are not typically necessary unless the
+ underlying machine-specific types are distinct (e.g., sign- or zero-extension is
+ apparently necessary, but casting "int" to "void *" would not be.)
+ Floating-point support may not work on all platforms (it does not appear to be
+ documented in the latest release).</p>
+
+ <p>LLVM: Compositional type system based on C types, supporting structures,
+ opaque types, and C integer and floating point types. Explicit cast instructions
+ are required to transform a value from one type to another.</p>
+
+ <p>GCC: Union of high-level types including those used in Pascal, C, C++, Ada,
+ Java, and FORTRAN.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="dataflowinformation">Control-flow and Data-flow Information</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>GNU lightning: No data-flow information encoded in the generated program. No
+ support for calculating CFG or def-use chains over generated programs.</p>
+
+ <p>LLVM: Scalar values in Static Single-Assignment form; def-use chains and CFG
+ always implicitly available and automatically kept up to date.</p>
+
+ <p>GCC: Trees and RTL do not directly encode data-flow info; but def-use chains
+ and CFGs can be calculated on the side. They are not automatically kept up to
+ date.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="registers">Registers</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>GNU lightning: Very small fixed register set -- it takes the least common
+ denominator of supported platforms; basically it inherits its tiny register set
+ from IA-32, unnecessarily crippling targets like PowerPC with a large register
+ set.</p>
+
+ <p>LLVM: An infinite register set, reduced to a particular platform's finite
+ register set by register allocator.</p>
+
+ <p>GCC: Trees and RTL provide an arbitrarily large set of values. Reduced to a
+ particular platform's finite register set by register allocator.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="programmerinterface">Programmer Interface</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>GNU lightning: Library interface based on C preprocessor macros that emit
+ binary code for a particular instruction to memory. No support for manipulating
+ code before emission.</p>
+
+ <p>LLVM: Library interface based on classes representing platform-independent
+ intermediate code (Instruction) and platform-dependent code (MachineInstr) which
+ can be manipulated arbitrarily and then emitted to memory.</p>
+
+ <p>GCC: Internal header file interface (tree.h) to abstract syntax trees,
+ representing roughly the union of all possible supported source-language
+ constructs; also, an internal header file interface (rtl.h, rtl.def) to a
+ low-level IR called RTL which represents roughly the union of all possible
+ target machine instructions.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="codeemission">Machine Code Emission</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>GNU lightning: Only supports binary machine code emission to memory.</p>
+
+ <p>LLVM: Supports writing out assembly language to a file, and binary machine
+ code to memory, from the same back-end.</p>
+
+ <p>GCC: Supports writing out assembly language to a file. No support for
+ emitting machine code to memory.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+
+ <hr>
+ <div class="doc_footer">
+ <address>Brian R. Gaeke</address>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
+ <br>
+ Last modified: $Date: 2005/05/18 14:33:21 $
+ </div>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/LangRef.html
diff -c /dev/null llvm-www/releases/1.5/docs/LangRef.html:1.1
*** /dev/null Wed May 18 09:34:35 2005
--- llvm-www/releases/1.5/docs/LangRef.html Wed May 18 09:33:21 2005
***************
*** 0 ****
--- 1,3311 ----
+ <!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">Function Structure</a></li>
+ </ol>
+ </li>
+ <li><a href="#typesystem">Type System</a>
+ <ol>
+ <li><a href="#t_primitive">Primitive Types</a>
+ <ol>
+ <li><a href="#t_classifications">Type Classifications</a></li>
+ </ol>
+ </li>
+ <li><a href="#t_derived">Derived Types</a>
+ <ol>
+ <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_packed">Packed 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="#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_div">'<tt>div</tt>' Instruction</a></li>
+ <li><a href="#i_rem">'<tt>rem</tt>' Instruction</a></li>
+ <li><a href="#i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a></li>
+ </ol>
+ </li>
+ <li><a href="#bitwiseops">Bitwise Binary Operations</a>
+ <ol>
+ <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>
+ <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
+ <li><a href="#i_shr">'<tt>shr</tt>' Instruction</a></li>
+ </ol>
+ </li>
+ <li><a href="#memoryops">Memory Access 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="#otherops">Other Operations</a>
+ <ol>
+ <li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li>
+ <li><a href="#i_cast">'<tt>cast .. to</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_vanext">'<tt>vanext</tt>' Instruction</a></li>
+ <li><a href="#i_vaarg">'<tt>vaarg</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="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
+ <li><a href="#i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a></li>
+ <li><a href="#i_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="#i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
+ <li><a href="#i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
+ <li><a href="#i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ <li><a href="#int_codegen">Code Generator Intrinsics</a>
+ <ol>
+ <li><a href="#i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
+ <li><a href="#i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li>
+ <li><a href="#i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
+ <li><a href="#i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ <li><a href="#int_os">Operating System Intrinsics</a>
+ <ol>
+ <li><a href="#i_readport">'<tt>llvm.readport</tt>' Intrinsic</a></li>
+ <li><a href="#i_writeport">'<tt>llvm.writeport</tt>' Intrinsic</a></li>
+ <li><a href="#i_readio">'<tt>llvm.readio</tt>' Intrinsic</a></li>
+ <li><a href="#i_writeio">'<tt>llvm.writeio</tt>' Intrinsic</a></li>
+ </ol>
+ <li><a href="#int_libc">Standard C Library Intrinsics</a>
+ <ol>
+ <li><a href="#i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a></li>
+ <li><a href="#i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a></li>
+ <li><a href="#i_memset">'<tt>llvm.memset</tt>' Intrinsic</a></li>
+ <li><a href="#i_isunordered">'<tt>llvm.isunordered</tt>' Intrinsic</a></li>
+ </ol>
+ </li>
+ <li><a href="#int_count">Bit counting Intrinsics</a>
+ <ol>
+ <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>
+ </ol>
+ </li>
+ <li><a href="#int_debugger">Debugger intrinsics</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="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 bytecode
+ 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>
+
+ <pre>
+ %x = <a href="#i_add">add</a> int 1, %x
+ </pre>
+
+ <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 bytecode. The violations pointed out
+ by the verifier pass indicate bugs in transformation passes or input to
+ the parser.</p>
+
+ <!-- Describe the typesetting conventions here. --> </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>LLVM uses three different forms of identifiers, for different
+ purposes:</p>
+
+ <ol>
+ <li>Named values are represented as a string of characters with a '%' 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 name.</li>
+
+ <li>Unnamed values are represented as an unsigned numeric value with a '%'
+ 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 '%' sign 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_cast">cast</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_uint">uint</a></tt>', etc...),
+ and others. These reserved words cannot conflict with variable names, because
+ none of them start with a '%' character.</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>
+
+ <pre>
+ %result = <a href="#i_mul">mul</a> uint %X, 8
+ </pre>
+
+ <p>After strength reduction:</p>
+
+ <pre>
+ %result = <a href="#i_shl">shl</a> uint %X, ubyte 3
+ </pre>
+
+ <p>And the hard way:</p>
+
+ <pre>
+ <a href="#i_add">add</a> uint %X, %X <i>; yields {uint}:%0</i>
+ <a href="#i_add">add</a> uint %0, %0 <i>; yields {uint}:%1</i>
+ %result = <a href="#i_add">add</a> uint %1, %1
+ </pre>
+
+ <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>
+
+ <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 sbyte]</a> c"hello world\0A\00" <i>; [13 x sbyte]*</i>
+
+ <i>; External declaration of the puts function</i>
+ <a href="#functionstructure">declare</a> int %puts(sbyte*) <i>; int(sbyte*)* </i>
+
+ <i>; Definition of main function</i>
+ int %main() { <i>; int()* </i>
+ <i>; Convert [13x sbyte]* to sbyte *...</i>
+ %cast210 = <a
+ href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
+
+ <i>; Call puts function to write out the string to stdout...</i>
+ <a
+ href="#i_call">call</a> int %puts(sbyte* %cast210) <i>; int</i>
+ <a
+ href="#i_ret">ret</a> int 0<br>}<br></pre>
+
+ <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, or the idea of "anonymous namespaces" in C++.
+ </dd>
+
+ <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt>
+
+ <dd>"<tt>linkonce</tt>" linkage is similar to <tt>internal</tt> linkage, with
+ the twist that linking together two modules defining the same
+ <tt>linkonce</tt> globals will cause one of the globals to be discarded. This
+ is typically used to implement inline functions. 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 to implement constructs 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_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><a name="linkage_external">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. It is illegal for a function <i>declaration</i>
+ to have any linkage type other than "externally visible".</a></p>
+
+ </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 tail call optimization 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="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. 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>
+
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="functionstructure">Functions</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM function definitions consist of an optional <a href="#linkage">linkage
+ type</a>, an optional <a href="#callingconv">calling convention</a>, a return
+ type, a function name, a (possibly empty) argument list, an opening curly brace,
+ a list of basic blocks, and a closing curly brace. LLVM function declarations
+ are defined with the "<tt>declare</tt>" keyword, an optional <a
+ href="#callingconv">calling convention</a>, a return type, a function name, and
+ a possibly empty list of arguments.</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 program 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 functions are identified by their name and type signature. Hence, two
+ functions with the same name but different parameter lists or return values are
+ considered different functions, and LLVM will resolve references to each
+ appropriately.</p>
+
+ </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_primitive">Primitive Types</a> </div>
+ <div class="doc_text">
+ <p>The primitive types are the fundamental building blocks of the LLVM
+ system. The current set of primitive types is as follows:</p>
+
+ <table class="layout">
+ <tr class="layout">
+ <td class="left">
+ <table>
+ <tbody>
+ <tr><th>Type</th><th>Description</th></tr>
+ <tr><td><tt>void</tt></td><td>No value</td></tr>
+ <tr><td><tt>ubyte</tt></td><td>Unsigned 8-bit value</td></tr>
+ <tr><td><tt>ushort</tt></td><td>Unsigned 16-bit value</td></tr>
+ <tr><td><tt>uint</tt></td><td>Unsigned 32-bit value</td></tr>
+ <tr><td><tt>ulong</tt></td><td>Unsigned 64-bit value</td></tr>
+ <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
+ <tr><td><tt>label</tt></td><td>Branch destination</td></tr>
+ </tbody>
+ </table>
+ </td>
+ <td class="right">
+ <table>
+ <tbody>
+ <tr><th>Type</th><th>Description</th></tr>
+ <tr><td><tt>bool</tt></td><td>True or False value</td></tr>
+ <tr><td><tt>sbyte</tt></td><td>Signed 8-bit value</td></tr>
+ <tr><td><tt>short</tt></td><td>Signed 16-bit value</td></tr>
+ <tr><td><tt>int</tt></td><td>Signed 32-bit value</td></tr>
+ <tr><td><tt>long</tt></td><td>Signed 64-bit value</td></tr>
+ <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
+ </tbody>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_classifications">Type
+ Classifications</a> </div>
+ <div class="doc_text">
+ <p>These different primitive 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 name="t_signed">signed</a></td>
+ <td><tt>sbyte, short, int, long, float, double</tt></td>
+ </tr>
+ <tr>
+ <td><a name="t_unsigned">unsigned</a></td>
+ <td><tt>ubyte, ushort, uint, ulong</tt></td>
+ </tr>
+ <tr>
+ <td><a name="t_integer">integer</a></td>
+ <td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td>
+ </tr>
+ <tr>
+ <td><a name="t_integral">integral</a></td>
+ <td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long</tt>
+ </td>
+ </tr>
+ <tr>
+ <td><a name="t_floating">floating point</a></td>
+ <td><tt>float, double</tt></td>
+ </tr>
+ <tr>
+ <td><a name="t_firstclass">first class</a></td>
+ <td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long,<br>
+ float, double, <a href="#t_pointer">pointer</a>,
+ <a href="#t_packed">packed</a></tt></td>
+ </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_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_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 int ]</tt><br/>
+ <tt>[41 x int ]</tt><br/>
+ <tt>[40 x uint]</tt><br/>
+ </td>
+ <td class="left">
+ Array of 40 integer values.<br/>
+ Array of 41 integer values.<br/>
+ Array of 40 unsigned integer values.<br/>
+ </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 int]]</tt><br/>
+ <tt>[12 x [10 x float]]</tt><br/>
+ <tt>[2 x [3 x [4 x uint]]]</tt><br/>
+ </td>
+ <td class="left">
+ 3x4 array of integer values.<br/>
+ 12x10 array of single precision floating point values.<br/>
+ 2x3x4 array of unsigned integer values.<br/>
+ </td>
+ </tr>
+ </table>
+ </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.
+ Function types are usually used to build virtual function tables
+ (which are structures of pointers to functions), for indirect function
+ calls, and when defining a function.</p>
+ <p>
+ The return type of a function type cannot be an aggregate type.
+ </p>
+ <h5>Syntax:</h5>
+ <pre> <returntype> (<parameter list>)<br></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.</p>
+ <h5>Examples:</h5>
+ <table class="layout">
+ <tr class="layout">
+ <td class="left">
+ <tt>int (int)</tt> <br/>
+ <tt>float (int, int *) *</tt><br/>
+ <tt>int (sbyte *, ...)</tt><br/>
+ </td>
+ <td class="left">
+ function taking an <tt>int</tt>, returning an <tt>int</tt><br/>
+ <a href="#t_pointer">Pointer</a> to a function that takes an
+ <tt>int</tt> and a <a href="#t_pointer">pointer</a> to <tt>int</tt>,
+ returning <tt>float</tt>.<br/>
+ A vararg function that takes at least one <a href="#t_pointer">pointer</a>
+ to <tt>sbyte</tt> (signed char in C), which returns an integer. This is
+ the signature for <tt>printf</tt> in LLVM.<br/>
+ </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>{ int, int, int }</tt><br/>
+ <tt>{ float, int (int) * }</tt><br/>
+ </td>
+ <td class="left">
+ a triple of three <tt>int</tt> values<br/>
+ 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>int</tt>, returning an <tt>int</tt>.<br/>
+ </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.</p>
+ <h5>Syntax:</h5>
+ <pre> <type> *<br></pre>
+ <h5>Examples:</h5>
+ <table class="layout">
+ <tr class="layout">
+ <td class="left">
+ <tt>[4x int]*</tt><br/>
+ <tt>int (int *) *</tt><br/>
+ </td>
+ <td class="left">
+ A <a href="#t_pointer">pointer</a> to <a href="#t_array">array</a> of
+ four <tt>int</tt> values<br/>
+ A <a href="#t_pointer">pointer</a> to a <a
+ href="#t_function">function</a> that takes an <tt>int*</tt>, returning an
+ <tt>int</tt>.<br/>
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="t_packed">Packed Type</a> </div>
+ <div class="doc_text">
+
+ <h5>Overview:</h5>
+
+ <p>A packed type is a simple derived type that represents a vector
+ of elements. Packed types are used when multiple primitive data
+ are operated in parallel using a single instruction (SIMD).
+ A packed type requires a size (number of
+ elements) and an underlying primitive data type. Packed 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 integral or floating point type.</p>
+
+ <h5>Examples:</h5>
+
+ <table class="layout">
+ <tr class="layout">
+ <td class="left">
+ <tt><4 x int></tt><br/>
+ <tt><8 x float></tt><br/>
+ <tt><2 x uint></tt><br/>
+ </td>
+ <td class="left">
+ Packed vector of 4 integer values.<br/>
+ Packed vector of 8 floating-point values.<br/>
+ Packed vector of 2 unsigned integer values.<br/>
+ </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 foward 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.<br/>
+ </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">bool</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 signed
+ 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). 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>{ int 4, float 17.0, int* %G }</tt>",
+ where "<tt>%G</tt>" is declared as "<tt>%G = external global int</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>[ int 42, int 11, int 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>Packed constants</b></dt>
+
+ <dd>Packed constants are represented with notation similar to packed type
+ definitions (a comma separated list of elements, surrounded by
+ less-than/greater-than's (<tt><></tt>)). For example: "<tt>< int 42,
+ int 11, int 74, int 100 ></tt>". Packed constants must have <a
+ href="#t_packed">packed 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>
+
+ <pre>
+ %X = global int 17
+ %Y = global int 42
+ %Z = global [2 x int*] [ int* %X, int* %Y ]
+ </pre>
+
+ </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>cast ( CST to TYPE )</tt></b></dt>
+
+ <dd>Cast a constant to another 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>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="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>
+ </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 a value 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 any '<a
+ href="#t_firstclass">first class</a>' type. Notice 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 a value that does 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.</p>
+ <h5>Example:</h5>
+ <pre> ret int 5 <i>; Return an integer value of 5</i>
+ ret void <i>; Return from a void function</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 bool <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>bool</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>bool</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_setcc">seteq</a> int %a, %b<br> br bool %cond, label %IfEqual, label %IfUnequal<br>IfEqual:<br> <a
+ href="#i_ret">ret</a> int 1<br>IfUnequal:<br> <a href="#i_ret">ret</a> int 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_cast">cast</a> bool %value to int
+ switch int %Val, label %truedest [int 0, label %falsedest ]
+
+ <i>; Emulate an unconditional br instruction</i>
+ switch uint 0, label %dest [ ]
+
+ <i>; Implement a jump table:</i>
+ switch uint %val, label %otherwise [ uint 0, label %onzero
+ uint 1, label %onone
+ uint 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> except 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.</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 int %Test(int 15) to label %Continue
+ except label %TestCleanup <i>; {int}:retval set</i>
+ %retval = invoke <a href="#callingconv">coldcc</a> int %Test(int 15) to label %Continue
+ except label %TestCleanup <i>; {int}: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>' intrinsic 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, 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_packed">packed</a> data type.
+ The result value of a binary operator is not
+ necessarily 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_packed">packed</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>
+ <h5>Example:</h5>
+ <pre> <result> = add int 4, %var <i>; yields {int}: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_packed">packed</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>
+ <h5>Example:</h5>
+ <pre> <result> = sub int 4, %var <i>; yields {int}:result = 4 - %var</i>
+ <result> = sub int 0, %val <i>; yields {int}: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_packed">packed</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>There is no signed vs unsigned multiplication. The appropriate
+ action is taken based on the type of the operand.</p>
+ <h5>Example:</h5>
+ <pre> <result> = mul int 4, %var <i>; yields {int}:result = 4 * %var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_div">'<tt>div</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = div <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>div</tt>' instruction returns the quotient of its two
+ operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>div</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_packed">packed</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 quotient of the
+ two operands.</p>
+ <h5>Example:</h5>
+ <pre> <result> = div int 4, %var <i>; yields {int}:result = 4 / %var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_rem">'<tt>rem</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = rem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>rem</tt>' instruction returns the remainder from the
+ division of its two operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>rem</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_packed">packed</a> versions of the values.
+ Both arguments must have identical types.</p>
+ <h5>Semantics:</h5>
+ <p>This returns the <i>remainder</i> of a division (where the result
+ has the same sign as the divisor), not the <i>modulus</i> (where the
+ result has the same sign as the dividend) 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>.</p>
+ <h5>Example:</h5>
+ <pre> <result> = rem int 4, %var <i>; yields {int}:result = 4 % %var</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_setcc">'<tt>set<i>cc</i></tt>'
+ Instructions</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = seteq <ty> <var1>, <var2> <i>; yields {bool}:result</i>
+ <result> = setne <ty> <var1>, <var2> <i>; yields {bool}:result</i>
+ <result> = setlt <ty> <var1>, <var2> <i>; yields {bool}:result</i>
+ <result> = setgt <ty> <var1>, <var2> <i>; yields {bool}:result</i>
+ <result> = setle <ty> <var1>, <var2> <i>; yields {bool}:result</i>
+ <result> = setge <ty> <var1>, <var2> <i>; yields {bool}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>set<i>cc</i></tt>' family of instructions returns a boolean
+ value based on a comparison of their two operands.</p>
+ <h5>Arguments:</h5>
+ <p>The two arguments to the '<tt>set<i>cc</i></tt>' instructions must
+ be of <a href="#t_firstclass">first class</a> type (it is not possible
+ to compare '<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>'
+ or '<tt>void</tt>' values, etc...). Both arguments must have identical
+ types.</p>
+ <h5>Semantics:</h5>
+ <p>The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
+ value if both operands are equal.<br>
+ The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
+ value if both operands are unequal.<br>
+ The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
+ value if the first operand is less than the second operand.<br>
+ The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
+ value if the first operand is greater than the second operand.<br>
+ The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
+ value if the first operand is less than or equal to the second operand.<br>
+ The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
+ value if the first operand is greater than or equal to the second
+ operand.</p>
+ <h5>Example:</h5>
+ <pre> <result> = seteq int 4, 5 <i>; yields {bool}:result = false</i>
+ <result> = setne float 4, 5 <i>; yields {bool}:result = true</i>
+ <result> = setlt uint 4, 5 <i>; yields {bool}:result = true</i>
+ <result> = setgt sbyte 4, 5 <i>; yields {bool}:result = false</i>
+ <result> = setle sbyte 4, 5 <i>; yields {bool}:result = true</i>
+ <result> = setge sbyte 4, 5 <i>; yields {bool}:result = false</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, execute an operation on them,
+ and produce a single value. The resulting value of the bitwise binary
+ operators is always the same type as its first operand.</p>
+ </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_integral">integral</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 int 4, %var <i>; yields {int}:result = 4 & %var</i>
+ <result> = and int 15, 40 <i>; yields {int}:result = 8</i>
+ <result> = and int 4, 8 <i>; yields {int}: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_integral">integral</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 int 4, %var <i>; yields {int}:result = 4 | %var</i>
+ <result> = or int 15, 40 <i>; yields {int}:result = 47</i>
+ <result> = or int 4, 8 <i>; yields {int}: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_integral">integral</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 int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
+ <result> = xor int 15, 40 <i>; yields {int}:result = 39</i>
+ <result> = xor int 4, 8 <i>; yields {int}:result = 12</i>
+ <result> = xor int %V, -1 <i>; yields {int}:result = ~%V</i>
+ </pre>
+ </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>, ubyte <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>The first argument to the '<tt>shl</tt>' instruction must be an <a
+ href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>'
+ type.</p>
+ <h5>Semantics:</h5>
+ <p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
+ <h5>Example:</h5>
+ <pre> <result> = shl int 4, ubyte %var <i>; yields {int}:result = 4 << %var</i>
+ <result> = shl int 4, ubyte 2 <i>; yields {int}:result = 16</i>
+ <result> = shl int 1, ubyte 10 <i>; yields {int}:result = 1024</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_shr">'<tt>shr</tt>'
+ Instruction</a> </div>
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> <result> = shr <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>shr</tt>' instruction returns the first operand shifted to
+ the right a specified number of bits.</p>
+ <h5>Arguments:</h5>
+ <p>The first argument to the '<tt>shr</tt>' instruction must be an <a
+ href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>'
+ type.</p>
+ <h5>Semantics:</h5>
+ <p>If the first argument is a <a href="#t_signed">signed</a> type, the
+ most significant bit is duplicated in the newly free'd bit positions.
+ If the first argument is unsigned, zero bits shall fill the empty
+ positions.</p>
+ <h5>Example:</h5>
+ <pre> <result> = shr int 4, ubyte %var <i>; yields {int}:result = 4 >> %var</i>
+ <result> = shr uint 4, ubyte 1 <i>; yields {uint}:result = 2</i>
+ <result> = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
+ <result> = shr sbyte 4, ubyte 3 <i>; yields {sbyte}:result = 0</i>
+ <result> = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
+ </pre>
+ </div>
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"> <a name="memoryops">Memory Access
+ 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>, uint <NumElements> <i>; yields {type*}:result</i>
+ <result> = malloc <type> <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.</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. The second form of the instruction is
+ a shorter version of the first instruction that defaults to allocating
+ one element.</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.</p>
+ <h5>Example:</h5>
+ <pre> %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
+
+ %size = <a
+ href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
+ %array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
+ %array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</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>
+ <p> </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.</p>
+ <h5>Example:</h5>
+ <pre> %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
+ free [4 x ubyte]* %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>, uint <NumElements> <i>; yields {type*}:result</i>
+ <result> = alloca <type> <i>; yields {type*}:result</i>
+ </pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>alloca</tt>' instruction allocates memory on the current
+ stack frame of the procedure that is live until the current function
+ returns to its caller.</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. The second form of the instruction is
+ a shorter version of the first that defaults to allocating one element.</p>
+ <p>'<tt>type</tt>' may be any sized type.</p>
+ <h5>Semantics:</h5>
+ <p>Memory is allocated; a pointer is returned. '<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.</p>
+ <h5>Example:</h5>
+ <pre> %ptr = alloca int <i>; yields {int*}:ptr</i>
+ %ptr = alloca int, uint 4 <i>; yields {int*}: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><br> <result> = volatile load <ty>* <pointer><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 to load from. 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>
+ <h5>Semantics:</h5>
+ <p>The location of memory pointed to is loaded.</p>
+ <h5>Examples:</h5>
+ <pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
+ <a
+ href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
+ %val = load int* %ptr <i>; yields {int}:val = int 3</i>
+ </pre>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
+ Instruction</a> </div>
+ <h5>Syntax:</h5>
+ <pre> store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
+ volatile store <ty> <value>, <ty>* <pointer> <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 to store it into. The type of the '<tt><pointer></tt>'
+ operand must be a pointer to the 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>
+ <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> int <i>; yields {int*}:ptr</i>
+ <a
+ href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
+ %val = load int* %ptr <i>; yields {int}:val = int 3</i>
+ </pre>
+ <!-- _______________________________________________________________________ -->
+ <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 constants 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>uint</tt>
+ integer constants are allowed. When indexing into an array or pointer,
+ <tt>int</tt> and <tt>long</tt> indexes are allowed of any sign.</p>
+
+ <p>For example, let's consider a C code fragment and how it gets
+ compiled to LLVM:</p>
+
+ <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>
+
+ <p>The LLVM code generated by the GCC frontend is:</p>
+
+ <pre>
+ %RT = type { sbyte, [10 x [20 x int]], sbyte }
+ %ST = type { int, double, %RT }
+
+ implementation
+
+ int* %foo(%ST* %s) {
+ entry:
+ %reg = getelementptr %ST* %s, int 1, uint 2, uint 1, int 5, int 13
+ ret int* %reg
+ }
+ </pre>
+
+ <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 require <tt>uint</tt>, <tt>int</tt>,
+ <tt>ulong</tt>, or <tt>long</tt> values, and <a href="#t_struct">structure</a>
+ types require <tt>uint</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>{ int, double, %RT
+ }</tt>' type, a structure. The second index indexes into the third element of
+ the structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]],
+ sbyte }</tt>' type, another structure. The third index indexes into the second
+ element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
+ array. The two dimensions of the array are subscripted into, yielding an
+ '<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction returns a pointer
+ to this element, thus computing a value of '<tt>int*</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>
+ int* %foo(%ST* %s) {
+ %t1 = getelementptr %ST* %s, int 1 <i>; yields %ST*:%t1</i>
+ %t2 = getelementptr %ST* %t1, int 0, uint 2 <i>; yields %RT*:%t2</i>
+ %t3 = getelementptr %RT* %t2, int 0, uint 1 <i>; yields [10 x [20 x int]]*:%t3</i>
+ %t4 = getelementptr [10 x [20 x int]]* %t3, int 0, int 5 <i>; yields [20 x int]*:%t4</i>
+ %t5 = getelementptr [20 x int]* %t4, int 0, int 13 <i>; yields int*:%t5</i>
+ ret int* %t5
+ }
+ </pre>
+ <h5>Example:</h5>
+ <pre>
+ <i>; yields [12 x ubyte]*:aptr</i>
+ %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, uint 1
+ </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_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 are 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 parameter, depending on which basic block we
+ came from in the last <a href="#terminators">terminator</a> instruction.</p>
+ <h5>Example:</h5>
+ <pre>Loop: ; Infinite loop that counts from 0 on up...<br> %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]<br> %nextindvar = add uint %indvar, 1<br> br label %Loop<br></pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <result> = cast <ty> <value> to <ty2> <i>; yields ty2</i>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>cast</tt>' instruction is used as the primitive means to convert
+ integers to floating point, change data type sizes, and break type safety (by
+ casting pointers).
+ </p>
+
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The '<tt>cast</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.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ This instruction follows the C rules for explicit casts when determining how the
+ data being cast must change to fit in its new container.
+ </p>
+
+ <p>
+ When casting to bool, any value that would be considered true in the context of
+ a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
+ all else are '<tt>false</tt>'.
+ </p>
+
+ <p>
+ When extending an integral value from a type of one signness to another (for
+ example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
+ <b>source</b> value is signed, and zero-extended if the source value is
+ unsigned. <tt>bool</tt> values are always zero extended into either zero or
+ one.
+ </p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %X = cast int 257 to ubyte <i>; yields ubyte:1</i>
+ %Y = cast int 123 to bool <i>; yields bool:true</i>
+ </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 bool <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 bool true, ubyte 17, ubyte 42 <i>; yields ubyte: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>* <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>': 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. This is a simpler case of
+ the <a href="#i_invoke">invoke</a> instruction.</p>
+
+ <h5>Example:</h5>
+
+ <pre>
+ %retval = call int %test(int %argc)
+ call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);
+ %X = tail call int %foo()
+ %Y = tail call <a href="#callingconv">fastcc</a> int %foo()
+ </pre>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_vanext">'<tt>vanext</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <resultarglist> = vanext <va_list> <arglist>, <argty>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>vanext</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 another <tt>va_list</tt>. The actual type of
+ <tt>va_list</tt> may be defined differently for different targets. Most targets
+ use a <tt>va_list</tt> type of <tt>sbyte*</tt> or some other pointer type.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>vanext</tt>' instruction advances the specified <tt>va_list</tt>
+ past an argument of the specified type. In conjunction with the <a
+ href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement
+ the <tt>va_arg</tt> macro available in C. 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>vanext</tt> is an LLVM instruction instead of an <a
+ href="#intrinsics">intrinsic function</a> because it takes a type as an
+ argument. The type refers to the current argument in the <tt>va_list</tt>; it
+ tells the compiler how far on the stack it needs to advance to find the next
+ 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_vaarg">'<tt>vaarg</tt>' Instruction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ <resultval> = vaarg <va_list> <arglist>, <argty>
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>The '<tt>vaarg</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. Again, the actual
+ type of <tt>va_list</tt> is target specific.</p>
+
+ <h5>Semantics:</h5>
+
+ <p>The '<tt>vaarg</tt>' instruction loads an argument of the specified type from
+ the specified <tt>va_list</tt>. In conjunction with the <a
+ href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to implement the
+ <tt>va_arg</tt> macro available in C. 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>vaarg</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_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 instructions represent an extension mechanism for
+ the LLVM language that does not require changing all of the transformations in
+ LLVM to add to the language (or the bytecode 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, functions may not be named
+ this. 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 that they all be documented here if any are added.</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_vanext"><tt>vanext</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 intrinsics with any type
+ used.</p>
+
+ <p>This example shows how the <a href="#i_vanext"><tt>vanext</tt></a>
+ instruction and the variable argument handling intrinsic functions are
+ used.</p>
+
+ <pre>
+ int %test(int %X, ...) {
+ ; Initialize variable argument processing
+ %ap = call sbyte* %<a href="#i_va_start">llvm.va_start</a>()
+
+ ; Read a single integer argument
+ %tmp = vaarg sbyte* %ap, int
+
+ ; Advance to the next argument
+ %ap2 = vanext sbyte* %ap, int
+
+ ; Demonstrate usage of llvm.va_copy and llvm.va_end
+ %aq = call sbyte* %<a href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)
+ call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %aq)
+
+ ; Stop processing of arguments.
+ call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)
+ ret int %tmp
+ }
+ </pre>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
+ </div>
+
+
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> declare <va_list> %llvm.va_start()<br></pre>
+ <h5>Overview:</h5>
+ <p>The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt><arglist></tt>
+ for subsequent use by the variable argument intrinsics.</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 and
+ returns a <tt>va_list</tt> element, so that the next <tt>vaarg</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; the compiler can figure that out.</p>
+ <p>Note that this intrinsic function is only legal to be called from
+ within the body of a variable argument function.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+ <h5>Syntax:</h5>
+ <pre> declare void %llvm.va_end(<va_list> <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="#i_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 <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>.
+ Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
+ href="#i_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="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ declare <va_list> %llvm.va_copy(<va_list> <destarglist>)
+ </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 argument is the <tt>va_list</tt> to copy.</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 returned list. This intrinsic is necessary
+ because the <tt><a href="#i_va_start">llvm.va_start</a></tt> intrinsic may be
+ arbitrarily complex and require memory allocation, for example.</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="#i_gcroot">GC roots on the
+ stack</a>, as well as garbage collector implementations that require <a
+ href="#i_gcread">read</a> and <a href="#i_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>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ declare void %llvm.gcroot(<ty>** %ptrloc, <ty2>* %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 intrinsics 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.
+ </p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ declare sbyte* %llvm.gcread(sbyte** %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 argument is the address to read from, which should be an address
+ allocated from the garbage collector.</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.</p>
+
+ </div>
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+
+ <pre>
+ declare void %llvm.gcwrite(sbyte* %P1, sbyte** %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, and the second is the heap
+ location to store to.</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.</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="i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void* %llvm.returnaddress(uint <level>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.returnaddress</tt>' intrinsic returns 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="i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void* %llvm.frameaddress(uint <level>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.frameaddress</tt>' intrinsic returns 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="i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void %llvm.prefetch(sbyte * <address>,
+ uint <rw>, uint <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="i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void %llvm.pcmarker( uint <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 guaranties that it will remain with any specific instruction
+ after optimizations. It is possible that the presense of a marker will inhibit
+ optimizations. The intended use is to be inserted after optmizations 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_subsection">
+ <a name="int_os">Operating System Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ These intrinsics are provided by LLVM to support the implementation of
+ operating system level code.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_readport">'<tt>llvm.readport</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare <integer type> %llvm.readport (<integer type> <address>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.readport</tt>' intrinsic reads data from the specified hardware
+ I/O port.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The argument to this intrinsic indicates the hardware I/O address from which
+ to read the data. The address is in the hardware I/O address namespace (as
+ opposed to being a memory location for memory mapped I/O).
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.readport</tt>' intrinsic reads data from the hardware I/O port
+ specified by <i>address</i> and returns the value. The address and return
+ value must be integers, but the size is dependent upon the platform upon which
+ the program is code generated. For example, on x86, the address must be an
+ unsigned 16-bit value, and the return value must be 8, 16, or 32 bits.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_writeport">'<tt>llvm.writeport</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ call void (<integer type>, <integer type>)*
+ %llvm.writeport (<integer type> <value>,
+ <integer type> <address>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.writeport</tt>' intrinsic writes data to the specified hardware
+ I/O port.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The first argument is the value to write to the I/O port.
+ </p>
+
+ <p>
+ The second argument indicates the hardware I/O address to which data should be
+ written. The address is in the hardware I/O address namespace (as opposed to
+ being a memory location for memory mapped I/O).
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.writeport</tt>' intrinsic writes <i>value</i> to the I/O port
+ specified by <i>address</i>. The address and value must be integers, but the
+ size is dependent upon the platform upon which the program is code generated.
+ For example, on x86, the address must be an unsigned 16-bit value, and the
+ value written must be 8, 16, or 32 bits in length.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_readio">'<tt>llvm.readio</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare <result> %llvm.readio (<ty> * <pointer>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.readio</tt>' intrinsic reads data from a memory mapped I/O
+ address.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The argument to this intrinsic is a pointer indicating the memory address from
+ which to read the data. The data must be a
+ <a href="#t_firstclass">first class</a> type.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.readio</tt>' intrinsic reads data from a memory mapped I/O
+ location specified by <i>pointer</i> and returns the value. The argument must
+ be a pointer, and the return value must be a
+ <a href="#t_firstclass">first class</a> type. However, certain architectures
+ may not support I/O on all first class types. For example, 32-bit processors
+ may only support I/O on data types that are 32 bits or less.
+ </p>
+
+ <p>
+ This intrinsic enforces an in-order memory model for llvm.readio and
+ llvm.writeio calls on machines that use dynamic scheduling. Dynamically
+ scheduled processors may execute loads and stores out of order, re-ordering at
+ run time accesses to memory mapped I/O registers. Using these intrinsics
+ ensures that accesses to memory mapped I/O registers occur in program order.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="i_writeio">'<tt>llvm.writeio</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void %llvm.writeio (<ty1> <value>, <ty2> * <pointer>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.writeio</tt>' intrinsic writes data to the specified memory
+ mapped I/O address.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The first argument is the value to write to the memory mapped I/O location.
+ The second argument is a pointer indicating the memory address to which the
+ data should be written.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.writeio</tt>' intrinsic writes <i>value</i> to the memory mapped
+ I/O address specified by <i>pointer</i>. The value must be a
+ <a href="#t_firstclass">first class</a> type. However, certain architectures
+ may not support I/O on all first class types. For example, 32-bit processors
+ may only support I/O on data types that are 32 bits or less.
+ </p>
+
+ <p>
+ This intrinsic enforces an in-order memory model for llvm.readio and
+ llvm.writeio calls on machines that use dynamic scheduling. Dynamically
+ scheduled processors may execute loads and stores out of order, re-ordering at
+ run time accesses to memory mapped I/O registers. Using these intrinsics
+ ensures that accesses to memory mapped I/O registers occur in program order.
+ </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="i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void %llvm.memcpy(sbyte* <dest>, sbyte* <src>,
+ uint <len>, uint <align>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.memcpy</tt>' intrinsic copies 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> 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, the second is a pointer to
+ the source. The third argument is an (arbitrarily sized) 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 size of the copy is a multiple of the alignment
+ and that both the source and destination pointers are aligned to that boundary.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.memcpy</tt>' intrinsic copies 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="i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void %llvm.memmove(sbyte* <dest>, sbyte* <src>,
+ uint <len>, uint <align>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.memmove</tt>' intrinsic moves 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> 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, the second is a pointer to
+ the source. The third argument is an (arbitrarily sized) 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 size of the copy is a multiple of the alignment
+ and that both the source and destination pointers are aligned to that boundary.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.memmove</tt>' intrinsic copies 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="i_memset">'<tt>llvm.memset</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare void %llvm.memset(sbyte* <dest>, ubyte <val>,
+ uint <len>, uint <align>)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.memset</tt>' intrinsic fills 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 (arbitrarily sized) 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 size of the copy is a multiple of the alignment
+ and that the destination pointer is aligned to that boundary.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ The '<tt>llvm.memset</tt>' intrinsic fills "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="i_isunordered">'<tt>llvm.isunordered</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare bool %llvm.isunordered(<float or double> Val1, <float or double> Val2)
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.isunordered</tt>' intrinsic returns true if either or both of the
+ specified floating point values is a NAN.
+ </p>
+
+ <h5>Arguments:</h5>
+
+ <p>
+ The arguments are floating point numbers of the same type.
+ </p>
+
+ <h5>Semantics:</h5>
+
+ <p>
+ If either or both of the arguments is a SNAN or QNAN, it returns true, otherwise
+ false.
+ </p>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="int_count">Bit Counting Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ LLVM provides intrinsics for a few important bit counting operations.
+ These allow efficient code generation for some algorithms.
+ </p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_ctpop">'<tt>llvm.ctpop</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare int %llvm.ctpop(int <src>)
+
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.ctpop</tt>' intrinsic counts the number of ones in a variable.
+ </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>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_ctlz">'<tt>llvm.ctlz</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare int %llvm.ctlz(int <src>)
+
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.ctlz</tt>' intrinsic counts the number of leading zeros in a
+ variable.
+ </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.ctlz</tt>' intrinsic counts the leading (most significant) zeros
+ in a variable. If the src == 0 then the result is the size in bits of the type
+ of src. For example, <tt>llvm.cttz(int 2) = 30</tt>.
+ </p>
+ </div>
+
+
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="int_cttz">'<tt>llvm.cttz</tt>' Intrinsic</a>
+ </div>
+
+ <div class="doc_text">
+
+ <h5>Syntax:</h5>
+ <pre>
+ declare int %llvm.cttz(int <src>)
+
+ </pre>
+
+ <h5>Overview:</h5>
+
+ <p>
+ The '<tt>llvm.cttz</tt>' intrinsic counts the number of trailing zeros.
+ </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.cttz</tt>' intrinsic counts the trailing (least significant) zeros
+ in a variable. If the src == 0 then the result is the size in bits of the type
+ of src. For example, <tt>llvm.cttz(2) = 1</tt>.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="int_debugger">Debugger Intrinsics</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix),
+ are described in the <a
+ href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level
+ Debugging</a> document.
+ </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.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:21 $
+ </address>
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/Lexicon.html
diff -c /dev/null llvm-www/releases/1.5/docs/Lexicon.html:1.1
*** /dev/null Wed May 18 09:34:36 2005
--- llvm-www/releases/1.5/docs/Lexicon.html Wed May 18 09:33:22 2005
***************
*** 0 ****
--- 1,172 ----
+ <!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 Lexicon</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ <meta name="author" content="Various">
+ <meta name="description"
+ content="A glossary of terms used with the LLVM project.">
+ </head>
+ <body>
+ <div class="doc_title">The LLVM Lexicon</div>
+ <p class="doc_warning">NOTE: This document is a work in progress!</p>
+ <!-- *********************************************************************** -->
+ <div class="doc_section">Table Of Contents</div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <table>
+ <tr><th colspan="8"><b>- <a href="#A">A</a> -</b></th></tr>
+ <tr>
+ <td><a href="#ADCE">ADCE</a></td>
+ </tr>
+ <tr><th colspan="8"><b>- <a href="#B">B</a> -</b></th></tr>
+ <tr>
+ <td><a href="#BURS">BURS</a></td>
+ </tr>
+ <tr><th colspan="8"><b>- <a href="#C">C</a> -</b></th></tr>
+ <tr>
+ <td><a href="#CSE">CSE</a></td>
+ </tr>
+ <tr><th colspan="8"><b>- <a href="#D">D</a> -</b></th></tr>
+ <tr>
+ <td><a href="#DSA">DSA</a></td>
+ <td><a href="#DSE">DSE</a></td>
+ </tr>
+ <tr><th colspan="8"><b>- <a href="#I">I</a> -</b></th></tr>
+ <tr>
+ <td><a href="#IPA">IPA</a></td>
+ <td><a href="#IPO">IPO</a></td>
+ </tr>
+ <tr><th colspan="8"><b>- <a href="#L">L</a> -</b></th></tr>
+ <tr>
+ <td><a href="#LICM">LICM</a></td>
+ <td><a href="#Load-VN">Load-VN</a></td>
+ </tr>
+ <tr><th colspan="8"><b>- <a href="#P">P</a> -</b></th></tr>
+ <tr>
+ <td><a href="#PRE">PRE</a></td>
+ </tr>
+ <tr><th colspan="8"><b>- <a href="#R">R</a> -</b></th></tr>
+ <tr>
+ <td><a href="#Reassociation">Reassociation</a></td>
+ </tr>
+ <tr><th colspan="8"><b>- <a href="#S">S</a> -</b></th></tr>
+ <tr>
+ <td><a href="#SCCP">SCCP</a></td>
+ <td><a href="#SSA">SSA</a></td>
+ </tr>
+ </table>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">Definitions</div>
+ <!-- *********************************************************************** -->
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="A">- A -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="ADCE"><b>ADCE</b></a></dt>
+ <dd>Aggressive Dead Code Elimination</dd>
+ </dl>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="B">- B -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="BURS"><b>BURS</b></a></dt>
+ <dd>Bottom Up Rewriting System - A method of instruction selection for
+ code generation. An example is the <a
+ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
+ </dl>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="C">- C -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="CSE"><b>CSE</b></a></dt>
+ <dd>Common Subexpression Elimination. An optimization that removes common
+ subexpression compuation. For example <tt>(a+b)*(a+b)</tt> has two
+ subexpressions that are the same: <tt>(a+b)</tt>. This optimization would
+ perform the addition only once and then perform the multiply (but only if
+ its compulationally correct/safe).
+ </dl>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="D">- D -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="DSA"><b>DSA</b></a></dt>
+ <dd>Data Structure Analysis</dd>
+ <dt><a name="DSE"><b>DSE</b></a></dt>
+ <dd>Dead Store Elimination</dd>
+ </dl>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="I">- I -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="IPA"><b>IPA</b></a></dt>
+ <dd>Inter-Procedural Analysis. Refers to any variety of code analysis that
+ occurs between procedures, functions or compilation units (modules).</dd>
+ <dt><a name="IPO"><b>IPO</b></a></dt>
+ <dd>Inter-Procedural Optimization. Refers to any variety of code
+ optimization that occurs between procedures, functions or compilation units
+ (modules).</dd>
+ </dl>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="L">- L -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="LICM"><b>LICM</b></a></dt>
+ <dd>Loop Invariant Code Motion</dd>
+ <dt><a name="Load-VN"><b>Load-VN</b></a></dt>
+ <dd>Load Value Numbering</dd>
+ </dl>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="P">- P -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="PRE"><b>PRE</b></a></dt>
+ <dd>Partial Redundancy Elimination</dd>
+ </dl>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="R">- R -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="Reassociation"><b>Reassociation</b></a></dt> <dd>Rearranging
+ associative expressions to promote better redundancy elimination and other
+ optimization. For example, changing (A+B-A) into (B+A-A), permitting it to
+ be optimized into (B+0) then (B).
+ </dl>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="S">- S -</a></div>
+ <div class="doc_text">
+ <dl>
+ <dt><a name="SCCP"><b>SCCP</b></a></dt>
+ <dd>Sparse Conditional Constant Propagation
+ <dt><a name="SSA"><b>SSA</b></a></dt>
+ <dd>Static Single Assignment</dd>
+ </dl>
+ </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 Team</a><br>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:22 $
+ </address>
+ <!-- vim: sw=2
+ -->
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/Makefile
diff -c /dev/null llvm-www/releases/1.5/docs/Makefile:1.1
*** /dev/null Wed May 18 09:34:36 2005
--- llvm-www/releases/1.5/docs/Makefile Wed May 18 09:33:22 2005
***************
*** 0 ****
--- 1,66 ----
+ ##===- docs/Makefile ---------------------------------------*- Makefile -*-===##
+ #
+ # The LLVM Compiler Infrastructure
+ #
+ # This file was developed by the LLVM research group and is distributed under
+ # the University of Illinois Open Source License. See LICENSE.TXT for details.
+ #
+ ##===----------------------------------------------------------------------===##
+
+ LEVEL := ..
+ DIRS := CommandGuide
+
+ include $(LEVEL)/Makefile.common
+
+ HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) \
+ $(wildcard $(PROJ_SRC_DIR)/*.css)
+ IMAGES := $(wildcard $(PROJ_SRC_DIR)/img/*.*)
+ DOXYFILES := doxygen.cfg.in doxygen.css doxygen.footer doxygen.header \
+ doxygen.intro
+ EXTRA_DIST := $(HTML) $(DOXYFILES) llvm.css CommandGuide img
+
+ .PHONY: install-html install-doxygen doxygen
+
+ ifeq ($(ENABLE_DOXYGEN),1)
+ install-local:: install-html install-doxygen
+ else
+ install-local:: install-html
+ endif
+
+ install-html: $(PROJ_OBJ_DIR)/html.tar.gz
+ $(Echo) Installing HTML documentation
+ $(Verb) $(MKDIR) $(PROJ_docsdir)/html
+ $(Verb) $(MKDIR) $(PROJ_docsdir)/html/img
+ $(Verb) $(DataInstall) $(HTML) $(PROJ_docsdir)/html
+ $(Verb) $(DataInstall) $(IMAGES) $(PROJ_docsdir)/html/img
+ $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/html.tar.gz $(PROJ_docsdir)
+
+ $(PROJ_OBJ_DIR)/html.tar.gz: $(HTML)
+ $(Echo) Packaging HTML documentation
+ $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar
+ $(Verb) cd $(PROJ_SRC_DIR) && \
+ $(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html
+ $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/html.tar
+
+ install-doxygen: doxygen
+ $(Echo) Installing doxygen documentation
+ $(Echo) Installing doxygen documentation
+ $(Verb) $(MKDIR) $(PROJ_docsdir)/html/doxygen
+ $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_docsdir)
+ $(Verb) cd $(PROJ_OBJ_DIR)/doxygen && \
+ $(FIND) . -type f -exec \
+ $(DataInstall) {} $(PROJ_docsdir)/html/doxygen \;
+
+ doxygen: $(PROJ_OBJ_DIR)/doxygen.tar.gz
+
+ $(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg
+ $(Echo) Building doxygen documentation
+ $(Verb) if test -e $(PROJ_OBJ_DIR)/doxygen ; then \
+ $(RM) -rf $(PROJ_OBJ_DIR)/doxygen ; \
+ fi
+ $(Verb) $(DOXYGEN) $(PROJ_OBJ_DIR)/doxygen.cfg
+ $(Echo) Packaging doxygen documentation
+ $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar
+ $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen
+ $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/doxygen.tar
+
Index: llvm-www/releases/1.5/docs/MakefileGuide.html
diff -c /dev/null llvm-www/releases/1.5/docs/MakefileGuide.html:1.1
*** /dev/null Wed May 18 09:34:36 2005
--- llvm-www/releases/1.5/docs/MakefileGuide.html Wed May 18 09:33:22 2005
***************
*** 0 ****
--- 1,1006 ----
+ <!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 Makefile Guide</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">LLVM Makefile Guide</div>
+
+ <ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#general">General Concepts</a>
+ <ol>
+ <li><a href="#projects">Projects</a></li>
+ <li><a href="#varvals">Variable Values</a></li>
+ <li><a href="#including">Including Makefiles</a>
+ <ol>
+ <li><a href="#Makefile">Makefile</a></li>
+ <li><a href="#Makefile.common">Makefile.common</a></li>
+ <li><a href="#Makefile.config">Makefile.config</a></li>
+ <li><a href="#Makefile.rules">Makefile.rules</a></li>
+ </ol>
+ </li>
+ <li><a href="#Comments">Comments</a></li>
+ </ol>
+ </li>
+ <li><a href="#tutorial">Tutorial</a>
+ <ol>
+ <li><a href="#libraries">Libraries</a>
+ <ol>
+ <li><a href="#Modules">Bytecode Modules</a></li>
+ </ol>
+ </li>
+ <li><a href="#tools">Tools</a>
+ <ol>
+ <li><a href="#JIT">JIT Tools</a></li>
+ </ol>
+ </li>
+ <li><a href="#projects">Projects</a></li>
+ </ol>
+ </li>
+ <li><a href="#targets">Targets Supported</a>
+ <ol>
+ <li><a href="#all">all</a></li>
+ <li><a href="#all-local">all-local</a></li>
+ <li><a href="#check">check</a></li>
+ <li><a href="#check-local">check-local</a></li>
+ <li><a href="#clean">clean</a></li>
+ <li><a href="#clean-local">clean-local</a></li>
+ <li><a href="#dist">dist</a></li>
+ <li><a href="#dist-check">dist-check</a></li>
+ <li><a href="#dist-clean">dist-clean</a></li>
+ <li><a href="#install">install</a></li>
+ <li><a href="#preconditions">preconditions</a></li>
+ <li><a href="#printvars">printvars</a></li>
+ <li><a href="#reconfigure">reconfigure</a></li>
+ <li><a href="#spotless">spotless</a></li>
+ <li><a href="#tags">tags</a></li>
+ <li><a href="#uninstall">uninstall</a></li>
+ </ol>
+ </li>
+ <li><a href="#variables">Using Variables</a>
+ <ol>
+ <li><a href="#setvars">Control Variables</a></li>
+ <li><a href="#overvars">Override Variables</a></li>
+ <li><a href="#getvars">Readable Variables</a></li>
+ <li><a href="#intvars">Internal Variables</a></li>
+ </ol>
+ </li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by <a href="mailto:reid at x10sys.com">Reid Spencer</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="introduction">Introduction </a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>This document provides <em>usage</em> information about the LLVM makefile
+ system. While loosely patterned after the BSD makefile system, LLVM has taken
+ a departure from BSD in order to implement additional features needed by LLVM.
+ Although makefile systems such as automake were attempted at one point, it
+ has become clear that the features needed by LLVM and the Makefile norm are
+ too great to use a more limited tool. Consequently, LLVM requires simply GNU
+ Make 3.79, a widely portable makefile processor. LLVM unabashedly makes heavy
+ use of the features of GNU Make so the dependency on GNU Make is firm. If
+ you're not familiar with <tt>make</tt>, it is recommended that you read the
+ <a href="http://www.gnu.org/software/make/manual/make.html">GNU Makefile Manual
+ </a>.</p>
+ <p>While this document is rightly part of the
+ <a href="ProgrammersManual.html">LLVM Programmer's Manual</a>, it is treated
+ separately here because of the volume of content and because it is often an
+ early source of bewilderment for new developers.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="general">General Concepts</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>The LLVM Makefile System is the component of LLVM that is responsible for
+ building the software, testing it, generating distributions, checking those
+ distributions, installing and uninstalling, etc. It consists of a several
+ files throughout the source tree. These files and other general concepts are
+ described in this section.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="projects">Projects</a></div>
+ <div class="doc_text">
+ <p>The LLVM Makefile System is quite generous. It not only builds its own
+ software, but it can build yours too. Built into the system is knowledge of
+ the <tt>llvm/projects</tt> directory. Any directory under <tt>projects</tt>
+ that has both a <tt>configure</tt> script and a <tt>Makefile</tt> is assumed
+ to be a project that uses the LLVM Makefile system. Building software that
+ uses LLVM does not require the LLVM Makefile System nor even placement in the
+ <tt>llvm/projects</tt> directory. However, doing so will allow your project
+ to get up and running quickly by utilizing the built-in features that are used
+ to compile LLVM. LLVM compiles itself using the same features of the makefile
+ system as used for projects.</p>
+ <p>For complete details on setting up your projects configuration, simply
+ mimic the <tt>llvm/projects/sample</tt> project or for further details,
+ consult the <a href="Projects.html">Projects.html</a> page.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="varvalues">Variable Values</a></div>
+ <div class="doc_text">
+ <p>To use the makefile system, you simply create a file named
+ <tt>Makefile</tt> in your directory and declare values for certain variables.
+ The variables and values that you select determine what the makefile system
+ will do. These variables enable rules and processing in the makefile system
+ that automatically Do The Right Thing™.
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="including">Including Makefiles</a></div>
+ <div class="doc_text">
+ <p>Setting variables alone is not enough. You must include into your Makefile
+ additional files that provide the rules of the LLVM Makefile system. The
+ various files involved are described in the sections that follow.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection"><a name="Makefile">Makefile</a></div>
+ <div class="doc_text">
+ <p>Each directory to participate in the build needs to have a file named
+ <tt>Makefile</tt>. This is the file first read by <tt>make</tt>. It has three
+ sections:</p>
+ <ol>
+ <li><a href="#setvars">Settable Variables</a> - Required that must be set
+ first.</li>
+ <li><a href="#Makefile.common">include <tt>$(LEVEL)/Makefile.common</tt></a>
+ - include the LLVM Makefile system.
+ <li><a href="#overvars">Override Variables</a> - Override variables set by
+ the LLVM Makefile system.
+ </ol>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection"><a name="Makefile.common">Makefile.common</a>
+ </div>
+ <div class="doc_text">
+ <p>Every project must have a <tt>Makefile.common</tt> file at its top source
+ directory. This file serves three purposes:</p>
+ <ol>
+ <li>It includes the project's configuration makefile to obtain values
+ determined by the <tt>configure</tt> script. This is done by including the
+ <a href="#Makefile.config"><tt>$(LEVEL)/Makefile.config</tt></a> file.</li>
+ <li>It specifies any other (static) values that are needed throughout the
+ project. Only values that are used in all or a large proportion of the
+ project's directories should be placed here.</li>
+ <li>It includes the standard rules for the LLVM Makefile system,
+ <a href="#Makefile.rules"><tt>$(LLVM_SRC_ROOT)/Makefile.rules</tt></a>.
+ This file is the "guts" of the LLVM Makefile system.</li>
+ </ol>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection"><a name="Makefile.config">Makefile.config</a>
+ </div>
+ <div class="doc_text">
+ <p>Every project must have a <tt>Makefile.config</tt> at the top of its
+ <em>build</em> directory. This file is <b>generated</b> by the
+ <tt>configure</tt> script from the pattern provided by the
+ <tt>Makefile.config.in</tt> file located at the top of the project's
+ <em>source</em> directory. The contents of this file depend largely on what
+ configuration items the project uses, however most projects can get what they
+ need by just relying on LLVM's configuration found in
+ <tt>$(LLVM_OBJ_ROOT)/Makefile.config</tt>.
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection"><a name="Makefile.rules">Makefile.rules</a></div>
+ <div class="doc_text">
+ <p>This file, located at <tt>$(LLVM_SRC_ROOT)/Makefile.rules</tt> is the heart
+ of the LLVM Makefile System. It provides all the logic, dependencies, and
+ rules for building the targets supported by the system. What it does largely
+ depends on the values of <tt>make</tt> <a href="#variables">variables</a> that
+ have been set <em>before</em> <tt>Makefile.rules</tt> is included.
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="Comments">Comments</a></div>
+ <div class="doc_text">
+ <p>User Makefiles need not have comments in them unless the construction is
+ unusual or it does not strictly follow the rules and patterns of the LLVM
+ makefile system. Makefile comments are invoked with the pound (#) character.
+ The # character and any text following it, to the end of the line, are ignored
+ by <tt>make</tt>.</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="tutorial">Tutorial</a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>This section provides some examples of the different kinds of modules you
+ can build with the LLVM makefile system. In general, each directory you
+ provide will build a single object although that object may be composed of
+ additionally compiled components.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="libraries">Libraries</a></div>
+ <div class="doc_text">
+ <p>Only a few variable definitions are needed to build a regular library.
+ Normally, the makefile system will build all the software into a single
+ <tt>libname.o</tt> (pre-linked) object. This means the library is not
+ searchable and that the distinction between compilation units has been
+ dissolved. Optionally, you can ask for a shared library (.so), archive library
+ (.a) or to not have the default (relinked) library built. For example:</p>
+ <pre><tt>
+ LIBRARYNAME = mylib
+ SHARED_LIBRARY = 1
+ ARCHIVE_LIBRARY = 1
+ DONT_BUILT_RELINKED = 1
+ </tt></pre>
+ <p>says to build a library named "mylib" with both a shared library
+ (<tt>mylib.so</tt>) and an archive library (<tt>mylib.a</tt>) version but
+ not to build the relinked object (<tt>mylib.o</tt>). The contents of all the
+ libraries produced will be the same, they are just constructed differently.
+ Note that you normally do not need to specify the sources involved. The LLVM
+ Makefile system will infer the source files from the contents of the source
+ directory.</p>
+ <p>The <tt>LOADABLE_MODULE=1</tt> directive can be used in conjunction with
+ <tt>SHARED_LIBRARY=1</tt> to indicate that the resulting shared library should
+ be openable with the <tt>dlopen</tt> function and searchable with the
+ <tt>dlsym</tt> function (or your operating system's equivalents). While this
+ isn't strictly necessary on Linux and a few other platforms, it is required
+ on systems like HP-UX and Darwin. You should use <tt>LOADABLE_MODULE</tt> for
+ any shared library that you intend to be loaded into an tool via the
+ <tt>-load</tt> option. See the
+ <a href="WritingAnLLVMPass.html#makefile">WritingAnLLVMPass.html</a> document
+ for an example of why you might want to do this.
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection"><a name="Modules">Bytecode Modules</a></div>
+ <div class="doc_text">
+ <p>In some situations, it is desireable to build a single bytecode module from
+ a variety of sources, instead of an archive, shared library, or bytecode
+ library. Bytecode modules can be specified in addition to any of the other
+ types of libraries by defining the <a href="#MODULE_NAME">MODULE_NAME</a>
+ variable. For example:</p>
+ <pre><tt>
+ LIBRARYNAME = mylib
+ BYTECODE_LIBRARY = 1
+ MODULE_NAME = mymod
+ </tt></pre>
+ <p>will build a module named <tt>mymod.bc</tt> from the sources in the
+ directory. This module will be an aggregation of all the bytecode modules
+ derived from the sources. The example will also build a bytecode archive
+ containing a bytecode module for each compiled source file. The difference is
+ subtle, but important depending on how the module or library is to be linked.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="tools">Tools</a></div>
+ <div class="doc_text">
+ <p>For building executable programs (tools), you must provide the name of the
+ tool and the names of the libraries you wish to link with the tool. For
+ example:</p>
+ <pre><tt>
+ TOOLNAME = mytool
+ USEDLIBS = mylib
+ LLVMLIBS = LLVMSupport.a LLVMSystem.a
+ </tt></pre>
+ <p>says that we are to build a tool name <tt>mytool</tt> and that it requires
+ three libraries: <tt>mylib</tt>, <tt>LLVMSupport.a</tt> and
+ <tt>LLVMSystem.a</tt>.</p>
+ <p>Note that two different variables are use to indicate which libraries are
+ linked: <tt>USEDLIBS</tt> and <tt>LLVMLIBS</tt>. This distinction is necessary
+ to support projects. <tt>LLVMLIBS</tt> refers to the LLVM libraries found in
+ the LLVM object directory. <tt>USEDLIBS</tt> refers to the libraries built by
+ your project. In the case of building LLVM tools, <tt>USEDLIBS</tt> and
+ <tt>LLVMLIBS</tt> can be used interchangeably since the "project" is LLVM
+ itself and <tt>USEDLIBS</tt> refers to the same place as <tt>LLVMLIBS</tt>.
+ </p>
+ <p>Also note that there are two different ways of specifying a library: with a
+ <tt>.a</tt> suffix and without. Without the suffix, the entry refers to the
+ re-linked (.o) file which will include <em>all</em> symbols of the library.
+ This is useful, for example, to include all passes from a library of passes.
+ If the <tt>.a</tt> suffix is used then the library is linked as a searchable
+ library (with the <tt>-l</tt> option). In this case, only the symbols that are
+ unresolved <em>at that point</em> will be resolved from the library, if they
+ exist. Other (unreferenced) symbols will not be included when the <tt>.a</tt>
+ syntax is used. Note that in order to use the <tt>.a</tt> suffix, the library
+ in question must have been built with the <tt>ARCHIVE_LIBRARY</tt> option set.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsubsection"><a name="JIT">JIT Tools</a></div>
+ <div class="doc_text">
+ <p>Many tools will want to use the JIT features of LLVM. However, getting the
+ right set of libraries to link with is tedious, platform specific, and error
+ prone. Additionally, the JIT has special linker switch options that it needs.
+ Consequently, to make it easier to build tools that use the JIT, you can
+ use a special value for the <tt>LLVMLIBS</tt> variable:</p>
+ <pre><tt>
+ TOOLNAME = my_jit_tool
+ USEDLIBS = mylib
+ LLVMLIBS = JIT
+ </tt></pre>
+ <p>Using a value of <tt>JIT</tt> for <tt>LLVMLIBS</tt> tells the makefile
+ system to construct a special value for LLVMLIBS that gives the program all
+ the LLVM libraries needed to run the JIT. Any additional libraries needed can
+ still be specified with <tt>USEDLIBS</tt>. To get a full understanding of how
+ this changes the linker command, it is recommended that you:</p>
+ <pre><tt>
+ cd examples/Fibonacci
+ make VERBOSE=1
+ </tt></pre>
+ <p>By default, using <tt>LLVMLIBS=JIT</tt> will link in enough to support JIT
+ code generation for the architecture on which the tool is linked. If you need
+ additional target architectures linked in, you may specify them on the command
+ line or in your <tt>Makefile</tt>. For example:</p>
+ <pre><tt>
+ ENABLE_X86_JIT=1
+ ENABLE_SPARCV9_JIT=1
+ ENALBE_PPC_JIT=1
+ </tt></pre>
+ <p>will cause the tool to be able to generate code for all three platforms.
+ </p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="targets">Targets Supported</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>This section describes each of the targets that can be built using the LLVM
+ Makefile system. Any target can be invoked from any directory but not all are
+ applicable to a given directory (e.g. "check", "dist" and "install" will
+ always operate as if invoked from the top level directory).</p>
+
+ <table style="text-align:left">
+ <tr>
+ <th>Target Name</th><th>Implied Targets</th><th>Target Description</th>
+ </tr>
+ <tr><td><a href="#all"><tt>all</tt></a></td><td></td>
+ <td>Compile the software recursively. Default target.
+ </td></tr>
+ <tr><td><a href="#all-local"><tt>all-local</tt></a></td><td></td>
+ <td>Compile the software in the local directory only.
+ </td></tr>
+ <tr><td><a href="#check"><tt>check</tt></a></td><td></td>
+ <td>Change to the <tt>test</tt> directory in a project and run the
+ test suite there.
+ </td></tr>
+ <tr><td><a href="#check-local"><tt>check-local</tt></a></td><td></td>
+ <td>Run a local test suite. Generally this is only defined in the
+ <tt>Makefile</tt> of the project's <tt>test</tt> directory.
+ </td></tr>
+ <tr><td><a href="#clean"><tt>clean</tt></a></td><td></td>
+ <td>Remove built objects recursively.
+ </td></tr>
+ <tr><td><a href="#clean-local"><tt>clean-local</tt></a></td><td></td>
+ <td>Remove built objects from the local directory only.
+ </td></tr>
+ <tr><td><a href="#dist"><tt>dist</tt></a></td><td>all</td>
+ <td>Prepare a source distribution tarball.
+ </td></tr>
+ <tr><td><a href="#dist-check"><tt>dist-check</tt></a></td><td>all</td>
+ <td>Prepare a source distribution tarball and check that it builds.
+ </td></tr>
+ <tr><td><a href="#dist-clean"><tt>dist-clean</tt></a></td><td>clean</td>
+ <td>Clean source distribution tarball temporary files.
+ </td></tr>
+ <tr><td><a href="#install"><tt>install</tt></a></td><td>all</td>
+ <td>Copy built objects to installation directory.
+ </td></tr>
+ <tr><td><a href="#preconditions"><tt>preconditions</tt></a></td><td>all</td>
+ <td>Check to make sure configuration and makefiles are up to date.
+ </td></tr>
+ <tr><td><a href="#printvars"><tt>printvars</tt></a></td><td>all</td>
+ <td>Prints variables defined by the makefile system (for debugging).
+ </td></tr>
+ <tr><td><a href="#tags"><tt>tags</tt></a></td><td></td>
+ <td>Make C and C++ tags files for emacs and vi.
+ </td></tr>
+ <tr><td><a href="#uninstall"><tt>uninstall</tt></a></td><td></td>
+ <td>Remove built objects from installation directory.
+ </td></tr>
+ </table>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="all">all (default)</a></div>
+ <div class="doc_text">
+ <p>When you invoke <tt>make</tt> with no arguments, you are implicitly
+ instructing it to seek the "all" target (goal). This target is used for
+ building the software recursively and will do different things in different
+ directories. For example, in a <tt>lib</tt> directory, the "all" target will
+ compile source files and generate libraries. But, in a <tt>tools</tt>
+ directory, it will link libraries and generate executables.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="all-local">all-local</a></div>
+ <div class="doc_text">
+ <p>This target is the same as <a href="#all">all</a> but it operates only on
+ the current directory instead of recursively.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="check">check</a></div>
+ <div class="doc_text">
+ <p>This target can be invoked from anywhere within a project's directories
+ but always invokes the <a href="#check-local"><tt>check-local</tt></a> target
+ in the project's <tt>test</tt> directory, if it exists and has a
+ <tt>Makefile</tt>. A warning is produced otherwise. If
+ <a href="#TESTSUITE"><tt>TESTSUITE</tt></a> is defined on the <tt>make</tt>
+ command line, it will be passed down to the invocation of
+ <tt>make check-local</tt> in the <tt>test</tt> directory. The intended usage
+ for this is to assist in running specific suites of tests. If
+ <tt>TESTSUITE</tt> is not set, the implementation of <tt>check-local</tt>
+ should run all normal tests. It is up to the project to define what
+ different values for <tt>TESTSUTE</tt> will do. See the
+ <a href="TestingGuide.html">TestingGuide</a> for further details.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="check-local">check-local</a></div>
+ <div class="doc_text">
+ <p>This target should be implemented by the <tt>Makefile</tt> in the project's
+ <tt>test</tt> directory. It is invoked by the <tt>check</tt> target elsewhere.
+ Each project is free to define the actions of <tt>check-local</tt> as
+ appropriate for that project. The LLVM project itself uses dejagnu to run a
+ suite of feature and regresson tests. Other projects may choose to use
+ dejagnu or any other testing mechanism.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="clean">clean</a></div>
+ <div class="doc_text">
+ <p>This target cleans the build directory, recursively removing all things
+ that the Makefile builds. The cleaning rules have been made guarded so they
+ shouldn't go awry (via <tt>rm -f $(UNSET_VARIABLE)/*</tt> which will attempt
+ to erase the entire directory structure.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="clean-local">clean-local</a></div>
+ <div class="doc_text">
+ <p>This target does the same thing as <tt>clean</tt> but only for the current
+ (local) directory.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="dist">dist</a></div>
+ <div class="doc_text">
+ <p>This target builds a distribution tarball. It first builds the entire
+ project using the <tt>all</tt> target and then tars up the necessary files and
+ compresses it. The generated tarball is sufficient for a casual source
+ distribution, but probably not for a release (see <tt>dist-check</tt>).</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="dist-check">dist-check</a></div>
+ <div class="doc_text">
+ <p>This target does the same thing as the <tt>dist</tt> target but also checks
+ the distribution tarball. The check is made by unpacking the tarball to a new
+ directory, configuring it, building it, installing it, and then verifying that
+ the installation results are correct (by comparing to the original build).
+ This target can take a long time to run but should be done before a release
+ goes out to make sure that the distributed tarball can actually be built into
+ a working release.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="dist-clean">dist-clean</a></div>
+ <div class="doc_text">
+ <p>This is a special form of the <tt>clean</tt> clean target. It performs a
+ normal <tt>clean</tt> but also removes things pertaining to building the
+ distribution.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="install">install</a></div>
+ <div class="doc_text">
+ <p>This target finalizes shared objects and executables and copies all
+ libraries, headers, executables and documentation to the directory given
+ with the <tt>--prefix</tt> option to <tt>configure</tt>. When completed,
+ the prefix directory will have everything needed to <b>use</b> LLVM. </p>
+ <p>The LLVM makefiles can generate complete <b>internal</b> documentation
+ for all the classes by using <tt>doxygen</tt>. By default, this feature is
+ <b>not</b> enabled because it takes a long time and generates a massive
+ amount of data (>100MB). If you want this feature, you must configure LLVM
+ with the --enable-doxygen switch and ensure that a modern version of doxygen
+ (1.3.7 or later) is available in your <tt>PATH</tt>. You can download
+ doxygen from
+ <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc">
+ here</a>.
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="preconditions">preconditions</a></div>
+ <div class="doc_text">
+ <p>This utility target checks to see if the <tt>Makefile</tt> in the object
+ directory is older than the <tt>Makefile</tt> in the source directory and
+ copies it if so. It also reruns the <tt>configure</tt> script if that needs to
+ be done and rebuilds the <tt>Makefile.config</tt> file similarly. Users may
+ overload this target to ensure that sanity checks are run <em>before</em> any
+ building of targets as all the targets depend on <tt>preconditions</tt>.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="printvars">printvars</a></div>
+ <div class="doc_text">
+ <p>This utility target just causes the LLVM makefiles to print out some of
+ the makefile variables so that you can double check how things are set. </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="reconfigure">reconfigure</a></div>
+ <div class="doc_text">
+ <p>This utility target will force a reconfigure of LLVM or your project. It
+ simply runs <tt>$(PROJ_OBJ_ROOT)/config.status --recheck</tt> to rerun the
+ configuration tests and rebuild the configured files. This isn't generally
+ useful as the makefiles will reconfigure themselves whenever its necessary.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="spotless">spotless</a></div>
+ <div class="doc_text">
+ <p>This utility target, only available when <tt>$(PROJ_OBJ_ROOT)</tt> is not
+ the same as <tt>$(PROJ_SRC_ROOT)</tt>, will completely clean the
+ <tt>$(PROJ_OBJ_ROOT)</tt> directoy by removing its content entirely and
+ reconfiguring the directory. This returns the <tt>$(PROJ_OBJ_ROOT)</tt>
+ directory to a completely fresh state. All content in the directory except
+ configured files and top-level makefiles will be lost.</p>
+ <div class="doc_warning"><p>Use with caution.</p></div>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="tags">tags</a></div>
+ <div class="doc_text">
+ <p>This target will generate a <tt>TAGS</tt> file in the top-level source
+ directory. It is meant for use with emacs, XEmacs, or ViM. The TAGS file
+ provides an index of symbol definitions so that the editor can jump you to the
+ definition quickly. </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="uninstall">uninstall</a></div>
+ <div class="doc_text">
+ <p>This target is the opposite of the <tt>install</tt> target. It removes the
+ header, library and executable files from the installation directories. Note
+ that the directories themselves are not removed because it is not guaranteed
+ that LLVM is the only thing installing there (e.g. --prefix=/usr).</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="variables">Variables</a></div>
+ <!-- *********************************************************************** -->
+ <div class="doc_text">
+ <p>Variables are used to tell the LLVM Makefile System what to do and to
+ obtain information from it. Variables are also used internally by the LLVM
+ Makefile System. Variable names that contain only the upper case alphabetic
+ letters and underscore are intended for use by the end user. All other
+ variables are internal to the LLVM Makefile System and should not be relied
+ upon nor modified. The sections below describe how to use the LLVM Makefile
+ variables.</p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="setvars">Control Variables</a></div>
+ <div class="doc_text">
+ <p>Variables listed in the table below should be set <em>before</em> the
+ inclusion of <a href="#Makefile.common"><tt>$(LEVEL)/Makefile.common</tt></a>.
+ These variables provide input to the LLVM make system that tell it what to do
+ for the current directory.</p>
+ <dl>
+ <dt><a name="BUILD_ARCHIVE"><tt>BUILD_ARCHIVE</tt></a></dt>
+ <dd>If set to any value, causes an archive (.a) library to be built.</dd>
+ <dt><a name="BUILT_SOURCES"><tt>BUILT_SOURCES</tt></a></dt>
+ <dd>Specifies a set of source files that are generated from other source
+ files. These sources will be built before any other target processing to
+ ensure they are present.</dd>
+ <dt><a name="BYTECODE_LIBRARY"><tt>BYTECODE_LIBRARY</tt></a></dt>
+ <dd>If set to any value, causes a bytecode library (.bc) to be built.</dd>
+ <dt><a name="CONFIG_FILES"><tt>CONFIG_FILES</tt></a></dt>
+ <dd>Specifies a set of configuration files to be installed.</dd>
+ <dt><a name="DIRS"><tt>DIRS</tt></a></dt>
+ <dd>Specifies a set of directories, usually children of the current
+ directory, that should also be made using the same goal. These directories
+ will be built serially.</dd>
+ <dt><a name="DISABLE_AUTO_DEPENDENCIES"><tt>DISABLE_AUTO_DEPENDENCIES</tt></a></dt>
+ <dd>If set to any value, causes the makefiles to <b>not</b> automatically
+ generate dependencies when running the compiler. Use of this feature is
+ discouraged and it may be removed at a later date.</dd>
+ <dt><a name="DONT_BUILD_RELINKED"><tt>DONT_BUILD_RELINKED</tt></a></dt>
+ <dd>If set to any value, causes a relinked library (.o) not to be built. By
+ default, libraries are built as re-linked since most LLVM libraries are
+ needed in their entirety and re-linked libraries will be linked more quickly
+ than equivalent archive libraries.</dd>
+ <dt><a name="ENABLE_OPTIMIZED"><tt>ENABLE_OPTIMIZED</tt></a></dt>
+ <dd>If set to any value, causes the build to generate optimized objects,
+ libraries and executables. This alters the flags specified to the compilers
+ and linkers. Generally debugging won't be a fun experience with an optimized
+ build.</dd>
+ <dt><a name="ENABLE_PROFILING"><tt>ENABLE_PROFILING</tt></a></dt>
+ <dd>If set to any value, causes the build to generate both optimized and
+ profiled objects, libraries and executables. This alters the flags specified
+ to the compilers and linkers to ensure that profile data can be collected
+ from the tools built. Use the <tt>gprof</tt> tool to analyze the output from
+ the profiled tools (<tt>gmon.out</tt>).</dd>
+ <dt><a name="EXPERIMENTAL_DIRS"><tt>EXPERIMENTAL_DIRS</tt></a></dt>
+ <dd>Specify a set of directories that should be built, but if they fail, it
+ should not cause the build to fail. Note that this should only be used
+ temporarily while code is being written.</dd>
+ <dt><a name="EXPORTED_SYMBOL_FILE"><tt>EXPORTED_SYMBOL_FILE</tt></a></dt>
+ <dd>Specifies the name of a single file that contains a list of the
+ symbols to be exported by the linker. One symbol per line.</dd>
+ <dt><a name="EXPORTED_SYMBOL_LIST"><tt>EXPORTED_SYMBOL_LIST</tt></a></dt>
+ <dd>Specifies a set of symbols to be exported by the linker.</dd>
+ <dt><a name="EXTRA_DIST"><tt>EXTRA_DIST</tt></a></dt>
+ <dd>Specifies additional files that should be distributed with LLVM. All
+ source files, all built sources, all Makefiles, and most documentation files
+ will be automatically distributed. Use this variable to distribute any
+ files that are not automatically distributed.</dd>
+ <dt><a name="FAKE_SOURCES"><tt>FAKE_SOURCES</tt><small>(optional)</small>
+ </a></dt>
+ <dd>This variable is like <a href="#SOURCES"><tt>SOURCES</tt></a> except that
+ the source files don't need to exist. The makefiles only use
+ <tt>FAKE_SOURCES</tt> to create the names of derived objects that should be
+ included in the directory's result. It is assumed that the project's
+ <tt>Makefile</tt> will define how to build the derived objects
+ necessary.</dd>
+ <dt><a name="KEEP_SYMBOLS"><tt>KEEP_SYMBOLS</tt></a></dt>
+ <dd>If set to any value, specifies that when linking executables the
+ makefiles should retain debug symbols in the executable. Normally, symbols
+ are stripped from the executable.</dd>
+ <dt><a name="LEVEL"><tt>LEVEL</tt></a><small>(required)</small></dt>
+ <dd>Specify the level of nesting from the top level. This variable must be
+ set in each makefile as it is used to find the top level and thus the other
+ makefiles.</dd>
+ <dt><a name="LIBRARYNAME"><tt>LIBRARYNAME</tt></a></dt>
+ <dd>Specify the name of the library to be built. (Required For
+ Libraries)</dd>
+ <dt><a name="LLVMLIBS"><tt>LLVMLIBS</tt></a></dt>
+ <dd>Specifies the set of libraries from the LLVM $(ObjDir) that will be
+ linked into the tool or library.</dd>
+ <dt><a name="LOADABLE_MODULE"><tt>LOADABLE_MODULE</tt></a></dt>
+ <dd>If set to any value, causes the shared library being built to also be
+ a loadable module. Loadable modules can be opened with the dlopen() function
+ and searched with dlsym (or the operating system's equivalent). Note that
+ setting this variable without also setting <tt>SHARED_LIBRARY</tt> will have
+ no effect.</dd>
+ <dt><a name="MODULE_NAME"><tt>MODULE_NAME</tt></a></dt>
+ <dd>Specifies the name of a bytecode module to be created. A bytecode
+ module can be specified in conjunction with other kinds of library builds
+ or by itself. It constructs from the sources a single linked bytecode
+ file.</dd>
+ <dt><a name="OPTIONAL_DIRS"><tt>OPTIONAL_DIRS</tt></a></dt>
+ <dd>Specify a set of directories that may be built, if they exist, but its
+ not an error for them not to exist.</dd>
+ <dt><a name="PARALLEL_DIRS"><tt>PARALLEL_DIRS</tt></a></dt>
+ <dd>Specify a set of directories to build recursively and in parallel if
+ the -j option was used with <tt>make</tt>.</dd>
+ <dt><a name="SHARED_LIBRARY"><tt>SHARED_LIBRARY</tt></a></dt>
+ <dd>If set to any value, causes a shared library (.so) to be built in
+ addition to any other kinds of libraries. Note that this option will cause
+ all source files to be built twice: once with options for position
+ independent code and once without. Use it only where you really need a
+ shared library.</dd>
+ <dt><a name="SOURCES"><tt>SOURCES</tt><small>(optional)</small></a></dt>
+ <dd>Specifies the list of source files in the current directory to be
+ built. Source files of any type may be specified (programs, documentation,
+ config files, etc.). If not specified, the makefile system will infer the
+ set of source files from the files present in the current directory.</dd>
+ <dt><a name="SUFFIXES"><tt>SUFFIXES</tt></a></dt>
+ <dd>Specifies a set of filename suffixes that occur in suffix match rules.
+ Only set this if your local <tt>Makefile</tt> specifies additional suffix
+ match rules.</dd>
+ <dt><a name="TARGET"><tt>TARGET</tt></a></dt>
+ <dd>Specifies the name of the LLVM code generation target that the
+ current directory builds. Setting this variable enables additional rules to
+ build <tt>.inc</tt> files from <tt>.td</tt> files. </dd>
+ <dt><a name="TESTSUITE"><tt>TESTSUITE</tt></a></dt>
+ <dd>Specifies the directory of tests to run in <tt>llvm/test</tt>.</dd>
+ <dt><a name="TOOLNAME"><tt>TOOLNAME</tt></a></dt>
+ <dd>Specifies the name of the tool that the current directory should
+ build.</dd>
+ <dt><a name="TOOL_VERBOSE"><tt>TOOL_VERBOSE</tt></a></dt>
+ <dd>Implies VERBOSE and also tells each tool invoked to be verbose. This is
+ handy when you're trying to see the sub-tools invoked by each tool invoked
+ by the makefile. For example, this will pass <tt>-v</tt> to the GCC
+ compilers which causes it to print out the command lines it uses to invoke
+ sub-tools (compiler, assembler, linker).</dd>
+ <dt><a name="USEDLIBS"><tt>USEDLIBS</tt></a></dt>
+ <dd>Specifies the list of project libraries that will be linked into the
+ tool or library.</dd>
+ <dt><a name="VERBOSE"><tt>VERBOSE</tt></a></dt>
+ <dd>Tells the Makefile system to produce detailed output of what it is doing
+ instead of just summary comments. This will generate a LOT of output.</dd>
+ </dl>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="overvars">Override Variables</a></div>
+ <div class="doc_text">
+ <p>Override variables can be used to override the default
+ values provided by the LLVM makefile system. These variables can be set in
+ several ways:</p>
+ <ul>
+ <li>In the environment (e.g. setenv, export) -- not recommended.</li>
+ <li>On the <tt>make</tt> command line -- recommended.</li>
+ <li>On the <tt>configure</tt> command line</li>
+ <li>In the Makefile (only <em>after</em> the inclusion of <a
+ href="#Makefile.common"><tt>$(LEVEL)/Makefile.common</tt></a>).</li>
+ </ul>
+ <p>The override variables are given below:</p>
+ <dl>
+ <dt><a name="AR"><tt>AR</tt></a> <small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>ar</tt> tool.</dd>
+ <dt><a name="BISON"><tt>BISON</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the path to the <tt>bison</tt> tool.</dd>
+ <dt><a name="PROJ_OBJ_DIR"><tt>PROJ_OBJ_DIR</tt></a></dt>
+ <dd>The directory into which the products of build rules will be placed.
+ This might be the same as
+ <a href="#PROJ_SRC_DIR"><tt>PROJ_SRC_DIR</tt></a> but typically is
+ not.</dd>
+ <dt><a name="PROJ_SRC_DIR"><tt>PROJ_SRC_DIR</tt></a></dt>
+ <dd>The directory which contains the source files to be built.</dd>
+ <dt><a name="BURG"><tt>BURG</tt></a></dt>
+ <dd>Specifies the path to the <tt>burg</tt> tool.</dd>
+ <dt><a name="BZIP2"><tt>BZIP2</tt></a><small>(configured)</small></dt>
+ <dd>The path to the <tt>bzip2</tt> tool.</dd>
+ <dt><a name="CC"><tt>CC</tt></a><small>(configured)</small></dt>
+ <dd>The path to the 'C' compiler.</dd>
+ <dt><a name="CFLAGS"><tt>CFLAGS</tt></a></dt>
+ <dd>Additional flags to be passed to the 'C' compiler.</dd>
+ <dt><a name="CXX"><tt>CXX</tt></a></dt>
+ <dd>Specifies the path to the C++ compiler.</dd>
+ <dt><a name="CXXFLAGS"><tt>CXXFLAGS</tt></a></dt>
+ <dd>Additional flags to be passed to the C++ compiler.</dd>
+ <dt><a name="DATE"><tt>DATE<small>(configured)</small></tt></a></dt>
+ <dd>Specifies the path to the <tt>date</tt> program or any program that can
+ generate the current date and time on its standard output</dd>
+ <dt><a name="DOT"><tt>DOT</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the path to the <tt>dot</tt> tool or <tt>false</tt> if there
+ isn't one.</dd>
+ <dt><a name="ECHO"><tt>ECHO</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the path to the <tt>echo</tt> tool for printing output.</dd>
+ <dt><a name="ETAGS"><tt>ETAGS</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the path to the <tt>etags</tt> tool.</dd>
+ <dt><a name="ETAGSFLAGS"><tt>ETAGSFLAGS</tt></a><small>(configured)</small></dt>
+ <dd>Provides flags to be passed to the <tt>etags</tt> tool.</dd>
+ <dt><a name="EXEEXT"><tt>EXEEXT</tt></a><small>(configured)</small></dt>
+ <dd>Provides the extension to be used on executables built by the makefiles.
+ The value may be empty on platforms that do not use file extensions for
+ executables (e.g. Unix).</dd>
+ <dt><a name="FLEX"><tt>FLEX</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the path to the <tt>flex</tt> tool.</dd>
+ <dt><a name="GCCLD"><tt>GCCLD</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>gccld</tt> tool.</dd>
+ <dt><a name="INSTALL"><tt>INSTALL</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the path to the <tt>install</tt> tool.</dd>
+ <dt><a name="LDFLAGS"><tt>LDFLAGS</tt></a><small>(configured)</small></dt>
+ <dd>Allows users to specify additional flags to pass to the linker.</dd>
+ <dt><a name="LIBS"><tt>LIBS</tt></a><small>(configured)</small></dt>
+ <dd>The list of libraries that should be linked with each tool.</dd>
+ <dt><a name="LIBTOOL"><tt>LIBTOOL</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the path to the <tt>libtool</tt> tool. This tool is renamed
+ <tt>mklib</tt> by the <tt>configure</tt> script and always located in the
+ <dt><a name="LLVMAS"><tt>LLVMAS</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>llvm-as</tt> tool.</dd>
+ <dt><a name="LLVMGCC"><tt>LLVMGCC</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the LLVM version of the GCC 'C' Compiler</dd>
+ <dt><a name="LLVMGXX"><tt>LLVMGXX</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the LLVM version of the GCC C++ Compiler</dd>
+ <dt><a name="LLVM_OBJ_ROOT"><tt>LLVM_OBJ_ROOT</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the top directory into which the output of the build is
+ placed.</dd>
+ <dt><a name="LLVM_SRC_ROOT"><tt>LLVM_SRC_ROOT</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the top directory in which the sources are found.</dd>
+ <dt><a name="LLVM_TARBALL_NAME"><tt>LLVM_TARBALL_NAME</tt></a><small>(configured)</small></dt>
+ <dd>Specifies the name of the distribution tarball to create. This is
+ configured from the name of the project and its version number.</dd>
+ <dt><a name="MKDIR"><tt>MKDIR</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>mkdir</tt> tool that creates
+ directories.</dd>
+ <dt><a name="PLATFORMSTRIPOPTS"><tt>PLATFORMSTRIPOPTS</tt></a></dt>
+ <dd>The options to provide to the linker to specify that a stripped (no
+ symbols) executable should be built.</dd>
+ <dt><a name="RANLIB"><tt>RANLIB</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>ranlib</tt> tool.</dd>
+ <dt><a name="RM"><tt>RM</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>rm</tt> tool.</dd>
+ <dt><a name="SED"><tt>SED</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>sed</tt> tool.</dd>
+ <dt><a name="SHLIBEXT"><tt>SHLIBEXT</tt></a><small>(configured)</small></dt>
+ <dd>Provides the filename extension to use for shared libraries.</dd>
+ <dt><a name="TBLGEN"><tt>TBLGEN</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>tblgen</tt> tool.</dd>
+ <dt><a name="TAR"><tt>TAR</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>tar</tt> tool.</dd>
+ <dt><a name="ZIP"><tt>ZIP</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the <tt>zip</tt> tool.</dd>
+ </dl>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="getvars">Readable Variables</a></div>
+ <div class="doc_text">
+ <p>Variables listed in the table below can be used by the user's Makefile but
+ should not be changed. Changing the value will generally cause the build to go
+ wrong, so don't do it.</p>
+ <dl>
+ <dt><a name="bindir"><tt>bindir</tt></a></dt>
+ <dd>The directory into which executables will ultimately be installed. This
+ value is derived from the <tt>--prefix</tt> option given to
+ <tt>configure</tt>.</dd>
+ <dt><a name="BuildMode"><tt>BuildMode</tt></a></dt>
+ <dd>The name of the type of build being performed: Debug, Release, or
+ Profile</dd>
+ <dt><a name="bytecode_libdir"><tt>bytecode_libdir</tt></a></dt>
+ <dd>The directory into which bytecode libraries will ultimately be installed.
+ This value is derived from the <tt>--prefix</tt> option given to
+ <tt>configure</tt>.</dd>
+ <dt><a name="ConfigureScriptFLAGS"><tt>ConfigureScriptFLAGS</tt></a></dt>
+ <dd>Additional flags given to the <tt>configure</tt> script when
+ reconfiguring.</dd>
+ <dt><a name="DistDir"><tt>DistDir</tt></a></dt>
+ <dd>The <em>current</em> directory for which a distribution copy is being
+ made.</dd>
+ <dt><a name="Echo"><tt>Echo</tt></a></dt>
+ <dd>The LLVM Makefile System output command. This provides the
+ <tt>llvm[n]</tt> prefix and starts with @ so the command itself is not
+ printed by <tt>make</tt>.</dd>
+ <dt><a name="EchoCmd"><tt>EchoCmd</tt></a></dt>
+ <dd> Same as <a href="#Echo"><tt>Echo</tt></a> but without the leading @.
+ </dd>
+ <dt><a name="includedir"><tt>includedir</tt></a></dt>
+ <dd>The directory into which include files will ultimately be installed.
+ This value is derived from the <tt>--prefix</tt> option given to
+ <tt>configure</tt>.</dd>
+ <dt><a name="libdir"><tt>libdir</tt></a></dt><dd></dd>
+ <dd>The directory into which native libraries will ultimately be installed.
+ This value is derived from the <tt>--prefix</tt> option given to
+ <tt>configure</tt>.</dd>
+ <dt><a name="LibDir"><tt>LibDir</tt></a></dt>
+ <dd>The configuration specific directory into which libraries are placed
+ before installation.</dd>
+ <dt><a name="MakefileConfig"><tt>MakefileConfig</tt></a></dt>
+ <dd>Full path of the <tt>Makefile.config</tt> file.</dd>
+ <dt><a name="MakefileConfigIn"><tt>MakefileConfigIn</tt></a></dt>
+ <dd>Full path of the <tt>Makefile.config.in</tt> file.</dd>
+ <dt><a name="ObjDir"><tt>ObjDir</tt></a></dt>
+ <dd>The configuration and directory specific directory where build objects
+ (compilation results) are placed.</dd>
+ <dt><a name="SubDirs"><tt>SubDirs</tt></a></dt>
+ <dd>The complete list of sub-directories of the current directory as
+ specified by other variables.</dd>
+ <dt><a name="Sources"><tt>Sources</tt></a></dt>
+ <dd>The complete list of source files.</dd>
+ <dt><a name="sysconfdir"><tt>sysconfdir</tt></a></dt>
+ <dd>The directory into which configuration files will ultimately be
+ installed. This value is derived from the <tt>--prefix</tt> option given to
+ <tt>configure</tt>.</dd>
+ <dt><a name="ToolDir"><tt>ToolDir</tt></a></dt>
+ <dd>The configuration specific directory into which executables are placed
+ before they are installed.</dd>
+ <dt><a name="TopDistDir"><tt>TopDistDir</tt></a></dt>
+ <dd>The top most directory into which the distribution files are copied.
+ </dd>
+ <dt><a name="Verb"><tt>Verb</tt></a></dt>
+ <dd>Use this as the first thing on your build script lines to enable or
+ disable verbose mode. It expands to either an @ (quiet mode) or nothing
+ (verbose mode). </dd>
+ </dl>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection"><a name="intvars">Internal Variables</a></div>
+ <div class="doc_text">
+ <p>Variables listed below are used by the LLVM Makefile System
+ and considered internal. You should not use these variables under any
+ circumstances.</p>
+ <p><tt>
+ Archive
+ AR.Flags
+ BaseNameSources
+ BCCompile.C
+ BCCompile.CXX
+ BCLinkLib
+ Burg
+ C.Flags
+ Compile.C
+ CompileCommonOpts
+ Compile.CXX
+ ConfigStatusScript
+ ConfigureScript
+ CPP.Flags
+ CPP.Flags
+ CXX.Flags
+ DependFiles
+ DestArchiveLib
+ DestBytecodeLib
+ DestModule
+ DestRelinkedLib
+ DestSharedLib
+ DestTool
+ DistAlways
+ DistCheckDir
+ DistCheckTop
+ DistFiles
+ DistName
+ DistOther
+ DistSources
+ DistSubDirs
+ DistTarBZ2
+ DistTarGZip
+ DistZip
+ ExtraLibs
+ FakeSources
+ INCFiles
+ InternalTargets
+ LD.Flags
+ LexFiles
+ LexOutput
+ LibName.A
+ LibName.BC
+ LibName.LA
+ LibName.O
+ LibTool.Flags
+ Link
+ LinkModule
+ LLVMLibDir
+ LLVMLibsOptions
+ LLVMLibsPaths
+ LLVMToolDir
+ LLVMUsedLibs
+ LocalTargets
+ LTCompile.C
+ LTCompile.CXX
+ LTInstall
+ Module
+ ObjectsBC
+ ObjectsLO
+ ObjectsO
+ ObjMakefiles
+ ParallelTargets
+ PreConditions
+ ProjLibsOptions
+ ProjLibsPaths
+ ProjUsedLibs
+ Ranlib
+ RecursiveTargets
+ Relink
+ SrcMakefiles
+ Strip
+ StripWarnMsg
+ TableGen
+ TDFiles
+ ToolBuildPath
+ TopLevelTargets
+ UserTargets
+ YaccFiles
+ YaccOutput
+ </tt></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:rspencer at x10sys.com">Reid Spencer</a><br>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:22 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/ProgrammersManual.html
diff -c /dev/null llvm-www/releases/1.5/docs/ProgrammersManual.html:1.1
*** /dev/null Wed May 18 09:34:36 2005
--- llvm-www/releases/1.5/docs/ProgrammersManual.html Wed May 18 09:33:23 2005
***************
*** 0 ****
--- 1,2243 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>LLVM Programmer's Manual</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">
+ LLVM Programmer's Manual
+ </div>
+
+ <ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#general">General Information</a>
+ <ul>
+ <li><a href="#stl">The C++ Standard Template Library</a></li>
+ <!--
+ <li>The <tt>-time-passes</tt> option</li>
+ <li>How to use the LLVM Makefile system</li>
+ <li>How to write a regression test</li>
+
+ -->
+ </ul>
+ </li>
+ <li><a href="#apis">Important and useful LLVM APIs</a>
+ <ul>
+ <li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt>
+ and <tt>dyn_cast<></tt> templates</a> </li>
+ <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt>
+ option</a>
+ <ul>
+ <li><a href="#DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt>
+ and the <tt>-debug-only</tt> option</a> </li>
+ </ul>
+ </li>
+ <li><a href="#Statistic">The <tt>Statistic</tt> template & <tt>-stats</tt>
+ option</a></li>
+ <!--
+ <li>The <tt>InstVisitor</tt> template
+ <li>The general graph API
+ -->
+ </ul>
+ </li>
+ <li><a href="#common">Helpful Hints for Common Operations</a>
+ <ul>
+ <li><a href="#inspection">Basic Inspection and Traversal Routines</a>
+ <ul>
+ <li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s
+ in a <tt>Function</tt></a> </li>
+ <li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s
+ in a <tt>BasicBlock</tt></a> </li>
+ <li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s
+ in a <tt>Function</tt></a> </li>
+ <li><a href="#iterate_convert">Turning an iterator into a
+ class pointer</a> </li>
+ <li><a href="#iterate_complex">Finding call sites: a more
+ complex example</a> </li>
+ <li><a href="#calls_and_invokes">Treating calls and invokes
+ the same way</a> </li>
+ <li><a href="#iterate_chains">Iterating over def-use &
+ use-def chains</a> </li>
+ </ul>
+ </li>
+ <li><a href="#simplechanges">Making simple changes</a>
+ <ul>
+ <li><a href="#schanges_creating">Creating and inserting new
+ <tt>Instruction</tt>s</a> </li>
+ <li><a href="#schanges_deleting">Deleting <tt>Instruction</tt>s</a> </li>
+ <li><a href="#schanges_replacing">Replacing an <tt>Instruction</tt>
+ with another <tt>Value</tt></a> </li>
+ </ul>
+ </li>
+ <!--
+ <li>Working with the Control Flow Graph
+ <ul>
+ <li>Accessing predecessors and successors of a <tt>BasicBlock</tt>
+ <li>
+ <li>
+ </ul>
+ -->
+ </ul>
+ </li>
+
+ <li><a href="#advanced">Advanced Topics</a>
+ <ul>
+ <li><a href="#TypeResolve">LLVM Type Resolution</a>
+ <ul>
+ <li><a href="#BuildRecType">Basic Recursive Type Construction</a></li>
+ <li><a href="#refineAbstractTypeTo">The <tt>refineAbstractTypeTo</tt> method</a></li>
+ <li><a href="#PATypeHolder">The PATypeHolder Class</a></li>
+ <li><a href="#AbstractTypeUser">The AbstractTypeUser Class</a></li>
+ </ul></li>
+
+ <li><a href="#SymbolTable">The <tt>SymbolTable</tt> class </a></li>
+ </ul></li>
+
+ <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
+ <ul>
+ <li><a href="#Value">The <tt>Value</tt> class</a>
+ <ul>
+ <li><a href="#User">The <tt>User</tt> class</a>
+ <ul>
+ <li><a href="#Instruction">The <tt>Instruction</tt> class</a>
+ <ul>
+ <li><a href="#GetElementPtrInst">The <tt>GetElementPtrInst</tt> class</a></li>
+ </ul>
+ </li>
+ <li><a href="#Module">The <tt>Module</tt> class</a></li>
+ <li><a href="#Constant">The <tt>Constant</tt> class</a>
+ <ul>
+ <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a>
+ <ul>
+ <li><a href="#BasicBlock">The <tt>BasicBlock</tt>class</a></li>
+ <li><a href="#Function">The <tt>Function</tt> class</a></li>
+ <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#Type">The <tt>Type</tt> class</a> </li>
+ <li><a href="#Argument">The <tt>Argument</tt> class</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:dhurjati at cs.uiuc.edu">Dinakar Dhurjati</a>,
+ <a href="mailto:jstanley at cs.uiuc.edu">Joel Stanley</a>, and
+ <a href="mailto:rspencer at x10sys.com">Reid Spencer</a></p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="introduction">Introduction </a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This document is meant to highlight some of the important classes and
+ interfaces available in the LLVM source-base. This manual is not
+ intended to explain what LLVM is, how it works, and what LLVM code looks
+ like. It assumes that you know the basics of LLVM and are interested
+ in writing transformations or otherwise analyzing or manipulating the
+ code.</p>
+
+ <p>This document should get you oriented so that you can find your
+ way in the continuously growing source code that makes up the LLVM
+ infrastructure. Note that this manual is not intended to serve as a
+ replacement for reading the source code, so if you think there should be
+ a method in one of these classes to do something, but it's not listed,
+ check the source. Links to the <a href="/doxygen/">doxygen</a> sources
+ are provided to make this as easy as possible.</p>
+
+ <p>The first section of this document describes general information that is
+ useful to know when working in the LLVM infrastructure, and the second describes
+ the Core LLVM classes. In the future this manual will be extended with
+ information describing how to use extension libraries, such as dominator
+ information, CFG traversal routines, and useful utilities like the <tt><a
+ href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> template.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="general">General Information</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This section contains general information that is useful if you are working
+ in the LLVM source-base, but that isn't specific to any particular API.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="stl">The C++ Standard Template Library</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>LLVM makes heavy use of the C++ Standard Template Library (STL),
+ perhaps much more than you are used to, or have seen before. Because of
+ this, you might want to do a little background reading in the
+ techniques used and capabilities of the library. There are many good
+ pages that discuss the STL, and several books on the subject that you
+ can get, so it will not be discussed in this document.</p>
+
+ <p>Here are some useful links:</p>
+
+ <ol>
+
+ <li><a href="http://www.dinkumware.com/refxcpp.html">Dinkumware C++ Library
+ reference</a> - an excellent reference for the STL and other parts of the
+ standard C++ library.</li>
+
+ <li><a href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> - This is an
+ O'Reilly book in the making. It has a decent
+ Standard Library
+ Reference that rivals Dinkumware's, and is unfortunately no longer free since the book has been
+ published.</li>
+
+ <li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently Asked
+ Questions</a></li>
+
+ <li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's Guide</a> -
+ Contains a useful <a
+ href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction to the
+ STL</a>.</li>
+
+ <li><a href="http://www.research.att.com/%7Ebs/C++.html">Bjarne Stroustrup's C++
+ Page</a></li>
+
+ <li><a href="http://64.78.49.204/">
+ Bruce Eckel's Thinking in C++, 2nd ed. Volume 2 Revision 4.0 (even better, get
+ the book).</a></li>
+
+ </ol>
+
+ <p>You are also encouraged to take a look at the <a
+ href="CodingStandards.html">LLVM Coding Standards</a> guide which focuses on how
+ to write maintainable code more than where to put your curly braces.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="stl">Other useful references</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ol>
+ <li><a href="http://www.psc.edu/%7Esemke/cvs_branches.html">CVS
+ Branch and Tag Primer</a></li>
+ <li><a href="http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html">Using
+ static and shared libraries across platforms</a></li>
+ </ol>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="apis">Important and useful LLVM APIs</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Here we highlight some LLVM APIs that are generally useful and good to
+ know about when writing transformations.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="isa">The isa<>, cast<> and dyn_cast<> templates</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The LLVM source-base makes extensive use of a custom form of RTTI.
+ These templates have many similarities to the C++ <tt>dynamic_cast<></tt>
+ operator, but they don't have some drawbacks (primarily stemming from
+ the fact that <tt>dynamic_cast<></tt> only works on classes that
+ have a v-table). Because they are used so often, you must know what they
+ do and how they work. All of these templates are defined in the <a
+ href="/doxygen/Casting_8h-source.html"><tt>llvm/Support/Casting.h</tt></a>
+ file (note that you very rarely have to include this file directly).</p>
+
+ <dl>
+ <dt><tt>isa<></tt>: </dt>
+
+ <dd>The <tt>isa<></tt> operator works exactly like the Java
+ "<tt>instanceof</tt>" operator. It returns true or false depending on whether
+ a reference or pointer points to an instance of the specified class. This can
+ be very useful for constraint checking of various sorts (example below).</dd>
+
+ <dt><tt>cast<></tt>: </dt>
+
+ <dd>The <tt>cast<></tt> operator is a "checked cast" operation. It
+ converts a pointer or reference from a base class to a derived cast, causing
+ an assertion failure if it is not really an instance of the right type. This
+ should be used in cases where you have some information that makes you believe
+ that something is of the right type. An example of the <tt>isa<></tt>
+ and <tt>cast<></tt> template is:
+
+ <pre>
+ static bool isLoopInvariant(const <a href="#Value">Value</a> *V, const Loop *L) {
+ if (isa<<a href="#Constant">Constant</a>>(V) || isa<<a href="#Argument">Argument</a>>(V) || isa<<a href="#GlobalValue">GlobalValue</a>>(V))
+ return true;
+
+ <i>// Otherwise, it must be an instruction...</i>
+ return !L->contains(cast<<a href="#Instruction">Instruction</a>>(V)->getParent());
+ }
+ </pre>
+
+ <p>Note that you should <b>not</b> use an <tt>isa<></tt> test followed
+ by a <tt>cast<></tt>, for that use the <tt>dyn_cast<></tt>
+ operator.</p>
+
+ </dd>
+
+ <dt><tt>dyn_cast<></tt>:</dt>
+
+ <dd>The <tt>dyn_cast<></tt> operator is a "checking cast" operation. It
+ checks to see if the operand is of the specified type, and if so, returns a
+ pointer to it (this operator does not work with references). If the operand is
+ not of the correct type, a null pointer is returned. Thus, this works very
+ much like the <tt>dynamic_cast</tt> operator in C++, and should be used in the
+ same circumstances. Typically, the <tt>dyn_cast<></tt> operator is used
+ in an <tt>if</tt> statement or some other flow control statement like this:
+
+ <pre>
+ if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) {
+ ...
+ }
+ </pre>
+
+ <p> This form of the <tt>if</tt> statement effectively combines together a
+ call to <tt>isa<></tt> and a call to <tt>cast<></tt> into one
+ statement, which is very convenient.</p>
+
+ <p>Note that the <tt>dyn_cast<></tt> operator, like C++'s
+ <tt>dynamic_cast</tt> or Java's <tt>instanceof</tt> operator, can be abused.
+ In particular you should not use big chained <tt>if/then/else</tt> blocks to
+ check for lots of different variants of classes. If you find yourself
+ wanting to do this, it is much cleaner and more efficient to use the
+ <tt>InstVisitor</tt> class to dispatch over the instruction type directly.</p>
+
+ </dd>
+
+ <dt><tt>cast_or_null<></tt>: </dt>
+
+ <dd>The <tt>cast_or_null<></tt> operator works just like the
+ <tt>cast<></tt> operator, except that it allows for a null pointer as
+ an argument (which it then propagates). This can sometimes be useful,
+ allowing you to combine several null checks into one.</dd>
+
+ <dt><tt>dyn_cast_or_null<></tt>: </dt>
+
+ <dd>The <tt>dyn_cast_or_null<></tt> operator works just like the
+ <tt>dyn_cast<></tt> operator, except that it allows for a null pointer
+ as an argument (which it then propagates). This can sometimes be useful,
+ allowing you to combine several null checks into one.</dd>
+
+ </dl>
+
+ <p>These five templates can be used with any classes, whether they have a
+ v-table or not. To add support for these templates, you simply need to add
+ <tt>classof</tt> static methods to the class you are interested casting
+ to. Describing this is currently outside the scope of this document, but there
+ are lots of examples in the LLVM source base.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt> option</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Often when working on your pass you will put a bunch of debugging printouts
+ and other code into your pass. After you get it working, you want to remove
+ it... but you may need it again in the future (to work out new bugs that you run
+ across).</p>
+
+ <p> Naturally, because of this, you don't want to delete the debug printouts,
+ but you don't want them to always be noisy. A standard compromise is to comment
+ them out, allowing you to enable them if you need them in the future.</p>
+
+ <p>The "<tt><a href="/doxygen/Debug_8h-source.html">llvm/Support/Debug.h</a></tt>"
+ file provides a macro named <tt>DEBUG()</tt> that is a much nicer solution to
+ this problem. Basically, you can put arbitrary code into the argument of the
+ <tt>DEBUG</tt> macro, and it is only executed if '<tt>opt</tt>' (or any other
+ tool) is run with the '<tt>-debug</tt>' command line argument:</p>
+
+ <pre> ... <br> DEBUG(std::cerr << "I am here!\n");<br> ...<br></pre>
+
+ <p>Then you can run your pass like this:</p>
+
+ <pre> $ opt < a.bc > /dev/null -mypass<br> <no output><br> $ opt < a.bc > /dev/null -mypass -debug<br> I am here!<br> $<br></pre>
+
+ <p>Using the <tt>DEBUG()</tt> macro instead of a home-brewed solution allows you
+ to not have to create "yet another" command line option for the debug output for
+ your pass. Note that <tt>DEBUG()</tt> macros are disabled for optimized builds,
+ so they do not cause a performance impact at all (for the same reason, they
+ should also not contain side-effects!).</p>
+
+ <p>One additional nice thing about the <tt>DEBUG()</tt> macro is that you can
+ enable or disable it directly in gdb. Just use "<tt>set DebugFlag=0</tt>" or
+ "<tt>set DebugFlag=1</tt>" from the gdb if the program is running. If the
+ program hasn't been started yet, you can always just run it with
+ <tt>-debug</tt>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt> and
+ the <tt>-debug-only</tt> option</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Sometimes you may find yourself in a situation where enabling <tt>-debug</tt>
+ just turns on <b>too much</b> information (such as when working on the code
+ generator). If you want to enable debug information with more fine-grained
+ control, you define the <tt>DEBUG_TYPE</tt> macro and the <tt>-debug</tt> only
+ option as follows:</p>
+
+ <pre> ...<br> DEBUG(std::cerr << "No debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE "foo"<br> DEBUG(std::cerr << "'foo' debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE "bar"<br> DEBUG(std::cerr << "'bar' debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE ""<br> DEBUG(std::cerr << "No debug type (2)\n");<br> ...<br></pre>
+
+ <p>Then you can run your pass like this:</p>
+
+ <pre> $ opt < a.bc > /dev/null -mypass<br> <no output><br> $ opt < a.bc > /dev/null -mypass -debug<br> No debug type<br> 'foo' debug type<br> 'bar' debug type<br> No debug type (2)<br> $ opt < a.bc > /dev/null -mypass -debug-only=foo<br> 'foo' debug type<br> $ opt < a.bc > /dev/null -mypass -debug-only=bar<br> 'bar' debug type<br> $<br></pre>
+
+ <p>Of course, in practice, you should only set <tt>DEBUG_TYPE</tt> at the top of
+ a file, to specify the debug type for the entire module (if you do this before
+ you <tt>#include "llvm/Support/Debug.h"</tt>, you don't have to insert the ugly
+ <tt>#undef</tt>'s). Also, you should use names more meaningful than "foo" and
+ "bar", because there is no system in place to ensure that names do not
+ conflict. If two different modules use the same string, they will all be turned
+ on when the name is specified. This allows, for example, all debug information
+ for instruction scheduling to be enabled with <tt>-debug-type=InstrSched</tt>,
+ even if the source lives in multiple files.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="Statistic">The <tt>Statistic</tt> template & <tt>-stats</tt>
+ option</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The "<tt><a
+ href="/doxygen/Statistic_8h-source.html">llvm/ADT/Statistic.h</a></tt>" file
+ provides a template named <tt>Statistic</tt> that is used as a unified way to
+ keep track of what the LLVM compiler is doing and how effective various
+ optimizations are. It is useful to see what optimizations are contributing to
+ making a particular program run faster.</p>
+
+ <p>Often you may run your pass on some big program, and you're interested to see
+ how many times it makes a certain transformation. Although you can do this with
+ hand inspection, or some ad-hoc method, this is a real pain and not very useful
+ for big programs. Using the <tt>Statistic</tt> template makes it very easy to
+ keep track of this information, and the calculated information is presented in a
+ uniform manner with the rest of the passes being executed.</p>
+
+ <p>There are many examples of <tt>Statistic</tt> uses, but the basics of using
+ it are as follows:</p>
+
+ <ol>
+ <li>Define your statistic like this:
+ <pre>static Statistic<> NumXForms("mypassname", "The # of times I did stuff");<br></pre>
+
+ <p>The <tt>Statistic</tt> template can emulate just about any data-type,
+ but if you do not specify a template argument, it defaults to acting like
+ an unsigned int counter (this is usually what you want).</p></li>
+
+ <li>Whenever you make a transformation, bump the counter:
+ <pre> ++NumXForms; // I did stuff<br></pre>
+ </li>
+ </ol>
+
+ <p>That's all you have to do. To get '<tt>opt</tt>' to print out the
+ statistics gathered, use the '<tt>-stats</tt>' option:</p>
+
+ <pre> $ opt -stats -mypassname < program.bc > /dev/null<br> ... statistic output ...<br></pre>
+
+ <p> When running <tt>gccas</tt> on a C file from the SPEC benchmark
+ suite, it gives a report that looks like this:</p>
+
+ <pre> 7646 bytecodewriter - Number of normal instructions<br> 725 bytecodewriter - Number of oversized instructions<br> 129996 bytecodewriter - Number of bytecode bytes written<br> 2817 raise - Number of insts DCEd or constprop'd<br> 3213 raise - Number of cast-of-self removed<br> 5046 raise - Number of expression trees converted<br> 75 raise - Number of other getelementptr's formed<br> 138 raise - Number of load/store peepholes<br> 42 deadtypeelim - Number of unused typenames removed from symtab<br> 392 funcresolve - Number of varargs functions resolved<br> 27 globaldce - Number of global variables removed<br> 2 adce - Number of basic blocks removed<br> 134 cee - Number of branches revectored<br> 49 cee - Number of setcc instruction eliminated<br> 532 gcse - Number of loads removed<br> 2919 gcse - Number!
of instructions removed<br> 86 indvars - Number of canonical indvars added<br> 87 indvars - Number of aux indvars removed<br> 25 instcombine - Number of dead inst eliminate<br> 434 instcombine - Number of insts combined<br> 248 licm - Number of load insts hoisted<br> 1298 licm - Number of insts hoisted to a loop pre-header<br> 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)<br> 75 mem2reg - Number of alloca's promoted<br> 1444 cfgsimplify - Number of blocks simplified<br></pre>
+
+ <p>Obviously, with so many optimizations, having a unified framework for this
+ stuff is very nice. Making your pass fit well into the framework makes it more
+ maintainable and useful.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="common">Helpful Hints for Common Operations</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This section describes how to perform some very simple transformations of
+ LLVM code. This is meant to give examples of common idioms used, showing the
+ practical side of LLVM transformations. <p> Because this is a "how-to" section,
+ you should also read about the main classes that you will be working with. The
+ <a href="#coreclasses">Core LLVM Class Hierarchy Reference</a> contains details
+ and descriptions of the main classes that you should know about.</p>
+
+ </div>
+
+ <!-- NOTE: this section should be heavy on example code -->
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="inspection">Basic Inspection and Traversal Routines</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The LLVM compiler infrastructure have many different data structures that may
+ be traversed. Following the example of the C++ standard template library, the
+ techniques used to traverse these various data structures are all basically the
+ same. For a enumerable sequence of values, the <tt>XXXbegin()</tt> function (or
+ method) returns an iterator to the start of the sequence, the <tt>XXXend()</tt>
+ function returns an iterator pointing to one past the last valid element of the
+ sequence, and there is some <tt>XXXiterator</tt> data type that is common
+ between the two operations.</p>
+
+ <p>Because the pattern for iteration is common across many different aspects of
+ the program representation, the standard template library algorithms may be used
+ on them, and it is easier to remember how to iterate. First we show a few common
+ examples of the data structures that need to be traversed. Other data
+ structures are traversed in very similar ways.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="iterate_function">Iterating over the </a><a
+ href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a
+ href="#Function"><tt>Function</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>It's quite common to have a <tt>Function</tt> instance that you'd like to
+ transform in some way; in particular, you'd like to manipulate its
+ <tt>BasicBlock</tt>s. To facilitate this, you'll need to iterate over all of
+ the <tt>BasicBlock</tt>s that constitute the <tt>Function</tt>. The following is
+ an example that prints the name of a <tt>BasicBlock</tt> and the number of
+ <tt>Instruction</tt>s it contains:</p>
+
+ <pre> // func is a pointer to a Function instance<br> for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i) {<br><br> // print out the name of the basic block if it has one, and then the<br> // number of instructions that it contains<br><br> cerr << "Basic block (name=" << i->getName() << ") has " <br> << i->size() << " instructions.\n";<br> }<br></pre>
+
+ <p>Note that i can be used as if it were a pointer for the purposes of
+ invoking member functions of the <tt>Instruction</tt> class. This is
+ because the indirection operator is overloaded for the iterator
+ classes. In the above code, the expression <tt>i->size()</tt> is
+ exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="iterate_basicblock">Iterating over the </a><a
+ href="#Instruction"><tt>Instruction</tt></a>s in a <a
+ href="#BasicBlock"><tt>BasicBlock</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Just like when dealing with <tt>BasicBlock</tt>s in <tt>Function</tt>s, it's
+ easy to iterate over the individual instructions that make up
+ <tt>BasicBlock</tt>s. Here's a code snippet that prints out each instruction in
+ a <tt>BasicBlock</tt>:</p>
+
+ <pre>
+ // blk is a pointer to a BasicBlock instance
+ for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
+ // the next statement works since operator<<(ostream&,...)
+ // is overloaded for Instruction&
+ std::cerr << *i << "\n";
+ </pre>
+
+ <p>However, this isn't really the best way to print out the contents of a
+ <tt>BasicBlock</tt>! Since the ostream operators are overloaded for virtually
+ anything you'll care about, you could have just invoked the print routine on the
+ basic block itself: <tt>std::cerr << *blk << "\n";</tt>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="iterate_institer">Iterating over the </a><a
+ href="#Instruction"><tt>Instruction</tt></a>s in a <a
+ href="#Function"><tt>Function</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>If you're finding that you commonly iterate over a <tt>Function</tt>'s
+ <tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s <tt>Instruction</tt>s,
+ <tt>InstIterator</tt> should be used instead. You'll need to include <a
+ href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>,
+ and then instantiate <tt>InstIterator</tt>s explicitly in your code. Here's a
+ small example that shows how to dump all instructions in a function to the standard error stream:<p>
+
+ <pre>#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"<br>...<br>// Suppose F is a ptr to a function<br>for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)<br> cerr << *i << "\n";<br></pre>
+ Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a
+ worklist with its initial contents. For example, if you wanted to
+ initialize a worklist to contain all instructions in a <tt>Function</tt>
+ F, all you would need to do is something like:
+ <pre>std::set<Instruction*> worklist;<br>worklist.insert(inst_begin(F), inst_end(F));<br></pre>
+
+ <p>The STL set <tt>worklist</tt> would now contain all instructions in the
+ <tt>Function</tt> pointed to by F.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="iterate_convert">Turning an iterator into a class pointer (and
+ vice-versa)</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Sometimes, it'll be useful to grab a reference (or pointer) to a class
+ instance when all you've got at hand is an iterator. Well, extracting
+ a reference or a pointer from an iterator is very straight-forward.
+ Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and <tt>j</tt>
+ is a <tt>BasicBlock::const_iterator</tt>:</p>
+
+ <pre> Instruction& inst = *i; // grab reference to instruction reference<br> Instruction* pinst = &*i; // grab pointer to instruction reference<br> const Instruction& inst = *j;<br></pre>
+
+ <p>However, the iterators you'll be working with in the LLVM framework are
+ special: they will automatically convert to a ptr-to-instance type whenever they
+ need to. Instead of dereferencing the iterator and then taking the address of
+ the result, you can simply assign the iterator to the proper pointer type and
+ you get the dereference and address-of operation as a result of the assignment
+ (behind the scenes, this is a result of overloading casting mechanisms). Thus
+ the last line of the last example,</p>
+
+ <pre>Instruction* pinst = &*i;</pre>
+
+ <p>is semantically equivalent to</p>
+
+ <pre>Instruction* pinst = i;</pre>
+
+ <p>It's also possible to turn a class pointer into the corresponding iterator,
+ and this is a constant time operation (very efficient). The following code
+ snippet illustrates use of the conversion constructors provided by LLVM
+ iterators. By using these, you can explicitly grab the iterator of something
+ without actually obtaining it via iteration over some structure:</p>
+
+ <pre>void printNextInstruction(Instruction* inst) {<br> BasicBlock::iterator it(inst);<br> ++it; // after this line, it refers to the instruction after *inst.<br> if (it != inst->getParent()->end()) cerr << *it << "\n";<br>}<br></pre>
+
+ </div>
+
+ <!--_______________________________________________________________________-->
+ <div class="doc_subsubsection">
+ <a name="iterate_complex">Finding call sites: a slightly more complex
+ example</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Say that you're writing a FunctionPass and would like to count all the
+ locations in the entire module (that is, across every <tt>Function</tt>) where a
+ certain function (i.e., some <tt>Function</tt>*) is already in scope. As you'll
+ learn later, you may want to use an <tt>InstVisitor</tt> to accomplish this in a
+ much more straight-forward manner, but this example will allow us to explore how
+ you'd do it if you didn't have <tt>InstVisitor</tt> around. In pseudocode, this
+ is what we want to do:</p>
+
+ <pre>initialize callCounter to zero<br>for each Function f in the Module<br> for each BasicBlock b in f<br> for each Instruction i in b<br> if (i is a CallInst and calls the given function)<br> increment callCounter<br></pre>
+
+ <p>And the actual code is (remember, since we're writing a
+ <tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply has to
+ override the <tt>runOnFunction</tt> method...):</p>
+
+ <pre>Function* targetFunc = ...;<br><br>class OurFunctionPass : public FunctionPass {<br> public:<br> OurFunctionPass(): callCounter(0) { }<br><br> virtual runOnFunction(Function& F) {<br> for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {<br> for (BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {<br> if (<a
+ href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a
+ href="#CallInst">CallInst</a>>(&*i)) {<br> // we know we've encountered a call instruction, so we<br> // need to determine if it's a call to the<br> // function pointed to by m_func or not.<br> <br> if (callInst->getCalledFunction() == targetFunc)<br> ++callCounter;<br> }<br> }<br> }<br> <br> private:<br> unsigned callCounter;<br>};<br></pre>
+
+ </div>
+
+ <!--_______________________________________________________________________-->
+ <div class="doc_subsubsection">
+ <a name="calls_and_invokes">Treating calls and invokes the same way</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>You may have noticed that the previous example was a bit oversimplified in
+ that it did not deal with call sites generated by 'invoke' instructions. In
+ this, and in other situations, you may find that you want to treat
+ <tt>CallInst</tt>s and <tt>InvokeInst</tt>s the same way, even though their
+ most-specific common base class is <tt>Instruction</tt>, which includes lots of
+ less closely-related things. For these cases, LLVM provides a handy wrapper
+ class called <a
+ href="http://llvm.cs.uiuc.edu/doxygen/classllvm_1_1CallSite.html"><tt>CallSite</tt></a>.
+ It is essentially a wrapper around an <tt>Instruction</tt> pointer, with some
+ methods that provide functionality common to <tt>CallInst</tt>s and
+ <tt>InvokeInst</tt>s.</p>
+
+ <p>This class has "value semantics": it should be passed by value, not by
+ reference and it should not be dynamically allocated or deallocated using
+ <tt>operator new</tt> or <tt>operator delete</tt>. It is efficiently copyable,
+ assignable and constructable, with costs equivalents to that of a bare pointer.
+ If you look at its definition, it has only a single pointer member.</p>
+
+ </div>
+
+ <!--_______________________________________________________________________-->
+ <div class="doc_subsubsection">
+ <a name="iterate_chains">Iterating over def-use & use-def chains</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Frequently, we might have an instance of the <a
+ href="/doxygen/structllvm_1_1Value.html">Value Class</a> and we want to
+ determine which <tt>User</tt>s use the <tt>Value</tt>. The list of all
+ <tt>User</tt>s of a particular <tt>Value</tt> is called a <i>def-use</i> chain.
+ For example, let's say we have a <tt>Function*</tt> named <tt>F</tt> to a
+ particular function <tt>foo</tt>. Finding all of the instructions that
+ <i>use</i> <tt>foo</tt> is as simple as iterating over the <i>def-use</i> chain
+ of <tt>F</tt>:</p>
+
+ <pre>Function* F = ...;<br><br>for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) {<br> if (Instruction *Inst = dyn_cast<Instruction>(*i)) {<br> cerr << "F is used in instruction:\n";<br> cerr << *Inst << "\n";<br> }<br>}<br></pre>
+
+ <p>Alternately, it's common to have an instance of the <a
+ href="/doxygen/classllvm_1_1User.html">User Class</a> and need to know what
+ <tt>Value</tt>s are used by it. The list of all <tt>Value</tt>s used by a
+ <tt>User</tt> is known as a <i>use-def</i> chain. Instances of class
+ <tt>Instruction</tt> are common <tt>User</tt>s, so we might want to iterate over
+ all of the values that a particular instruction uses (that is, the operands of
+ the particular <tt>Instruction</tt>):</p>
+
+ <pre>Instruction* pi = ...;<br><br>for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {<br> Value* v = *i;<br> ...<br>}<br></pre>
+
+ <!--
+ def-use chains ("finding all users of"): Value::use_begin/use_end
+ use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
+ -->
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="simplechanges">Making simple changes</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>There are some primitive transformation operations present in the LLVM
+ infrastructure that are worth knowing about. When performing
+ transformations, it's fairly common to manipulate the contents of basic
+ blocks. This section describes some of the common methods for doing so
+ and gives example code.</p>
+
+ </div>
+
+ <!--_______________________________________________________________________-->
+ <div class="doc_subsubsection">
+ <a name="schanges_creating">Creating and inserting new
+ <tt>Instruction</tt>s</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><i>Instantiating Instructions</i></p>
+
+ <p>Creation of <tt>Instruction</tt>s is straight-forward: simply call the
+ constructor for the kind of instruction to instantiate and provide the necessary
+ parameters. For example, an <tt>AllocaInst</tt> only <i>requires</i> a
+ (const-ptr-to) <tt>Type</tt>. Thus:</p>
+
+ <pre>AllocaInst* ai = new AllocaInst(Type::IntTy);</pre>
+
+ <p>will create an <tt>AllocaInst</tt> instance that represents the allocation of
+ one integer in the current stack frame, at runtime. Each <tt>Instruction</tt>
+ subclass is likely to have varying default parameters which change the semantics
+ of the instruction, so refer to the <a
+ href="/doxygen/classllvm_1_1Instruction.html">doxygen documentation for the subclass of
+ Instruction</a> that you're interested in instantiating.</p>
+
+ <p><i>Naming values</i></p>
+
+ <p>It is very useful to name the values of instructions when you're able to, as
+ this facilitates the debugging of your transformations. If you end up looking
+ at generated LLVM machine code, you definitely want to have logical names
+ associated with the results of instructions! By supplying a value for the
+ <tt>Name</tt> (default) parameter of the <tt>Instruction</tt> constructor, you
+ associate a logical name with the result of the instruction's execution at
+ runtime. For example, say that I'm writing a transformation that dynamically
+ allocates space for an integer on the stack, and that integer is going to be
+ used as some kind of index by some other code. To accomplish this, I place an
+ <tt>AllocaInst</tt> at the first point in the first <tt>BasicBlock</tt> of some
+ <tt>Function</tt>, and I'm intending to use it within the same
+ <tt>Function</tt>. I might do:</p>
+
+ <pre>AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");</pre>
+
+ <p>where <tt>indexLoc</tt> is now the logical name of the instruction's
+ execution value, which is a pointer to an integer on the runtime stack.</p>
+
+ <p><i>Inserting instructions</i></p>
+
+ <p>There are essentially two ways to insert an <tt>Instruction</tt>
+ into an existing sequence of instructions that form a <tt>BasicBlock</tt>:</p>
+
+ <ul>
+ <li>Insertion into an explicit instruction list
+
+ <p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within that
+ <tt>BasicBlock</tt>, and a newly-created instruction we wish to insert
+ before <tt>*pi</tt>, we do the following: </p>
+
+ <pre> BasicBlock *pb = ...;<br> Instruction *pi = ...;<br> Instruction *newInst = new Instruction(...);<br> pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb<br></pre>
+
+ <p>Appending to the end of a <tt>BasicBlock</tt> is so common that
+ the <tt>Instruction</tt> class and <tt>Instruction</tt>-derived
+ classes provide constructors which take a pointer to a
+ <tt>BasicBlock</tt> to be appended to. For example code that
+ looked like: </p>
+
+ <pre> BasicBlock *pb = ...;<br> Instruction *newInst = new Instruction(...);<br> pb->getInstList().push_back(newInst); // appends newInst to pb<br></pre>
+
+ <p>becomes: </p>
+
+ <pre> BasicBlock *pb = ...;<br> Instruction *newInst = new Instruction(..., pb);<br></pre>
+
+ <p>which is much cleaner, especially if you are creating
+ long instruction streams.</p></li>
+
+ <li>Insertion into an implicit instruction list
+
+ <p><tt>Instruction</tt> instances that are already in <tt>BasicBlock</tt>s
+ are implicitly associated with an existing instruction list: the instruction
+ list of the enclosing basic block. Thus, we could have accomplished the same
+ thing as the above code without being given a <tt>BasicBlock</tt> by doing:
+ </p>
+
+ <pre> Instruction *pi = ...;<br> Instruction *newInst = new Instruction(...);<br> pi->getParent()->getInstList().insert(pi, newInst);<br></pre>
+
+ <p>In fact, this sequence of steps occurs so frequently that the
+ <tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes provide
+ constructors which take (as a default parameter) a pointer to an
+ <tt>Instruction</tt> which the newly-created <tt>Instruction</tt> should
+ precede. That is, <tt>Instruction</tt> constructors are capable of
+ inserting the newly-created instance into the <tt>BasicBlock</tt> of a
+ provided instruction, immediately before that instruction. Using an
+ <tt>Instruction</tt> constructor with a <tt>insertBefore</tt> (default)
+ parameter, the above code becomes:</p>
+
+ <pre>Instruction* pi = ...;<br>Instruction* newInst = new Instruction(..., pi);<br></pre>
+
+ <p>which is much cleaner, especially if you're creating a lot of
+ instructions and adding them to <tt>BasicBlock</tt>s.</p></li>
+ </ul>
+
+ </div>
+
+ <!--_______________________________________________________________________-->
+ <div class="doc_subsubsection">
+ <a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Deleting an instruction from an existing sequence of instructions that form a
+ <a href="#BasicBlock"><tt>BasicBlock</tt></a> is very straight-forward. First,
+ you must have a pointer to the instruction that you wish to delete. Second, you
+ need to obtain the pointer to that instruction's basic block. You use the
+ pointer to the basic block to get its list of instructions and then use the
+ erase function to remove your instruction. For example:</p>
+
+ <pre> <a href="#Instruction">Instruction</a> *I = .. ;<br> <a
+ href="#BasicBlock">BasicBlock</a> *BB = I->getParent();<br> BB->getInstList().erase(I);<br></pre>
+
+ </div>
+
+ <!--_______________________________________________________________________-->
+ <div class="doc_subsubsection">
+ <a name="schanges_replacing">Replacing an <tt>Instruction</tt> with another
+ <tt>Value</tt></a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><i>Replacing individual instructions</i></p>
+
+ <p>Including "<a href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>"
+ permits use of two very useful replace functions: <tt>ReplaceInstWithValue</tt>
+ and <tt>ReplaceInstWithInst</tt>.</p>
+
+ <h4><a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a></h4>
+
+ <ul>
+ <li><tt>ReplaceInstWithValue</tt>
+
+ <p>This function replaces all uses (within a basic block) of a given
+ instruction with a value, and then removes the original instruction. The
+ following example illustrates the replacement of the result of a particular
+ <tt>AllocaInst</tt> that allocates memory for a single integer with a null
+ pointer to an integer.</p>
+
+ <pre>AllocaInst* instToReplace = ...;<br>BasicBlock::iterator ii(instToReplace);<br>ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,<br> Constant::getNullValue(PointerType::get(Type::IntTy)));<br></pre></li>
+
+ <li><tt>ReplaceInstWithInst</tt>
+
+ <p>This function replaces a particular instruction with another
+ instruction. The following example illustrates the replacement of one
+ <tt>AllocaInst</tt> with another.</p>
+
+ <pre>AllocaInst* instToReplace = ...;<br>BasicBlock::iterator ii(instToReplace);<br>ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,<br> new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));<br></pre></li>
+ </ul>
+
+ <p><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></p>
+
+ <p>You can use <tt>Value::replaceAllUsesWith</tt> and
+ <tt>User::replaceUsesOfWith</tt> to change more than one use at a time. See the
+ doxygen documentation for the <a href="/doxygen/structllvm_1_1Value.html">Value Class</a>
+ and <a href="/doxygen/classllvm_1_1User.html">User Class</a>, respectively, for more
+ information.</p>
+
+ <!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
+ include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
+ ReplaceInstWithValue, ReplaceInstWithInst -->
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="advanced">Advanced Topics</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+ <p>
+ This section describes some of the advanced or obscure API's that most clients
+ do not need to be aware of. These API's tend manage the inner workings of the
+ LLVM system, and only need to be accessed in unusual circumstances.
+ </p>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="TypeResolve">LLVM Type Resolution</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ The LLVM type system has a very simple goal: allow clients to compare types for
+ structural equality with a simple pointer comparison (aka a shallow compare).
+ This goal makes clients much simpler and faster, and is used throughout the LLVM
+ system.
+ </p>
+
+ <p>
+ Unfortunately achieving this goal is not a simple matter. In particular,
+ recursive types and late resolution of opaque types makes the situation very
+ difficult to handle. Fortunately, for the most part, our implementation makes
+ most clients able to be completely unaware of the nasty internal details. The
+ primary case where clients are exposed to the inner workings of it are when
+ building a recursive type. In addition to this case, the LLVM bytecode reader,
+ assembly parser, and linker also have to be aware of the inner workings of this
+ system.
+ </p>
+
+ <p>
+ For our purposes below, we need three concepts. First, an "Opaque Type" is
+ exactly as defined in the <a href="LangRef.html#t_opaque">language
+ reference</a>. Second an "Abstract Type" is any type which includes an
+ opaque type as part of its type graph (for example "<tt>{ opaque, int }</tt>").
+ Third, a concrete type is a type that is not an abstract type (e.g. "<tt>[ int,
+ float }</tt>").
+ </p>
+
+ </div>
+
+ <!-- ______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="BuildRecType">Basic Recursive Type Construction</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ Because the most common question is "how do I build a recursive type with LLVM",
+ we answer it now and explain it as we go. Here we include enough to cause this
+ to be emitted to an output .ll file:
+ </p>
+
+ <pre>
+ %mylist = type { %mylist*, int }
+ </pre>
+
+ <p>
+ To build this, use the following LLVM APIs:
+ </p>
+
+ <pre>
+ //<i> Create the initial outer struct.</i>
+ <a href="#PATypeHolder">PATypeHolder</a> StructTy = OpaqueType::get();
+ std::vector<const Type*> Elts;
+ Elts.push_back(PointerType::get(StructTy));
+ Elts.push_back(Type::IntTy);
+ StructType *NewSTy = StructType::get(Elts);
+
+ //<i> At this point, NewSTy = "{ opaque*, int }". Tell VMCore that</i>
+ //<i> the struct and the opaque type are actually the same.</i>
+ cast<OpaqueType>(StructTy.get())-><a href="#refineAbstractTypeTo">refineAbstractTypeTo</a>(NewSTy);
+
+ // <i>NewSTy is potentially invalidated, but StructTy (a <a href="#PATypeHolder">PATypeHolder</a>) is</i>
+ // <i>kept up-to-date.</i>
+ NewSTy = cast<StructType>(StructTy.get());
+
+ // <i>Add a name for the type to the module symbol table (optional).</i>
+ MyModule->addTypeName("mylist", NewSTy);
+ </pre>
+
+ <p>
+ This code shows the basic approach used to build recursive types: build a
+ non-recursive type using 'opaque', then use type unification to close the cycle.
+ The type unification step is performed by the <tt><a
+ ref="#refineAbstractTypeTo">refineAbstractTypeTo</a></tt> method, which is
+ described next. After that, we describe the <a
+ href="#PATypeHolder">PATypeHolder class</a>.
+ </p>
+
+ </div>
+
+ <!-- ______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="refineAbstractTypeTo">The <tt>refineAbstractTypeTo</tt> method</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ The <tt>refineAbstractTypeTo</tt> method starts the type unification process.
+ While this method is actually a member of the DerivedType class, it is most
+ often used on OpaqueType instances. Type unification is actually a recursive
+ process. After unification, types can become structurally isomorphic to
+ existing types, and all duplicates are deleted (to preserve pointer equality).
+ </p>
+
+ <p>
+ In the example above, the OpaqueType object is definitely deleted.
+ Additionally, if there is an "{ \2*, int}" type already created in the system,
+ the pointer and struct type created are <b>also</b> deleted. Obviously whenever
+ a type is deleted, any "Type*" pointers in the program are invalidated. As
+ such, it is safest to avoid having <i>any</i> "Type*" pointers to abstract types
+ live across a call to <tt>refineAbstractTypeTo</tt> (note that non-abstract
+ types can never move or be deleted). To deal with this, the <a
+ href="#PATypeHolder">PATypeHolder</a> class is used to maintain a stable
+ reference to a possibly refined type, and the <a
+ href="#AbstractTypeUser">AbstractTypeUser</a> class is used to update more
+ complex datastructures.
+ </p>
+
+ </div>
+
+ <!-- ______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="PATypeHolder">The PATypeHolder Class</a>
+ </div>
+
+ <div class="doc_text">
+ <p>
+ PATypeHolder is a form of a "smart pointer" for Type objects. When VMCore
+ happily goes about nuking types that become isomorphic to existing types, it
+ automatically updates all PATypeHolder objects to point to the new type. In the
+ example above, this allows the code to maintain a pointer to the resultant
+ resolved recursive type, even though the Type*'s are potentially invalidated.
+ </p>
+
+ <p>
+ PATypeHolder is an extremely light-weight object that uses a lazy union-find
+ implementation to update pointers. For example the pointer from a Value to its
+ Type is maintained by PATypeHolder objects.
+ </p>
+
+ </div>
+
+ <!-- ______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="AbstractTypeUser">The AbstractTypeUser Class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ Some data structures need more to perform more complex updates when types get
+ resolved. The <a href="#SymbolTable">SymbolTable</a> class, for example, needs
+ move and potentially merge type planes in its representation when a pointer
+ changes.</p>
+
+ <p>
+ To support this, a class can derive from the AbstractTypeUser class. This class
+ allows it to get callbacks when certain types are resolved. To register to get
+ callbacks for a particular type, the DerivedType::{add/remove}AbstractTypeUser
+ methods can be called on a type. Note that these methods only work for <i>
+ abstract</i> types. Concrete types (those that do not include an opaque objects
+ somewhere) can never be refined.
+ </p>
+ </div>
+
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="SymbolTable">The <tt>SymbolTable</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+ <p>This class provides a symbol table that the <a
+ href="#Function"><tt>Function</tt></a> and <a href="#Module">
+ <tt>Module</tt></a> classes use for naming definitions. The symbol table can
+ provide a name for any <a href="#Value"><tt>Value</tt></a> or <a
+ href="#Type"><tt>Type</tt></a>. <tt>SymbolTable</tt> is an abstract data
+ type. It hides the data it contains and provides access to it through a
+ controlled interface.</p>
+
+ <p>Note that the symbol table class is should not be directly accessed by most
+ clients. It should only be used when iteration over the symbol table names
+ themselves are required, which is very special purpose. Note that not all LLVM
+ <a href="#Value">Value</a>s have names, and those without names (i.e. they have
+ an empty name) do not exist in the symbol table.
+ </p>
+
+ <p>To use the <tt>SymbolTable</tt> well, you need to understand the
+ structure of the information it holds. The class contains two
+ <tt>std::map</tt> objects. The first, <tt>pmap</tt>, is a map of
+ <tt>Type*</tt> to maps of name (<tt>std::string</tt>) to <tt>Value*</tt>.
+ The second, <tt>tmap</tt>, is a map of names to <tt>Type*</tt>. Thus, Values
+ are stored in two-dimensions and accessed by <tt>Type</tt> and name. Types,
+ however, are stored in a single dimension and accessed only by name.</p>
+
+ <p>The interface of this class provides three basic types of operations:
+ <ol>
+ <li><em>Accessors</em>. Accessors provide read-only access to information
+ such as finding a value for a name with the
+ <a href="#SymbolTable_lookup">lookup</a> method.</li>
+ <li><em>Mutators</em>. Mutators allow the user to add information to the
+ <tt>SymbolTable</tt> with methods like
+ <a href="#SymbolTable_insert"><tt>insert</tt></a>.</li>
+ <li><em>Iterators</em>. Iterators allow the user to traverse the content
+ of the symbol table in well defined ways, such as the method
+ <a href="#SymbolTable_type_begin"><tt>type_begin</tt></a>.</li>
+ </ol>
+
+ <h3>Accessors</h3>
+ <dl>
+ <dt><tt>Value* lookup(const Type* Ty, const std::string& name) const</tt>:
+ </dt>
+ <dd>The <tt>lookup</tt> method searches the type plane given by the
+ <tt>Ty</tt> parameter for a <tt>Value</tt> with the provided <tt>name</tt>.
+ If a suitable <tt>Value</tt> is not found, null is returned.</dd>
+
+ <dt><tt>Type* lookupType( const std::string& name) const</tt>:</dt>
+ <dd>The <tt>lookupType</tt> method searches through the types for a
+ <tt>Type</tt> with the provided <tt>name</tt>. If a suitable <tt>Type</tt>
+ is not found, null is returned.</dd>
+
+ <dt><tt>bool hasTypes() const</tt>:</dt>
+ <dd>This function returns true if an entry has been made into the type
+ map.</dd>
+
+ <dt><tt>bool isEmpty() const</tt>:</dt>
+ <dd>This function returns true if both the value and types maps are
+ empty</dd>
+ </dl>
+
+ <h3>Mutators</h3>
+ <dl>
+ <dt><tt>void insert(Value *Val)</tt>:</dt>
+ <dd>This method adds the provided value to the symbol table. The Value must
+ have both a name and a type which are extracted and used to place the value
+ in the correct type plane under the value's name.</dd>
+
+ <dt><tt>void insert(const std::string& Name, Value *Val)</tt>:</dt>
+ <dd> Inserts a constant or type into the symbol table with the specified
+ name. There can be a many to one mapping between names and constants
+ or types.</dd>
+
+ <dt><tt>void insert(const std::string& Name, Type *Typ)</tt>:</dt>
+ <dd> Inserts a type into the symbol table with the specified name. There
+ can be a many-to-one mapping between names and types. This method
+ allows a type with an existing entry in the symbol table to get
+ a new name.</dd>
+
+ <dt><tt>void remove(Value* Val)</tt>:</dt>
+ <dd> This method removes a named value from the symbol table. The
+ type and name of the Value are extracted from \p N and used to
+ lookup the Value in the correct type plane. If the Value is
+ not in the symbol table, this method silently ignores the
+ request.</dd>
+
+ <dt><tt>void remove(Type* Typ)</tt>:</dt>
+ <dd> This method removes a named type from the symbol table. The
+ name of the type is extracted from \P T and used to look up
+ the Type in the type map. If the Type is not in the symbol
+ table, this method silently ignores the request.</dd>
+
+ <dt><tt>Value* remove(const std::string& Name, Value *Val)</tt>:</dt>
+ <dd> Remove a constant or type with the specified name from the
+ symbol table.</dd>
+
+ <dt><tt>Type* remove(const std::string& Name, Type* T)</tt>:</dt>
+ <dd> Remove a type with the specified name from the symbol table.
+ Returns the removed Type.</dd>
+
+ <dt><tt>Value *value_remove(const value_iterator& It)</tt>:</dt>
+ <dd> Removes a specific value from the symbol table.
+ Returns the removed value.</dd>
+
+ <dt><tt>bool strip()</tt>:</dt>
+ <dd> This method will strip the symbol table of its names leaving
+ the type and values. </dd>
+
+ <dt><tt>void clear()</tt>:</dt>
+ <dd>Empty the symbol table completely.</dd>
+ </dl>
+
+ <h3>Iteration</h3>
+ <p>The following functions describe three types of iterators you can obtain
+ the beginning or end of the sequence for both const and non-const. It is
+ important to keep track of the different kinds of iterators. There are
+ three idioms worth pointing out:</p>
+ <table>
+ <tr><th>Units</th><th>Iterator</th><th>Idiom</th></tr>
+ <tr>
+ <td align="left">Planes Of name/Value maps</td><td>PI</td>
+ <td align="left"><pre><tt>
+ for (SymbolTable::plane_const_iterator PI = ST.plane_begin(),
+ PE = ST.plane_end(); PI != PE; ++PI ) {
+ PI->first // This is the Type* of the plane
+ PI->second // This is the SymbolTable::ValueMap of name/Value pairs
+ </tt></pre></td>
+ </tr>
+ <tr>
+ <td align="left">All name/Type Pairs</td><td>TI</td>
+ <td align="left"><pre><tt>
+ for (SymbolTable::type_const_iterator TI = ST.type_begin(),
+ TE = ST.type_end(); TI != TE; ++TI )
+ TI->first // This is the name of the type
+ TI->second // This is the Type* value associated with the name
+ </tt></pre></td>
+ </tr>
+ <tr>
+ <td align="left">name/Value pairs in a plane</td><td>VI</td>
+ <td align="left"><pre><tt>
+ for (SymbolTable::value_const_iterator VI = ST.value_begin(SomeType),
+ VE = ST.value_end(SomeType); VI != VE; ++VI )
+ VI->first // This is the name of the Value
+ VI->second // This is the Value* value associated with the name
+ </tt></pre></td>
+ </tr>
+ </table>
+
+ <p>Using the recommended iterator names and idioms will help you avoid
+ making mistakes. Of particular note, make sure that whenever you use
+ value_begin(SomeType) that you always compare the resulting iterator
+ with value_end(SomeType) not value_end(SomeOtherType) or else you
+ will loop infinitely.</p>
+
+ <dl>
+
+ <dt><tt>plane_iterator plane_begin()</tt>:</dt>
+ <dd>Get an iterator that starts at the beginning of the type planes.
+ The iterator will iterate over the Type/ValueMap pairs in the
+ type planes. </dd>
+
+ <dt><tt>plane_const_iterator plane_begin() const</tt>:</dt>
+ <dd>Get a const_iterator that starts at the beginning of the type
+ planes. The iterator will iterate over the Type/ValueMap pairs
+ in the type planes. </dd>
+
+ <dt><tt>plane_iterator plane_end()</tt>:</dt>
+ <dd>Get an iterator at the end of the type planes. This serves as
+ the marker for end of iteration over the type planes.</dd>
+
+ <dt><tt>plane_const_iterator plane_end() const</tt>:</dt>
+ <dd>Get a const_iterator at the end of the type planes. This serves as
+ the marker for end of iteration over the type planes.</dd>
+
+ <dt><tt>value_iterator value_begin(const Type *Typ)</tt>:</dt>
+ <dd>Get an iterator that starts at the beginning of a type plane.
+ The iterator will iterate over the name/value pairs in the type plane.
+ Note: The type plane must already exist before using this.</dd>
+
+ <dt><tt>value_const_iterator value_begin(const Type *Typ) const</tt>:</dt>
+ <dd>Get a const_iterator that starts at the beginning of a type plane.
+ The iterator will iterate over the name/value pairs in the type plane.
+ Note: The type plane must already exist before using this.</dd>
+
+ <dt><tt>value_iterator value_end(const Type *Typ)</tt>:</dt>
+ <dd>Get an iterator to the end of a type plane. This serves as the marker
+ for end of iteration of the type plane.
+ Note: The type plane must already exist before using this.</dd>
+
+ <dt><tt>value_const_iterator value_end(const Type *Typ) const</tt>:</dt>
+ <dd>Get a const_iterator to the end of a type plane. This serves as the
+ marker for end of iteration of the type plane.
+ Note: the type plane must already exist before using this.</dd>
+
+ <dt><tt>type_iterator type_begin()</tt>:</dt>
+ <dd>Get an iterator to the start of the name/Type map.</dd>
+
+ <dt><tt>type_const_iterator type_begin() cons</tt>:</dt>
+ <dd> Get a const_iterator to the start of the name/Type map.</dd>
+
+ <dt><tt>type_iterator type_end()</tt>:</dt>
+ <dd>Get an iterator to the end of the name/Type map. This serves as the
+ marker for end of iteration of the types.</dd>
+
+ <dt><tt>type_const_iterator type_end() const</tt>:</dt>
+ <dd>Get a const-iterator to the end of the name/Type map. This serves
+ as the marker for end of iteration of the types.</dd>
+
+ <dt><tt>plane_const_iterator find(const Type* Typ ) const</tt>:</dt>
+ <dd>This method returns a plane_const_iterator for iteration over
+ the type planes starting at a specific plane, given by \p Ty.</dd>
+
+ <dt><tt>plane_iterator find( const Type* Typ </tt>:</dt>
+ <dd>This method returns a plane_iterator for iteration over the
+ type planes starting at a specific plane, given by \p Ty.</dd>
+
+ </dl>
+ </div>
+
+
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="coreclasses">The Core LLVM Class Hierarchy Reference </a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The Core LLVM classes are the primary means of representing the program
+ being inspected or transformed. The core LLVM classes are defined in
+ header files in the <tt>include/llvm/</tt> directory, and implemented in
+ the <tt>lib/VMCore</tt> directory.</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="Value">The <tt>Value</tt> class</a>
+ </div>
+
+ <div>
+
+ <p><tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt>
+ <br>
+ doxygen info: <a href="/doxygen/structllvm_1_1Value.html">Value Class</a></p>
+
+ <p>The <tt>Value</tt> class is the most important class in the LLVM Source
+ base. It represents a typed value that may be used (among other things) as an
+ operand to an instruction. There are many different types of <tt>Value</tt>s,
+ such as <a href="#Constant"><tt>Constant</tt></a>s,<a
+ href="#Argument"><tt>Argument</tt></a>s. Even <a
+ href="#Instruction"><tt>Instruction</tt></a>s and <a
+ href="#Function"><tt>Function</tt></a>s are <tt>Value</tt>s.</p>
+
+ <p>A particular <tt>Value</tt> may be used many times in the LLVM representation
+ for a program. For example, an incoming argument to a function (represented
+ with an instance of the <a href="#Argument">Argument</a> class) is "used" by
+ every instruction in the function that references the argument. To keep track
+ of this relationship, the <tt>Value</tt> class keeps a list of all of the <a
+ href="#User"><tt>User</tt></a>s that is using it (the <a
+ href="#User"><tt>User</tt></a> class is a base class for all nodes in the LLVM
+ graph that can refer to <tt>Value</tt>s). This use list is how LLVM represents
+ def-use information in the program, and is accessible through the <tt>use_</tt>*
+ methods, shown below.</p>
+
+ <p>Because LLVM is a typed representation, every LLVM <tt>Value</tt> is typed,
+ and this <a href="#Type">Type</a> is available through the <tt>getType()</tt>
+ method. In addition, all LLVM values can be named. The "name" of the
+ <tt>Value</tt> is a symbolic string printed in the LLVM code:</p>
+
+ <pre> %<b>foo</b> = add int 1, 2<br></pre>
+
+ <p><a name="#nameWarning">The name of this instruction is "foo".</a> <b>NOTE</b>
+ that the name of any value may be missing (an empty string), so names should
+ <b>ONLY</b> be used for debugging (making the source code easier to read,
+ debugging printouts), they should not be used to keep track of values or map
+ between them. For this purpose, use a <tt>std::map</tt> of pointers to the
+ <tt>Value</tt> itself instead.</p>
+
+ <p>One important aspect of LLVM is that there is no distinction between an SSA
+ variable and the operation that produces it. Because of this, any reference to
+ the value produced by an instruction (or the value available as an incoming
+ argument, for example) is represented as a direct pointer to the instance of
+ the class that
+ represents this value. Although this may take some getting used to, it
+ simplifies the representation and makes it easier to manipulate.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_Value">Important Public Members of the <tt>Value</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><tt>Value::use_iterator</tt> - Typedef for iterator over the
+ use-list<br>
+ <tt>Value::use_const_iterator</tt> - Typedef for const_iterator over
+ the use-list<br>
+ <tt>unsigned use_size()</tt> - Returns the number of users of the
+ value.<br>
+ <tt>bool use_empty()</tt> - Returns true if there are no users.<br>
+ <tt>use_iterator use_begin()</tt> - Get an iterator to the start of
+ the use-list.<br>
+ <tt>use_iterator use_end()</tt> - Get an iterator to the end of the
+ use-list.<br>
+ <tt><a href="#User">User</a> *use_back()</tt> - Returns the last
+ element in the list.
+ <p> These methods are the interface to access the def-use
+ information in LLVM. As with all other iterators in LLVM, the naming
+ conventions follow the conventions defined by the <a href="#stl">STL</a>.</p>
+ </li>
+ <li><tt><a href="#Type">Type</a> *getType() const</tt>
+ <p>This method returns the Type of the Value.</p>
+ </li>
+ <li><tt>bool hasName() const</tt><br>
+ <tt>std::string getName() const</tt><br>
+ <tt>void setName(const std::string &Name)</tt>
+ <p> This family of methods is used to access and assign a name to a <tt>Value</tt>,
+ be aware of the <a href="#nameWarning">precaution above</a>.</p>
+ </li>
+ <li><tt>void replaceAllUsesWith(Value *V)</tt>
+
+ <p>This method traverses the use list of a <tt>Value</tt> changing all <a
+ href="#User"><tt>User</tt>s</a> of the current value to refer to
+ "<tt>V</tt>" instead. For example, if you detect that an instruction always
+ produces a constant value (for example through constant folding), you can
+ replace all uses of the instruction with the constant like this:</p>
+
+ <pre> Inst->replaceAllUsesWith(ConstVal);<br></pre>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="User">The <tt>User</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>
+ <tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt><br>
+ doxygen info: <a href="/doxygen/classllvm_1_1User.html">User Class</a><br>
+ Superclass: <a href="#Value"><tt>Value</tt></a></p>
+
+ <p>The <tt>User</tt> class is the common base class of all LLVM nodes that may
+ refer to <a href="#Value"><tt>Value</tt></a>s. It exposes a list of "Operands"
+ that are all of the <a href="#Value"><tt>Value</tt></a>s that the User is
+ referring to. The <tt>User</tt> class itself is a subclass of
+ <tt>Value</tt>.</p>
+
+ <p>The operands of a <tt>User</tt> point directly to the LLVM <a
+ href="#Value"><tt>Value</tt></a> that it refers to. Because LLVM uses Static
+ Single Assignment (SSA) form, there can only be one definition referred to,
+ allowing this direct connection. This connection provides the use-def
+ information in LLVM.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_User">Important Public Members of the <tt>User</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>The <tt>User</tt> class exposes the operand list in two ways: through
+ an index access interface and through an iterator based interface.</p>
+
+ <ul>
+ <li><tt>Value *getOperand(unsigned i)</tt><br>
+ <tt>unsigned getNumOperands()</tt>
+ <p> These two methods expose the operands of the <tt>User</tt> in a
+ convenient form for direct access.</p></li>
+
+ <li><tt>User::op_iterator</tt> - Typedef for iterator over the operand
+ list<br>
+ <tt>op_iterator op_begin()</tt> - Get an iterator to the start of
+ the operand list.<br>
+ <tt>op_iterator op_end()</tt> - Get an iterator to the end of the
+ operand list.
+ <p> Together, these methods make up the iterator based interface to
+ the operands of a <tt>User</tt>.</p></li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="Instruction">The <tt>Instruction</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>#include "</tt><tt><a
+ href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt><br>
+ doxygen info: <a href="/doxygen/classllvm_1_1Instruction.html">Instruction Class</a><br>
+ Superclasses: <a href="#User"><tt>User</tt></a>, <a
+ href="#Value"><tt>Value</tt></a></p>
+
+ <p>The <tt>Instruction</tt> class is the common base class for all LLVM
+ instructions. It provides only a few methods, but is a very commonly used
+ class. The primary data tracked by the <tt>Instruction</tt> class itself is the
+ opcode (instruction type) and the parent <a
+ href="#BasicBlock"><tt>BasicBlock</tt></a> the <tt>Instruction</tt> is embedded
+ into. To represent a specific type of instruction, one of many subclasses of
+ <tt>Instruction</tt> are used.</p>
+
+ <p> Because the <tt>Instruction</tt> class subclasses the <a
+ href="#User"><tt>User</tt></a> class, its operands can be accessed in the same
+ way as for other <a href="#User"><tt>User</tt></a>s (with the
+ <tt>getOperand()</tt>/<tt>getNumOperands()</tt> and
+ <tt>op_begin()</tt>/<tt>op_end()</tt> methods).</p> <p> An important file for
+ the <tt>Instruction</tt> class is the <tt>llvm/Instruction.def</tt> file. This
+ file contains some meta-data about the various different types of instructions
+ in LLVM. It describes the enum values that are used as opcodes (for example
+ <tt>Instruction::Add</tt> and <tt>Instruction::SetLE</tt>), as well as the
+ concrete sub-classes of <tt>Instruction</tt> that implement the instruction (for
+ example <tt><a href="#BinaryOperator">BinaryOperator</a></tt> and <tt><a
+ href="#SetCondInst">SetCondInst</a></tt>). Unfortunately, the use of macros in
+ this file confuses doxygen, so these enum values don't show up correctly in the
+ <a href="/doxygen/classllvm_1_1Instruction.html">doxygen output</a>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_Instruction">Important Public Members of the <tt>Instruction</tt>
+ class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt>
+ <p>Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that
+ this <tt>Instruction</tt> is embedded into.</p></li>
+ <li><tt>bool mayWriteToMemory()</tt>
+ <p>Returns true if the instruction writes to memory, i.e. it is a
+ <tt>call</tt>,<tt>free</tt>,<tt>invoke</tt>, or <tt>store</tt>.</p></li>
+ <li><tt>unsigned getOpcode()</tt>
+ <p>Returns the opcode for the <tt>Instruction</tt>.</p></li>
+ <li><tt><a href="#Instruction">Instruction</a> *clone() const</tt>
+ <p>Returns another instance of the specified instruction, identical
+ in all ways to the original except that the instruction has no parent
+ (ie it's not embedded into a <a href="#BasicBlock"><tt>BasicBlock</tt></a>),
+ and it has no name</p></li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="BasicBlock">The <tt>BasicBlock</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>#include "<a
+ href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt><br>
+ doxygen info: <a href="/doxygen/structllvm_1_1BasicBlock.html">BasicBlock
+ Class</a><br>
+ Superclass: <a href="#Value"><tt>Value</tt></a></p>
+
+ <p>This class represents a single entry multiple exit section of the code,
+ commonly known as a basic block by the compiler community. The
+ <tt>BasicBlock</tt> class maintains a list of <a
+ href="#Instruction"><tt>Instruction</tt></a>s, which form the body of the block.
+ Matching the language definition, the last element of this list of instructions
+ is always a terminator instruction (a subclass of the <a
+ href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).</p>
+
+ <p>In addition to tracking the list of instructions that make up the block, the
+ <tt>BasicBlock</tt> class also keeps track of the <a
+ href="#Function"><tt>Function</tt></a> that it is embedded into.</p>
+
+ <p>Note that <tt>BasicBlock</tt>s themselves are <a
+ href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions
+ like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type
+ <tt>label</tt>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_BasicBlock">Important Public Members of the <tt>BasicBlock</tt>
+ class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ul>
+
+ <li><tt>BasicBlock(const std::string &Name = "", </tt><tt><a
+ href="#Function">Function</a> *Parent = 0)</tt>
+
+ <p>The <tt>BasicBlock</tt> constructor is used to create new basic blocks for
+ insertion into a function. The constructor optionally takes a name for the new
+ block, and a <a href="#Function"><tt>Function</tt></a> to insert it into. If
+ the <tt>Parent</tt> parameter is specified, the new <tt>BasicBlock</tt> is
+ automatically inserted at the end of the specified <a
+ href="#Function"><tt>Function</tt></a>, if not specified, the BasicBlock must be
+ manually inserted into the <a href="#Function"><tt>Function</tt></a>.</p></li>
+
+ <li><tt>BasicBlock::iterator</tt> - Typedef for instruction list iterator<br>
+ <tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
+ <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
+ <tt>size()</tt>, <tt>empty()</tt>
+ STL-style functions for accessing the instruction list.
+
+ <p>These methods and typedefs are forwarding functions that have the same
+ semantics as the standard library methods of the same names. These methods
+ expose the underlying instruction list of a basic block in a way that is easy to
+ manipulate. To get the full complement of container operations (including
+ operations to update the list), you must use the <tt>getInstList()</tt>
+ method.</p></li>
+
+ <li><tt>BasicBlock::InstListType &getInstList()</tt>
+
+ <p>This method is used to get access to the underlying container that actually
+ holds the Instructions. This method must be used when there isn't a forwarding
+ function in the <tt>BasicBlock</tt> class for the operation that you would like
+ to perform. Because there are no forwarding functions for "updating"
+ operations, you need to use this if you want to update the contents of a
+ <tt>BasicBlock</tt>.</p></li>
+
+ <li><tt><a href="#Function">Function</a> *getParent()</tt>
+
+ <p> Returns a pointer to <a href="#Function"><tt>Function</tt></a> the block is
+ embedded into, or a null pointer if it is homeless.</p></li>
+
+ <li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt>
+
+ <p> Returns a pointer to the terminator instruction that appears at the end of
+ the <tt>BasicBlock</tt>. If there is no terminator instruction, or if the last
+ instruction in the block is not a terminator, then a null pointer is
+ returned.</p></li>
+
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="GlobalValue">The <tt>GlobalValue</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>#include "<a
+ href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt><br>
+ doxygen info: <a href="/doxygen/classllvm_1_1GlobalValue.html">GlobalValue
+ Class</a><br>
+ Superclasses: <a href="#User"><tt>User</tt></a>, <a
+ href="#Value"><tt>Value</tt></a></p>
+
+ <p>Global values (<a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s or <a
+ href="#Function"><tt>Function</tt></a>s) are the only LLVM values that are
+ visible in the bodies of all <a href="#Function"><tt>Function</tt></a>s.
+ Because they are visible at global scope, they are also subject to linking with
+ other globals defined in different translation units. To control the linking
+ process, <tt>GlobalValue</tt>s know their linkage rules. Specifically,
+ <tt>GlobalValue</tt>s know whether they have internal or external linkage, as
+ defined by the <tt>LinkageTypes</tt> enumeration.</p>
+
+ <p>If a <tt>GlobalValue</tt> has internal linkage (equivalent to being
+ <tt>static</tt> in C), it is not visible to code outside the current translation
+ unit, and does not participate in linking. If it has external linkage, it is
+ visible to external code, and does participate in linking. In addition to
+ linkage information, <tt>GlobalValue</tt>s keep track of which <a
+ href="#Module"><tt>Module</tt></a> they are currently part of.</p>
+
+ <p>Because <tt>GlobalValue</tt>s are memory objects, they are always referred to
+ by their <b>address</b>. As such, the <a href="#Type"><tt>Type</tt></a> of a
+ global is always a pointer to its contents. It is important to remember this
+ when using the <tt>GetElementPtrInst</tt> instruction because this pointer must
+ be dereferenced first. For example, if you have a <tt>GlobalVariable</tt> (a
+ subclass of <tt>GlobalValue)</tt> that is an array of 24 ints, type <tt>[24 x
+ int]</tt>, then the <tt>GlobalVariable</tt> is a pointer to that array. Although
+ the address of the first element of this array and the value of the
+ <tt>GlobalVariable</tt> are the same, they have different types. The
+ <tt>GlobalVariable</tt>'s type is <tt>[24 x int]</tt>. The first element's type
+ is <tt>int.</tt> Because of this, accessing a global value requires you to
+ dereference the pointer with <tt>GetElementPtrInst</tt> first, then its elements
+ can be accessed. This is explained in the <a href="LangRef.html#globalvars">LLVM
+ Language Reference Manual</a>.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_GlobalValue">Important Public Members of the <tt>GlobalValue</tt>
+ class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><tt>bool hasInternalLinkage() const</tt><br>
+ <tt>bool hasExternalLinkage() const</tt><br>
+ <tt>void setInternalLinkage(bool HasInternalLinkage)</tt>
+ <p> These methods manipulate the linkage characteristics of the <tt>GlobalValue</tt>.</p>
+ <p> </p>
+ </li>
+ <li><tt><a href="#Module">Module</a> *getParent()</tt>
+ <p> This returns the <a href="#Module"><tt>Module</tt></a> that the
+ GlobalValue is currently embedded into.</p></li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="Function">The <tt>Function</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>#include "<a
+ href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt><br> doxygen
+ info: <a href="/doxygen/classllvm_1_1Function.html">Function Class</a><br>
+ Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
+ href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p>
+
+ <p>The <tt>Function</tt> class represents a single procedure in LLVM. It is
+ actually one of the more complex classes in the LLVM heirarchy because it must
+ keep track of a large amount of data. The <tt>Function</tt> class keeps track
+ of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <a
+ href="#Argument"><tt>Argument</tt></a>s, and a <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a>.</p>
+
+ <p>The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most
+ commonly used part of <tt>Function</tt> objects. The list imposes an implicit
+ ordering of the blocks in the function, which indicate how the code will be
+ layed out by the backend. Additionally, the first <a
+ href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node for the
+ <tt>Function</tt>. It is not legal in LLVM to explicitly branch to this initial
+ block. There are no implicit exit nodes, and in fact there may be multiple exit
+ nodes from a single <tt>Function</tt>. If the <a
+ href="#BasicBlock"><tt>BasicBlock</tt></a> list is empty, this indicates that
+ the <tt>Function</tt> is actually a function declaration: the actual body of the
+ function hasn't been linked in yet.</p>
+
+ <p>In addition to a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, the
+ <tt>Function</tt> class also keeps track of the list of formal <a
+ href="#Argument"><tt>Argument</tt></a>s that the function receives. This
+ container manages the lifetime of the <a href="#Argument"><tt>Argument</tt></a>
+ nodes, just like the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list does for
+ the <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.</p>
+
+ <p>The <a href="#SymbolTable"><tt>SymbolTable</tt></a> is a very rarely used
+ LLVM feature that is only used when you have to look up a value by name. Aside
+ from that, the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is used
+ internally to make sure that there are not conflicts between the names of <a
+ href="#Instruction"><tt>Instruction</tt></a>s, <a
+ href="#BasicBlock"><tt>BasicBlock</tt></a>s, or <a
+ href="#Argument"><tt>Argument</tt></a>s in the function body.</p>
+
+ <p>Note that <tt>Function</tt> is a <a href="#GlobalValue">GlobalValue</a>
+ and therefore also a <a href="#Constant">Constant</a>. The value of the function
+ is its address (after linking) which is guaranteed to be constant.</p>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_Function">Important Public Members of the <tt>Function</tt>
+ class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><tt>Function(const </tt><tt><a href="#FunctionType">FunctionType</a>
+ *Ty, LinkageTypes Linkage, const std::string &N = "", Module* Parent = 0)</tt>
+
+ <p>Constructor used when you need to create new <tt>Function</tt>s to add
+ the the program. The constructor must specify the type of the function to
+ create and what type of linkage the function should have. The <a
+ href="#FunctionType"><tt>FunctionType</tt></a> argument
+ specifies the formal arguments and return value for the function. The same
+ <a href="#FunctionTypel"><tt>FunctionType</tt></a> value can be used to
+ create multiple functions. The <tt>Parent</tt> argument specifies the Module
+ in which the function is defined. If this argument is provided, the function
+ will automatically be inserted into that module's list of
+ functions.</p></li>
+
+ <li><tt>bool isExternal()</tt>
+
+ <p>Return whether or not the <tt>Function</tt> has a body defined. If the
+ function is "external", it does not have a body, and thus must be resolved
+ by linking with a function defined in a different translation unit.</p></li>
+
+ <li><tt>Function::iterator</tt> - Typedef for basic block list iterator<br>
+ <tt>Function::const_iterator</tt> - Typedef for const_iterator.<br>
+
+ <tt>begin()</tt>, <tt>end()</tt>
+ <tt>size()</tt>, <tt>empty()</tt>
+
+ <p>These are forwarding methods that make it easy to access the contents of
+ a <tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
+ list.</p></li>
+
+ <li><tt>Function::BasicBlockListType &getBasicBlockList()</tt>
+
+ <p>Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s. This
+ is necessary to use when you need to update the list or perform a complex
+ action that doesn't have a forwarding method.</p></li>
+
+ <li><tt>Function::arg_iterator</tt> - Typedef for the argument list
+ iterator<br>
+ <tt>Function::const_arg_iterator</tt> - Typedef for const_iterator.<br>
+
+ <tt>arg_begin()</tt>, <tt>arg_end()</tt>
+ <tt>arg_size()</tt>, <tt>arg_empty()</tt>
+
+ <p>These are forwarding methods that make it easy to access the contents of
+ a <tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a>
+ list.</p></li>
+
+ <li><tt>Function::ArgumentListType &getArgumentList()</tt>
+
+ <p>Returns the list of <a href="#Argument"><tt>Argument</tt></a>s. This is
+ necessary to use when you need to update the list or perform a complex
+ action that doesn't have a forwarding method.</p></li>
+
+ <li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryBlock()</tt>
+
+ <p>Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
+ function. Because the entry block for the function is always the first
+ block, this returns the first block of the <tt>Function</tt>.</p></li>
+
+ <li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
+ <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt>
+
+ <p>This traverses the <a href="#Type"><tt>Type</tt></a> of the
+ <tt>Function</tt> and returns the return type of the function, or the <a
+ href="#FunctionType"><tt>FunctionType</tt></a> of the actual
+ function.</p></li>
+
+ <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
+
+ <p> Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+ for this <tt>Function</tt>.</p></li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>#include "<a
+ href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt>
+ <br>
+ doxygen info: <a href="/doxygen/classllvm_1_1GlobalVariable.html">GlobalVariable
+ Class</a><br> Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
+ href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p>
+
+ <p>Global variables are represented with the (suprise suprise)
+ <tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are also
+ subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such are
+ always referenced by their address (global values must live in memory, so their
+ "name" refers to their address). See <a
+ href="#GlobalValue"><tt>GlobalValue</tt></a> for more on this. Global variables
+ may have an initial value (which must be a <a
+ href="#Constant"><tt>Constant</tt></a>), and if they have an initializer, they
+ may be marked as "constant" themselves (indicating that their contents never
+ change at runtime).</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_GlobalVariable">Important Public Members of the
+ <tt>GlobalVariable</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><tt>GlobalVariable(const </tt><tt><a href="#Type">Type</a> *Ty, bool
+ isConstant, LinkageTypes& Linkage, <a href="#Constant">Constant</a>
+ *Initializer = 0, const std::string &Name = "", Module* Parent = 0)</tt>
+
+ <p>Create a new global variable of the specified type. If
+ <tt>isConstant</tt> is true then the global variable will be marked as
+ unchanging for the program. The Linkage parameter specifies the type of
+ linkage (internal, external, weak, linkonce, appending) for the variable. If
+ the linkage is InternalLinkage, WeakLinkage, or LinkOnceLinkage, then
+ the resultant global variable will have internal linkage. AppendingLinkage
+ concatenates together all instances (in different translation units) of the
+ variable into a single variable but is only applicable to arrays. See
+ the <a href="LangRef.html#modulestructure">LLVM Language Reference</a> for
+ further details on linkage types. Optionally an initializer, a name, and the
+ module to put the variable into may be specified for the global variable as
+ well.</p></li>
+
+ <li><tt>bool isConstant() const</tt>
+
+ <p>Returns true if this is a global variable that is known not to
+ be modified at runtime.</p></li>
+
+ <li><tt>bool hasInitializer()</tt>
+
+ <p>Returns true if this <tt>GlobalVariable</tt> has an intializer.</p></li>
+
+ <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt>
+
+ <p>Returns the intial value for a <tt>GlobalVariable</tt>. It is not legal
+ to call this method if there is no initializer.</p></li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="Module">The <tt>Module</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p><tt>#include "<a
+ href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt><br> doxygen info:
+ <a href="/doxygen/classllvm_1_1Module.html">Module Class</a></p>
+
+ <p>The <tt>Module</tt> class represents the top level structure present in LLVM
+ programs. An LLVM module is effectively either a translation unit of the
+ original program or a combination of several translation units merged by the
+ linker. The <tt>Module</tt> class keeps track of a list of <a
+ href="#Function"><tt>Function</tt></a>s, a list of <a
+ href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it contains a few
+ helpful member functions that try to make common operations easy.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_Module">Important Public Members of the <tt>Module</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ul>
+ <li><tt>Module::Module(std::string name = "")</tt></li>
+ </ul>
+
+ <p>Constructing a <a href="#Module">Module</a> is easy. You can optionally
+ provide a name for it (probably based on the name of the translation unit).</p>
+
+ <ul>
+ <li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
+ <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
+
+ <tt>begin()</tt>, <tt>end()</tt>
+ <tt>size()</tt>, <tt>empty()</tt>
+
+ <p>These are forwarding methods that make it easy to access the contents of
+ a <tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
+ list.</p></li>
+
+ <li><tt>Module::FunctionListType &getFunctionList()</tt>
+
+ <p> Returns the list of <a href="#Function"><tt>Function</tt></a>s. This is
+ necessary to use when you need to update the list or perform a complex
+ action that doesn't have a forwarding method.</p>
+
+ <p><!-- Global Variable --></p></li>
+ </ul>
+
+ <hr>
+
+ <ul>
+ <li><tt>Module::global_iterator</tt> - Typedef for global variable list iterator<br>
+
+ <tt>Module::const_global_iterator</tt> - Typedef for const_iterator.<br>
+
+ <tt>global_begin()</tt>, <tt>global_end()</tt>
+ <tt>global_size()</tt>, <tt>global_empty()</tt>
+
+ <p> These are forwarding methods that make it easy to access the contents of
+ a <tt>Module</tt> object's <a
+ href="#GlobalVariable"><tt>GlobalVariable</tt></a> list.</p></li>
+
+ <li><tt>Module::GlobalListType &getGlobalList()</tt>
+
+ <p>Returns the list of <a
+ href="#GlobalVariable"><tt>GlobalVariable</tt></a>s. This is necessary to
+ use when you need to update the list or perform a complex action that
+ doesn't have a forwarding method.</p>
+
+ <p><!-- Symbol table stuff --> </p></li>
+ </ul>
+
+ <hr>
+
+ <ul>
+ <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
+
+ <p>Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+ for this <tt>Module</tt>.</p>
+
+ <p><!-- Convenience methods --></p></li>
+ </ul>
+
+ <hr>
+
+ <ul>
+ <li><tt><a href="#Function">Function</a> *getFunction(const std::string
+ &Name, const <a href="#FunctionType">FunctionType</a> *Ty)</tt>
+
+ <p>Look up the specified function in the <tt>Module</tt> <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return
+ <tt>null</tt>.</p></li>
+
+ <li><tt><a href="#Function">Function</a> *getOrInsertFunction(const
+ std::string &Name, const <a href="#FunctionType">FunctionType</a> *T)</tt>
+
+ <p>Look up the specified function in the <tt>Module</tt> <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an
+ external declaration for the function and return it.</p></li>
+
+ <li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt>
+
+ <p>If there is at least one entry in the <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a
+ href="#Type"><tt>Type</tt></a>, return it. Otherwise return the empty
+ string.</p></li>
+
+ <li><tt>bool addTypeName(const std::string &Name, const <a
+ href="#Type">Type</a> *Ty)</tt>
+
+ <p>Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+ mapping <tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this
+ name, true is returned and the <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a> is not modified.</p></li>
+ </ul>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="Constant">The <tt>Constant</tt> class and subclasses</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Constant represents a base class for different types of constants. It
+ is subclassed by ConstantBool, ConstantInt, ConstantSInt, ConstantUInt,
+ ConstantArray etc for representing the various types of Constants.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_Constant">Important Public Methods</a>
+ </div>
+ <div class="doc_text">
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">Important Subclasses of Constant </div>
+ <div class="doc_text">
+ <ul>
+ <li>ConstantSInt : This subclass of Constant represents a signed integer
+ constant.
+ <ul>
+ <li><tt>int64_t getValue() const</tt>: Returns the underlying value of
+ this constant. </li>
+ </ul>
+ </li>
+ <li>ConstantUInt : This class represents an unsigned integer.
+ <ul>
+ <li><tt>uint64_t getValue() const</tt>: Returns the underlying value of
+ this constant. </li>
+ </ul>
+ </li>
+ <li>ConstantFP : This class represents a floating point constant.
+ <ul>
+ <li><tt>double getValue() const</tt>: Returns the underlying value of
+ this constant. </li>
+ </ul>
+ </li>
+ <li>ConstantBool : This represents a boolean constant.
+ <ul>
+ <li><tt>bool getValue() const</tt>: Returns the underlying value of this
+ constant. </li>
+ </ul>
+ </li>
+ <li>ConstantArray : This represents a constant array.
+ <ul>
+ <li><tt>const std::vector<Use> &getValues() const</tt>: Returns
+ a vector of component constants that makeup this array. </li>
+ </ul>
+ </li>
+ <li>ConstantStruct : This represents a constant struct.
+ <ul>
+ <li><tt>const std::vector<Use> &getValues() const</tt>: Returns
+ a vector of component constants that makeup this array. </li>
+ </ul>
+ </li>
+ <li>GlobalValue : This represents either a global variable or a function. In
+ either case, the value is a constant fixed address (after linking).
+ </li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="Type">The <tt>Type</tt> class and Derived Types</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>Type as noted earlier is also a subclass of a Value class. Any primitive
+ type (like int, short etc) in LLVM is an instance of Type Class. All other
+ types are instances of subclasses of type like FunctionType, ArrayType
+ etc. DerivedType is the interface for all such dervied types including
+ FunctionType, ArrayType, PointerType, StructType. Types can have names. They can
+ be recursive (StructType). There exists exactly one instance of any type
+ structure at a time. This allows using pointer equality of Type *s for comparing
+ types.</p>
+
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_Value">Important Public Methods</a>
+ </div>
+
+ <div class="doc_text">
+
+ <ul>
+
+ <li><tt>bool isSigned() const</tt>: Returns whether an integral numeric type
+ is signed. This is true for SByteTy, ShortTy, IntTy, LongTy. Note that this is
+ not true for Float and Double. </li>
+
+ <li><tt>bool isUnsigned() const</tt>: Returns whether a numeric type is
+ unsigned. This is not quite the complement of isSigned... nonnumeric types
+ return false as they do with isSigned. This returns true for UByteTy,
+ UShortTy, UIntTy, and ULongTy. </li>
+
+ <li><tt>bool isInteger() const</tt>: Equivalent to isSigned() || isUnsigned().</li>
+
+ <li><tt>bool isIntegral() const</tt>: Returns true if this is an integral
+ type, which is either Bool type or one of the Integer types.</li>
+
+ <li><tt>bool isFloatingPoint()</tt>: Return true if this is one of the two
+ floating point types.</li>
+
+ <li><tt>isLosslesslyConvertableTo (const Type *Ty) const</tt>: Return true if
+ this type can be converted to 'Ty' without any reinterpretation of bits. For
+ example, uint to int or one pointer type to another.</li>
+ </ul>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsubsection">
+ <a name="m_Value">Important Derived Types</a>
+ </div>
+ <div class="doc_text">
+ <ul>
+ <li>SequentialType : This is subclassed by ArrayType and PointerType
+ <ul>
+ <li><tt>const Type * getElementType() const</tt>: Returns the type of each
+ of the elements in the sequential type. </li>
+ </ul>
+ </li>
+ <li>ArrayType : This is a subclass of SequentialType and defines interface for
+ array types.
+ <ul>
+ <li><tt>unsigned getNumElements() const</tt>: Returns the number of
+ elements in the array. </li>
+ </ul>
+ </li>
+ <li>PointerType : Subclass of SequentialType for pointer types. </li>
+ <li>StructType : subclass of DerivedTypes for struct types </li>
+ <li>FunctionType : subclass of DerivedTypes for function types.
+ <ul>
+ <li><tt>bool isVarArg() const</tt>: Returns true if its a vararg
+ function</li>
+ <li><tt> const Type * getReturnType() const</tt>: Returns the
+ return type of the function.</li>
+ <li><tt>const Type * getParamType (unsigned i)</tt>: Returns
+ the type of the ith parameter.</li>
+ <li><tt> const unsigned getNumParams() const</tt>: Returns the
+ number of formal parameters.</li>
+ </ul>
+ </li>
+ </ul>
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="Argument">The <tt>Argument</tt> class</a>
+ </div>
+
+ <div class="doc_text">
+
+ <p>This subclass of Value defines the interface for incoming formal
+ arguments to a function. A Function maintains a list of its formal
+ arguments. An argument has a pointer to the parent Function.</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:dhurjati at cs.uiuc.edu">Dinakar Dhurjati</a> and
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2005/05/18 14:33:23 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/Projects.html
diff -c /dev/null llvm-www/releases/1.5/docs/Projects.html:1.1
*** /dev/null Wed May 18 09:34:36 2005
--- llvm-www/releases/1.5/docs/Projects.html Wed May 18 09:33:23 2005
***************
*** 0 ****
--- 1,454 ----
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>Creating an LLVM Project</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ </head>
+ <body>
+
+ <div class="doc_title">Creating an LLVM Project</div>
+
+ <ol>
+ <li><a href="#overview">Overview</a></li>
+ <li><a href="#create">Create a project from the Sample Project</a></li>
+ <li><a href="#source">Source tree layout</a></li>
+ <li><a href="#makefiles">Writing LLVM-style Makefiles</a>
+ <ol>
+ <li><a href="#reqVars">Required Variables</a></li>
+ <li><a href="#varsBuildDir">Variables for Building Subdirectories</a></li>
+ <li><a href="#varsBuildLib">Variables for Building Libraries</a></li>
+ <li><a href="#varsBuildProg">Variables for Building Programs</a></li>
+ <li><a href="#miscVars">Miscellaneous Variables</a></li>
+ </ol></li>
+ <li><a href="#objcode">Placement of object code</a></li>
+ <li><a href="#help">Further help</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by John Criswell</p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section"><a name="overview">Overview</a></div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The LLVM build system is designed to facilitate the building of third party
+ projects that use LLVM header files, libraries, and tools. In order to use
+ these facilities, a Makefile from a project must do the following things:</p>
+
+ <ol>
+ <li>Set <tt>make</tt> variables. There are several variables that a Makefile
+ needs to set to use the LLVM build system:
+ <ul>
+ <li><tt>PROJECT_NAME</tt> - The name by which your project is known.</li>
+ <li><tt>LLVM_SRC_ROOT</tt> - The root of the LLVM source tree.</li>
+ <li><tt>LLVM_OBJ_ROOT</tt> - The root of the LLVM object tree.</li>
+ <li><tt>PROJ_SRC_ROOT</tt> - The root of the project's source tree.</li>
+ <li><tt>PROJ_OBJ_ROOT</tt> - The root of the project's object tree.</li>
+ <li><tt>PROJ_INSTALL_ROOT</tt> - The root installation directory.</li>
+ <li><tt>LEVEL</tt> - The relative path from the current directory to the
+ project's root ($PROJ_OBJ_ROOT).</li>
+ </ul></li>
+ <li>Include <tt>Makefile.config</tt> from <tt>$(LLVM_OBJ_ROOT)</tt>.</li>
+ <li>Include <tt>Makefile.rules</tt> from <tt>$(LLVM_SRC_ROOT)</tt>.</li>
+ </ol>
+
+ <p>There are two ways that you can set all of these variables:</p>
+ <ol>
+ <li>You can write your own Makefiles which hard-code these values.</li>
+ <li>You can use the pre-made LLVM sample project. This sample project
+ includes Makefiles, a configure script that can be used to configure the
+ location of LLVM, and the ability to support multiple object directories
+ from a single source directory.</li>
+ </ol>
+
+ <p>This document assumes that you will base your project on the LLVM sample
+ project found in <tt>llvm/projects/sample</tt>. If you want to devise your own
+ build system, studying the sample project and LLVM Makefiles will probably
+ provide enough information on how to write your own Makefiles.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="create">Create a Project from the Sample Project</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>Follow these simple steps to start your project:</p>
+
+ <ol>
+ <li>Copy the <tt>llvm/projects/sample</tt> directory to any place of your
+ choosing. You can place it anywhere you like. Rename the directory to match
+ the name of your project.</li>
+
+ <li>Add your source code and Makefiles to your source tree.</li>
+
+ <li>If you want your project to be configured with the <tt>configure</tt> script
+ then you need to edit <tt>autoconf/configure.ac</tt> as follows:
+ <ul>
+ <li><b>AC_INIT</b>. Place the name of your project, its version number and
+ a contact email address for your project as the arguments to this macro</li>
+ <li><b>AC_CONFIG_AUC_DIR</b>. If your project isn't in the
+ <tt>llvm/projects</tt> directory then you might need to adjust this so that
+ it specifies a relative path to the <tt>llvm/autoconf</tt> directory.</li>
+ <li><b>LLVM_CONFIG_PROJECT</b>. Just leave this alone.</li>
+ <li><b>AC_CONFIG_SRCDIR</b>. Specify a path to a file name that identifies
+ your project; or just leave it at <tt>Makefile.config.in</tt></li>
+ <li><b>AC_CONFIG_FILES</b>. Do not change.</li>
+ <li><b>AC_CONFIG_MAKEFILE</b>. Use one of these macros for each Makefile
+ that your project uses. This macro arranges for your makefiles to be copied
+ from the source directory, unmodified, to the build directory.</li>
+ </ul>
+ </li>
+
+ <li>After updating <tt>autoconf/configure.ac</tt>, regenerate the
+ configure script with these commands:
+
+ <div class="doc_code">
+ <p><tt>% cd autoconf<br>
+ % AutoRegen.sh</tt></p>
+ </div>
+
+ <p>You must be using Autoconf version 2.59 or later and your aclocal version
+ should 1.9 or later.</p></li>
+
+ <li>Run <tt>configure</tt> in the directory in which you want to place
+ object code. Use the following options to tell your project where it
+ can find LLVM:
+
+ <dl>
+ <dt><tt>--with-llvmsrc=<directory></tt></dt>
+ <dd>Tell your project where the LLVM source tree is located.</dd>
+ <dt><br/><tt>--with-llvmobj=<directory></tt></dt>
+ <dd>Tell your project where the LLVM object tree is located.</dd>
+ <dt><br/><tt>--prefix=<directory></tt></dt>
+ <dd>Tell your project where it should get installed.</dd>
+ </dl>
+ </ol>
+
+ <p>That's it! Now all you have to do is type <tt>gmake</tt> (or <tt>make</tt>
+ if your on a GNU/Linux system) in the root of your object directory, and your
+ project should build.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="source">Source Tree Layout</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>In order to use the LLVM build system, you will want to organize your
+ source code so that it can benefit from the build system's features.
+ Mainly, you want your source tree layout to look similar to the LLVM
+ source tree layout. The best way to do this is to just copy the
+ project tree from <tt>llvm/projects/sample</tt> and modify it to meet
+ your needs, but you can certainly add to it if you want.</p>
+
+ <p>Underneath your top level directory, you should have the following
+ directories:</p>
+
+ <dl>
+ <dt><b>lib</b>
+ <dd>
+ This subdirectory should contain all of your library source
+ code. For each library that you build, you will have one
+ directory in <b>lib</b> that will contain that library's source
+ code.
+
+ <p>
+ Libraries can be object files, archives, or dynamic libraries.
+ The <b>lib</b> directory is just a convenient place for libraries
+ as it places them all in a directory from which they can be linked
+ later.
+
+ <dt><b>include</b>
+ <dd>
+ This subdirectory should contain any header files that are
+ global to your project. By global, we mean that they are used
+ by more than one library or executable of your project.
+ <p>
+ By placing your header files in <b>include</b>, they will be
+ found automatically by the LLVM build system. For example, if
+ you have a file <b>include/jazz/note.h</b>, then your source
+ files can include it simply with <b>#include "jazz/note.h"</b>.
+
+ <dt><b>tools</b>
+ <dd>
+ This subdirectory should contain all of your source
+ code for executables. For each program that you build, you
+ will have one directory in <b>tools</b> that will contain that
+ program's source code.
+ <p>
+
+ <dt><b>test</b>
+ <dd>
+ This subdirectory should contain tests that verify that your code
+ works correctly. Automated tests are especially useful.
+ <p>
+ Currently, the LLVM build system provides basic support for tests.
+ The LLVM system provides the following:
+ <ul>
+ <li>
+ LLVM provides a tcl procedure that is used by Dejagnu to run
+ tests. It can be found in <tt>llvm/lib/llvm-dg.exp</tt>. This
+ test procedure uses RUN lines in the actual test case to determine
+ how to run the test. See the <a
+ href="TestingGuide.html">TestingGuide</a> for more details. You
+ can easily write Makefile support similar to the Makefiles in
+ <tt>llvm/test</tt> to use Dejagnu to run your project's tests.<br/></li>
+ <li>
+ LLVM contains an optional package called <tt>llvm-test</tt>
+ which provides benchmarks and programs that are known to compile with the
+ LLVM GCC front ends. You can use these
+ programs to test your code, gather statistics information, and
+ compare it to the current LLVM performance statistics.
+ <br/>Currently, there is no way to hook your tests directly into the
+ <tt>llvm/test</tt> testing harness. You will simply
+ need to find a way to use the source provided within that directory
+ on your own.
+ </ul>
+ </dl>
+
+ <p>Typically, you will want to build your <b>lib</b> directory first followed by
+ your <b>tools</b> directory.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="makefiles">Writing LLVM Style Makefiles</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The LLVM build system provides a convenient way to build libraries and
+ executables. Most of your project Makefiles will only need to define a few
+ variables. Below is a list of the variables one can set and what they can
+ do:</p>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="reqVars">Required Variables</a>
+ </div>
+
+ <div class="doc_text">
+
+ <dl>
+ <dt>LEVEL
+ <dd>
+ This variable is the relative path from this Makefile to the
+ top directory of your project's source code. For example, if
+ your source code is in <tt>/tmp/src</tt>, then the Makefile in
+ <tt>/tmp/src/jump/high</tt> would set <tt>LEVEL</tt> to <tt>"../.."</tt>.
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="varsBuildDir">Variables for Building Subdirectories</a>
+ </div>
+
+ <div class="doc_text">
+
+ <dl>
+ <dt>DIRS
+ <dd>
+ This is a space separated list of subdirectories that should be
+ built. They will be built, one at a time, in the order
+ specified.
+ <p>
+
+ <dt>PARALLEL_DIRS
+ <dd>
+ This is a list of directories that can be built in parallel.
+ These will be built after the directories in DIRS have been
+ built.
+ <p>
+
+ <dt>OPTIONAL_DIRS
+ <dd>
+ This is a list of directories that can be built if they exist,
+ but will not cause an error if they do not exist. They are
+ built serially in the order in which they are listed.
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="varsBuildLib">Variables for Building Libraries</a>
+ </div>
+
+ <div class="doc_text">
+
+ <dl>
+ <dt>LIBRARYNAME
+ <dd>
+ This variable contains the base name of the library that will
+ be built. For example, to build a library named
+ <tt>libsample.a</tt>, LIBRARYNAME should be set to
+ <tt>sample</tt>.
+ <p>
+
+ <dt>BUILD_ARCHIVE
+ <dd>
+ By default, a library is a <tt>.o</tt> file that is linked
+ directly into a program. To build an archive (also known as
+ a static library), set the BUILD_ARCHIVE variable.
+ <p>
+
+ <dt>SHARED_LIBRARY
+ <dd>
+ If SHARED_LIBRARY is defined in your Makefile, a shared
+ (or dynamic) library will be built.
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="varsBuildProg">Variables for Building Programs</a>
+ </div>
+
+ <div class="doc_text">
+
+ <dl>
+ <dt>TOOLNAME
+ <dd>
+ This variable contains the name of the program that will
+ be built. For example, to build an executable named
+ <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
+ <p>
+
+ <dt>USEDLIBS
+ <dd>
+ This variable holds a space separated list of libraries that
+ should be linked into the program. These libraries must either
+ be LLVM libraries or libraries that come from your <b>lib</b>
+ directory. The libraries must be specified by their base name.
+ For example, to link libsample.a, you would set USEDLIBS to
+ <tt>sample</tt>.
+ <p>
+ Note that this works only for statically linked libraries.
+ <p>
+
+ <dt>LIBS
+ <dd>
+ To link dynamic libraries, add <tt>-l<library base name></tt> to
+ the LIBS variable. The LLVM build system will look in the same places
+ for dynamic libraries as it does for static libraries.
+ <p>
+ For example, to link <tt>libsample.so</tt>, you would have the
+ following line in your <tt>Makefile</tt>:
+ <p>
+ <tt>
+ LIBS += -lsample
+ </tt>
+ </dl>
+
+ </div>
+
+ <!-- ======================================================================= -->
+ <div class="doc_subsection">
+ <a name="miscVars">Miscellaneous Variables</a>
+ </div>
+
+ <div class="doc_text">
+
+ <dl>
+ <dt>ExtraSource
+ <dd>
+ This variable contains a space separated list of extra source
+ files that need to be built. It is useful for including the
+ output of Lex and Yacc programs.
+ <p>
+
+ <dt>CFLAGS
+ <dt>CPPFLAGS
+ <dd>
+ This variable can be used to add options to the C and C++
+ compiler, respectively. It is typically used to add options
+ that tell the compiler the location of additional directories
+ to search for header files.
+ <p>
+ It is highly suggested that you append to CFLAGS and CPPFLAGS as
+ opposed to overwriting them. The master Makefiles may already
+ have useful options in them that you may not want to overwrite.
+ <p>
+ </dl>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="objcode">Placement of Object Code</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>The final location of built libraries and executables will depend upon
+ whether you do a Debug, Release, or Profile build.</p>
+
+ <dl>
+ <dt>Libraries
+ <dd>
+ All libraries (static and dynamic) will be stored in
+ <tt>PROJ_OBJ_ROOT/<type>/lib</tt>, where type is <tt>Debug</tt>,
+ <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or
+ profiled build, respectively.<p>
+
+ <dt>Executables
+ <dd>All executables will be stored in
+ <tt>PROJ_OBJ_ROOT/<type>/bin</tt>, where type is <tt>Debug</tt>,
+ <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or profiled
+ build, respectively.
+ </dl>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="help">Further Help</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>If you have any questions or need any help creating an LLVM project,
+ the LLVM team would be more than happy to help. You can always post your
+ questions to the <a
+ href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
+ Mailing List</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="mailto:criswell at uiuc.edu">John Criswell</a><br>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
+ <br>
+ Last modified: $Date: 2005/05/18 14:33:23 $
+ </address>
+
+ </body>
+ </html>
Index: llvm-www/releases/1.5/docs/ReleaseNotes.html
diff -c /dev/null llvm-www/releases/1.5/docs/ReleaseNotes.html:1.1
*** /dev/null Wed May 18 09:34:36 2005
--- llvm-www/releases/1.5/docs/ReleaseNotes.html Wed May 18 09:33:23 2005
***************
*** 0 ****
--- 1,833 ----
+ <!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">
+ <title>LLVM 1.5 Release Notes</title>
+ </head>
+ <body>
+
+ <div class="doc_title">LLVM 1.5 Release Notes</div>
+
+ <ol>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#whatsnew">What's New?</a></li>
+ <li><a href="GettingStarted.html">Installation Instructions</a></li>
+ <li><a href="#portability">Portability and Supported Platforms</a></li>
+ <li><a href="#knownproblems">Known Problems</a>
+ <li><a href="#additionalinfo">Additional Information</a></li>
+ </ol>
+
+ <div class="doc_author">
+ <p>Written by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a><p>
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="intro">Introduction</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This document contains the release notes for the LLVM compiler
+ infrastructure, release 1.5. Here we describe the status of LLVM, including any
+ known problems and major improvements from the previous release. The most
+ up-to-date version of this document can be found on the <a
+ href="http://llvm.cs.uiuc.edu/releases/1.5/">LLVM 1.5 web site</a>. If you are
+ not reading this on the LLVM web pages, you should probably go there because
+ this document may be updated after the release.</p>
+
+ <p>For more information about LLVM, including information about the latest
+ release, please check out the <a href="http://llvm.cs.uiuc.edu">main LLVM
+ web site</a>. If you have questions or comments, the <a
+ href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM developer's mailing
+ list</a> is a good place to send them.</p>
+
+ <p>Note that if you are reading this file from CVS or the main LLVM web page,
+ this document applies to the <i>next</i> release, not the current one. To see
+ the release notes for the current or previous releases, see the <a
+ href="http://llvm.cs.uiuc.edu/releases/">releases page</a>.</p>
+
+ </div>
+
+ <!-- *********************************************************************** -->
+ <div class="doc_section">
+ <a name="whatsnew">What's New?</a>
+ </div>
+ <!-- *********************************************************************** -->
+
+ <div class="doc_text">
+
+ <p>This is the sixth public release of the LLVM Compiler Infrastructure.</p>
+
+ <p>LLVM 1.5 is known to correctly compile a wide range of C and C++ programs,
+ includes bug fixes for those problems found since the 1.4 release, and includes
+ a large number of new features and enhancements, described below.</p>
+
+ </div>
+
+ <!--=========================================================================-->
+ <div class="doc_subsection">
+ <a name="newfeatures">New Features in LLVM 1.5</a>
+ </div>
+
+ <!--_________________________________________________________________________-->
+ <div class="doc_subsubsection"><a name="newcg">New Native Code
+ Generators</a></div>
+
+ <div class="doc_text">
+ <p>
+ This release includes new native code generators for <a
+ href="#alpha-be">Alpha</a>, <a href="#ia64-be">IA-64</a>, and <a
+ href="#sparcv8">SPARC-V8</a> (32-bit SPARC). These code generators are still
+ beta quality, but are progressing rapidly. The Alpha backend is implemented
+ with an eye towards being compatible with the widely used SimpleScalar
+ simulator.
+ </p>
+ </div>
+
+ <!--_________________________________________________________________________-->
+ <div class="doc_subsubsection"><a name="selectiondag">New Instruction
+ Selector Framework</a></div>
+
+ <div class="doc_text">
+ <p>This release includes a <a href="CodeGenerator.html#instselect">new framework
+ for building instruction selectors</a>, which has long been the hardest part of
+ building a new LLVM target. This framework handles a lot of the mundane (but
+ easy to get wrong) details of writing the instruction selector, such as
+ generating efficient code for <a
+ href="LangRef.html#i_getelementptr">getelementptr</a> instructions, promoting
+ small integer types to larger types (e.g. for RISC targets with one size of
+ integer registers), expanding 64-bit integer operations for 32-bit targets, etc.
+ Currently, the X86, PowerPC, Alpha, and IA-64 backends use this framework. The
+ SPARC backends will be migrated when time permits.
+ </p>
+ </div>
+
+ <!--_________________________________________________________________________-->
+ <div class="doc_subsubsection"><a name="customccs">New Support for Per-Function
+ Calling Conventions</a></div>
+
+ <div class="doc_text">
+ <p>LLVM 1.5 adds supports for <a href="LangRef.html#callingconv">per-function
+ calling conventions</a>. Traditionally, the LLVM code generators match the
+ native C calling conventions for a target. This is important for compatibility,
+ but is not very flexible. This release allows custom calling conventions to be
+ established for functions, and defines three target-independent conventions (<a
+ href="LangRef.html#callingconv">C call, fast call, and cold call</a>) which may
+ be supported by code generators. When possible, the LLVM optimizer promotes C
+ functions to use the "fastcc" convention, allowing the use of more efficient
+ calling sequences (e.g., parameters are passed in registers in the X86 target).
+ </p>
+
+ <p>Targets may now also define target-specific calling conventions, allowing
+ LLVM to fully support calling convention altering options (e.g. GCC's
+ <tt>-mregparm</tt> flag) and well-defined target conventions (e.g. stdcall and
+ fastcall on X86).</p>
+ </div>
+
+ <!--_________________________________________________________________________-->
+ <div class="doc_subsubsection"><a name="tailcalls">New Support for
+ Proper Tail Calls</a></div>
+
+ <div class="doc_text">
+ <p>The release now includes support for <a
+ href="http://doi.acm.org/10.1145/277650.277719">proper tail calls</a>, as
+ required to implement languages like Scheme. Tail calls make use of two
+ features: custom calling conventions (described above), which allow the code
+ generator to use a convention where the caller deallocates its stack before it
+ returns. The second feature is a flag on the <a href="LangRef.html#i_call">call
+ instruction</a>, which indicates that the callee does not access the caller's
+ stack frame (indicating that it is acceptable to deallocate the caller stack
+ before invoking the callee). LLVM proper tail calls run on the system stack (as
+ do normal calls), supports indirect tail calls, tail calls with arbitrary
+ numbers of arguments, tail calls where the callee requires more argument space
+ than the caller, etc. The only case not supported are varargs calls, but that
+ could be added if desired.
+ </p>
+
+ <p>In order for a front-end to get a guaranteed tail call, it must mark
+ functions as "fastcc", mark calls with the 'tail' marker, and follow the call
+ with a return of the called value (or void). The optimizer and code generator
+ attempt to handle more general cases, but the simple case will always work if
+ the code generator supports tail calls. Here is an example:</p>
+
+ <pre>
+ fastcc int %bar(int %X, int(double, int)* %FP) { ;<i> fastcc</i>
+ %Y = tail call fastcc int %FP(double 0.0, int %X) ;<i> tail, fastcc</i>
+ ret int %Y
+ }
+ </pre>
+
+ <p>In LLVM 1.5, the X86 code generator is the only target that has been enhanced
+ to support proper tail calls (other targets will be enhanced in future).
+ Further, because this support was added very close to the release, it is
+ disabled by default. Pass <tt>-enable-x86-fastcc</tt> to llc to enable it (this
+ will be enabled by default in the next release). The example above compiles to:
+ </p>
+
+ <pre>
+ bar:
+ sub ESP, 8 # Callee uses more space than the caller
+ mov ECX, DWORD PTR [ESP + 8] # Get the old return address
+ mov DWORD PTR [ESP + 4], 0 # First half of 0.0
+ mov DWORD PTR [ESP + 8], 0 # Second half of 0.0
+ mov DWORD PTR [ESP], ECX # Put the return address where it belongs
+ jmp EDX # Tail call "FP"
+ </pre>
+
+ <p>
+ With fastcc on X86, the first two integer arguments are passed in EAX/EDX, the
+ callee pops its arguments off the stack, and the argument area is always a
+ multiple of 8 bytes in size.
+ </p>
+
+ </div>
+
+ <!--_________________________________________________________________________-->
+ <div class="doc_subsubsection">Other New Features</div>
+
+ <div class="doc_text">
+ <ol>
+ <li>LLVM now includes an <a href="http://llvm.cs.uiuc.edu/PR415">
+ Interprocedural Sparse Conditional Constant Propagation</a> pass, named
+ -ipsccp, which is run by default at link-time.</li>
+ <li>LLVM 1.5 is now about 15% faster than LLVM 1.4 and its core data
+ structures use about 30% less memory.</li>
+ <li>Support for Microsoft Visual Studio is improved, and <a
+ href="GettingStartedVS.html">now documented</a>. Most LLVM tools build
+ natively with Visual C++ now.</li>
+ <li><a href="GettingStarted.html#config">Configuring LLVM to build a subset
+ of the available targets</a> is now implemented, via the
+ <tt>--en