X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FWritingAnLLVMPass.html;h=af1ffa4fb7adeb8e3bd26d0b65b68a8467d624f1;hb=1c211640e53226540cd403948f5dd89c36c4beb8;hp=f3e791f094ba366a917f6585c0a8137a5c5cf005;hpb=6f25d9fa83ab992151c550e7f3180a3a2a4d34ab;p=oota-llvm.git diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html index f3e791f094b..af1ffa4fb7a 100644 --- a/docs/WritingAnLLVMPass.html +++ b/docs/WritingAnLLVMPass.html @@ -4,13 +4,13 @@ Writing an LLVM Pass - + -
+

Writing an LLVM Pass -

+
  1. Introduction - What is a pass?
    2. @@ -51,6 +51,14 @@
  2. The doFinalization() method
    3. +
  3. The RegionPass class +
  4. The BasicBlockPass class
- - -
- The runOnMachineFunction(MachineFunction - &MF) method -
+

+ + The runOnMachineFunction(MachineFunction &MF) method + +

-
+
-  virtual bool runOnMachineFunction(MachineFunction &MF) = 0;
+virtual bool runOnMachineFunction(MachineFunction &MF) = 0;

runOnMachineFunction can be considered the main entry point of a @@ -959,23 +1069,26 @@ remember, you may not modify the LLVM Function or its contents from a

+
+ + + -
+

Pass registration -

+ -
+

In the Hello World example pass we illustrated how 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.

As we saw above, passes are registered with the RegisterPass -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 +template. The template 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, with opt or bugpoint). The second argument is the +example, with opt or bugpoint). The first argument is the name of the pass, which is to be used for the -help output of programs, as well as for debug output generated by the --debug-pass option.

@@ -983,17 +1096,15 @@ well as for debug output generated by the --debug-pass option.

If you want your pass to be easily dumpable, you should implement the virtual print method:

-
- -
+

The print method -

+ -
+
-  virtual void print(std::ostream &O, const Module *M) const;
+virtual void print(std::ostream &O, const Module *M) const;

The print method must be implemented by "analyses" in order to print @@ -1010,13 +1121,15 @@ depended on.

+
+ -
+

Specifying interactions between passes -

+ -
+

One of the main responsibilities of the PassManager is to make sure that passes interact with each other correctly. Because PassManager @@ -1033,17 +1146,15 @@ specifies. If a pass does not implement the getAnalysisUsage method, it defaults to not having any prerequisite passes, and invalidating all other passes.

-
- -
+

The getAnalysisUsage method -

+ -
+
-  virtual void getAnalysisUsage(AnalysisUsage &Info) const;
+virtual void getAnalysisUsage(AnalysisUsage &Info) const;

By implementing the getAnalysisUsage method, the required and @@ -1056,11 +1167,14 @@ object:

-
- The AnalysisUsage::addRequired<> and AnalysisUsage::addRequiredTransitive<> methods -
- -
+

+ + The AnalysisUsage::addRequired<> + and AnalysisUsage::addRequiredTransitive<> methods + +

+ +

If your pass requires a previous pass to be executed (an analysis for example), it can use one of these methods to arrange for it to be run before your pass. @@ -1082,11 +1196,13 @@ pass is.

-
- The AnalysisUsage::addPreserved<> method -
+

+ + The AnalysisUsage::addPreserved<> method + +

-
+

One of the jobs of the PassManager is to optimize how and when analyses are run. In particular, it attempts to avoid recomputing data unless it needs to. For @@ -1117,40 +1233,33 @@ the fact that it hacks on the CFG.

-
- Example implementations of getAnalysisUsage -
- -
- -
-  // This is an example implementation from an analysis, which does not modify
-  // the program at all, yet has a prerequisite.
-  void PostDominanceFrontier::getAnalysisUsage(AnalysisUsage &AU) const {
-    AU.setPreservesAll();
-    AU.addRequired<PostDominatorTree>();
-  }
-
+

+ + Example implementations of getAnalysisUsage + +

-

and:

+
-  // This example modifies the program, but does not modify the CFG
-  void LICM::getAnalysisUsage(AnalysisUsage &AU) const {
-    AU.setPreservesCFG();
-    AU.addRequired<LoopInfo>();
-  }
+// This example modifies the program, but does not modify the CFG
+void LICM::getAnalysisUsage(AnalysisUsage &AU) const {
+  AU.setPreservesCFG();
+  AU.addRequired<LoopInfo>();
+}
-
- The getAnalysis<> and -getAnalysisIfAvailable<> methods -
+

