Pass.h revision 07cf79ef537caff6d39145f190a28a336e629b6f
1//===- llvm/Pass.h - Base class for Passes ----------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file defines a base class that indicates that a specified class is a
11// transformation pass implementation.
12//
13// Passes are designed this way so that it is possible to run passes in a cache
14// and organizationally optimal order without having to specify it at the front
15// end.  This allows arbitrary passes to be strung together and have them
16// executed as effeciently as possible.
17//
18// Passes should extend one of the classes below, depending on the guarantees
19// that it can make about what will be modified as it is run.  For example, most
20// global optimizations should derive from FunctionPass, because they do not add
21// or delete functions, they operate on the internals of the function.
22//
23// Note that this file #includes PassSupport.h and PassAnalysisSupport.h (at the
24// bottom), so the APIs exposed by these files are also automatically available
25// to all users of this file.
26//
27//===----------------------------------------------------------------------===//
28
29#ifndef LLVM_PASS_H
30#define LLVM_PASS_H
31
32#include "llvm/Module.h"
33#include "llvm/Support/DataTypes.h"
34#include "llvm/Support/Streams.h"
35#include <cassert>
36#include <iosfwd>
37#include <utility>
38#include <vector>
39
40namespace llvm {
41
42class BasicBlock;
43class Function;
44class Module;
45class AnalysisUsage;
46class PassInfo;
47class ImmutablePass;
48class PMStack;
49class AnalysisResolver;
50class PMDataManager;
51class LLVMContext;
52
53// AnalysisID - Use the PassInfo to identify a pass...
54typedef const PassInfo* AnalysisID;
55
56/// Different types of internal pass managers. External pass managers
57/// (PassManager and FunctionPassManager) are not represented here.
58/// Ordering of pass manager types is important here.
59enum PassManagerType {
60  PMT_Unknown = 0,
61  PMT_ModulePassManager = 1, /// MPPassManager
62  PMT_CallGraphPassManager,  /// CGPassManager
63  PMT_FunctionPassManager,   /// FPPassManager
64  PMT_LoopPassManager,       /// LPPassManager
65  PMT_BasicBlockPassManager, /// BBPassManager
66  PMT_Last
67};
68
69//===----------------------------------------------------------------------===//
70/// Pass interface - Implemented by all 'passes'.  Subclass this if you are an
71/// interprocedural optimization or you do not fit into any of the more
72/// constrained passes described below.
73///
74class Pass {
75  AnalysisResolver *Resolver;  // Used to resolve analysis
76  intptr_t PassID;
77
78  void operator=(const Pass&);  // DO NOT IMPLEMENT
79  Pass(const Pass &);           // DO NOT IMPLEMENT
80
81protected:
82  LLVMContext *Context;
83
84public:
85  explicit Pass(intptr_t pid) : Resolver(0), PassID(pid) {
86    assert(pid && "pid cannot be 0");
87  }
88  explicit Pass(const void *pid) : Resolver(0), PassID((intptr_t)pid) {
89    assert(pid && "pid cannot be 0");
90  }
91  virtual ~Pass();
92
93  /// getPassName - Return a nice clean name for a pass.  This usually
94  /// implemented in terms of the name that is registered by one of the
95  /// Registration templates, but can be overloaded directly.
96  ///
97  virtual const char *getPassName() const;
98
99  /// getPassInfo - Return the PassInfo data structure that corresponds to this
100  /// pass...  If the pass has not been registered, this will return null.
101  ///
102  const PassInfo *getPassInfo() const;
103
104  /// print - Print out the internal state of the pass.  This is called by
105  /// Analyze to print out the contents of an analysis.  Otherwise it is not
106  /// necessary to implement this method.  Beware that the module pointer MAY be
107  /// null.  This automatically forwards to a virtual function that does not
108  /// provide the Module* in case the analysis doesn't need it it can just be
109  /// ignored.
110  ///
111  virtual void print(std::ostream &O, const Module *M) const;
112  void print(std::ostream *O, const Module *M) const { if (O) print(*O, M); }
113  void dump() const; // dump - call print(std::cerr, 0);
114
115  /// Each pass is responsible for assigning a pass manager to itself.
116  /// PMS is the stack of available pass manager.
117  virtual void assignPassManager(PMStack &,
118                                 PassManagerType = PMT_Unknown) {}
119  /// Check if available pass managers are suitable for this pass or not.
120  virtual void preparePassManager(PMStack &) {}
121
122  ///  Return what kind of Pass Manager can manage this pass.
123  virtual PassManagerType getPotentialPassManagerType() const {
124    return PMT_Unknown;
125  }
126
127  // Access AnalysisResolver
128  inline void setResolver(AnalysisResolver *AR) {
129    assert (!Resolver && "Resolver is already set");
130    Resolver = AR;
131  }
132  inline AnalysisResolver *getResolver() {
133    return Resolver;
134  }
135
136  /// getAnalysisUsage - This function should be overriden by passes that need
137  /// analysis information to do their job.  If a pass specifies that it uses a
138  /// particular analysis result to this function, it can then use the
139  /// getAnalysis<AnalysisType>() function, below.
140  ///
141  virtual void getAnalysisUsage(AnalysisUsage &) const {
142    // By default, no analysis results are used, all are invalidated.
143  }
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  ///
156  virtual void releaseMemory() {}
157
158  /// verifyAnalysis() - This member can be implemented by a analysis pass to
159  /// check state of analysis information.
160  virtual void verifyAnalysis() const {}
161
162  // dumpPassStructure - Implement the -debug-passes=PassStructure option
163  virtual void dumpPassStructure(unsigned Offset = 0);
164
165  template<typename AnalysisClass>
166  static const PassInfo *getClassPassInfo() {
167    return lookupPassInfo(intptr_t(&AnalysisClass::ID));
168  }
169
170  // lookupPassInfo - Return the pass info object for the specified pass class,
171  // or null if it is not known.
172  static const PassInfo *lookupPassInfo(intptr_t TI);
173
174  /// getAnalysisIfAvailable<AnalysisType>() - Subclasses use this function to
175  /// get analysis information that might be around, for example to update it.
176  /// This is different than getAnalysis in that it can fail (if the analysis
177  /// results haven't been computed), so should only be used if you can handle
178  /// the case when the analysis is not available.  This method is often used by
179  /// transformation APIs to update analysis results for a pass automatically as
180  /// the transform is performed.
181  ///
182  template<typename AnalysisType> AnalysisType *
183    getAnalysisIfAvailable() const; // Defined in PassAnalysisSupport.h
184
185  /// mustPreserveAnalysisID - This method serves the same function as
186  /// getAnalysisIfAvailable, but works if you just have an AnalysisID.  This
187  /// obviously cannot give you a properly typed instance of the class if you
188  /// don't have the class name available (use getAnalysisIfAvailable if you
189  /// do), but it can tell you if you need to preserve the pass at least.
190  ///
191  bool mustPreserveAnalysisID(const PassInfo *AnalysisID) const;
192
193  /// getAnalysis<AnalysisType>() - This function is used by subclasses to get
194  /// to the analysis information that they claim to use by overriding the
195  /// getAnalysisUsage function.
196  ///
197  template<typename AnalysisType>
198  AnalysisType &getAnalysis() const; // Defined in PassAnalysisSupport.h
199
200  template<typename AnalysisType>
201  AnalysisType &getAnalysis(Function &F); // Defined in PassanalysisSupport.h
202
203  template<typename AnalysisType>
204  AnalysisType &getAnalysisID(const PassInfo *PI) const;
205
206  template<typename AnalysisType>
207  AnalysisType &getAnalysisID(const PassInfo *PI, Function &F);
208};
209
210inline std::ostream &operator<<(std::ostream &OS, const Pass &P) {
211  P.print(OS, 0); return OS;
212}
213
214//===----------------------------------------------------------------------===//
215/// ModulePass class - This class is used to implement unstructured
216/// interprocedural optimizations and analyses.  ModulePasses may do anything
217/// they want to the program.
218///
219class ModulePass : public Pass {
220public:
221  /// runOnModule - Virtual method overriden by subclasses to process the module
222  /// being operated on.
223  virtual bool runOnModule(Module &M) = 0;
224
225  virtual void assignPassManager(PMStack &PMS,
226                                 PassManagerType T = PMT_ModulePassManager);
227
228  ///  Return what kind of Pass Manager can manage this pass.
229  virtual PassManagerType getPotentialPassManagerType() const {
230    return PMT_ModulePassManager;
231  }
232
233  explicit ModulePass(intptr_t pid) : Pass(pid) {}
234  explicit ModulePass(const void *pid) : Pass(pid) {}
235  // Force out-of-line virtual method.
236  virtual ~ModulePass();
237};
238
239
240//===----------------------------------------------------------------------===//
241/// ImmutablePass class - This class is used to provide information that does
242/// not need to be run.  This is useful for things like target information and
243/// "basic" versions of AnalysisGroups.
244///
245class ImmutablePass : public ModulePass {
246public:
247  /// initializePass - This method may be overriden by immutable passes to allow
248  /// them to perform various initialization actions they require.  This is
249  /// primarily because an ImmutablePass can "require" another ImmutablePass,
250  /// and if it does, the overloaded version of initializePass may get access to
251  /// these passes with getAnalysis<>.
252  ///
253  virtual void initializePass() {}
254
255  /// ImmutablePasses are never run.
256  ///
257  bool runOnModule(Module &) { return false; }
258
259  explicit ImmutablePass(intptr_t pid) : ModulePass(pid) {}
260  explicit ImmutablePass(const void *pid)
261  : ModulePass(pid) {}
262
263  // Force out-of-line virtual method.
264  virtual ~ImmutablePass();
265};
266
267//===----------------------------------------------------------------------===//
268/// FunctionPass class - This class is used to implement most global
269/// optimizations.  Optimizations should subclass this class if they meet the
270/// following constraints:
271///
272///  1. Optimizations are organized globally, i.e., a function at a time
273///  2. Optimizing a function does not cause the addition or removal of any
274///     functions in the module
275///
276class FunctionPass : public Pass {
277public:
278  explicit FunctionPass(intptr_t pid) : Pass(pid) {}
279  explicit FunctionPass(const void *pid) : Pass(pid) {}
280
281  /// doInitialization - Virtual method overridden by subclasses to do
282  /// any necessary per-module initialization.
283  ///
284  virtual bool doInitialization(Module &M) {
285    Context = &M.getContext();
286    return false;
287  }
288
289  /// runOnFunction - Virtual method overriden by subclasses to do the
290  /// per-function processing of the pass.
291  ///
292  virtual bool runOnFunction(Function &F) = 0;
293
294  /// doFinalization - Virtual method overriden by subclasses to do any post
295  /// processing needed after all passes have run.
296  ///
297  virtual bool doFinalization(Module &) { return false; }
298
299  /// runOnModule - On a module, we run this pass by initializing,
300  /// ronOnFunction'ing once for every function in the module, then by
301  /// finalizing.
302  ///
303  virtual bool runOnModule(Module &M);
304
305  /// run - On a function, we simply initialize, run the function, then
306  /// finalize.
307  ///
308  bool run(Function &F);
309
310  virtual void assignPassManager(PMStack &PMS,
311                                 PassManagerType T = PMT_FunctionPassManager);
312
313  ///  Return what kind of Pass Manager can manage this pass.
314  virtual PassManagerType getPotentialPassManagerType() const {
315    return PMT_FunctionPassManager;
316  }
317};
318
319
320
321//===----------------------------------------------------------------------===//
322/// BasicBlockPass class - This class is used to implement most local
323/// optimizations.  Optimizations should subclass this class if they
324/// meet the following constraints:
325///   1. Optimizations are local, operating on either a basic block or
326///      instruction at a time.
327///   2. Optimizations do not modify the CFG of the contained function, or any
328///      other basic block in the function.
329///   3. Optimizations conform to all of the constraints of FunctionPasses.
330///
331class BasicBlockPass : public Pass {
332public:
333  explicit BasicBlockPass(intptr_t pid) : Pass(pid) {}
334  explicit BasicBlockPass(const void *pid) : Pass(pid) {}
335
336  /// doInitialization - Virtual method overridden by subclasses to do
337  /// any necessary per-module initialization.
338  ///
339  virtual bool doInitialization(Module &M) {
340    Context = &M.getContext();
341    return false;
342  }
343
344  /// doInitialization - Virtual method overridden by BasicBlockPass subclasses
345  /// to do any necessary per-function initialization.
346  ///
347  virtual bool doInitialization(Function &) { return false; }
348
349  /// runOnBasicBlock - Virtual method overriden by subclasses to do the
350  /// per-basicblock processing of the pass.
351  ///
352  virtual bool runOnBasicBlock(BasicBlock &BB) = 0;
353
354  /// doFinalization - Virtual method overriden by BasicBlockPass subclasses to
355  /// do any post processing needed after all passes have run.
356  ///
357  virtual bool doFinalization(Function &) { return false; }
358
359  /// doFinalization - Virtual method overriden by subclasses to do any post
360  /// processing needed after all passes have run.
361  ///
362  virtual bool doFinalization(Module &) { return false; }
363
364
365  // To run this pass on a function, we simply call runOnBasicBlock once for
366  // each function.
367  //
368  bool runOnFunction(Function &F);
369
370  virtual void assignPassManager(PMStack &PMS,
371                                 PassManagerType T = PMT_BasicBlockPassManager);
372
373  ///  Return what kind of Pass Manager can manage this pass.
374  virtual PassManagerType getPotentialPassManagerType() const {
375    return PMT_BasicBlockPassManager;
376  }
377};
378
379/// If the user specifies the -time-passes argument on an LLVM tool command line
380/// then the value of this boolean will be true, otherwise false.
381/// @brief This is the storage for the -time-passes option.
382extern bool TimePassesIsEnabled;
383
384} // End llvm namespace
385
386// Include support files that contain important APIs commonly used by Passes,
387// but that we want to separate out to make it easier to read the header files.
388//
389#include "llvm/PassSupport.h"
390#include "llvm/PassAnalysisSupport.h"
391
392#endif
393