1//===- llvm/Pass.h - Base class for Passes ----------------------*- C++ -*-===//
2//
3// The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file defines a base class that indicates that a specified class is a
11// transformation pass implementation.
12//
13// Passes are designed this way so that it is possible to run passes in a cache
14// and organizationally optimal order without having to specify it at the front
15// end. This allows arbitrary passes to be strung together and have them
16// executed as efficiently as possible.
17//
18// Passes should extend one of the classes below, depending on the guarantees
19// that it can make about what will be modified as it is run. For example, most
20// global optimizations should derive from FunctionPass, because they do not add
21// or delete functions, they operate on the internals of the function.
22//
23// Note that this file #includes PassSupport.h and PassAnalysisSupport.h (at the
24// bottom), so the APIs exposed by these files are also automatically available
25// to all users of this file.
26//
27//===----------------------------------------------------------------------===//
28
29#ifndef LLVM_PASS_H
30#define LLVM_PASS_H
31
32#include "llvm/ADT/StringRef.h"
33#include <string>
34
35namespace llvm {
36
37class AnalysisResolver;
38class AnalysisUsage;
39class BasicBlock;
40class Function;
41class ImmutablePass;
42class Module;
43class PassInfo;
44class PMDataManager;
45class PMStack;
46class raw_ostream;
47
48// AnalysisID - Use the PassInfo to identify a pass...
49using AnalysisID = const void *;
50
51/// Different types of internal pass managers. External pass managers
52/// (PassManager and FunctionPassManager) are not represented here.
53/// Ordering of pass manager types is important here.
54enum PassManagerType {
55 PMT_Unknown = 0,
56 PMT_ModulePassManager = 1, ///< MPPassManager
57 PMT_CallGraphPassManager, ///< CGPassManager
58 PMT_FunctionPassManager, ///< FPPassManager
59 PMT_LoopPassManager, ///< LPPassManager
60 PMT_RegionPassManager, ///< RGPassManager
61 PMT_BasicBlockPassManager, ///< BBPassManager
62 PMT_Last
63};
64
65// Different types of passes.
66enum PassKind {
67 PT_BasicBlock,
68 PT_Region,
69 PT_Loop,
70 PT_Function,
71 PT_CallGraphSCC,
72 PT_Module,
73 PT_PassManager
74};
75
76//===----------------------------------------------------------------------===//
77/// Pass interface - Implemented by all 'passes'. Subclass this if you are an
78/// interprocedural optimization or you do not fit into any of the more
79/// constrained passes described below.
80///
81class Pass {
82 AnalysisResolver *Resolver = nullptr; // Used to resolve analysis
83 const void *PassID;
84 PassKind Kind;
85
86public:
87 explicit Pass(PassKind K, char &pid) : PassID(&pid), Kind(K) {}
88 Pass(const Pass &) = delete;
89 Pass &operator=(const Pass &) = delete;
90 virtual ~Pass();
91
92 PassKind getPassKind() const { return Kind; }
93
94 /// getPassName - Return a nice clean name for a pass. This usually
95 /// implemented in terms of the name that is registered by one of the
96 /// Registration templates, but can be overloaded directly.
97 virtual StringRef getPassName() const;
98
99 /// getPassID - Return the PassID number that corresponds to this pass.
100 AnalysisID getPassID() const {
101 return PassID;
102 }
103
104 /// doInitialization - Virtual method overridden by subclasses to do
105 /// any necessary initialization before any pass is run.
106 virtual bool doInitialization(Module &) { return false; }
107
108 /// doFinalization - Virtual method overriden by subclasses to do any
109 /// necessary clean up after all passes have run.
110 virtual bool doFinalization(Module &) { return false; }
111
112 /// print - Print out the internal state of the pass. This is called by
113 /// Analyze to print out the contents of an analysis. Otherwise it is not
114 /// necessary to implement this method. Beware that the module pointer MAY be
115 /// null. This automatically forwards to a virtual function that does not
116 /// provide the Module* in case the analysis doesn't need it it can just be
117 /// ignored.
118 virtual void print(raw_ostream &OS, const Module *M) const;
119
120 void dump() const; // dump - Print to stderr.
121
122 /// createPrinterPass - Get a Pass appropriate to print the IR this
123 /// pass operates on (Module, Function or MachineFunction).
124 virtual Pass *createPrinterPass(raw_ostream &OS,
125 const std::string &Banner) const = 0;
126
127 /// Each pass is responsible for assigning a pass manager to itself.
128 /// PMS is the stack of available pass manager.
129 virtual void assignPassManager(PMStack &,
130 PassManagerType) {}
131
132 /// Check if available pass managers are suitable for this pass or not.
133 virtual void preparePassManager(PMStack &);
134
135 /// Return what kind of Pass Manager can manage this pass.
136 virtual PassManagerType getPotentialPassManagerType() const;
137
138 // Access AnalysisResolver
139 void setResolver(AnalysisResolver *AR);
140 AnalysisResolver *getResolver() const { return Resolver; }
141
142 /// getAnalysisUsage - This function should be overriden by passes that need
143 /// analysis information to do their job. If a pass specifies that it uses a
144 /// particular analysis result to this function, it can then use the
145 /// getAnalysis<AnalysisType>() function, below.
146 virtual void getAnalysisUsage(AnalysisUsage &) const;
147
148 /// releaseMemory() - This member can be implemented by a pass if it wants to
149 /// be able to release its memory when it is no longer needed. The default
150 /// behavior of passes is to hold onto memory for the entire duration of their
151 /// lifetime (which is the entire compile time). For pipelined passes, this
152 /// is not a big deal because that memory gets recycled every time the pass is
153 /// invoked on another program unit. For IP passes, it is more important to
154 /// free memory when it is unused.
155 ///
156 /// Optionally implement this function to release pass memory when it is no
157 /// longer used.
158 virtual void releaseMemory();
159
160 /// getAdjustedAnalysisPointer - This method is used when a pass implements
161 /// an analysis interface through multiple inheritance. If needed, it should
162 /// override this to adjust the this pointer as needed for the specified pass
163 /// info.
164 virtual void *getAdjustedAnalysisPointer(AnalysisID ID);
165 virtual ImmutablePass *getAsImmutablePass();
166 virtual PMDataManager *getAsPMDataManager();
167
168 /// verifyAnalysis() - This member can be implemented by a analysis pass to
169 /// check state of analysis information.
170 virtual void verifyAnalysis() const;
171
172 // dumpPassStructure - Implement the -debug-passes=PassStructure option
173 virtual void dumpPassStructure(unsigned Offset = 0);
174
175 // lookupPassInfo - Return the pass info object for the specified pass class,
176 // or null if it is not known.
177 static const PassInfo *lookupPassInfo(const void *TI);
178
179 // lookupPassInfo - Return the pass info object for the pass with the given
180 // argument string, or null if it is not known.
181 static const PassInfo *lookupPassInfo(StringRef Arg);
182
183 // createPass - Create a object for the specified pass class,
184 // or null if it is not known.
185 static Pass *createPass(AnalysisID ID);
186
187 /// getAnalysisIfAvailable<AnalysisType>() - Subclasses use this function to
188 /// get analysis information that might be around, for example to update it.
189 /// This is different than getAnalysis in that it can fail (if the analysis
190 /// results haven't been computed), so should only be used if you can handle
191 /// the case when the analysis is not available. This method is often used by
192 /// transformation APIs to update analysis results for a pass automatically as
193 /// the transform is performed.
194 template<typename AnalysisType> AnalysisType *
195 getAnalysisIfAvailable() const; // Defined in PassAnalysisSupport.h
196
197 /// mustPreserveAnalysisID - This method serves the same function as
198 /// getAnalysisIfAvailable, but works if you just have an AnalysisID. This
199 /// obviously cannot give you a properly typed instance of the class if you
200 /// don't have the class name available (use getAnalysisIfAvailable if you
201 /// do), but it can tell you if you need to preserve the pass at least.
202 bool mustPreserveAnalysisID(char &AID) const;
203
204 /// getAnalysis<AnalysisType>() - This function is used by subclasses to get
205 /// to the analysis information that they claim to use by overriding the
206 /// getAnalysisUsage function.
207 template<typename AnalysisType>
208 AnalysisType &getAnalysis() const; // Defined in PassAnalysisSupport.h
209
210 template<typename AnalysisType>
211 AnalysisType &getAnalysis(Function &F); // Defined in PassAnalysisSupport.h
212
213 template<typename AnalysisType>
214 AnalysisType &getAnalysisID(AnalysisID PI) const;
215
216 template<typename AnalysisType>
217 AnalysisType &getAnalysisID(AnalysisID PI, Function &F);
218};
219
220//===----------------------------------------------------------------------===//
221/// ModulePass class - This class is used to implement unstructured
222/// interprocedural optimizations and analyses. ModulePasses may do anything
223/// they want to the program.
224///
225class ModulePass : public Pass {
226public:
227 explicit ModulePass(char &pid) : Pass(PT_Module, pid) {}
228
229 // Force out-of-line virtual method.
230 ~ModulePass() override;
231
232 /// createPrinterPass - Get a module printer pass.
233 Pass *createPrinterPass(raw_ostream &OS,
234 const std::string &Banner) const override;
235
236 /// runOnModule - Virtual method overriden by subclasses to process the module
237 /// being operated on.
238 virtual bool runOnModule(Module &M) = 0;
239
240 void assignPassManager(PMStack &PMS, PassManagerType T) override;
241
242 /// Return what kind of Pass Manager can manage this pass.
243 PassManagerType getPotentialPassManagerType() const override;
244
245protected:
246 /// Optional passes call this function to check whether the pass should be
247 /// skipped. This is the case when optimization bisect is over the limit.
248 bool skipModule(Module &M) const;
249};
250
251//===----------------------------------------------------------------------===//
252/// ImmutablePass class - This class is used to provide information that does
253/// not need to be run. This is useful for things like target information and
254/// "basic" versions of AnalysisGroups.
255///
256class ImmutablePass : public ModulePass {
257public:
258 explicit ImmutablePass(char &pid) : ModulePass(pid) {}
259
260 // Force out-of-line virtual method.
261 ~ImmutablePass() override;
262
263 /// initializePass - This method may be overriden by immutable passes to allow
264 /// them to perform various initialization actions they require. This is
265 /// primarily because an ImmutablePass can "require" another ImmutablePass,
266 /// and if it does, the overloaded version of initializePass may get access to
267 /// these passes with getAnalysis<>.
268 virtual void initializePass();
269
270 ImmutablePass *getAsImmutablePass() override { return this; }
271
272 /// ImmutablePasses are never run.
273 bool runOnModule(Module &) override { return false; }
274};
275
276//===----------------------------------------------------------------------===//
277/// FunctionPass class - This class is used to implement most global
278/// optimizations. Optimizations should subclass this class if they meet the
279/// following constraints:
280///
281/// 1. Optimizations are organized globally, i.e., a function at a time
282/// 2. Optimizing a function does not cause the addition or removal of any
283/// functions in the module
284///
285class FunctionPass : public Pass {
286public:
287 explicit FunctionPass(char &pid) : Pass(PT_Function, pid) {}
288
289 /// createPrinterPass - Get a function printer pass.
290 Pass *createPrinterPass(raw_ostream &OS,
291 const std::string &Banner) const override;
292
293 /// runOnFunction - Virtual method overriden by subclasses to do the
294 /// per-function processing of the pass.
295 virtual bool runOnFunction(Function &F) = 0;
296
297 void assignPassManager(PMStack &PMS, PassManagerType T) override;
298
299 /// Return what kind of Pass Manager can manage this pass.
300 PassManagerType getPotentialPassManagerType() const override;
301
302protected:
303 /// Optional passes call this function to check whether the pass should be
304 /// skipped. This is the case when Attribute::OptimizeNone is set or when
305 /// optimization bisect is over the limit.
306 bool skipFunction(const Function &F) const;
307};
308
309//===----------------------------------------------------------------------===//
310/// BasicBlockPass class - This class is used to implement most local
311/// optimizations. Optimizations should subclass this class if they
312/// meet the following constraints:
313/// 1. Optimizations are local, operating on either a basic block or
314/// instruction at a time.
315/// 2. Optimizations do not modify the CFG of the contained function, or any
316/// other basic block in the function.
317/// 3. Optimizations conform to all of the constraints of FunctionPasses.
318///
319class BasicBlockPass : public Pass {
320public:
321 explicit BasicBlockPass(char &pid) : Pass(PT_BasicBlock, pid) {}
322
323 /// createPrinterPass - Get a basic block printer pass.
324 Pass *createPrinterPass(raw_ostream &OS,
325 const std::string &Banner) const override;
326
327 using llvm::Pass::doInitialization;
328 using llvm::Pass::doFinalization;
329
330 /// doInitialization - Virtual method overridden by BasicBlockPass subclasses
331 /// to do any necessary per-function initialization.
332 virtual bool doInitialization(Function &);
333
334 /// runOnBasicBlock - Virtual method overriden by subclasses to do the
335 /// per-basicblock processing of the pass.
336 virtual bool runOnBasicBlock(BasicBlock &BB) = 0;
337
338 /// doFinalization - Virtual method overriden by BasicBlockPass subclasses to
339 /// do any post processing needed after all passes have run.
340 virtual bool doFinalization(Function &);
341
342 void assignPassManager(PMStack &PMS, PassManagerType T) override;
343
344 /// Return what kind of Pass Manager can manage this pass.
345 PassManagerType getPotentialPassManagerType() const override;
346
347protected:
348 /// Optional passes call this function to check whether the pass should be
349 /// skipped. This is the case when Attribute::OptimizeNone is set or when
350 /// optimization bisect is over the limit.
351 bool skipBasicBlock(const BasicBlock &BB) const;
352};
353
354/// If the user specifies the -time-passes argument on an LLVM tool command line
355/// then the value of this boolean will be true, otherwise false.
356/// This is the storage for the -time-passes option.
357extern bool TimePassesIsEnabled;
358
359} // end namespace llvm
360
361// Include support files that contain important APIs commonly used by Passes,
362// but that we want to separate out to make it easier to read the header files.
363#include "llvm/InitializePasses.h"
364#include "llvm/PassAnalysisSupport.h"
365#include "llvm/PassSupport.h"
366
367#endif // LLVM_PASS_H
368