LLVM API Documentation
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