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