LLVM API Documentation

Pass.h

Go to the documentation of this file.
00001 //===- llvm/Pass.h - Base class for Passes ----------------------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file defines a base class that indicates that a specified class is a
00011 // transformation pass implementation.
00012 //
00013 // Passes are designed this way so that it is possible to run passes in a cache
00014 // and organizationally optimal order without having to specify it at the front
00015 // end.  This allows arbitrary passes to be strung together and have them
00016 // executed as effeciently as possible.
00017 //
00018 // Passes should extend one of the classes below, depending on the guarantees
00019 // that it can make about what will be modified as it is run.  For example, most
00020 // global optimizations should derive from FunctionPass, because they do not add
00021 // or delete functions, they operate on the internals of the function.
00022 //
00023 // Note that this file #includes PassSupport.h and PassAnalysisSupport.h (at the
00024 // bottom), so the APIs exposed by these files are also automatically available
00025 // to all users of this file.
00026 //
00027 //===----------------------------------------------------------------------===//
00028 
00029 #ifndef LLVM_PASS_H
00030 #define LLVM_PASS_H
00031 
00032 #include "llvm/Support/DataTypes.h"
00033 #include "llvm/Support/Streams.h"
00034 #include <cassert>
00035 #include <iosfwd>
00036 #include <utility>
00037 #include <vector>
00038 
00039 namespace llvm {
00040 
00041 class BasicBlock;
00042 class Function;
00043 class Module;
00044 class AnalysisUsage;
00045 class PassInfo;
00046 class ImmutablePass;
00047 class PMStack;
00048 class AnalysisResolver;
00049 class PMDataManager;
00050 
00051 // AnalysisID - Use the PassInfo to identify a pass...
00052 typedef const PassInfo* AnalysisID;
00053 
00054 /// Different types of internal pass managers. External pass managers
00055 /// (PassManager and FunctionPassManager) are not represented here.
00056 /// Ordering of pass manager types is important here.
00057 enum PassManagerType {
00058   PMT_Unknown = 0,
00059   PMT_ModulePassManager = 1, /// MPPassManager 
00060   PMT_CallGraphPassManager,  /// CGPassManager
00061   PMT_FunctionPassManager,   /// FPPassManager
00062   PMT_LoopPassManager,       /// LPPassManager
00063   PMT_BasicBlockPassManager, /// BBPassManager
00064   PMT_Last
00065 };
00066 
00067 //===----------------------------------------------------------------------===//
00068 /// Pass interface - Implemented by all 'passes'.  Subclass this if you are an
00069 /// interprocedural optimization or you do not fit into any of the more
00070 /// constrained passes described below.
00071 ///
00072 class Pass {
00073   AnalysisResolver *Resolver;  // Used to resolve analysis
00074   intptr_t PassID;
00075 
00076   void operator=(const Pass&);  // DO NOT IMPLEMENT
00077   Pass(const Pass &);           // DO NOT IMPLEMENT
00078   
00079 public:
00080   explicit Pass(intptr_t pid) : Resolver(0), PassID(pid) {
00081     assert(pid && "pid cannot be 0");
00082   }
00083   explicit Pass(const void *pid) : Resolver(0), PassID((intptr_t)pid) {
00084     assert(pid && "pid cannot be 0"); 
00085   }
00086   virtual ~Pass();
00087 
00088   /// getPassName - Return a nice clean name for a pass.  This usually
00089   /// implemented in terms of the name that is registered by one of the
00090   /// Registration templates, but can be overloaded directly.
00091   ///
00092   virtual const char *getPassName() const;
00093 
00094   /// getPassInfo - Return the PassInfo data structure that corresponds to this
00095   /// pass...  If the pass has not been registered, this will return null.
00096   ///
00097   const PassInfo *getPassInfo() const;
00098 
00099   /// print - Print out the internal state of the pass.  This is called by
00100   /// Analyze to print out the contents of an analysis.  Otherwise it is not
00101   /// necessary to implement this method.  Beware that the module pointer MAY be
00102   /// null.  This automatically forwards to a virtual function that does not
00103   /// provide the Module* in case the analysis doesn't need it it can just be
00104   /// ignored.
00105   ///
00106   virtual void print(std::ostream &O, const Module *M) const;
00107   void print(std::ostream *O, const Module *M) const { if (O) print(*O, M); }
00108   void dump() const; // dump - Print to stderr.
00109 
00110   /// Each pass is responsible for assigning a pass manager to itself.
00111   /// PMS is the stack of available pass manager. 
00112   virtual void assignPassManager(PMStack &, 
00113                                  PassManagerType = PMT_Unknown) {}
00114   /// Check if available pass managers are suitable for this pass or not.
00115   virtual void preparePassManager(PMStack &) {}
00116   
00117   ///  Return what kind of Pass Manager can manage this pass.
00118   virtual PassManagerType getPotentialPassManagerType() const {
00119     return PMT_Unknown; 
00120   }
00121 
00122   // Access AnalysisResolver
00123   inline void setResolver(AnalysisResolver *AR) { 
00124     assert (!Resolver && "Resolver is already set");
00125     Resolver = AR; 
00126   }
00127   inline AnalysisResolver *getResolver() { 
00128     return Resolver; 
00129   }
00130 
00131   /// getAnalysisUsage - This function should be overriden by passes that need
00132   /// analysis information to do their job.  If a pass specifies that it uses a
00133   /// particular analysis result to this function, it can then use the
00134   /// getAnalysis<AnalysisType>() function, below.
00135   ///
00136   virtual void getAnalysisUsage(AnalysisUsage &) const {
00137     // By default, no analysis results are used, all are invalidated.
00138   }
00139 
00140   /// releaseMemory() - This member can be implemented by a pass if it wants to
00141   /// be able to release its memory when it is no longer needed.  The default
00142   /// behavior of passes is to hold onto memory for the entire duration of their
00143   /// lifetime (which is the entire compile time).  For pipelined passes, this
00144   /// is not a big deal because that memory gets recycled every time the pass is
00145   /// invoked on another program unit.  For IP passes, it is more important to
00146   /// free memory when it is unused.
00147   ///
00148   /// Optionally implement this function to release pass memory when it is no
00149   /// longer used.
00150   ///
00151   virtual void releaseMemory() {}
00152 
00153   /// verifyAnalysis() - This member can be implemented by a analysis pass to
00154   /// check state of analysis information. 
00155   virtual void verifyAnalysis() const {}
00156 
00157   // dumpPassStructure - Implement the -debug-passes=PassStructure option
00158   virtual void dumpPassStructure(unsigned Offset = 0);
00159 
00160   template<typename AnalysisClass>
00161   static const PassInfo *getClassPassInfo() {
00162     return lookupPassInfo(intptr_t(&AnalysisClass::ID));
00163   }
00164 
00165   // lookupPassInfo - Return the pass info object for the specified pass class,
00166   // or null if it is not known.
00167   static const PassInfo *lookupPassInfo(intptr_t TI);
00168 
00169   /// getAnalysisIfAvailable<AnalysisType>() - Subclasses use this function to
00170   /// get analysis information that might be around, for example to update it.
00171   /// This is different than getAnalysis in that it can fail (if the analysis
00172   /// results haven't been computed), so should only be used if you can handle
00173   /// the case when the analysis is not available.  This method is often used by
00174   /// transformation APIs to update analysis results for a pass automatically as
00175   /// the transform is performed.
00176   ///
00177   template<typename AnalysisType> AnalysisType *
00178     getAnalysisIfAvailable() const; // Defined in PassAnalysisSupport.h
00179 
00180   /// mustPreserveAnalysisID - This method serves the same function as
00181   /// getAnalysisIfAvailable, but works if you just have an AnalysisID.  This
00182   /// obviously cannot give you a properly typed instance of the class if you
00183   /// don't have the class name available (use getAnalysisIfAvailable if you
00184   /// do), but it can tell you if you need to preserve the pass at least.
00185   ///
00186   bool mustPreserveAnalysisID(const PassInfo *AnalysisID) const;
00187 
00188   /// getAnalysis<AnalysisType>() - This function is used by subclasses to get
00189   /// to the analysis information that they claim to use by overriding the
00190   /// getAnalysisUsage function.
00191   ///
00192   template<typename AnalysisType>
00193   AnalysisType &getAnalysis() const; // Defined in PassAnalysisSupport.h
00194 
00195   template<typename AnalysisType>
00196   AnalysisType &getAnalysis(Function &F); // Defined in PassanalysisSupport.h
00197 
00198   template<typename AnalysisType>
00199   AnalysisType &getAnalysisID(const PassInfo *PI) const;
00200 
00201   template<typename AnalysisType>
00202   AnalysisType &getAnalysisID(const PassInfo *PI, Function &F);
00203 };
00204 
00205 inline std::ostream &operator<<(std::ostream &OS, const Pass &P) {
00206   P.print(OS, 0); return OS;
00207 }
00208 
00209 //===----------------------------------------------------------------------===//
00210 /// ModulePass class - This class is used to implement unstructured
00211 /// interprocedural optimizations and analyses.  ModulePasses may do anything
00212 /// they want to the program.
00213 ///
00214 class ModulePass : public Pass {
00215 public:
00216   /// runOnModule - Virtual method overriden by subclasses to process the module
00217   /// being operated on.
00218   virtual bool runOnModule(Module &M) = 0;
00219 
00220   virtual void assignPassManager(PMStack &PMS, 
00221                                  PassManagerType T = PMT_ModulePassManager);
00222 
00223   ///  Return what kind of Pass Manager can manage this pass.
00224   virtual PassManagerType getPotentialPassManagerType() const {
00225     return PMT_ModulePassManager;
00226   }
00227 
00228   explicit ModulePass(intptr_t pid) : Pass(pid) {}
00229   explicit ModulePass(const void *pid) : Pass(pid) {}
00230   // Force out-of-line virtual method.
00231   virtual ~ModulePass();
00232 };
00233 
00234 
00235 //===----------------------------------------------------------------------===//
00236 /// ImmutablePass class - This class is used to provide information that does
00237 /// not need to be run.  This is useful for things like target information and
00238 /// "basic" versions of AnalysisGroups.
00239 ///
00240 class ImmutablePass : public ModulePass {
00241 public:
00242   /// initializePass - This method may be overriden by immutable passes to allow
00243   /// them to perform various initialization actions they require.  This is
00244   /// primarily because an ImmutablePass can "require" another ImmutablePass,
00245   /// and if it does, the overloaded version of initializePass may get access to
00246   /// these passes with getAnalysis<>.
00247   ///
00248   virtual void initializePass() {}
00249 
00250   /// ImmutablePasses are never run.
00251   ///
00252   bool runOnModule(Module &) { return false; }
00253 
00254   explicit ImmutablePass(intptr_t pid) : ModulePass(pid) {}
00255   explicit ImmutablePass(const void *pid) 
00256   : ModulePass(pid) {}
00257   
00258   // Force out-of-line virtual method.
00259   virtual ~ImmutablePass();
00260 };
00261 
00262 //===----------------------------------------------------------------------===//
00263 /// FunctionPass class - This class is used to implement most global
00264 /// optimizations.  Optimizations should subclass this class if they meet the
00265 /// following constraints:
00266 ///
00267 ///  1. Optimizations are organized globally, i.e., a function at a time
00268 ///  2. Optimizing a function does not cause the addition or removal of any
00269 ///     functions in the module
00270 ///
00271 class FunctionPass : public Pass {
00272 public:
00273   explicit FunctionPass(intptr_t pid) : Pass(pid) {}
00274   explicit FunctionPass(const void *pid) : Pass(pid) {}
00275 
00276   /// doInitialization - Virtual method overridden by subclasses to do
00277   /// any necessary per-module initialization.
00278   ///
00279   virtual bool doInitialization(Module &M) { return false; }
00280   
00281   /// runOnFunction - Virtual method overriden by subclasses to do the
00282   /// per-function processing of the pass.
00283   ///
00284   virtual bool runOnFunction(Function &F) = 0;
00285 
00286   /// doFinalization - Virtual method overriden by subclasses to do any post
00287   /// processing needed after all passes have run.
00288   ///
00289   virtual bool doFinalization(Module &) { return false; }
00290 
00291   /// runOnModule - On a module, we run this pass by initializing,
00292   /// ronOnFunction'ing once for every function in the module, then by
00293   /// finalizing.
00294   ///
00295   virtual bool runOnModule(Module &M);
00296 
00297   /// run - On a function, we simply initialize, run the function, then
00298   /// finalize.
00299   ///
00300   bool run(Function &F);
00301 
00302   virtual void assignPassManager(PMStack &PMS, 
00303                                  PassManagerType T = PMT_FunctionPassManager);
00304 
00305   ///  Return what kind of Pass Manager can manage this pass.
00306   virtual PassManagerType getPotentialPassManagerType() const {
00307     return PMT_FunctionPassManager;
00308   }
00309 };
00310 
00311 
00312 
00313 //===----------------------------------------------------------------------===//
00314 /// BasicBlockPass class - This class is used to implement most local
00315 /// optimizations.  Optimizations should subclass this class if they
00316 /// meet the following constraints:
00317 ///   1. Optimizations are local, operating on either a basic block or
00318 ///      instruction at a time.
00319 ///   2. Optimizations do not modify the CFG of the contained function, or any
00320 ///      other basic block in the function.
00321 ///   3. Optimizations conform to all of the constraints of FunctionPasses.
00322 ///
00323 class BasicBlockPass : public Pass {
00324 public:
00325   explicit BasicBlockPass(intptr_t pid) : Pass(pid) {}
00326   explicit BasicBlockPass(const void *pid) : Pass(pid) {}
00327 
00328   /// doInitialization - Virtual method overridden by subclasses to do
00329   /// any necessary per-module initialization.
00330   ///
00331   virtual bool doInitialization(Module &M) { return false; }
00332 
00333   /// doInitialization - Virtual method overridden by BasicBlockPass subclasses
00334   /// to do any necessary per-function initialization.
00335   ///
00336   virtual bool doInitialization(Function &) { return false; }
00337 
00338   /// runOnBasicBlock - Virtual method overriden by subclasses to do the
00339   /// per-basicblock processing of the pass.
00340   ///
00341   virtual bool runOnBasicBlock(BasicBlock &BB) = 0;
00342 
00343   /// doFinalization - Virtual method overriden by BasicBlockPass subclasses to
00344   /// do any post processing needed after all passes have run.
00345   ///
00346   virtual bool doFinalization(Function &) { return false; }
00347 
00348   /// doFinalization - Virtual method overriden by subclasses to do any post
00349   /// processing needed after all passes have run.
00350   ///
00351   virtual bool doFinalization(Module &) { return false; }
00352 
00353 
00354   // To run this pass on a function, we simply call runOnBasicBlock once for
00355   // each function.
00356   //
00357   bool runOnFunction(Function &F);
00358 
00359   virtual void assignPassManager(PMStack &PMS, 
00360                                  PassManagerType T = PMT_BasicBlockPassManager);
00361 
00362   ///  Return what kind of Pass Manager can manage this pass.
00363   virtual PassManagerType getPotentialPassManagerType() const {
00364     return PMT_BasicBlockPassManager; 
00365   }
00366 };
00367 
00368 /// If the user specifies the -time-passes argument on an LLVM tool command line
00369 /// then the value of this boolean will be true, otherwise false.
00370 /// @brief This is the storage for the -time-passes option.
00371 extern bool TimePassesIsEnabled;
00372 
00373 } // End llvm namespace
00374 
00375 // Include support files that contain important APIs commonly used by Passes,
00376 // but that we want to separate out to make it easier to read the header files.
00377 //
00378 #include "llvm/PassSupport.h"
00379 #include "llvm/PassAnalysisSupport.h"
00380 
00381 #endif