Pass.h revision 353358
1193323Sed//===- llvm/Pass.h - Base class for Passes ----------------------*- C++ -*-===// 2193323Sed// 3353358Sdim// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4353358Sdim// See https://llvm.org/LICENSE.txt for license information. 5353358Sdim// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6193323Sed// 7193323Sed//===----------------------------------------------------------------------===// 8193323Sed// 9193323Sed// This file defines a base class that indicates that a specified class is a 10193323Sed// transformation pass implementation. 11193323Sed// 12193323Sed// Passes are designed this way so that it is possible to run passes in a cache 13193323Sed// and organizationally optimal order without having to specify it at the front 14193323Sed// end. This allows arbitrary passes to be strung together and have them 15221345Sdim// executed as efficiently as possible. 16193323Sed// 17193323Sed// Passes should extend one of the classes below, depending on the guarantees 18193323Sed// that it can make about what will be modified as it is run. For example, most 19193323Sed// global optimizations should derive from FunctionPass, because they do not add 20193323Sed// or delete functions, they operate on the internals of the function. 21193323Sed// 22193323Sed// Note that this file #includes PassSupport.h and PassAnalysisSupport.h (at the 23193323Sed// bottom), so the APIs exposed by these files are also automatically available 24193323Sed// to all users of this file. 25193323Sed// 26193323Sed//===----------------------------------------------------------------------===// 27193323Sed 28193323Sed#ifndef LLVM_PASS_H 29193323Sed#define LLVM_PASS_H 30193323Sed 31327952Sdim#include "llvm/ADT/StringRef.h" 32206124Srdivacky#include <string> 33193323Sed 34193323Sednamespace llvm { 35193323Sed 36327952Sdimclass AnalysisResolver; 37327952Sdimclass AnalysisUsage; 38193323Sedclass BasicBlock; 39193323Sedclass Function; 40327952Sdimclass ImmutablePass; 41193323Sedclass Module; 42193323Sedclass PassInfo; 43327952Sdimclass PMDataManager; 44193323Sedclass PMStack; 45198090Srdivackyclass raw_ostream; 46193323Sed 47193323Sed// AnalysisID - Use the PassInfo to identify a pass... 48327952Sdimusing AnalysisID = const void *; 49193323Sed 50193323Sed/// Different types of internal pass managers. External pass managers 51193323Sed/// (PassManager and FunctionPassManager) are not represented here. 52193323Sed/// Ordering of pass manager types is important here. 53193323Sedenum PassManagerType { 54193323Sed PMT_Unknown = 0, 55234353Sdim PMT_ModulePassManager = 1, ///< MPPassManager 56203954Srdivacky PMT_CallGraphPassManager, ///< CGPassManager 57203954Srdivacky PMT_FunctionPassManager, ///< FPPassManager 58203954Srdivacky PMT_LoopPassManager, ///< LPPassManager 59218893Sdim PMT_RegionPassManager, ///< RGPassManager 60203954Srdivacky PMT_BasicBlockPassManager, ///< BBPassManager 61193323Sed PMT_Last 62193323Sed}; 63193323Sed 64202878Srdivacky// Different types of passes. 65202878Srdivackyenum PassKind { 66202878Srdivacky PT_BasicBlock, 67218893Sdim PT_Region, 68202878Srdivacky PT_Loop, 69202878Srdivacky PT_Function, 70202878Srdivacky PT_CallGraphSCC, 71202878Srdivacky PT_Module, 72202878Srdivacky PT_PassManager 73202878Srdivacky}; 74218893Sdim 75193323Sed//===----------------------------------------------------------------------===// 76193323Sed/// Pass interface - Implemented by all 'passes'. Subclass this if you are an 77193323Sed/// interprocedural optimization or you do not fit into any of the more 78193323Sed/// constrained passes described below. 79193323Sed/// 80193323Sedclass Pass { 81327952Sdim AnalysisResolver *Resolver = nullptr; // Used to resolve analysis 82212904Sdim const void *PassID; 83202878Srdivacky PassKind Kind; 84234353Sdim 85193323Sedpublic: 86327952Sdim explicit Pass(PassKind K, char &pid) : PassID(&pid), Kind(K) {} 87327952Sdim Pass(const Pass &) = delete; 88327952Sdim Pass &operator=(const Pass &) = delete; 89193323Sed virtual ~Pass(); 90193323Sed 91202878Srdivacky PassKind getPassKind() const { return Kind; } 92234353Sdim 93193323Sed /// getPassName - Return a nice clean name for a pass. This usually 94193323Sed /// implemented in terms of the name that is registered by one of the 95193323Sed /// Registration templates, but can be overloaded directly. 96314564Sdim virtual StringRef getPassName() const; 97193323Sed 98212904Sdim /// getPassID - Return the PassID number that corresponds to this pass. 99234353Sdim AnalysisID getPassID() const { 100212904Sdim return PassID; 101212904Sdim } 102193323Sed 103249423Sdim /// doInitialization - Virtual method overridden by subclasses to do 104249423Sdim /// any necessary initialization before any pass is run. 105249423Sdim virtual bool doInitialization(Module &) { return false; } 106249423Sdim 107249423Sdim /// doFinalization - Virtual method overriden by subclasses to do any 108249423Sdim /// necessary clean up after all passes have run. 109249423Sdim virtual bool doFinalization(Module &) { return false; } 110249423Sdim 111193323Sed /// print - Print out the internal state of the pass. This is called by 112193323Sed /// Analyze to print out the contents of an analysis. Otherwise it is not 113193323Sed /// necessary to implement this method. Beware that the module pointer MAY be 114193323Sed /// null. This automatically forwards to a virtual function that does not 115193323Sed /// provide the Module* in case the analysis doesn't need it it can just be 116193323Sed /// ignored. 117327952Sdim virtual void print(raw_ostream &OS, const Module *M) const; 118327952Sdim 119198090Srdivacky void dump() const; // dump - Print to stderr. 120193323Sed 121206124Srdivacky /// createPrinterPass - Get a Pass appropriate to print the IR this 122221345Sdim /// pass operates on (Module, Function or MachineFunction). 123327952Sdim virtual Pass *createPrinterPass(raw_ostream &OS, 124206124Srdivacky const std::string &Banner) const = 0; 125206124Srdivacky 126193323Sed /// Each pass is responsible for assigning a pass manager to itself. 127234353Sdim /// PMS is the stack of available pass manager. 128234353Sdim virtual void assignPassManager(PMStack &, 129212904Sdim PassManagerType) {} 130327952Sdim 131193323Sed /// Check if available pass managers are suitable for this pass or not. 132200581Srdivacky virtual void preparePassManager(PMStack &); 133234353Sdim 134193323Sed /// Return what kind of Pass Manager can manage this pass. 135200581Srdivacky virtual PassManagerType getPotentialPassManagerType() const; 136193323Sed 137193323Sed // Access AnalysisResolver 138210299Sed void setResolver(AnalysisResolver *AR); 139210299Sed AnalysisResolver *getResolver() const { return Resolver; } 140193323Sed 141193323Sed /// getAnalysisUsage - This function should be overriden by passes that need 142193323Sed /// analysis information to do their job. If a pass specifies that it uses a 143193323Sed /// particular analysis result to this function, it can then use the 144193323Sed /// getAnalysis<AnalysisType>() function, below. 145200581Srdivacky virtual void getAnalysisUsage(AnalysisUsage &) const; 146193323Sed 147193323Sed /// releaseMemory() - This member can be implemented by a pass if it wants to 148193323Sed /// be able to release its memory when it is no longer needed. The default 149193323Sed /// behavior of passes is to hold onto memory for the entire duration of their 150193323Sed /// lifetime (which is the entire compile time). For pipelined passes, this 151193323Sed /// is not a big deal because that memory gets recycled every time the pass is 152193323Sed /// invoked on another program unit. For IP passes, it is more important to 153193323Sed /// free memory when it is unused. 154193323Sed /// 155193323Sed /// Optionally implement this function to release pass memory when it is no 156193323Sed /// longer used. 157200581Srdivacky virtual void releaseMemory(); 158193323Sed 159202878Srdivacky /// getAdjustedAnalysisPointer - This method is used when a pass implements 160202878Srdivacky /// an analysis interface through multiple inheritance. If needed, it should 161202878Srdivacky /// override this to adjust the this pointer as needed for the specified pass 162202878Srdivacky /// info. 163212904Sdim virtual void *getAdjustedAnalysisPointer(AnalysisID ID); 164210299Sed virtual ImmutablePass *getAsImmutablePass(); 165210299Sed virtual PMDataManager *getAsPMDataManager(); 166234353Sdim 167193323Sed /// verifyAnalysis() - This member can be implemented by a analysis pass to 168234353Sdim /// check state of analysis information. 169200581Srdivacky virtual void verifyAnalysis() const; 170193323Sed 171193323Sed // dumpPassStructure - Implement the -debug-passes=PassStructure option 172193323Sed virtual void dumpPassStructure(unsigned Offset = 0); 173193323Sed 174193323Sed // lookupPassInfo - Return the pass info object for the specified pass class, 175193323Sed // or null if it is not known. 176212904Sdim static const PassInfo *lookupPassInfo(const void *TI); 177193323Sed 178198090Srdivacky // lookupPassInfo - Return the pass info object for the pass with the given 179198090Srdivacky // argument string, or null if it is not known. 180199481Srdivacky static const PassInfo *lookupPassInfo(StringRef Arg); 181198090Srdivacky 182234353Sdim // createPass - Create a object for the specified pass class, 183234353Sdim // or null if it is not known. 184234353Sdim static Pass *createPass(AnalysisID ID); 185234353Sdim 186193323Sed /// getAnalysisIfAvailable<AnalysisType>() - Subclasses use this function to 187193323Sed /// get analysis information that might be around, for example to update it. 188193323Sed /// This is different than getAnalysis in that it can fail (if the analysis 189193323Sed /// results haven't been computed), so should only be used if you can handle 190193323Sed /// the case when the analysis is not available. This method is often used by 191193323Sed /// transformation APIs to update analysis results for a pass automatically as 192193323Sed /// the transform is performed. 193193323Sed template<typename AnalysisType> AnalysisType * 194193323Sed getAnalysisIfAvailable() const; // Defined in PassAnalysisSupport.h 195193323Sed 196193323Sed /// mustPreserveAnalysisID - This method serves the same function as 197193323Sed /// getAnalysisIfAvailable, but works if you just have an AnalysisID. This 198193323Sed /// obviously cannot give you a properly typed instance of the class if you 199193323Sed /// don't have the class name available (use getAnalysisIfAvailable if you 200193323Sed /// do), but it can tell you if you need to preserve the pass at least. 201212904Sdim bool mustPreserveAnalysisID(char &AID) const; 202193323Sed 203193323Sed /// getAnalysis<AnalysisType>() - This function is used by subclasses to get 204193323Sed /// to the analysis information that they claim to use by overriding the 205193323Sed /// getAnalysisUsage function. 206193323Sed template<typename AnalysisType> 207193323Sed AnalysisType &getAnalysis() const; // Defined in PassAnalysisSupport.h 208193323Sed 209193323Sed template<typename AnalysisType> 210198090Srdivacky AnalysisType &getAnalysis(Function &F); // Defined in PassAnalysisSupport.h 211193323Sed 212193323Sed template<typename AnalysisType> 213212904Sdim AnalysisType &getAnalysisID(AnalysisID PI) const; 214193323Sed 215193323Sed template<typename AnalysisType> 216212904Sdim AnalysisType &getAnalysisID(AnalysisID PI, Function &F); 217193323Sed}; 218193323Sed 219193323Sed//===----------------------------------------------------------------------===// 220193323Sed/// ModulePass class - This class is used to implement unstructured 221193323Sed/// interprocedural optimizations and analyses. ModulePasses may do anything 222193323Sed/// they want to the program. 223193323Sed/// 224193323Sedclass ModulePass : public Pass { 225193323Sedpublic: 226327952Sdim explicit ModulePass(char &pid) : Pass(PT_Module, pid) {} 227327952Sdim 228327952Sdim // Force out-of-line virtual method. 229327952Sdim ~ModulePass() override; 230327952Sdim 231206124Srdivacky /// createPrinterPass - Get a module printer pass. 232327952Sdim Pass *createPrinterPass(raw_ostream &OS, 233276479Sdim const std::string &Banner) const override; 234206124Srdivacky 235193323Sed /// runOnModule - Virtual method overriden by subclasses to process the module 236193323Sed /// being operated on. 237193323Sed virtual bool runOnModule(Module &M) = 0; 238193323Sed 239276479Sdim void assignPassManager(PMStack &PMS, PassManagerType T) override; 240193323Sed 241193323Sed /// Return what kind of Pass Manager can manage this pass. 242276479Sdim PassManagerType getPotentialPassManagerType() const override; 243193323Sed 244309124Sdimprotected: 245309124Sdim /// Optional passes call this function to check whether the pass should be 246309124Sdim /// skipped. This is the case when optimization bisect is over the limit. 247309124Sdim bool skipModule(Module &M) const; 248193323Sed}; 249193323Sed 250193323Sed//===----------------------------------------------------------------------===// 251193323Sed/// ImmutablePass class - This class is used to provide information that does 252193323Sed/// not need to be run. This is useful for things like target information and 253193323Sed/// "basic" versions of AnalysisGroups. 254193323Sed/// 255193323Sedclass ImmutablePass : public ModulePass { 256193323Sedpublic: 257327952Sdim explicit ImmutablePass(char &pid) : ModulePass(pid) {} 258327952Sdim 259327952Sdim // Force out-of-line virtual method. 260327952Sdim ~ImmutablePass() override; 261327952Sdim 262193323Sed /// initializePass - This method may be overriden by immutable passes to allow 263193323Sed /// them to perform various initialization actions they require. This is 264193323Sed /// primarily because an ImmutablePass can "require" another ImmutablePass, 265193323Sed /// and if it does, the overloaded version of initializePass may get access to 266193323Sed /// these passes with getAnalysis<>. 267200581Srdivacky virtual void initializePass(); 268193323Sed 269276479Sdim ImmutablePass *getAsImmutablePass() override { return this; } 270202878Srdivacky 271193323Sed /// ImmutablePasses are never run. 272276479Sdim bool runOnModule(Module &) override { return false; } 273193323Sed}; 274193323Sed 275193323Sed//===----------------------------------------------------------------------===// 276193323Sed/// FunctionPass class - This class is used to implement most global 277193323Sed/// optimizations. Optimizations should subclass this class if they meet the 278193323Sed/// following constraints: 279193323Sed/// 280193323Sed/// 1. Optimizations are organized globally, i.e., a function at a time 281193323Sed/// 2. Optimizing a function does not cause the addition or removal of any 282193323Sed/// functions in the module 283193323Sed/// 284193323Sedclass FunctionPass : public Pass { 285193323Sedpublic: 286212904Sdim explicit FunctionPass(char &pid) : Pass(PT_Function, pid) {} 287193323Sed 288206124Srdivacky /// createPrinterPass - Get a function printer pass. 289327952Sdim Pass *createPrinterPass(raw_ostream &OS, 290276479Sdim const std::string &Banner) const override; 291206124Srdivacky 292193323Sed /// runOnFunction - Virtual method overriden by subclasses to do the 293193323Sed /// per-function processing of the pass. 294193323Sed virtual bool runOnFunction(Function &F) = 0; 295193323Sed 296276479Sdim void assignPassManager(PMStack &PMS, PassManagerType T) override; 297193323Sed 298193323Sed /// Return what kind of Pass Manager can manage this pass. 299276479Sdim PassManagerType getPotentialPassManagerType() const override; 300276479Sdim 301276479Sdimprotected: 302309124Sdim /// Optional passes call this function to check whether the pass should be 303309124Sdim /// skipped. This is the case when Attribute::OptimizeNone is set or when 304309124Sdim /// optimization bisect is over the limit. 305309124Sdim bool skipFunction(const Function &F) const; 306193323Sed}; 307193323Sed 308193323Sed//===----------------------------------------------------------------------===// 309193323Sed/// BasicBlockPass class - This class is used to implement most local 310193323Sed/// optimizations. Optimizations should subclass this class if they 311193323Sed/// meet the following constraints: 312193323Sed/// 1. Optimizations are local, operating on either a basic block or 313193323Sed/// instruction at a time. 314193323Sed/// 2. Optimizations do not modify the CFG of the contained function, or any 315193323Sed/// other basic block in the function. 316193323Sed/// 3. Optimizations conform to all of the constraints of FunctionPasses. 317193323Sed/// 318193323Sedclass BasicBlockPass : public Pass { 319193323Sedpublic: 320212904Sdim explicit BasicBlockPass(char &pid) : Pass(PT_BasicBlock, pid) {} 321193323Sed 322221345Sdim /// createPrinterPass - Get a basic block printer pass. 323327952Sdim Pass *createPrinterPass(raw_ostream &OS, 324276479Sdim const std::string &Banner) const override; 325206124Srdivacky 326249423Sdim using llvm::Pass::doInitialization; 327249423Sdim using llvm::Pass::doFinalization; 328193323Sed 329193323Sed /// doInitialization - Virtual method overridden by BasicBlockPass subclasses 330193323Sed /// to do any necessary per-function initialization. 331200581Srdivacky virtual bool doInitialization(Function &); 332193323Sed 333193323Sed /// runOnBasicBlock - Virtual method overriden by subclasses to do the 334193323Sed /// per-basicblock processing of the pass. 335193323Sed virtual bool runOnBasicBlock(BasicBlock &BB) = 0; 336193323Sed 337193323Sed /// doFinalization - Virtual method overriden by BasicBlockPass subclasses to 338193323Sed /// do any post processing needed after all passes have run. 339200581Srdivacky virtual bool doFinalization(Function &); 340193323Sed 341276479Sdim void assignPassManager(PMStack &PMS, PassManagerType T) override; 342193323Sed 343193323Sed /// Return what kind of Pass Manager can manage this pass. 344276479Sdim PassManagerType getPotentialPassManagerType() const override; 345276479Sdim 346276479Sdimprotected: 347309124Sdim /// Optional passes call this function to check whether the pass should be 348309124Sdim /// skipped. This is the case when Attribute::OptimizeNone is set or when 349309124Sdim /// optimization bisect is over the limit. 350309124Sdim bool skipBasicBlock(const BasicBlock &BB) const; 351193323Sed}; 352193323Sed 353193323Sed/// If the user specifies the -time-passes argument on an LLVM tool command line 354193323Sed/// then the value of this boolean will be true, otherwise false. 355341825Sdim/// This is the storage for the -time-passes option. 356193323Sedextern bool TimePassesIsEnabled; 357193323Sed 358327952Sdim} // end namespace llvm 359327952Sdim 360193323Sed// Include support files that contain important APIs commonly used by Passes, 361193323Sed// but that we want to separate out to make it easier to read the header files. 362327952Sdim#include "llvm/InitializePasses.h" 363321369Sdim#include "llvm/PassAnalysisSupport.h" 364193323Sed#include "llvm/PassSupport.h" 365193323Sed 366327952Sdim#endif // LLVM_PASS_H 367