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