diff options
Diffstat (limited to 'docs/WritingAnLLVMPass.html')
| -rw-r--r-- | docs/WritingAnLLVMPass.html | 1954 |
1 files changed, 0 insertions, 1954 deletions
diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html deleted file mode 100644 index af1ffa4fb7..0000000000 --- a/docs/WritingAnLLVMPass.html +++ /dev/null @@ -1,1954 +0,0 @@ -<!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>Writing an LLVM Pass</title> - <link rel="stylesheet" href="_static/llvm.css" type="text/css"> -</head> -<body> - -<h1> - Writing an LLVM Pass -</h1> - -<ol> - <li><a href="#introduction">Introduction - What is a pass?</a></li> - <li><a href="#quickstart">Quick Start - Writing hello world</a> - <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></a></li> - </ul></li> - <li><a href="#passtype">Pass classes and requirements</a> - <ul> - <li><a href="#ImmutablePass">The <tt>ImmutablePass</tt> class</a></li> - <li><a href="#ModulePass">The <tt>ModulePass</tt> class</a> - <ul> - <li><a href="#runOnModule">The <tt>runOnModule</tt> method</a></li> - </ul></li> - <li><a href="#CallGraphSCCPass">The <tt>CallGraphSCCPass</tt> class</a> - <ul> - <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(CallGraph - &)</tt> method</a></li> - </ul></li> - <li><a href="#FunctionPass">The <tt>FunctionPass</tt> class</a> - <ul> - <li><a href="#doInitialization_mod">The <tt>doInitialization(Module - &)</tt> method</a></li> - <li><a href="#runOnFunction">The <tt>runOnFunction</tt> method</a></li> - <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="#RegionPass">The <tt>RegionPass</tt> class</a> - <ul> - <li><a href="#doInitialization_region">The <tt>doInitialization(Region *, - RGPassManager &)</tt> method</a></li> - <li><a href="#runOnRegion">The <tt>runOnRegion</tt> method</a></li> - <li><a href="#doFinalization_region">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 - &)</tt> method</a></li> - <li><a href="#runOnBasicBlock">The <tt>runOnBasicBlock</tt> - method</a></li> - <li><a href="#doFinalization_fn">The <tt>doFinalization(Function - &)</tt> method</a></li> - </ul></li> - <li><a href="#MachineFunctionPass">The <tt>MachineFunctionPass</tt> - class</a> - <ul> - <li><a href="#runOnMachineFunction">The - <tt>runOnMachineFunction(MachineFunction &)</tt> method</a></li> - </ul></li> - </ul> - <li><a href="#registration">Pass Registration</a> - <ul> - <li><a href="#print">The <tt>print</tt> method</a></li> - </ul></li> - <li><a href="#interaction">Specifying interactions between passes</a> - <ul> - <li><a href="#getAnalysisUsage">The <tt>getAnalysisUsage</tt> - method</a></li> - <li><a href="#AU::addRequired">The <tt>AnalysisUsage::addRequired<></tt> and <tt>AnalysisUsage::addRequiredTransitive<></tt> methods</a></li> - <li><a href="#AU::addPreserved">The <tt>AnalysisUsage::addPreserved<></tt> method</a></li> - <li><a href="#AU::examples">Example implementations of <tt>getAnalysisUsage</tt></a></li> - <li><a href="#getAnalysis">The <tt>getAnalysis<></tt> and -<tt>getAnalysisIfAvailable<></tt> methods</a></li> - </ul></li> - <li><a href="#analysisgroup">Implementing Analysis Groups</a> - <ul> - <li><a href="#agconcepts">Analysis Group Concepts</a></li> - <li><a href="#registerag">Using <tt>RegisterAnalysisGroup</tt></a></li> - </ul></li> - <li><a href="#passStatistics">Pass Statistics</a> - <li><a href="#passmanager">What PassManager does</a> - <ul> - <li><a href="#releaseMemory">The <tt>releaseMemory</tt> method</a></li> - </ul></li> - <li><a href="#registering">Registering dynamically loaded passes</a> - <ul> - <li><a href="#registering_existing">Using existing registries</a></li> - <li><a href="#registering_new">Creating new registries</a></li> - </ul></li> - <li><a href="#debughints">Using GDB with dynamically loaded passes</a> - <ul> - <li><a href="#breakpoint">Setting a breakpoint in your pass</a></li> - <li><a href="#debugmisc">Miscellaneous Problems</a></li> - </ul></li> - <li><a href="#future">Future extensions planned</a> - <ul> - <li><a href="#SMP">Multithreaded LLVM</a></li> - </ul></li> -</ol> - -<div class="doc_author"> - <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and - <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p> -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="introduction">Introduction - What is a pass?</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<p>The LLVM Pass Framework is an important part of the LLVM system, because LLVM -passes are where most of the interesting parts of the compiler exist. Passes -perform the transformations and optimizations that make up the compiler, they -build the analysis results that are used by these transformations, and they are, -above all, a structuring technique for compiler code.</p> - -<p>All LLVM passes are subclasses of the <tt><a -href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a></tt> -class, which implement functionality by overriding virtual methods inherited -from <tt>Pass</tt>. Depending on how your pass works, you should inherit from -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="#RegionPass">RegionPass</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 -schedules passes to run in an efficient way based on the constraints that your -pass meets (which are indicated by which class they derive from).</p> - -<p>We start by showing you how to construct a pass, everything from setting up -the code, to compiling, loading, and executing it. After the basics are down, -more advanced features are discussed.</p> - -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="quickstart">Quick Start - Writing hello world</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<p>Here we describe how to write the "hello world" of passes. The "Hello" pass -is designed to simply print out the name of non-external functions that exist in -the program being compiled. It does not modify the program at all, it just -inspects it. The source code and files for this pass are available in the LLVM -source tree in the <tt>lib/Transforms/Hello</tt> directory.</p> - -<!-- ======================================================================= --> -<h3> - <a name="makefile">Setting up the build environment</a> -</h3> - -<div> - - <p>First, configure and build LLVM. This needs to be done directly inside the - LLVM source tree rather than in a separate objects directory. - Next, you need to create a new directory somewhere in the LLVM source - base. For this example, we'll assume that you made - <tt>lib/Transforms/Hello</tt>. Finally, you must set up a build script - (Makefile) that will compile the source code for the new pass. To do this, - copy the following into <tt>Makefile</tt>:</p> - <hr> - -<div class="doc_code"><pre> -# Makefile for hello pass - -# Path to top level of LLVM hierarchy -LEVEL = ../../.. - -# Name of the library to build -LIBRARYNAME = Hello - -# Make the shared library become a loadable module so the tools can -# dlopen/dlsym on the resulting library. -LOADABLE_MODULE = 1 - -# 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 shared object -<tt>$(LEVEL)/Debug+Asserts/lib/Hello.so</tt> that can be dynamically loaded by -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> - -<p>If you are used CMake to build LLVM, see -<a href="CMake.html#passdev">Developing an LLVM pass with CMake</a>.</p> - -<p>Now that we have the build scripts set up, we just need to write the code for -the pass itself.</p> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="basiccode">Basic code required</a> -</h3> - -<div> - -<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> -<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> - -<p>Which are needed because we are writing a <tt><a -href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a></tt>, -we are operating on <tt><a -href="http://llvm.org/doxygen/classllvm_1_1Function.html">Function</a></tt>'s, -and we will be doing some printing.</p> - -<p>Next we have:</p> - -<div class="doc_code"> -<pre> -<b>using namespace llvm;</b> -</pre> -</div> - -<p>... which is required because the functions from the include files -live in the llvm namespace.</p> - -<p>Next we have:</p> - -<div class="doc_code"> -<pre> -<b>namespace</b> { -</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 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> - <b>struct</b> Hello : <b>public</b> <a href="#FunctionPass">FunctionPass</a> { -</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 on a function at a -time.</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> - -<div class="doc_code"> -<pre> - <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { - errs() << "<i>Hello: </i>"; - errs().write_escaped(F.getName()) << "\n"; - <b>return false</b>; - } - }; <i>// end of struct Hello</i> -} <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 -href="#FunctionPass"><tt>FunctionPass</tt></a>. This is where we are supposed -to do our thing, so we just print out our message with the name of each -function.</p> - -<div class="doc_code"> -<pre> -char Hello::ID = 0; -</pre> -</div> - -<p>We initialize pass ID here. LLVM uses ID's address to identify a pass, so -initialization value is not important.</p> - -<div class="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>". 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> -<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>" - -<b>using namespace llvm;</b> - -<b>namespace</b> { - <b>struct Hello</b> : <b>public</b> <a href="#FunctionPass">FunctionPass</a> { - - static char ID; - Hello() : FunctionPass(ID) {} - - <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { - 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> - -<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> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="running">Running a pass with <tt>opt</tt></a> -</h3> - -<div> - -<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 <tt>RegisterPass</tt>, 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 -href="GettingStarted.html">Getting Started Guide</a> to compile "Hello World" to -LLVM. We can now run the bitcode file (<tt>hello.bc</tt>) for the program -through our transformation like this (or course, any bitcode file will -work):</p> - -<div class="doc_code"><pre> -$ opt -load ../../../Debug+Asserts/lib/Hello.so -hello < hello.bc > /dev/null -Hello: __main -Hello: puts -Hello: main -</pre></div> - -<p>The '<tt>-load</tt>' option specifies that '<tt>opt</tt>' should load your -pass as a shared object, which makes '<tt>-hello</tt>' a valid command line -argument (which is one reason you need to <a href="#registration">register your -pass</a>). Because the hello pass does not modify the program in any -interesting way, we just throw away the result of <tt>opt</tt> (sending it to -<tt>/dev/null</tt>).</p> - -<p>To see what happened to the other string you registered, try running -<tt>opt</tt> with the <tt>-help</tt> option:</p> - -<div class="doc_code"><pre> -$ opt -load ../../../Debug+Asserts/lib/Hello.so -help -OVERVIEW: llvm .bc -> .bc modular optimizer - -USAGE: opt [options] <input bitcode> - -OPTIONS: - Optimizations available: -... - -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 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 -is. The <a href="#passManager"><tt>PassManager</tt></a> provides a nice command -line option (<tt>--time-passes</tt>) that allows you to get information about -the execution time of your pass along with the other passes you queue up. For -example:</p> - -<div class="doc_code"><pre> -$ opt -load ../../../Debug+Asserts/lib/Hello.so -hello -time-passes < hello.bc > /dev/null -Hello: __main -Hello: puts -Hello: main -=============================================================================== - ... Pass execution timing report ... -=============================================================================== - Total Execution Time: 0.02 seconds (0.0479059 wall clock) - - ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Pass Name --- - 0.0100 (100.0%) 0.0000 ( 0.0%) 0.0100 ( 50.0%) 0.0402 ( 84.0%) Bitcode Writer - 0.0000 ( 0.0%) 0.0100 (100.0%) 0.0100 ( 50.0%) 0.0031 ( 6.4%) Dominator Set Construction - 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0013 ( 2.7%) Module Verifier - <b> 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0033 ( 6.9%) Hello World Pass</b> - 0.0100 (100.0%) 0.0100 (100.0%) 0.0200 (100.0%) 0.0479 (100.0%) TOTAL -</pre></div> - -<p>As you can see, our implementation above is pretty fast :). The additional -passes listed are automatically inserted by the '<tt>opt</tt>' tool to verify -that the LLVM emitted by your pass is still valid and well formed LLVM, which -hasn't been broken somehow.</p> - -<p>Now that you have seen the basics of the mechanics behind passes, we can talk -about some more details of how they work and how to use them.</p> - -</div> - -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="passtype">Pass classes and requirements</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<p>One of the first things that you should do when designing a new pass is to -decide what class you should subclass for your pass. The <a -href="#basiccode">Hello World</a> example uses the <tt><a -href="#FunctionPass">FunctionPass</a></tt> class for its implementation, but we -did not discuss why or when this should occur. Here we talk about the classes -available, from the most general to the most specific.</p> - -<p>When choosing a superclass for your Pass, you should choose the <b>most -specific</b> class possible, while still being able to meet the requirements -listed. This gives the LLVM Pass Infrastructure information necessary to -optimize how passes are run, so that the resultant compiler isn't unnecessarily -slow.</p> - -<!-- ======================================================================= --> -<h3> - <a name="ImmutablePass">The <tt>ImmutablePass</tt> class</a> -</h3> - -<div> - -<p>The most plain and boring type of pass is the "<tt><a -href="http://llvm.org/doxygen/classllvm_1_1ImmutablePass.html">ImmutablePass</a></tt>" -class. This pass type is used for passes that do not have to be run, do not -change state, and never need to be updated. This is not a normal type of -transformation or analysis, but can provide information about the current -compiler configuration.</p> - -<p>Although this pass class is very infrequently used, it is important for -providing information about the current target machine being compiled for, and -other static information that can affect the various transformations.</p> - -<p><tt>ImmutablePass</tt>es never invalidate other transformations, are never -invalidated, and are never "run".</p> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="ModulePass">The <tt>ModulePass</tt> class</a> -</h3> - -<div> - -<p>The "<tt><a -href="http://llvm.org/doxygen/classllvm_1_1ModulePass.html">ModulePass</a></tt>" -class is the most general of all superclasses that you can use. Deriving from -<tt>ModulePass</tt> indicates that your pass uses the entire program as a unit, -referring to function bodies in no predictable order, or adding and removing -functions. Because nothing is known about the behavior of <tt>ModulePass</tt> -subclasses, no optimization can be done for their execution.</p> - -<p>A module pass can use function level passes (e.g. dominators) using -the getAnalysis interface -<tt>getAnalysis<DominatorTree>(llvm::Function *)</tt> to provide the -function to retrieve analysis result for, if the function pass does not require -any module or immutable passes. Note that this can only be done for functions for which the -analysis ran, e.g. in the case of dominators you should only ask for the -DominatorTree for function definitions, not declarations.</p> - -<p>To write a correct <tt>ModulePass</tt> subclass, derive from -<tt>ModulePass</tt> and overload the <tt>runOnModule</tt> method with the -following signature:</p> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="runOnModule">The <tt>runOnModule</tt> method</a> -</h4> - -<div> - -<div class="doc_code"><pre> -<b>virtual bool</b> runOnModule(Module &M) = 0; -</pre></div> - -<p>The <tt>runOnModule</tt> method performs the interesting work of the pass. -It should return true if the module was modified by the transformation and -false otherwise.</p> - -</div> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="CallGraphSCCPass">The <tt>CallGraphSCCPass</tt> class</a> -</h3> - -<div> - -<p>The "<tt><a -href="http://llvm.org/doxygen/classllvm_1_1CallGraphSCCPass.html">CallGraphSCCPass</a></tt>" -is used by passes that need to traverse the program bottom-up on the call graph -(callees before callers). Deriving from CallGraphSCCPass provides some -mechanics for building and traversing the CallGraph, but also allows the system -to optimize execution of CallGraphSCCPass's. If your pass meets the -requirements outlined below, and doesn't meet the requirements of a <tt><a -href="#FunctionPass">FunctionPass</a></tt> or <tt><a -href="#BasicBlockPass">BasicBlockPass</a></tt>, you should derive from -<tt>CallGraphSCCPass</tt>.</p> - -<p><b>TODO</b>: explain briefly what SCC, Tarjan's algo, and B-U mean.</p> - -<p>To be explicit, <tt>CallGraphSCCPass</tt> subclasses are:</p> - -<ol> - -<li>... <em>not allowed</em> to inspect or modify any <tt>Function</tt>s other -than those in the current SCC and the direct callers and direct callees of the -SCC.</li> - -<li>... <em>required</em> to preserve the current CallGraph object, updating it -to reflect any changes made to the program.</li> - -<li>... <em>not allowed</em> to add or remove SCC's from the current Module, -though they may change the contents of an SCC.</li> - -<li>... <em>allowed</em> to add or remove global variables from the current -Module.</li> - -<li>... <em>allowed</em> to maintain state across invocations of - <a href="#runOnSCC"><tt>runOnSCC</tt></a> (including global data).</li> -</ol> - -<p>Implementing a <tt>CallGraphSCCPass</tt> is slightly tricky in some cases -because it has to handle SCCs with more than one node in it. All of the virtual -methods described below should return true if they modified the program, or -false if they didn't.</p> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="doInitialization_scc"> - The <tt>doInitialization(CallGraph &)</tt> method - </a> -</h4> - -<div> - -<div class="doc_code"><pre> -<b>virtual bool</b> doInitialization(CallGraph &CG); -</pre></div> - -<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that -<tt>CallGraphSCCPass</tt>'s are not allowed to do. They can add and remove -functions, get pointers to functions, etc. The <tt>doInitialization</tt> method -is designed to do simple initialization type of stuff that does not depend on -the SCCs being processed. The <tt>doInitialization</tt> method call is not -scheduled to overlap with any other pass executions (thus it should be very -fast).</p> - -</div> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="runOnSCC">The <tt>runOnSCC</tt> method</a> -</h4> - -<div> - -<div class="doc_code"><pre> -<b>virtual bool</b> runOnSCC(CallGraphSCC &SCC) = 0; -</pre></div> - -<p>The <tt>runOnSCC</tt> method performs the interesting work of the pass, and -should return true if the module was modified by the transformation, false -otherwise.</p> - -</div> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="doFinalization_scc"> - The <tt>doFinalization(CallGraph &)</tt> method - </a> -</h4> - -<div> - -<div class="doc_code"><pre> -<b>virtual bool</b> doFinalization(CallGraph &CG); -</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="#runOnFunction"><tt>runOnFunction</tt></a> for every function in the -program being compiled.</p> - -</div> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="FunctionPass">The <tt>FunctionPass</tt> class</a> -</h3> - -<div> - -<p>In contrast to <tt>ModulePass</tt> subclasses, <tt><a -href="http://llvm.org/doxygen/classllvm_1_1Pass.html">FunctionPass</a></tt> -subclasses do have a predictable, local behavior that can be expected by the -system. All <tt>FunctionPass</tt> execute on each function in the program -independent of all of the other functions in the program. -<tt>FunctionPass</tt>'s do not require that they are executed in a particular -order, and <tt>FunctionPass</tt>'s do not modify external functions.</p> - -<p>To be explicit, <tt>FunctionPass</tt> subclasses are not allowed to:</p> - -<ol> -<li>Modify a Function other than the one currently being processed.</li> -<li>Add or remove Function's from the current Module.</li> -<li>Add or remove global variables from the current Module.</li> -<li>Maintain state across invocations of - <a href="#runOnFunction"><tt>runOnFunction</tt></a> (including global data)</li> -</ol> - -<p>Implementing a <tt>FunctionPass</tt> is usually straightforward (See the <a -href="#basiccode">Hello World</a> pass for example). <tt>FunctionPass</tt>'s -may overload three virtual methods to do their work. All of these methods -should return true if they modified the program, or false if they didn't.</p> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="doInitialization_mod"> - The <tt>doInitialization(Module &)</tt> method - </a> -</h4> - -<div> - -<div class="doc_code"><pre> -<b>virtual bool</b> doInitialization(Module &M); -</pre></div> - -<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that -<tt>FunctionPass</tt>'s are not allowed to do. They can add and remove -functions, get pointers to functions, etc. 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).</p> - -<p>A good example of how this method should be used is the <a -href="http://llvm.org/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations</a> -pass. This pass converts <tt>malloc</tt> and <tt>free</tt> instructions into -platform dependent <tt>malloc()</tt> and <tt>free()</tt> function calls. It -uses the <tt>doInitialization</tt> method to get a reference to the malloc and -free functions that it needs, adding prototypes to the module if necessary.</p> - -</div> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="runOnFunction">The <tt>runOnFunction</tt> method</a> -</h4> - -<div> - -<div class="doc_code"><pre> -<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 -the transformation or analysis work of your pass. As usual, a true value should -be returned if the function is modified.</p> - -</div> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="doFinalization_mod"> - The <tt>doFinalization(Module &)</tt> method - </a> -</h4> - -<div> - -<div class="doc_code"><pre> -<b>virtual bool</b> doFinalization(Module &M); -</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="#runOnFunction"><tt>runOnFunction</tt></a> for every function in the -program being compiled.</p> - -</div> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="LoopPass">The <tt>LoopPass</tt> class </a> -</h3> - -<div> - -<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> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="doInitialization_loop"> - The <tt>doInitialization(Loop *,LPPassManager &)</tt> method - </a> -</h4> - -<div> - -<div class="doc_code"><pre> -<b>virtual bool</b> doInitialization(Loop *, LPPassManager &LPM); -</pre></div> - -<p>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> - - -<!-- _______________________________________________________________________ --> -<h4> - <a name="runOnLoop">The <tt>runOnLoop</tt> method</a> -</h4> - -<div> - -<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> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="doFinalization_loop">The <tt>doFinalization()</tt> method</a> -</h4> - -<div> - -<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 - |