<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Writing an LLVM Pass</title>
- <link rel="stylesheet" href="llvm.css" type="text/css">
+ <link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
<body>
<p>Now that we have a way to compile our new pass, we just have to write it.
Start out with:</p>
-<div class="doc_code"><pre>
+<div class="doc_code">
+<pre>
<b>#include</b> "<a href="http://llvm.org/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
<b>#include</b> "<a href="http://llvm.org/doxygen/Function_8h-source.html">llvm/Function.h</a>"
<b>#include</b> "<a href="http://llvm.org/doxygen/raw__ostream_8h.html">llvm/Support/raw_ostream.h</a>"
-</pre></div>
+</pre>
+</div>
<p>Which are needed because we are writing a <tt><a
href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a></tt>,
and we will be doing some printing.</p>
<p>Next we have:</p>
-<div class="doc_code"><pre>
+
+<div class="doc_code">
+<pre>
<b>using namespace llvm;</b>
-</pre></div>
+</pre>
+</div>
+
<p>... which is required because the functions from the include files
-live in the llvm namespace.
-</p>
+live in the llvm namespace.</p>
<p>Next we have:</p>
-<div class="doc_code"><pre>
+<div class="doc_code">
+<pre>
<b>namespace</b> {
-</pre></div>
+</pre>
+</div>
<p>... which starts out an anonymous namespace. Anonymous namespaces are to C++
what the "<tt>static</tt>" keyword is to C (at global scope). It makes the
-things declared inside of the anonymous namespace only visible to the current
+things declared inside of the anonymous namespace visible only to the current
file. If you're not familiar with them, consult a decent C++ book for more
information.</p>
<p>Next, we declare our pass itself:</p>
-<div class="doc_code"><pre>
+<div class="doc_code">
+<pre>
<b>struct</b> Hello : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
-</pre></div><p>
+</pre>
+</div>
<p>This declares a "<tt>Hello</tt>" class that is a subclass of <tt><a
href="http://llvm.org/doxygen/classllvm_1_1FunctionPass.html">FunctionPass</a></tt>.
The different builtin pass subclasses are described in detail <a
href="#passtype">later</a>, but for now, know that <a
-href="#FunctionPass"><tt>FunctionPass</tt></a>'s operate a function at a
+href="#FunctionPass"><tt>FunctionPass</tt></a>'s operate on a function at a
time.</p>
-<div class="doc_code"><pre>
- static char ID;
- Hello() : FunctionPass(ID) {}
-</pre></div><p>
+<div class="doc_code">
+<pre>
+ static char ID;
+ Hello() : FunctionPass(ID) {}
+</pre>
+</div>
-<p> This declares pass identifier used by LLVM to identify pass. This allows LLVM to
-avoid using expensive C++ runtime information.</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>
+<div class="doc_code">
+<pre>
<b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
- errs() << "<i>Hello: </i>" << F.getName() << "\n";
+ errs() << "<i>Hello: </i>";
+ errs().write_escaped(F.getName()) << "\n";
<b>return false</b>;
}
}; <i>// end of struct Hello</i>
-</pre></div>
+} <i>// end of anonymous namespace</i>
+</pre>
+</div>
<p>We declare a "<a href="#runOnFunction"><tt>runOnFunction</tt></a>" method,
which overloads an abstract virtual method inherited from <a
to do our thing, so we just print out our message with the name of each
function.</p>
-<div class="doc_code"><pre>
- char Hello::ID = 0;
-</pre></div>
+<div class="doc_code">
+<pre>
+char Hello::ID = 0;
+</pre>
+</div>
-<p> We initialize pass ID here. LLVM uses ID's address to identify pass so
+<p>We initialize pass ID here. LLVM uses ID's address to identify a pass, so
initialization value is not important.</p>
-<div class="doc_code"><pre>
- static RegisterPass<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>",
- false /* Only looks at CFG */,
- false /* Analysis Pass */);
-} <i>// end of anonymous namespace</i>
-</pre></div>
+<div class="doc_code">
+<pre>
+static RegisterPass<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>",
+ false /* Only looks at CFG */,
+ false /* Analysis Pass */);
+</pre>
+</div>
-<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>".
-Last two arguments describe its behavior.
-If a pass walks CFG without modifying it then third argument is set to true.
-If a pass is an analysis pass, for example dominator tree pass, then true
-is supplied as fourth argument. </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>". The last two arguments describe its behavior: if a pass walks CFG
+without modifying it then the third argument is set to <tt>true</tt>; if a pass
+is an analysis pass, for example dominator tree pass, then <tt>true</tt> is
+supplied as the fourth argument.</p>
<p>As a whole, the <tt>.cpp</tt> file looks like:</p>
-<div class="doc_code"><pre>
+<div class="doc_code">
+<pre>
<b>#include</b> "<a href="http://llvm.org/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
<b>#include</b> "<a href="http://llvm.org/doxygen/Function_8h-source.html">llvm/Function.h</a>"
<b>#include</b> "<a href="http://llvm.org/doxygen/raw__ostream_8h.html">llvm/Support/raw_ostream.h</a>"
Hello() : FunctionPass(ID) {}
<b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
- errs() << "<i>Hello: </i>" << F.getName() << "\n";
+ errs() << "<i>Hello: </i>";
+ errs().write_escaped(F.getName()) << '\n';
<b>return false</b>;
}
+
};
-
- char Hello::ID = 0;
- static RegisterPass<Hello> X("hello", "Hello World Pass", false, false);
}
-
-</pre></div>
+
+char Hello::ID = 0;
+static RegisterPass<Hello> X("hello", "Hello World Pass", false, false);
+</pre>
+</div>
<p>Now that it's all together, compile the file with a simple "<tt>gmake</tt>"
command in the local directory and you should get a new file
"<tt>Debug+Asserts/lib/Hello.so</tt>" under the top level directory of the LLVM
source tree (not in the local directory). Note that everything in this file is
-contained in an anonymous namespace: this reflects the fact that passes are self
-contained units that do not need external interfaces (although they can have
-them) to be useful.</p>
+contained in an anonymous namespace — this reflects the fact that passes
+are self contained units that do not need external interfaces (although they can
+have them) to be useful.</p>
</div>
OPTIONS:
Optimizations available:
...
- -funcresolve - Resolve Functions
- -gcse - Global Common Subexpression Elimination
- -globaldce - Dead Global Elimination
- <b>-hello - Hello World Pass</b>
- -indvars - Canonicalize Induction Variables
- -inline - Function Integration/Inlining
- -instcombine - Combine redundant instructions
+ -globalopt - Global Variable Optimizer
+ -globalsmodref-aa - Simple mod/ref analysis for globals
+ -gvn - Global Value Numbering
+ <b>-hello - Hello World Pass</b>
+ -indvars - Induction Variable Simplification
+ -inline - Function Integration/Inlining
+ -insert-edge-profiling - Insert instrumentation for edge profiling
...
</pre></div>
-<p>The pass name get added as the information string for your pass, giving some
+<p>The pass name gets added as the information string for your pass, giving some
documentation to users of <tt>opt</tt>. Now that you have a working pass, you
would go ahead and make it do the cool transformations you want. Once you get
it all working and tested, it may become useful to find out how fast your pass
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> runOnModule(Module &M) = 0;
+<b>virtual bool</b> runOnModule(Module &M) = 0;
</pre></div>
<p>The <tt>runOnModule</tt> method performs the interesting work of the pass.
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doInitialization(CallGraph &CG);
+<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>
<div class="doc_code"><pre>
- <b>virtual bool</b> runOnSCC(CallGraphSCC &SCC) = 0;
+<b>virtual bool</b> runOnSCC(CallGraphSCC &SCC) = 0;
</pre></div>
<p>The <tt>runOnSCC</tt> method performs the interesting work of the pass, and
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doFinalization(CallGraph &CG);
+<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_code"><pre>
- <b>virtual bool</b> doInitialization(Module &M);
+<b>virtual bool</b> doInitialization(Module &M);
</pre></div>
<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> runOnFunction(Function &F) = 0;
+<b>virtual bool</b> runOnFunction(Function &F) = 0;
</pre></div><p>
<p>The <tt>runOnFunction</tt> method must be implemented by your subclass to do
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doFinalization(Module &M);
+<b>virtual bool</b> doFinalization(Module &M);
</pre></div>
<p>The <tt>doFinalization</tt> method is an infrequently used method that is
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doInitialization(Loop *, LPPassManager &LPM);
+<b>virtual bool</b> doInitialization(Loop *, LPPassManager &LPM);
</pre></div>
<p>The <tt>doInitialization</tt> method is designed to do simple initialization
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> runOnLoop(Loop *, LPPassManager &LPM) = 0;
+<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
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doFinalization();
+<b>virtual bool</b> doFinalization();
</pre></div>
<p>The <tt>doFinalization</tt> method is an infrequently used method that is
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doInitialization(Region *, RGPassManager &RGM);
+<b>virtual bool</b> doInitialization(Region *, RGPassManager &RGM);
</pre></div>
<p>The <tt>doInitialization</tt> method is designed to do simple initialization
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> runOnRegion(Region *, RGPassManager &RGM) = 0;
+<b>virtual bool</b> runOnRegion(Region *, RGPassManager &RGM) = 0;
</pre></div><p>
<p>The <tt>runOnRegion</tt> method must be implemented by your subclass to do
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doFinalization();
+<b>virtual bool</b> doFinalization();
</pre></div>
<p>The <tt>doFinalization</tt> method is an infrequently used method that is
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doInitialization(Function &F);
+<b>virtual bool</b> doInitialization(Function &F);
</pre></div>
<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> runOnBasicBlock(BasicBlock &BB) = 0;
+<b>virtual bool</b> runOnBasicBlock(BasicBlock &BB) = 0;
</pre></div>
<p>Override this function to do the work of the <tt>BasicBlockPass</tt>. This
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> doFinalization(Function &F);
+<b>virtual bool</b> doFinalization(Function &F);
</pre></div>
<p>The <tt>doFinalization</tt> method is an infrequently used method that is
<div>
<div class="doc_code"><pre>
- <b>virtual bool</b> runOnMachineFunction(MachineFunction &MF) = 0;
+<b>virtual bool</b> runOnMachineFunction(MachineFunction &MF) = 0;
</pre></div>
<p><tt>runOnMachineFunction</tt> can be considered the main entry point of a
<div>
<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(std::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
<div>
<div class="doc_code"><pre>
- <b>virtual void</b> getAnalysisUsage(AnalysisUsage &Info) <b>const</b>;
+<b>virtual void</b> getAnalysisUsage(AnalysisUsage &Info) <b>const</b>;
</pre></div>
<p>By implementing the <tt>getAnalysisUsage</tt> method, the required and
<div>
<div class="doc_code"><pre>
- <i>// This example modifies the program, but does not modify the CFG</i>
-
<b>void</b> <a href="http://llvm.org/doxygen/structLICM.html">LICM</a>::getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
- AU.setPreservesCFG();
-
AU.addRequired<<a href="http://llvm.org/doxygen/classllvm_1_1LoopInfo.html">LoopInfo</a>>();
- }
+<i>// This example modifies the program, but does not modify the CFG</i>
+<b>void</b> <a href="http://llvm.org/doxygen/structLICM.html">LICM</a>::getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
+ AU.setPreservesCFG();
+ AU.addRequired<<a href="http://llvm.org/doxygen/classllvm_1_1LoopInfo.html">LoopInfo</a>>();
+}
</pre></div>
</div>
want, and returns a reference to that pass. For example:</p>
<div class="doc_code"><pre>
- bool LICM::runOnFunction(Function &F) {
- LoopInfo &LI = getAnalysis<LoopInfo>();
- ...
- }
+bool LICM::runOnFunction(Function &F) {
+ LoopInfo &LI = getAnalysis<LoopInfo>();
+ ...
+}
</pre></div>
<p>This method call returns a reference to the pass desired. You may get a
For example:</p>
<div class="doc_code"><pre>
- bool ModuleLevelPass::runOnModule(Module &M) {
- ...
- DominatorTree &DT = getAnalysis<DominatorTree>(Func);
- ...
- }
+bool ModuleLevelPass::runOnModule(Module &M) {
+ ...
+ DominatorTree &DT = getAnalysis<DominatorTree>(Func);
+ ...
+}
</pre></div>
<p>In above example, runOnFunction for DominatorTree is called by pass manager
if it is active. For example:</p>
<div class="doc_code"><pre>
- ...
- if (DominatorSet *DS = getAnalysisIfAvailable<DominatorSet>()) {
- <i>// A DominatorSet is active. This code will update it.</i>
- }
- ...
+...
+if (DominatorSet *DS = getAnalysisIfAvailable<DominatorSet>()) {
+ <i>// A DominatorSet is active. This code will update it.</i>
+}
+...
</pre></div>
</div>
for the Analysis Group Interface itself, because it is "abstract":</p>
<div class="doc_code"><pre>
-
<b>static</b> RegisterAnalysisGroup<<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>> A("<i>Alias Analysis</i>");
+<b>static</b> RegisterAnalysisGroup<<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>> A("<i>Alias Analysis</i>");
</pre></div>
<p>Once the analysis is registered, passes can declare that they are valid
//<i> Declare that we implement the AliasAnalysis interface</i>
INITIALIZE_AG_PASS(FancyAA, <a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>, "<i>somefancyaa</i>",
"<i>A more complex alias analysis implementation</i>",
- false, // <i>Is CFG Only?</i>
- true, // <i>Is Analysis?</i>
- false, // <i>Is default Analysis Group implementation?</i>
- );
+ false, // <i>Is CFG Only?</i>
+ true, // <i>Is Analysis?</i>
+ false); // <i>Is default Analysis Group implementation?</i>
}
</pre></div>
"<i>Basic Alias Analysis (default AA impl)</i>",
false, // <i>Is CFG Only?</i>
true, // <i>Is Analysis?</i>
- true, // <i>Is default Analysis Group implementation?</i>
- );
+ true); // <i>Is default Analysis Group implementation?</i>
}
</pre></div>
href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method to our pass:</p>
<div class="doc_code"><pre>
- <i>// We don't modify the program, so we preserve all analyses</i>
- <b>virtual void</b> getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
- AU.setPreservesAll();
- }
+<i>// We don't modify the program, so we preserve all analyses</i>
+<b>virtual void</b> getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
+ AU.setPreservesAll();
+}
</pre></div>
<p>Now when we run our pass, we get this output:</p>
allocator machine pass.</p>
<p>Implement your register allocator machine pass. In your register allocator
-.cpp file add the following include;</p>
+<tt>.cpp</tt> 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
form; </p>
<div class="doc_code"><pre>
- FunctionPass *createMyRegisterAllocator() {
- return new MyRegisterAllocator();
- }
+FunctionPass *createMyRegisterAllocator() {
+ return new MyRegisterAllocator();
+}
</pre></div>
<p>Note that the signature of this function should match the type of
"installing" declaration, in the form;</p>
<div class="doc_code"><pre>
- static RegisterRegAlloc myRegAlloc("myregalloc",
- " my register allocator help string",
- createMyRegisterAllocator);
+static RegisterRegAlloc myRegAlloc("myregalloc",
+ "my register allocator help string",
+ createMyRegisterAllocator);
</pre></div>
<p>Note the two spaces prior to the help string produces a tidy result on the
<p>And finally, declare the command line option for your passes. Example:</p>
<div class="doc_code"><pre>
- cl::opt<RegisterMyPasses::FunctionPassCtor, false,
- RegisterPassParser<RegisterMyPasses> >
- MyPassOpt("mypass",
- cl::init(&createDefaultMyPass),
- cl::desc("my pass option help"));
+cl::opt<RegisterMyPasses::FunctionPassCtor, false,
+ RegisterPassParser<RegisterMyPasses> >
+MyPassOpt("mypass",
+ cl::init(&createDefaultMyPass),
+ cl::desc("my pass option help"));
</pre></div>
<p>Here the command option is "mypass", with createDefaultMyPass as the default
projects / oota-llvm.git / blobdiff