+ + The getAnalysis<> and + getAnalysisIfAvailable<> methods + +

-
+

The Pass::getAnalysis<> method is automatically inherited by your class, providing you with access to the passes that you declared that you @@ -1159,10 +1268,10 @@ method. It takes a single template argument that specifies which pass class you want, and returns a reference to that pass. For example:

-   bool LICM::runOnFunction(Function &F) {
-     LoopInfo &LI = getAnalysis<LoopInfo>();
-     ...
-   }
+bool LICM::runOnFunction(Function &F) {
+  LoopInfo &LI = getAnalysis<LoopInfo>();
+  ...
+}

This method call returns a reference to the pass desired. You may get a @@ -1176,11 +1285,11 @@ A module level pass can use function level analysis info using this interface. For example:

-   bool ModuleLevelPass::runOnModule(Module &M) {
-     ...
-     DominatorTree &DT = getAnalysis<DominatorTree>(Func);
-     ...
-   }
+bool ModuleLevelPass::runOnModule(Module &M) {
+  ...
+  DominatorTree &DT = getAnalysis<DominatorTree>(Func);
+  ...
+}

In above example, runOnFunction for DominatorTree is called by pass manager @@ -1193,22 +1302,24 @@ If your pass is capable of updating analyses if they exist (e.g., if it is active. For example:

-  ...
-  if (DominatorSet *DS = getAnalysisIfAvailable<DominatorSet>()) {
-    // A DominatorSet is active.  This code will update it.
-  }
-  ...
+...
+if (DominatorSet *DS = getAnalysisIfAvailable<DominatorSet>()) {
+  // A DominatorSet is active.  This code will update it.
+}
+...
+
+ -
+

Implementing Analysis Groups -

+ -
+

Now that we understand the basics of how passes are defined, how they are used, and how they are required from other passes, it's time to get a little bit @@ -1227,14 +1338,12 @@ between these two extremes for other implementations). To cleanly support situations like this, the LLVM Pass Infrastructure supports the notion of Analysis Groups.

-
- -
+

Analysis Group Concepts -

+ -
+

An Analysis Group is a single simple interface that may be implemented by multiple different passes. Analysis Groups can be given human readable names @@ -1252,7 +1361,7 @@ between passes still apply.

Although Pass Registration is optional for normal passes, all analysis group implementations must be registered, and must use the -RegisterAnalysisGroup template to join the +INITIALIZE_AG_PASS template to join the implementation pool. Also, a default implementation of the interface must be registered with RegisterAnalysisGroup.

@@ -1281,20 +1390,22 @@ hypothetical example) instead.

-
+

Using RegisterAnalysisGroup -

+ -
+

The RegisterAnalysisGroup template is used to register the analysis -group itself as well as add pass implementations to the analysis group. First, -an analysis should be registered, with a human readable name provided for it. +group itself, while the INITIALIZE_AG_PASS is used to add pass +implementations to the analysis group. First, +an analysis group should be registered, with a human readable name +provided for it. Unlike registration of passes, there is no command line argument to be specified for the Analysis Group Interface itself, because it is "abstract":

-  static RegisterAnalysisGroup<AliasAnalysis> A("Alias Analysis");
+static RegisterAnalysisGroup<AliasAnalysis> A("Alias Analysis");

Once the analysis is registered, passes can declare that they are valid @@ -1302,35 +1413,34 @@ implementations of the interface by using the following code:

 namespace {
-  // Analysis Group implementations must be registered normally...
-  RegisterPass<FancyAA>
-  B("somefancyaa", "A more complex alias analysis implementation");
-
   // Declare that we implement the AliasAnalysis interface
-  RegisterAnalysisGroup<AliasAnalysis> C(B);
+  INITIALIZE_AG_PASS(FancyAA, AliasAnalysis, "somefancyaa",
+                     "A more complex alias analysis implementation",
+                     false,  // Is CFG Only?
+                     true,   // Is Analysis?
+                     false); // Is default Analysis Group implementation?
 }
-

This just shows a class FancyAA that is registered normally, then -uses the RegisterAnalysisGroup template to "join" the AliasAnalysis +

This just shows a class FancyAA that +uses the INITIALIZE_AG_PASS macro both to register and +to "join" the AliasAnalysis analysis group. Every implementation of an analysis group should join using -this template. A single pass may join multiple different analysis groups with -no problem.

