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