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 60193323Sed PMT_Last 61193323Sed}; 62193323Sed 63202878Srdivacky// Different types of passes. 64202878Srdivackyenum PassKind { 65218893Sdim PT_Region, 66202878Srdivacky PT_Loop, 67202878Srdivacky PT_Function, 68202878Srdivacky PT_CallGraphSCC, 69202878Srdivacky PT_Module, 70202878Srdivacky PT_PassManager 71202878Srdivacky}; 72218893Sdim 73193323Sed//===----------------------------------------------------------------------===// 74193323Sed/// Pass interface - Implemented by all 'passes'. Subclass this if you are an 75193323Sed/// interprocedural optimization or you do not fit into any of the more 76193323Sed/// constrained passes described below. 77193323Sed/// 78193323Sedclass Pass { 79327952Sdim AnalysisResolver *Resolver = nullptr; // Used to resolve analysis 80212904Sdim const void *PassID; 81202878Srdivacky PassKind Kind; 82234353Sdim 83193323Sedpublic: 84327952Sdim explicit Pass(PassKind K, char &pid) : PassID(&pid), Kind(K) {} 85327952Sdim Pass(const Pass &) = delete; 86327952Sdim Pass &operator=(const Pass &) = delete; 87193323Sed virtual ~Pass(); 88193323Sed 89202878Srdivacky PassKind getPassKind() const { return Kind; } 90234353Sdim 91193323Sed /// getPassName - Return a nice clean name for a pass. This usually 92193323Sed /// implemented in terms of the name that is registered by one of the 93193323Sed /// Registration templates, but can be overloaded directly. 94314564Sdim virtual StringRef getPassName() const; 95193323Sed 96212904Sdim /// getPassID - Return the PassID number that corresponds to this pass. 97234353Sdim AnalysisID getPassID() const { 98212904Sdim return PassID; 99212904Sdim } 100193323Sed 101249423Sdim /// doInitialization - Virtual method overridden by subclasses to do 102249423Sdim /// any necessary initialization before any pass is run. 103249423Sdim virtual bool doInitialization(Module &) { return false; } 104249423Sdim 105249423Sdim /// doFinalization - Virtual method overriden by subclasses to do any 106249423Sdim /// necessary clean up after all passes have run. 107249423Sdim virtual bool doFinalization(Module &) { return false; } 108249423Sdim 109193323Sed /// print - Print out the internal state of the pass. This is called by 110193323Sed /// Analyze to print out the contents of an analysis. Otherwise it is not 111193323Sed /// necessary to implement this method. Beware that the module pointer MAY be 112193323Sed /// null. This automatically forwards to a virtual function that does not 113193323Sed /// provide the Module* in case the analysis doesn't need it it can just be 114193323Sed /// ignored. 115327952Sdim virtual void print(raw_ostream &OS, const Module *M) const; 116327952Sdim 117198090Srdivacky void dump() const; // dump - Print to stderr. 118193323Sed 119206124Srdivacky /// createPrinterPass - Get a Pass appropriate to print the IR this 120221345Sdim /// pass operates on (Module, Function or MachineFunction). 121327952Sdim virtual Pass *createPrinterPass(raw_ostream &OS, 122206124Srdivacky const std::string &Banner) const = 0; 123206124Srdivacky 124193323Sed /// Each pass is responsible for assigning a pass manager to itself. 125234353Sdim /// PMS is the stack of available pass manager. 126234353Sdim virtual void assignPassManager(PMStack &, 127212904Sdim PassManagerType) {} 128327952Sdim 129193323Sed /// Check if available pass managers are suitable for this pass or not. 130200581Srdivacky virtual void preparePassManager(PMStack &); 131234353Sdim 132193323Sed /// Return what kind of Pass Manager can manage this pass. 133200581Srdivacky virtual PassManagerType getPotentialPassManagerType() const; 134193323Sed 135193323Sed // Access AnalysisResolver 136210299Sed void setResolver(AnalysisResolver *AR); 137210299Sed AnalysisResolver *getResolver() const { return Resolver; } 138193323Sed 139193323Sed /// getAnalysisUsage - This function should be overriden by passes that need 140193323Sed /// analysis information to do their job. If a pass specifies that it uses a 141193323Sed /// particular analysis result to this function, it can then use the 142193323Sed /// getAnalysis<AnalysisType>() function, below. 143200581Srdivacky virtual void getAnalysisUsage(AnalysisUsage &) const; 144193323Sed 145193323Sed /// releaseMemory() - This member can be implemented by a pass if it wants to 146193323Sed /// be able to release its memory when it is no longer needed. The default 147193323Sed /// behavior of passes is to hold onto memory for the entire duration of their 148193323Sed /// lifetime (which is the entire compile time). For pipelined passes, this 149193323Sed /// is not a big deal because that memory gets recycled every time the pass is 150193323Sed /// invoked on another program unit. For IP passes, it is more important to 151193323Sed /// free memory when it is unused. 152193323Sed /// 153193323Sed /// Optionally implement this function to release pass memory when it is no 154193323Sed /// longer used. 155200581Srdivacky virtual void releaseMemory(); 156193323Sed 157202878Srdivacky /// getAdjustedAnalysisPointer - This method is used when a pass implements 158202878Srdivacky /// an analysis interface through multiple inheritance. If needed, it should 159202878Srdivacky /// override this to adjust the this pointer as needed for the specified pass 160202878Srdivacky /// info. 161212904Sdim virtual void *getAdjustedAnalysisPointer(AnalysisID ID); 162210299Sed virtual ImmutablePass *getAsImmutablePass(); 163210299Sed virtual PMDataManager *getAsPMDataManager(); 164234353Sdim 165193323Sed /// verifyAnalysis() - This member can be implemented by a analysis pass to 166234353Sdim /// check state of analysis information. 167200581Srdivacky virtual void verifyAnalysis() const; 168193323Sed 169193323Sed // dumpPassStructure - Implement the -debug-passes=PassStructure option 170193323Sed virtual void dumpPassStructure(unsigned Offset = 0); 171193323Sed 172193323Sed // lookupPassInfo - Return the pass info object for the specified pass class, 173193323Sed // or null if it is not known. 174212904Sdim static const PassInfo *lookupPassInfo(const void *TI); 175193323Sed 176198090Srdivacky // lookupPassInfo - Return the pass info object for the pass with the given 177198090Srdivacky // argument string, or null if it is not known. 178199481Srdivacky static const PassInfo *lookupPassInfo(StringRef Arg); 179198090Srdivacky 180234353Sdim // createPass - Create a object for the specified pass class, 181234353Sdim // or null if it is not known. 182234353Sdim static Pass *createPass(AnalysisID ID); 183234353Sdim 184193323Sed /// getAnalysisIfAvailable<AnalysisType>() - Subclasses use this function to 185193323Sed /// get analysis information that might be around, for example to update it. 186193323Sed /// This is different than getAnalysis in that it can fail (if the analysis 187193323Sed /// results haven't been computed), so should only be used if you can handle 188193323Sed /// the case when the analysis is not available. This method is often used by 189193323Sed /// transformation APIs to update analysis results for a pass automatically as 190193323Sed /// the transform is performed. 191193323Sed template<typename AnalysisType> AnalysisType * 192193323Sed getAnalysisIfAvailable() const; // Defined in PassAnalysisSupport.h 193193323Sed 194193323Sed /// mustPreserveAnalysisID - This method serves the same function as 195193323Sed /// getAnalysisIfAvailable, but works if you just have an AnalysisID. This 196193323Sed /// obviously cannot give you a properly typed instance of the class if you 197193323Sed /// don't have the class name available (use getAnalysisIfAvailable if you 198193323Sed /// do), but it can tell you if you need to preserve the pass at least. 199212904Sdim bool mustPreserveAnalysisID(char &AID) const; 200193323Sed 201193323Sed /// getAnalysis<AnalysisType>() - This function is used by subclasses to get 202193323Sed /// to the analysis information that they claim to use by overriding the 203193323Sed /// getAnalysisUsage function. 204193323Sed template<typename AnalysisType> 205193323Sed AnalysisType &getAnalysis() const; // Defined in PassAnalysisSupport.h 206193323Sed 207193323Sed template<typename AnalysisType> 208198090Srdivacky AnalysisType &getAnalysis(Function &F); // Defined in PassAnalysisSupport.h 209193323Sed 210193323Sed template<typename AnalysisType> 211212904Sdim AnalysisType &getAnalysisID(AnalysisID PI) const; 212193323Sed 213193323Sed template<typename AnalysisType> 214212904Sdim AnalysisType &getAnalysisID(AnalysisID PI, Function &F); 215193323Sed}; 216193323Sed 217193323Sed//===----------------------------------------------------------------------===// 218193323Sed/// ModulePass class - This class is used to implement unstructured 219193323Sed/// interprocedural optimizations and analyses. ModulePasses may do anything 220193323Sed/// they want to the program. 221193323Sed/// 222193323Sedclass ModulePass : public Pass { 223193323Sedpublic: 224327952Sdim explicit ModulePass(char &pid) : Pass(PT_Module, pid) {} 225327952Sdim 226327952Sdim // Force out-of-line virtual method. 227327952Sdim ~ModulePass() override; 228327952Sdim 229206124Srdivacky /// createPrinterPass - Get a module printer pass. 230327952Sdim Pass *createPrinterPass(raw_ostream &OS, 231276479Sdim const std::string &Banner) const override; 232206124Srdivacky 233193323Sed /// runOnModule - Virtual method overriden by subclasses to process the module 234193323Sed /// being operated on. 235193323Sed virtual bool runOnModule(Module &M) = 0; 236193323Sed 237276479Sdim void assignPassManager(PMStack &PMS, PassManagerType T) override; 238193323Sed 239193323Sed /// Return what kind of Pass Manager can manage this pass. 240276479Sdim PassManagerType getPotentialPassManagerType() const override; 241193323Sed 242309124Sdimprotected: 243309124Sdim /// Optional passes call this function to check whether the pass should be 244309124Sdim /// skipped. This is the case when optimization bisect is over the limit. 245309124Sdim bool skipModule(Module &M) const; 246193323Sed}; 247193323Sed 248193323Sed//===----------------------------------------------------------------------===// 249193323Sed/// ImmutablePass class - This class is used to provide information that does 250193323Sed/// not need to be run. This is useful for things like target information and 251193323Sed/// "basic" versions of AnalysisGroups. 252193323Sed/// 253193323Sedclass ImmutablePass : public ModulePass { 254193323Sedpublic: 255327952Sdim explicit ImmutablePass(char &pid) : ModulePass(pid) {} 256327952Sdim 257327952Sdim // Force out-of-line virtual method. 258327952Sdim ~ImmutablePass() override; 259327952Sdim 260193323Sed /// initializePass - This method may be overriden by immutable passes to allow 261193323Sed /// them to perform various initialization actions they require. This is 262193323Sed /// primarily because an ImmutablePass can "require" another ImmutablePass, 263193323Sed /// and if it does, the overloaded version of initializePass may get access to 264193323Sed /// these passes with getAnalysis<>. 265200581Srdivacky virtual void initializePass(); 266193323Sed 267276479Sdim ImmutablePass *getAsImmutablePass() override { return this; } 268202878Srdivacky 269193323Sed /// ImmutablePasses are never run. 270276479Sdim bool runOnModule(Module &) override { return false; } 271193323Sed}; 272193323Sed 273193323Sed//===----------------------------------------------------------------------===// 274193323Sed/// FunctionPass class - This class is used to implement most global 275193323Sed/// optimizations. Optimizations should subclass this class if they meet the 276193323Sed/// following constraints: 277193323Sed/// 278193323Sed/// 1. Optimizations are organized globally, i.e., a function at a time 279193323Sed/// 2. Optimizing a function does not cause the addition or removal of any 280193323Sed/// functions in the module 281193323Sed/// 282193323Sedclass FunctionPass : public Pass { 283193323Sedpublic: 284212904Sdim explicit FunctionPass(char &pid) : Pass(PT_Function, pid) {} 285193323Sed 286206124Srdivacky /// createPrinterPass - Get a function printer pass. 287327952Sdim Pass *createPrinterPass(raw_ostream &OS, 288276479Sdim const std::string &Banner) const override; 289206124Srdivacky 290193323Sed /// runOnFunction - Virtual method overriden by subclasses to do the 291193323Sed /// per-function processing of the pass. 292193323Sed virtual bool runOnFunction(Function &F) = 0; 293193323Sed 294276479Sdim void assignPassManager(PMStack &PMS, PassManagerType T) override; 295193323Sed 296193323Sed /// Return what kind of Pass Manager can manage this pass. 297276479Sdim PassManagerType getPotentialPassManagerType() const override; 298276479Sdim 299276479Sdimprotected: 300309124Sdim /// Optional passes call this function to check whether the pass should be 301309124Sdim /// skipped. This is the case when Attribute::OptimizeNone is set or when 302309124Sdim /// optimization bisect is over the limit. 303309124Sdim bool skipFunction(const Function &F) const; 304193323Sed}; 305193323Sed 306193323Sed/// If the user specifies the -time-passes argument on an LLVM tool command line 307193323Sed/// then the value of this boolean will be true, otherwise false. 308341825Sdim/// This is the storage for the -time-passes option. 309193323Sedextern bool TimePassesIsEnabled; 310193323Sed 311327952Sdim} // end namespace llvm 312327952Sdim 313193323Sed// Include support files that contain important APIs commonly used by Passes, 314193323Sed// but that we want to separate out to make it easier to read the header files. 315321369Sdim#include "llvm/PassAnalysisSupport.h" 316193323Sed#include "llvm/PassSupport.h" 317193323Sed 318327952Sdim#endif // LLVM_PASS_H 319