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//===----------------------------------------------------------------------===//
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///
94class Pass {
95 AnalysisResolver *Resolver = nullptr; // Used to resolve analysis
96 const void *PassID;
97 PassKind Kind;
98
99public:
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///
251class ModulePass : public Pass {
252public:
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
271protected:
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///
282class ImmutablePass : public ModulePass {
283public:
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///
311class FunctionPass : public Pass {
312public:
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
328protected:
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.
338extern 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)
344extern 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

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