+this macro.

 namespace {
-  // Analysis Group implementations must be registered normally...
-  RegisterPass<BasicAliasAnalysis>
-  D("basicaa", "Basic Alias Analysis (default AA impl)");
-
   // Declare that we implement the AliasAnalysis interface
-  RegisterAnalysisGroup<AliasAnalysis, true> E(D);
+  INITIALIZE_AG_PASS(BasicAA, AliasAnalysis, "basicaa",
+                     "Basic Alias Analysis (default AA impl)",
+                     false, // Is CFG Only?
+                     true,  // Is Analysis?
+                     true); // Is default Analysis Group implementation?
 }
-

Here we show how the default implementation is specified (using the extra -argument to the RegisterAnalysisGroup template). There must be exactly +

Here we show how the default implementation is specified (using the final +argument to the INITIALIZE_AG_PASS template). There must be exactly one default implementation available at all times for an Analysis Group to be used. Only default implementation can derive from ImmutablePass. Here we declare that the @@ -1339,13 +1449,15 @@ pass is the default implementation for the interface.

+
+ -
+

Pass Statistics -

+ -
+

The Statistic class is designed to be an easy way to expose various success @@ -1357,12 +1469,12 @@ line. See the St -

+

What PassManager does -

+ -
+

The PassManager @@ -1388,7 +1500,7 @@ results as soon as they are no longer needed.

  • Pipeline the execution of passes on the program - The PassManager attempts to get better cache and memory usage behavior out of a series of passes by pipelining the passes together. This means that, given -a series of consequtive FunctionPass's, it +a series of consecutive FunctionPass's, it will execute all of the FunctionPass's on the first function, then all of the FunctionPasses on the second function, @@ -1423,7 +1535,7 @@ how our Hello World pass interacts with other passes. Lets try it out with the gcse and licm passes:

    -$ opt -load ../../../Debug/lib/Hello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
+$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
 Module Pass Manager
   Function Pass Manager
     Dominator Set Construction
@@ -1460,7 +1572,7 @@ passes.
    
 World pass in between the two passes:
    
 
 
    -$ opt -load ../../../Debug/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
+$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
 Module Pass Manager
   Function Pass Manager
     Dominator Set Construction
@@ -1492,16 +1604,16 @@ we need to add the following getAnalysisUsage method to our pass:
    
 
 
    -    // We don't modify the program, so we preserve all analyses
-    virtual void getAnalysisUsage(AnalysisUsage &AU) const {
-      AU.setPreservesAll();
-    }
+// We don't modify the program, so we preserve all analyses
+virtual void getAnalysisUsage(AnalysisUsage &AU) const {
+  AU.setPreservesAll();
+}
 
    
 
 
    Now when we run our pass, we get this output:
    
 
 
    -$ opt -load ../../../Debug/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
+$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
 Pass Arguments:  -gcse -hello -licm
 Module Pass Manager
   Function Pass Manager
@@ -1529,14 +1641,12 @@ Hello: main
 
    Which shows that we don't accidentally invalidate dominator information
 anymore, and therefore do not have to compute it twice.
    
 
-
    
-
 
-
    
+
    
   The releaseMemory method
-
    
+
 
-
    
+
    
 
 
       virtual void releaseMemory();
@@ -1557,13 +1667,15 @@ class, before the next call of run* in your pass.
    
 
 
    
 
+
    
+
 
-
    
+
    
   Registering dynamically loaded passes
-
    
+
 
 
-
    
+
    
 
 
    Size matters when constructing production quality tools using llvm, 
 both for the purposes of distribution, and for regulating the resident code size
@@ -1590,14 +1702,12 @@ the static destructor unregisters. Thus a pass that is statically linked
 in the tool will be registered at start up. A dynamically loaded pass will
 register on load and unregister at unload.
    
 
-
    
-
 
-
    
+
    
   Using existing registries
-
    
+
 
-
    
+
    
 
 
    There are predefined registries to track instruction scheduling
 (RegisterScheduler) and register allocation (RegisterRegAlloc)
@@ -1605,19 +1715,19 @@ machine passes.  Here we will describe how to register a register
 allocator machine pass.
    
 
 
    Implement your register allocator machine pass.  In your register allocator
-.cpp file add the following include;
    
