diff options
| -rw-r--r-- | docs/WritingAnLLVMPass.html | 1144 |
1 files changed, 645 insertions, 499 deletions
diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html index dc70d036c8..3570717b75 100644 --- a/docs/WritingAnLLVMPass.html +++ b/docs/WritingAnLLVMPass.html @@ -1,146 +1,158 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>Writing an LLVM Pass</title></head> - -<body bgcolor=white> - -<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> -<tr><td> <font size=+3 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>Writing an LLVM Pass</b></font></td> -</tr></table> - +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>Writing an LLVM Pass</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<div class="doc_title"> + Writing an LLVM Pass +</div> <ol> - <li><a href="#introduction">Introduction - What is a pass?</a> + <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><a href="#basiccode">Basic code required</a> + <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> - </ul> + or <tt>analyze</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><a href="#ImmutablePass">The <tt>ImmutablePass</tt> class</a></li> <li><a href="#Pass">The <tt>Pass</tt> class</a> <ul> - <li><a href="#run">The <tt>run</tt> method</a> - </ul> + <li><a href="#run">The <tt>run</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><a href="#runOnFunction">The <tt>runOnFunction</tt> method</a> + &)</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> - </ul> + &)</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><a href="#runOnBasicBlock">The <tt>runOnBasicBlock</tt> method</a> + &)</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> - </ul> + &)</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> - </ul> + <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> - </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><a href="#getAnalysis">The <tt>getAnalysis</tt> method</a> - </ul> + <li><a href="#getAnalysisUsage">The <tt>getAnalysisUsage</tt> + method</a></li> + <li><a href="#getAnalysis">The <tt>getAnalysis</tt> method</a></li> + </ul></li> <li><a href="#analysisgroup">Implementing Analysis Groups</a> <ul> - <li><a href="#agconcepts">Analysis Group Concepts</a> - <li><a href="#registerag">Using <tt>RegisterAnalysisGroup</tt></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="#passmanager">What PassManager does</a> <ul> - <li><a href="#releaseMemory">The <tt>releaseMemory</tt> method</a> - </ul> + <li><a href="#releaseMemory">The <tt>releaseMemory</tt> method</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 - <li><a href="#debugmisc">Miscellaneous Problems - </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><a href="#ModuleSource">A new <tt>ModuleSource</tt> interface</a> - <li><a href="#PassFunctionPass"><tt>Pass</tt>'s requiring <tt>FunctionPass</tt>'s</a> - </ul> - + <li><a href="#SMP">Multithreaded LLVM</a></li> + <li><a href="#ModuleSource">A new <tt>ModuleSource</tt> interface</a></li> + <li><a href="#PassFunctionPass"><tt>Pass</tt>es requiring + <tt>FunctionPass</tt>es</a></li> + </ul></li> +</ol> + +<div class="doc_text"> <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></b><p> -</ol><p> - - +</div> <!-- *********************************************************************** --> -<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> -<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b> -<a name="introduction">Introduction - What is a pass? -</b></font></td></tr></table><ul> +<div class="doc_section"> + <a name="introduction">Introduction - What is a pass?</a> +</div> <!-- *********************************************************************** --> -The LLVM Pass Framework is an important part of the LLVM system, because LLVM +<div class="doc_text"> + +<p>The LLVM Pass Framework is an important part of the LLVM system, because LLVM passes are where 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> - -All LLVM passes are subclasses of the <tt><a -href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt> class, which -implement functionality by overriding virtual methods inherited from -<tt>Pass</tt>. Depending on how your pass works, you may be able to inherit -from the <tt><a -href="http://llvm.cs.uiuc.edu/doxygen/structFunctionPass.html">FunctionPass</a></tt> +all, a structuring technique for compiler code.</p> + +<p>All LLVM passes are subclasses of the <tt><a +href="http://llvm.cs.uiuc.edu/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 may be able to +inherit from the <tt><a +href="http://llvm.cs.uiuc.edu/doxygen/structllvm_1_1FunctionPass.html">FunctionPass</a></tt> or <tt><a -href="http://llvm.cs.uiuc.edu/doxygen/structBasicBlockPass.html">BasicBlockPass</a></tt>, +href="http://llvm.cs.uiuc.edu/doxygen/structllvm_1_1BasicBlockPass.html">BasicBlockPass</a></tt>, 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 has.<p> +constraints that your pass has.</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> +<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> <!-- *********************************************************************** --> -</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> -<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b> -<a name="quickstart">Quick Start - Writing hello world -</b></font></td></tr></table><ul> +<div class="doc_section"> + <a name="quickstart">Quick Start - Writing hello world</a> +</div> <!-- *********************************************************************** --> -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 +<div class="doc_text"> + +<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, 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> +source tree in the <tt>lib/Transforms/Hello</tt> directory.</p> +</div> <!-- ======================================================================= --> -</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> -<tr><td> </td><td width="100%"> -<font color="#EEEEFF" face="Georgia,Palatino"><b> -<a name="makefile">Setting up the build environment -</b></font></td></tr></table><ul> +<div class="doc_subsection"> + <a name="makefile">Setting up the build environment</a> +</div> + +<div class="doc_text"> -First thing you need to do is create a new directory somewhere in the LLVM +<p>First thing you need to do is create a new directory somewhere in the LLVM source base. For this example, we'll assume that you made "<tt>lib/Transforms/Hello</tt>". The first thing you must do is set up a build script (Makefile) that will compile the source code for the new pass. To do -this, copy this into "<tt>Makefile</tt>":<p> +this, copy this into "<tt>Makefile</tt>":</p> -</ul><hr><ul><pre> +<hr> + +<pre> # Makefile for hello pass # Path to top level of LLVM heirarchy @@ -154,87 +166,89 @@ SHARED_LIBRARY = 1 # Include the makefile implementation stuff include $(LEVEL)/Makefile.common -</pre></ul><hr><ul><p> +</pre> -This makefile specifies that all of the <tt>.cpp</tt> files in the current +<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>lib/Debug/libhello.so</tt> shared object that can be dynamically loaded by -the <tt>opt</tt> or <tt>analyze</tt> tools.<p> +the <tt>opt</tt> or <tt>analyze</tt> tools.</p> -Now that we have the build scripts set up, we just need to write the code for -the pass itself.<p> +<p>Now that we have the build scripts set up, we just need to write the code for +the pass itself.</p> +</div> <!-- ======================================================================= --> -</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> -<tr><td> </td><td width="100%"> -<font color="#EEEEFF" face="Georgia,Palatino"><b> -<a name="basiccode">Basic code required -</b></font></td></tr></table><ul> +<div class="doc_subsection"> + <a name="basiccode">Basic code required</a> +</div> + +<div class="doc_text"> -Now that we have a way to compile our new pass, we just have to write it. Start -out with:<p> +<p>Now that we have a way to compile our new pass, we just have to write it. +Start out with:</p> <pre> <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Pass_8h-source.html">llvm/Pass.h</a>" <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Function_8h-source.html">llvm/Function.h</a>" </pre> -Which are needed because we are writing a <tt><a -href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt>, and we are -operating on <tt><a -href="http://llvm.cs.uiuc.edu/doxygen/classFunction.html">Function</a></tt>'s.<p> +<p>Which are needed because we are writing a <tt><a +href="http://llvm.cs.uiuc.edu/doxygen/classllvm_1_1Pass.html">Pass</a></tt>, and +we are operating on <tt><a +href="http://llvm.cs.uiuc.edu/doxygen/classllvm_1_1Function.html">Function</a></tt>'s.</p> -Next we have:<p> +<p>Next we have:</p> <pre> <b>namespace</b> { -</pre><p> +</pre> -... which starts out an anonymous namespace. Anonymous namespaces are to C++ +<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 file. If you're not familiar with them, consult a decent C++ book for more -information.<p> +information.</p> -Next, we declare our pass itself:<p> +<p>Next, we declare our pass itself:</p> <pre> <b>struct</b> Hello : <b>public</b> <a href="#FunctionPass">FunctionPass</a> { </pre><p> -This declares a "<tt>Hello</tt>" class that is a subclass of <tt><a -href="http://llvm.cs.uiuc.edu/doxygen/structFunctionPass.html">FunctionPass</a></tt>. +<p>This declares a "<tt>Hello</tt>" class that is a subclass of <tt><a +href="http://llvm.cs.uiuc.edu/doxygen/structllvm_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 time.<p> +href="#passtype">later</a>, but for now, know that <a +href="#FunctionPass"><tt>FunctionPass</tt></a>'s operate a function at a +time.</p> <pre> - <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { + <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { std::cerr << "<i>Hello: </i>" << F.getName() << "\n"; <b>return false</b>; } }; <i>// end of struct Hello</i> </pre> -We declare a "<a href="#runOnFunction"><tt>runOnFunction</tt></a>" method, which -overloads an abstract virtual method inherited from <a +<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> +function.</p> <pre> RegisterOpt<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>"); } <i>// end of anonymous namespace</i> -</pre><p> +</pre> -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 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> -As a whole, the <tt>.cpp</tt> file looks like:<p> +<p>As a whole, the <tt>.cpp</tt> file looks like:</p> <pre> <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Pass_8h-source.html">llvm/Pass.h</a>" @@ -242,7 +256,7 @@ 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> { - <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { + <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { std::cerr << "<i>Hello: </i>" << F.getName() << "\n"; <b>return false</b>; } @@ -250,50 +264,51 @@ As a whole, the <tt>.cpp</tt> file looks like:<p> RegisterOpt<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>"); } -</pre><p> +</pre> -Now that it's all together, compile the file with a simple "<tt>gmake</tt>" +<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 "<tt>lib/Debug/libhello.so</tt> file. 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> +them) to be useful.</p> +</div> <!-- ======================================================================= --> -</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> -<tr><td> </td><td width="100%"> -<font color="#EEEEFF" face="Georgia,Palatino"><b> -<a name="running">Running a pass with <tt>opt</tt> or <tt>analyze</tt> -</b></font></td></tr></table><ul> +<div class="doc_subsection"> + <a name="running">Running a pass with <tt>opt</tt> or <tt>analyze</tt></a> +</div> -Now that you have a brand new shiny <tt>.so</tt> file, we can use the +<div class="doc_text"> + +<p>Now that you have a brand new shiny <tt>.so</tt> 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 -use the <tt>opt</tt> tool to access it, once loaded.<p> +use the <tt>opt</tt> tool to access it, once loaded.</p> -To test it, follow the example at the end of the <a +<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 bytecode file (<tt>hello.bc</tt>) for the program through our transformation like this (or course, any bytecode file will -work):<p> +work):</p> <pre> $ opt -load ../../../lib/Debug/libhello.so -hello < hello.bc > /dev/null Hello: __main Hello: puts Hello: main -</pre><p> +</pre> -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 +<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> +<tt>/dev/null</tt>).</p> -To see what happened to the other string you registered, try running -<tt>opt</tt> with the <tt>--help</tt> option:<p> +<p>To see what happened to the other string you registered, try running +<tt>opt</tt> with the <tt>--help</tt> option:</p> <pre> $ opt -load ../../../lib/Debug/libhello.so --help @@ -312,16 +327,16 @@ OPTIONS: -inline - Function Integration/Inlining -instcombine - Combine redundant instructions ... -</pre><p> +</pre> -The pass name get added as the information string for your pass, giving some +<p>The pass name get 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> +example:</p> <pre> $ opt -load ../../../lib/Debug/libhello.so -hello -time-passes < hello.bc > /dev/null @@ -339,400 +354,469 @@ Hello: main 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><p> +</pre> -As you can see, our implementation above is pretty fast :). The additional +<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. - -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> +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> <!-- *********************************************************************** --> -</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> -<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b> -<a name="passtype">Pass classes and requirements -</b></font></td></tr></table><ul> +<div class="doc_section"> + <a name="passtype">Pass classes and requirements</a> +</div> <!-- *********************************************************************** --> -One of the first things that you should do when designing a new pass is to +<div class="doc_text"> + +<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> +available, from the most general to the most specific.</p> -When choosing a superclass for your Pass, you should choose the <b>most +<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 unneccesarily -slow.<p> +slow.</p> +</div> <!-- ======================================================================= --> -</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> -<tr><td> </td><td width="100%"> -<font color="#EEEEFF" face="Georgia,Palatino"><b> -<a name="ImmutablePass">The <tt>ImmutablePass</tt> class -</b></font></td></tr></table><ul> - -The most plain and boring type of pass is the "<tt><a -href="http://llvm.cs.uiuc.edu/doxygen/structImmutablePass.html">ImmutablePass</a></tt>" +<div class="doc_subsection"> + <a name="ImmutablePass">The <tt>ImmutablePass</tt> class</a> +</div> + +<div class="doc_text"> + +<p>The most plain and boring type of pass is the "<tt><a +href="http://llvm.cs.uiuc.edu/doxygen/structllvm_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> +compiler configuration.</p> -Although this pass class is very infrequently used, it is important for +<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> +other static information that can affect the various transformations.</p> -<tt>ImmutablePass</tt>'s never invalidate other transformations, are never -invalidated, and are never "run".<p> +<p><tt>ImmutablePass</tt>es never invalidate other transformations, are never +invalidated, and are never "run".</p> +</div> <!-- ======================================================================= --> -</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> -<tr><td> </td><td width="100%"> -<font color="#EEEEFF" face="Georgia,Palatino"><b> -<a name="Pass">The <tt>Pass</tt> class -</b></font></td></tr></table><ul> +<div class="doc_subsection"> + <a name="Pass">The <tt>Pass</tt> class</a> +</div> -The "<tt><a href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt>" +<div class="doc_text"> + +<p>The "<tt><a +href="http://llvm.cs.uiuc.edu/doxygen/classllvm_1_1Pass.html">Pass</a></tt>" class is the most general of all superclasses that you can use. Deriving from <tt>Pass</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 direct <tt>Pass</tt> -subclasses, no optimization can be done for their execution.<p> +subclasses, no optimization can be done for their execution.</p> + +<p>To write a correct <tt>Pass</tt> subclass, derive from <tt>Pass</tt> and +overload the <tt>run</tt> method with the following signature:</p> -To write a correct <tt>Pass</tt> subclass, derive from <tt>Pass</tt> and -overload the <tt>run</tt> method with the following signature:<p> +</div> <!-- _______________________________________________________________________ --> -</ul><h4><a name="run"><hr size=0>The <tt>run</tt> method</h4><ul> +<div class="doc_subsubsection"> + <a name="run">The <tt>run</tt> method</a> +</div> +<div class="doc_text"> <pre> <b>virtual bool</b> run(Module &M) = 0; -</pre><p> +</pre> -The <tt>run</tt> method performs the interesting work of the pass, and should +<p>The <tt>run</tt> method performs the interesting work of the pass, and should return true if the module was modified by the transformation, false -otherwise.<p> - +otherwise.</p> +</div> <!-- ======================================================================= --> -</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> -<tr><td> </td><td width="100%"> -<font color="#EEEEFF" face="Georgia,Palatino"><b> -<a name="FunctionPass">The <tt>FunctionPass</tt> class -</b></font></td></tr></table><ul> - -In contrast to direct <tt>Pass</tt> subclasses, direct <tt><a -href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">FunctionPass</a></tt> +<div class="doc_subsection"> + <a name="FunctionPass">The <tt>FunctionPass</tt> class</a> +</div> + +<div class="doc_text"> + +<p>In contrast to direct <tt>Pass</tt> subclasses, direct <tt><a +href="http://llvm.cs.uiuc.edu/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> +order, and <tt>FunctionPass</tt>'s do not modify external functions.</p> -To be explicit, <tt>FunctionPass</tt> subclasses are not allowed to:<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>Add or remove Function's from the current Module. -<li>Add or remove global variables from the current Module. +<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) -</ol><p> + <a href="#runOnFunction"><tt>runOnFunction</tt></a> (including global data)</li> +</ol> -Implementing a <tt>FunctionPass</tt> is usually straightforward (See the <a +<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> +should return true if they modified the program, or false if they didn't.</p> + +</div> <!-- _______________________________________________________________________ --> -</ul><h4><a name="doInitialization_mod"><hr size=0>The -<tt>doInitialization(Module &)</tt> method</h4><ul> +<div class="subsubsection"> + <a name="doInitialization_mod">The <tt>doInitialization(Module &)</tt> + method</a> +</div> + +<div class="doc_text"> <pre> <b>virtual bool</b> doInitialization(Module &M); -</pre><p> +</pre> -The <tt>doIninitialize</tt> method is allowed to do most of the things that +<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> +fast).</p> -A good example of how this method should be used is the <a +<p>A good example of how this method should be used is the <a href="http://llvm.cs.uiuc.edu/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> +free functions that it needs, adding prototypes to the module if necessary.</p> + +</div> <!-- _______________________________________________________________________ --> -</ul><h4><a name="runOnFunction"><hr size=0>The <tt>runOnFunction</tt> method</h4><ul> +<div class="subsubsection"> + <a name="runOnFunction">The <tt>runOnFunction</tt> method</a> +</div> + +<div class="doc_text"> <pre> <b>virtual bool</b> runOnFunction(Function &F) = 0; </pre><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> +<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> <!-- _______________________________________________________________________ --> -</ul><h4><a name="doFinalization_mod"><hr size=0>The <tt>doFinalization(Module &)</tt> method</h4><ul> +<div class="subsubsection"> + <a name="doFinalization_mod">The <tt>doFinalization(Module + &)</tt> method</a> +</div> + +<div class="doc_text"> <pre> <b>virtual bool</b> doFinalization(Module &M); -</pre></p> +</pre> -The <tt>doFinalization</tt> method is an infrequently used method that is called -when the pass framework has finished calling <a +<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> - +program being compiled.</p> +</div> <!-- ======================================================================= --> -</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> -<tr><td> </td><td width="100%"> -<font color="#EEEEFF" face="Georgia,Palatino"><b> -<a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a> -</b></font></td></tr></table><ul> +<div class="doc_subsection"> + <a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a> +</div> + +<div class="doc_text"> -<tt>BasicBlockPass</tt>'s are just like <a +<p><tt>BasicBlockPass</tt>'s are just like <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s, except that they must limit their scope of inspection and modification to a single basic block at a time. -As such, they are <b>not</b> allowed to do any of the following:<p> +As such, they are <b>not</b> allowed to do any of the following:</p> <ol> -<li>Modify or inspect any basic blocks outside of the current one +<li>Modify or inspect any basic blocks outside of the current one</li> <li>Maintain state across invocations of - <a href="#runOnBasicBlock"><tt>runOnBasicBlock</tt></a> -<li>Modify the constrol flow graph (by altering terminator instructions) + <a href="#runOnBasicBlock"><tt>runOnBasicBlock</tt></a></li> +<li>Modify the constrol flow graph (by altering terminator instructions)</li> <li>Any of the things verboten for - <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s. -</ol><p> + <a href="#FunctionPass"><tt>FunctionPass</tt></a>es.</li> +</ol> -<tt>BasicBlockPass</tt>'s are useful for traditional local and "peephole" +<p><tt>BasicBlockPass</tt>es are useful for traditional local and "peephole" optimizations. They may override the same <a href="#doInitialization_mod"><tt>doInitialization(Module &)</tt></a> and <a href="#doFinalization_mod"><tt>doFinalization(Module &)</tt></a> methods that <a -href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have the following virtual methods that may also be implemented:<p> +href="#FunctionPass"& |