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

source code of llvm/include/llvm/Pass.h