+.cpp file add the following include;
    
 
 
    -  #include "llvm/CodeGen/RegAllocRegistry.h"
+#include "llvm/CodeGen/RegAllocRegistry.h"
 
    
 
 
    Also in your register allocator .cpp file, define a creator function in the
 form; 
    
 
 
    -  FunctionPass *createMyRegisterAllocator() {
-    return new MyRegisterAllocator();
-  }
+FunctionPass *createMyRegisterAllocator() {
+  return new MyRegisterAllocator();
+}
 
    
 
 
    Note that the signature of this function should match the type of
@@ -1625,9 +1735,9 @@ form; 
    
 "installing" declaration, in the form;
    
 
 
    -  static RegisterRegAlloc myRegAlloc("myregalloc",
-    "  my register allocator help string",
-    createMyRegisterAllocator);
+static RegisterRegAlloc myRegAlloc("myregalloc",
+                                   "my register allocator help string",
+                                   createMyRegisterAllocator);
 
    
 
 
    Note the two spaces prior to the help string produces a tidy result on the
@@ -1658,11 +1768,11 @@ call line to llvm/Codegen/LinkAllCodegenComponents.h.
    
 
 
 
-
    
+
    
   Creating new registries
-
    
+
 
-
    
+
    
 
 
    The easiest way to get started is to clone one of the existing registries; we
 recommend llvm/CodeGen/RegAllocRegistry.h.  The key things to modify
@@ -1678,11 +1788,11 @@ MachinePassRegistry RegisterMyPasses::Registry;
 
    And finally, declare the command line option for your passes.  Example:
     
 
 
    -  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")); 
 
    
 
 
    Here the command option is "mypass", with createDefaultMyPass as the default
@@ -1690,13 +1800,15 @@ creator.
    
 
 
    
 
+
    
+
 
-
    
+
    
   Using GDB with dynamically loaded passes
-
    
+
 
 
-
    
+
    
 
 
    Unfortunately, using GDB with dynamically loaded passes is not as easy as it
 should be.  First of all, you can't set a breakpoint in a shared object that has
@@ -1708,14 +1820,12 @@ GDB.
    
 transformation invoked by opt, although nothing described here depends
 on that.
    
 
-
    
-
 
-
    
+
    
   Setting a breakpoint in your pass
-
    
+
 
-
    
+
    
 
 
    First thing you do is start gdb on the opt process:
    
 
@@ -1742,8 +1852,8 @@ want:
    
 
     (gdb) break llvm::PassManager::run
 Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.
-(gdb) run test.bc -load $(LLVMTOP)/llvm/Debug/lib/[libname].so -[passoption]
-Starting program: opt test.bc -load $(LLVMTOP)/llvm/Debug/lib/[libname].so -[passoption]
+(gdb) run test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]
+Starting program: opt test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]
 Breakpoint 1, PassManager::run (this=0xffbef174, M=@0x70b298) at Pass.cpp:70
 70      bool PassManager::run(Module &M) { return PM->run(M); }
 (gdb)
@@ -1756,11 +1866,11 @@ or do other standard debugging stuff.
    
 
    
 
 
-
    
+
    
   Miscellaneous Problems
-
    
+
 
-
    
+
    
 
 
    Once you have the basics down, there are a couple of problems that GDB has,
 some with solutions, some without.
    
@@ -1788,26 +1898,26 @@ href="mailto:sabre@nondot.org">Chris.
    
 
 
    
 
+
    
+
 
-
    
+
    
   Future extensions planned
-
    
+
 
 
-
    
+
    
 
 
    Although the LLVM Pass Infrastructure is very capable as it stands, and does
 some nifty stuff, there are things we'd like to add in the future.  Here is
 where we are going:
    
 
-
    
-
 
-
    
+
    
   Multithreaded LLVM
-
    
+
 
-
    
+
    
 
 
    Multiple CPU machines are becoming more common and compilation can never be
 fast enough: obviously we should allow for a multithreaded compiler.  Because of
@@ -1825,6 +1935,8 @@ Despite that, we have kept the LLVM passes SMP ready, and you should too.
    
 
 
    
 
+
    
+
 
 
    
 
    
@@ -1834,7 +1946,7 @@ Despite that, we have kept the LLVM passes SMP ready, and you should too.
    
   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01">
 
   Chris Lattner
    
-  The LLVM Compiler Infrastructure
    
+  The LLVM Compiler Infrastructure
    
   Last modified: $Date$