<ul>
<li><a href="#makefile">Setting up the build environment</a></li>
<li><a href="#basiccode">Basic code required</a></li>
- <li><a href="#running">Running a pass with <tt>opt</tt>
- or <tt>analyze</tt></a></li>
+ <li><a href="#running">Running a pass with <tt>opt</tt></a></li>
</ul></li>
<li><a href="#passtype">Pass classes and requirements</a>
<ul>
</ul></li>
<li><a href="#CallGraphSCCPass">The <tt>CallGraphSCCPass</tt> class</a>
<ul>
- <li><a href="#doInitialization_scc">The <tt>doInitialization(Module
+ <li><a href="#doInitialization_scc">The <tt>doInitialization(CallGraph
&)</tt> method</a></li>
<li><a href="#runOnSCC">The <tt>runOnSCC</tt> method</a></li>
- <li><a href="#doFinalization_scc">The <tt>doFinalization(Module
+ <li><a href="#doFinalization_scc">The <tt>doFinalization(CallGraph
&)</tt> method</a></li>
</ul></li>
<li><a href="#FunctionPass">The <tt>FunctionPass</tt> class</a>
<li><a href="#doFinalization_mod">The <tt>doFinalization(Module
&)</tt> method</a></li>
</ul></li>
+ <li><a href="#LoopPass">The <tt>LoopPass</tt> class</a>
+ <ul>
+ <li><a href="#doInitialization_loop">The <tt>doInitialization(Loop *,
+ LPPassManager &)</tt> method</a></li>
+ <li><a href="#runOnLoop">The <tt>runOnLoop</tt> method</a></li>
+ <li><a href="#doFinalization_loop">The <tt>doFinalization()
+ </tt> method</a></li>
+ </ul></li>
<li><a href="#BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
<ul>
<li><a href="#doInitialization_fn">The <tt>doInitialization(Function
<li><a href="#future">Future extensions planned</a>
<ul>
<li><a href="#SMP">Multithreaded LLVM</a></li>
- <li><a href="#PassFunctionPass"><tt>ModulePass</tt>es requiring
- <tt>FunctionPass</tt>es</a></li>
</ul></li>
</ol>
<div class="doc_author">
- <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
- <a href="mailto:jlaskey@apple.com">Jim Laskey</a></p>
+ <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
+ <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
</div>
<!-- *********************************************************************** -->
the <tt><a href="#ModulePass">ModulePass</a></tt>, <tt><a
href="#CallGraphSCCPass">CallGraphSCCPass</a></tt>, <tt><a
href="#FunctionPass">FunctionPass</a></tt>, or <tt><a
+href="#LoopPass">LoopPass</a></tt>, or <tt><a
href="#BasicBlockPass">BasicBlockPass</a></tt> classes, which gives the system
more information about what your pass does, and how it can be combined with
other passes. One of the main features of the LLVM Pass Framework is that it
# Name of the library to build
LIBRARYNAME = Hello
-# Build a dynamically linkable shared object
-SHARED_LIBRARY = 1
-
# Make the shared library become a loadable module so the tools can
# dlopen/dlsym on the resulting library.
LOADABLE_MODULE = 1
+# Tell the build system which LLVM libraries your pass needs. You'll probably
+# need at least LLVMSystem.a, LLVMSupport.a, LLVMCore.a but possibly several
+# others too.
+LLVMLIBS = LLVMCore.a LLVMSupport.a LLVMSystem.a
+
# Include the makefile implementation stuff
include $(LEVEL)/Makefile.common
</pre></div>
<p>This makefile specifies that all of the <tt>.cpp</tt> files in the current
directory are to be compiled and linked together into a
<tt>Debug/lib/Hello.so</tt> shared object that can be dynamically loaded by
-the <tt>opt</tt> or <tt>analyze</tt> tools via their <tt>-load</tt> options.
+the <tt>opt</tt> or <tt>bugpoint</tt> tools via their <tt>-load</tt> options.
If your operating system uses a suffix other than .so (such as windows or
Mac OS/X), the appropriate extension will be used.</p>
href="#FunctionPass"><tt>FunctionPass</tt></a>'s operate a function at a
time.</p>
+<div class="doc_code"><pre>
+ static const int ID;
+ Hello() : FunctionPass((intptr_t)&ID) {}
+</pre></div><p>
+
+<p> This declares pass identifier used by LLVM to identify pass. This allows LLVM to
+avoid using expensive C++ runtime information.</p>
+
<div class="doc_code"><pre>
<b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
- std::cerr << "<i>Hello: </i>" << F.getName() << "\n";
+ llvm::cerr << "<i>Hello: </i>" << F.getName() << "\n";
<b>return false</b>;
}
}; <i>// end of struct Hello</i>
function.</p>
<div class="doc_code"><pre>
- RegisterOpt<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>");
+ const int Hello::ID = 0;
+</pre></div>
+
+<p> We initialize pass ID here. LLVM uses ID's address to identify pass so
+initialization value is not important.</p>
+
+<div class="doc_code"><pre>
+ RegisterPass<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>");
} <i>// end of anonymous namespace</i>
</pre></div>
-<p>Lastly, we register our class <tt>Hello</tt>, giving it a command line
-argument "<tt>hello</tt>", and a name "<tt>Hello World Pass</tt>". There are
-several different ways of <a href="#registration">registering your pass</a>,
-depending on what it is to be used for. For "optimizations" we use the
-<tt>RegisterOpt</tt> template.</p>
+<p>Lastly, we <a href="#registration">register our class</a> <tt>Hello</tt>,
+giving it a command line
+argument "<tt>hello</tt>", and a name "<tt>Hello World Pass</tt>".</p>
<p>As a whole, the <tt>.cpp</tt> file looks like:</p>
<b>namespace</b> {
<b>struct Hello</b> : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
+
+ static const int ID;
+ Hello() : FunctionPass((intptr_t)&ID) {}
+
<b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
- std::cerr << "<i>Hello: </i>" << F.getName() << "\n";
+ llvm::cerr << "<i>Hello: </i>" << F.getName() << "\n";
<b>return false</b>;
}
};
- RegisterOpt<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>");
+ RegisterPass<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>");
}
</pre></div>
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="running">Running a pass with <tt>opt</tt> or <tt>analyze</tt></a>
+ <a name="running">Running a pass with <tt>opt</tt></a>
</div>
<div class="doc_text">
<p>Now that you have a brand new shiny shared object file, we can use the
<tt>opt</tt> command to run an LLVM program through your pass. Because you
-registered your pass with the <tt>RegisterOpt</tt> template, you will be able to
+registered your pass with the <tt>RegisterPass</tt> template, you will be able to
use the <tt>opt</tt> tool to access it, once loaded.</p>
<p>To test it, follow the example at the end of the <a
<tt>ModulePass</tt> indicates that your pass uses the entire program as a unit,
refering to function bodies in no predictable order, or adding and removing
functions. Because nothing is known about the behavior of <tt>ModulePass</tt>
-subclasses, no optimization can be done for their execution.</p>
+subclasses, no optimization can be done for their execution. A module pass
+can use function level passes (e.g. dominators) using getAnalysis interface
+<tt> getAnalysis<DominatorTree>(Function)</tt>. </p>
<p>To write a correct <tt>ModulePass</tt> subclass, derive from
<tt>ModulePass</tt> and overload the <tt>runOnModule</tt> method with the
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="doInitialization_scc">The <tt>doInitialization(Module &)</tt>
+ <a name="doInitialization_scc">The <tt>doInitialization(CallGraph &)</tt>
method</a>
</div>
<div class="doc_text">
<div class="doc_code"><pre>
- <b>virtual bool</b> doInitialization(Module &M);
+ <b>virtual bool</b> doInitialization(CallGraph &CG);
</pre></div>
<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="doFinalization_scc">The <tt>doFinalization(Module
+ <a name="doFinalization_scc">The <tt>doFinalization(CallGraph
&)</tt> method</a>
</div>
<div class="doc_text">
<div class="doc_code"><pre>
- <b>virtual bool</b> doFinalization(Module &M);
+ <b>virtual bool</b> doFinalization(CallGraph &CG);
</pre></div>
<p>The <tt>doFinalization</tt> method is an infrequently used method that is
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="LoopPass">The <tt>LoopPass</tt> class </a>
+</div>
+
+<div class="doc_text">
+
+<p> All <tt>LoopPass</tt> execute on each loop in the function independent of
+all of the other loops in the function. <tt>LoopPass</tt> processes loops in
+loop nest order such that outer most loop is processed last. </p>
+
+<p> <tt>LoopPass</tt> subclasses are allowed to update loop nest using
+<tt>LPPassManager</tt> interface. Implementing a loop pass is usually
+straightforward. <tt>Looppass</tt>'s may overload three virtual methods to
+do their work. All these methods should return true if they modified the
+program, or false if they didn't. </p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="doInitialization_loop">The <tt>doInitialization(Loop *,
+ LPPassManager &)</tt>
+ method</a>
+</div>
+
+<div class="doc_text">
+
+<div class="doc_code"><pre>
+ <b>virtual bool</b> doInitialization(Loop *, LPPassManager &LPM);
+</pre></div>
+
+The <tt>doInitialization</tt> method is designed to do simple initialization
+type of stuff that does not depend on the functions being processed. The
+<tt>doInitialization</tt> method call is not scheduled to overlap with any
+other pass executions (thus it should be very fast). LPPassManager
+interface should be used to access Function or Module level analysis
+information.</p>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="runOnLoop">The <tt>runOnLoop</tt> method</a>
+</div>
+
+<div class="doc_text">
+
+<div class="doc_code"><pre>
+ <b>virtual bool</b> runOnLoop(Loop *, LPPassManager &LPM) = 0;
+</pre></div><p>
+
+<p>The <tt>runOnLoop</tt> method must be implemented by your subclass to do
+the transformation or analysis work of your pass. As usual, a true value should
+be returned if the function is modified. <tt>LPPassManager</tt> interface
+should be used to update loop nest.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="doFinalization_loop">The <tt>doFinalization()</tt> method</a>
+</div>
+
+<div class="doc_text">
+
+<div class="doc_code"><pre>
+ <b>virtual bool</b> doFinalization();
+</pre></div>
+
+<p>The <tt>doFinalization</tt> method is an infrequently used method that is
+called when the pass framework has finished calling <a
+href="#runOnLoop"><tt>runOnLoop</tt></a> for every loop in the
+program being compiled. </p>
+
+</div>
+
+
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
pass registration works, and discussed some of the reasons that it is used and
what it does. Here we discuss how and why passes are registered.</p>
-<p>Passes can be registered in several different ways. Depending on the general
-classification of the pass, you should use one of the following templates to
-register the pass:</p>
-
-<ul>
-<li><b><tt>RegisterOpt</tt></b> - This template should be used when you are
-registering a pass that logically should be available for use in the
-'<tt>opt</tt>' utility.</li>
-
-<li><b><tt>RegisterAnalysis</tt></b> - This template should be used when you are
-registering a pass that logically should be available for use in the
-'<tt>analyze</tt>' utility.</li>
-
-<li><b><tt>RegisterPass</tt></b> - This is the generic form of the
-<tt>Register*</tt> templates that should be used if you want your pass listed by
-multiple or no utilities. This template takes an extra third argument that
-specifies which tools it should be listed in. See the <a
-href="http://llvm.org/doxygen/PassSupport_8h-source.html">PassSupport.h</a>
-file for more information.</li>
-
-</ul>
-
-<p>Regardless of how you register your pass, you must specify at least two
+<p>As we saw above, passes are registered with the <b><tt>RegisterPass</tt></b>
+template, which requires you to pass at least two
parameters. The first parameter is the name of the pass that is to be used on
the command line to specify that the pass should be added to a program (for
-example <tt>opt</tt> or <tt>analyze</tt>). The second argument is the name of
-the pass, which is to be used for the <tt>--help</tt> output of programs, as
+example, with <tt>opt</tt> or <tt>bugpoint</tt>). The second argument is the
+name of the pass, which is to be used for the <tt>--help</tt> output of
+programs, as
well as for debug output generated by the <tt>--debug-pass</tt> option.</p>
-<p>If a pass is registered to be used by the <tt>analyze</tt> utility, you
-should implement the virtual <tt>print</tt> method:</p>
+<p>If you want your pass to be easily dumpable, you should
+implement the virtual <tt>print</tt> method:</p>
</div>
<div class="doc_text">
<div class="doc_code"><pre>
- <b>virtual void</b> print(std::ostream &O, <b>const</b> Module *M) <b>const</b>;
+ <b>virtual void</b> print(llvm::OStream &O, <b>const</b> Module *M) <b>const</b>;
</pre></div>
<p>The <tt>print</tt> method must be implemented by "analyses" in order to print
a human readable version of the analysis results. This is useful for debugging
an analysis itself, as well as for other people to figure out how an analysis
-works. The <tt>analyze</tt> tool uses this method to generate its output.</p>
+works. Use the <tt>opt -analyze</tt> argument to invoke this method.</p>
-<p>The <tt>ostream</tt> parameter specifies the stream to write the results on,
+<p>The <tt>llvm::OStream</tt> parameter specifies the stream to write the results on,
and the <tt>Module</tt> parameter gives a pointer to the top level module of the
program that has been analyzed. Note however that this pointer may be null in
certain circumstances (such as calling the <tt>Pass::dump()</tt> from a
declare as required in your <a
href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> implementation. This
method can be called by your <tt>run*</tt> method implementation, or by any
-other local method invoked by your <tt>run*</tt> method.</p>
+other local method invoked by your <tt>run*</tt> method.
+
+A module level pass can use function level analysis info using this interface.
+For example:</p>
+
+<div class="doc_code"><pre>
+ bool ModuleLevelPass::runOnModule(Module &M) {
+ ...
+ DominatorTree &DT = getAnalysis<DominatorTree>(Func);
+ ...
+ }
+</pre></div>
+
+In above example, runOnFunction for DominatorTree is called by pass manager
+before returning a reference to the desired pass.</p>
<p>
If your pass is capable of updating analyses if they exist (e.g.,
<div class="doc_code"><pre>
<b>namespace</b> {
//<i> Analysis Group implementations <b>must</b> be registered normally...</i>
- RegisterOpt<FancyAA>
+ RegisterPass<FancyAA>
B("<i>somefancyaa</i>", "<i>A more complex alias analysis implementation</i>");
//<i> Declare that we implement the AliasAnalysis interface</i>
- RegisterAnalysisGroup<<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>, FancyAA> C;
+ RegisterAnalysisGroup<<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>> C(B);
}
</pre></div>
<div class="doc_code"><pre>
<b>namespace</b> {
//<i> Analysis Group implementations <b>must</b> be registered normally...</i>
- Register
Opt<<a href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">BasicAliasAnalysis</a>>
+ Register
Pass<<a href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">BasicAliasAnalysis</a>>
D("<i>basicaa</i>", "<i>Basic Alias Analysis (default AA impl)</i>");
//<i> Declare that we implement the AliasAnalysis interface</i>
- RegisterAnalysisGroup<<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>, <a href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">BasicAliasAnalysis</a>, <b>true</b>> E;
+ RegisterAnalysisGroup<<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>, <b>true</b>> E(D);
}
</pre></div>
.cpp file add the following include;</p>
<div class="doc_code"><pre>
- #include ""llvm/CodeGen/RegAllocRegistry.h""
+ #include "llvm/CodeGen/RegAllocRegistry.h"
</pre></div>
<p>Also in your register allocator .cpp file, define a creator function in the
<p>And that's it. The user is now free to use <tt>-regalloc=myregalloc</tt> as
an option. Registering instruction schedulers is similar except use the
-<tt>RegisterRegAlloc</tt> class. Note that the
-<tt>RegisterRegAlloc::FunctionPassCtor</tt> is significantly different from
+<tt>RegisterScheduler</tt> class. Note that the
+<tt>RegisterScheduler::FunctionPassCtor</tt> is significantly different from
<tt>RegisterRegAlloc::FunctionPassCtor</tt>.</p>
<p>To force the load/linking of your register allocator into the llc/lli tools,
want:</p>
<div class="doc_code"><pre>
-(gdb) <b>break PassManager::run</b>
+(gdb) <b>break llvm::PassManager::run</b>
Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.
(gdb) <b>run test.bc -load $(LLVMTOP)/llvm/Debug/lib/[libname].so -[passoption]</b>
Starting program: opt test.bc -load $(LLVMTOP)/llvm/Debug/lib/[libname].so -[passoption]
haven't had time (or multiprocessor machines, thus a reason) to implement this.
Despite that, we have kept the LLVM passes SMP ready, and you should too.</p>
-</div>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
-<a name="PassFunctionPass"><tt>ModulePass</tt>es requiring <tt>FunctionPass</tt>es</a>
-</div>
-
-<div class="doc_text">
-
-<p>Currently it is illegal for a <a href="#ModulePass"><tt>ModulePass</tt></a>
-to require a <a href="#FunctionPass"><tt>FunctionPass</tt></a>. This is because
-there is only one instance of the <a
-href="#FunctionPass"><tt>FunctionPass</tt></a> object ever created, thus nowhere
-to store information for all of the functions in the program at the same time.
-Although this has come up a couple of times before, this has always been worked
-around by factoring one big complicated pass into a global and an
-interprocedural part, both of which are distinct. In the future, it would be
-nice to have this though.</p>
-
-<p>Note that it is no problem for a <a
-href="#FunctionPass"><tt>FunctionPass</tt></a> to require the results of a <a
-href="#ModulePass"><tt>ModulePass</tt></a>, only the other way around.</p>
-
-</div>
-
<!-- *********************************************************************** -->
<hr>
<address>
projects / oota-llvm.git / blobdiff