Pass.h revision 203954
1193323Sed//===- llvm/Pass.h - Base class for Passes ----------------------*- C++ -*-===//
2193323Sed//
3193323Sed//                     The LLVM Compiler Infrastructure
4193323Sed//
5193323Sed// This file is distributed under the University of Illinois Open Source
6193323Sed// License. See LICENSE.TXT for details.
7193323Sed//
8193323Sed//===----------------------------------------------------------------------===//
9193323Sed//
10193323Sed// This file defines a base class that indicates that a specified class is a
11193323Sed// transformation pass implementation.
12193323Sed//
13193323Sed// Passes are designed this way so that it is possible to run passes in a cache
14193323Sed// and organizationally optimal order without having to specify it at the front
15193323Sed// end.  This allows arbitrary passes to be strung together and have them
16193323Sed// executed as effeciently as possible.
17193323Sed//
18193323Sed// Passes should extend one of the classes below, depending on the guarantees
19193323Sed// that it can make about what will be modified as it is run.  For example, most
20193323Sed// global optimizations should derive from FunctionPass, because they do not add
21193323Sed// or delete functions, they operate on the internals of the function.
22193323Sed//
23193323Sed// Note that this file #includes PassSupport.h and PassAnalysisSupport.h (at the
24193323Sed// bottom), so the APIs exposed by these files are also automatically available
25193323Sed// to all users of this file.
26193323Sed//
27193323Sed//===----------------------------------------------------------------------===//
28193323Sed
29193323Sed#ifndef LLVM_PASS_H
30193323Sed#define LLVM_PASS_H
31193323Sed
32198892Srdivacky#include "llvm/System/DataTypes.h"
33193323Sed#include <cassert>
34193323Sed#include <utility>
35193323Sed#include <vector>
36193323Sed
37193323Sednamespace llvm {
38193323Sed
39193323Sedclass BasicBlock;
40193323Sedclass Function;
41193323Sedclass Module;
42193323Sedclass AnalysisUsage;
43193323Sedclass PassInfo;
44193323Sedclass ImmutablePass;
45193323Sedclass PMStack;
46193323Sedclass AnalysisResolver;
47193323Sedclass PMDataManager;
48198090Srdivackyclass raw_ostream;
49198090Srdivackyclass StringRef;
50193323Sed
51193323Sed// AnalysisID - Use the PassInfo to identify a pass...
52193323Sedtypedef const PassInfo* AnalysisID;
53193323Sed
54193323Sed/// Different types of internal pass managers. External pass managers
55193323Sed/// (PassManager and FunctionPassManager) are not represented here.
56193323Sed/// Ordering of pass manager types is important here.
57193323Sedenum PassManagerType {
58193323Sed  PMT_Unknown = 0,
59203954Srdivacky  PMT_ModulePassManager = 1, ///< MPPassManager
60203954Srdivacky  PMT_CallGraphPassManager,  ///< CGPassManager
61203954Srdivacky  PMT_FunctionPassManager,   ///< FPPassManager
62203954Srdivacky  PMT_LoopPassManager,       ///< LPPassManager
63203954Srdivacky  PMT_BasicBlockPassManager, ///< BBPassManager
64193323Sed  PMT_Last
65193323Sed};
66193323Sed
67202878Srdivacky// Different types of passes.
68202878Srdivackyenum PassKind {
69202878Srdivacky  PT_BasicBlock,
70202878Srdivacky  PT_Loop,
71202878Srdivacky  PT_Function,
72202878Srdivacky  PT_CallGraphSCC,
73202878Srdivacky  PT_Module,
74202878Srdivacky  PT_PassManager
75202878Srdivacky};
76202878Srdivacky
77193323Sed//===----------------------------------------------------------------------===//
78193323Sed/// Pass interface - Implemented by all 'passes'.  Subclass this if you are an
79193323Sed/// interprocedural optimization or you do not fit into any of the more
80193323Sed/// constrained passes described below.
81193323Sed///
82193323Sedclass Pass {
83193323Sed  AnalysisResolver *Resolver;  // Used to resolve analysis
84193323Sed  intptr_t PassID;
85202878Srdivacky  PassKind Kind;
86193323Sed  void operator=(const Pass&);  // DO NOT IMPLEMENT
87193323Sed  Pass(const Pass &);           // DO NOT IMPLEMENT
88195340Sed
89193323Sedpublic:
90202878Srdivacky  explicit Pass(PassKind K, intptr_t pid) : Resolver(0), PassID(pid), Kind(K) {
91193323Sed    assert(pid && "pid cannot be 0");
92193323Sed  }
93202878Srdivacky  explicit Pass(PassKind K, const void *pid)
94202878Srdivacky    : Resolver(0), PassID((intptr_t)pid), Kind(K) {
95193323Sed    assert(pid && "pid cannot be 0");
96193323Sed  }
97193323Sed  virtual ~Pass();
98193323Sed
99202878Srdivacky
100202878Srdivacky  PassKind getPassKind() const { return Kind; }
101202878Srdivacky
102193323Sed  /// getPassName - Return a nice clean name for a pass.  This usually
103193323Sed  /// implemented in terms of the name that is registered by one of the
104193323Sed  /// Registration templates, but can be overloaded directly.
105193323Sed  ///
106193323Sed  virtual const char *getPassName() const;
107193323Sed
108193323Sed  /// getPassInfo - Return the PassInfo data structure that corresponds to this
109193323Sed  /// pass...  If the pass has not been registered, this will return null.
110193323Sed  ///
111193323Sed  const PassInfo *getPassInfo() const;
112193323Sed
113193323Sed  /// print - Print out the internal state of the pass.  This is called by
114193323Sed  /// Analyze to print out the contents of an analysis.  Otherwise it is not
115193323Sed  /// necessary to implement this method.  Beware that the module pointer MAY be
116193323Sed  /// null.  This automatically forwards to a virtual function that does not
117193323Sed  /// provide the Module* in case the analysis doesn't need it it can just be
118193323Sed  /// ignored.
119193323Sed  ///
120198090Srdivacky  virtual void print(raw_ostream &O, const Module *M) const;
121198090Srdivacky  void dump() const; // dump - Print to stderr.
122193323Sed
123193323Sed  /// Each pass is responsible for assigning a pass manager to itself.
124193323Sed  /// PMS is the stack of available pass manager.
125193323Sed  virtual void assignPassManager(PMStack &,
126193323Sed                                 PassManagerType = PMT_Unknown) {}
127193323Sed  /// Check if available pass managers are suitable for this pass or not.
128200581Srdivacky  virtual void preparePassManager(PMStack &);
129193323Sed
130193323Sed  ///  Return what kind of Pass Manager can manage this pass.
131200581Srdivacky  virtual PassManagerType getPotentialPassManagerType() const;
132193323Sed
133193323Sed  // Access AnalysisResolver
134193323Sed  inline void setResolver(AnalysisResolver *AR) {
135202878Srdivacky    assert(!Resolver && "Resolver is already set");
136193323Sed    Resolver = AR;
137193323Sed  }
138193323Sed  inline AnalysisResolver *getResolver() {
139193323Sed    return Resolver;
140193323Sed  }
141193323Sed
142193323Sed  /// getAnalysisUsage - This function should be overriden by passes that need
143193323Sed  /// analysis information to do their job.  If a pass specifies that it uses a
144193323Sed  /// particular analysis result to this function, it can then use the
145193323Sed  /// getAnalysis<AnalysisType>() function, below.
146193323Sed  ///
147200581Srdivacky  virtual void getAnalysisUsage(AnalysisUsage &) const;
148193323Sed
149193323Sed  /// releaseMemory() - This member can be implemented by a pass if it wants to
150193323Sed  /// be able to release its memory when it is no longer needed.  The default
151193323Sed  /// behavior of passes is to hold onto memory for the entire duration of their
152193323Sed  /// lifetime (which is the entire compile time).  For pipelined passes, this
153193323Sed  /// is not a big deal because that memory gets recycled every time the pass is
154193323Sed  /// invoked on another program unit.  For IP passes, it is more important to
155193323Sed  /// free memory when it is unused.
156193323Sed  ///
157193323Sed  /// Optionally implement this function to release pass memory when it is no
158193323Sed  /// longer used.
159193323Sed  ///
160200581Srdivacky  virtual void releaseMemory();
161193323Sed
162202878Srdivacky  /// getAdjustedAnalysisPointer - This method is used when a pass implements
163202878Srdivacky  /// an analysis interface through multiple inheritance.  If needed, it should
164202878Srdivacky  /// override this to adjust the this pointer as needed for the specified pass
165202878Srdivacky  /// info.
166202878Srdivacky  virtual void *getAdjustedAnalysisPointer(const PassInfo *PI) {
167202878Srdivacky    return this;
168202878Srdivacky  }
169202878Srdivacky  virtual ImmutablePass *getAsImmutablePass() { return 0; }
170202878Srdivacky  virtual PMDataManager *getAsPMDataManager() { return 0; }
171202878Srdivacky
172193323Sed  /// verifyAnalysis() - This member can be implemented by a analysis pass to
173193323Sed  /// check state of analysis information.
174200581Srdivacky  virtual void verifyAnalysis() const;
175193323Sed
176193323Sed  // dumpPassStructure - Implement the -debug-passes=PassStructure option
177193323Sed  virtual void dumpPassStructure(unsigned Offset = 0);
178193323Sed
179193323Sed  template<typename AnalysisClass>
180193323Sed  static const PassInfo *getClassPassInfo() {
181193323Sed    return lookupPassInfo(intptr_t(&AnalysisClass::ID));
182193323Sed  }
183193323Sed
184193323Sed  // lookupPassInfo - Return the pass info object for the specified pass class,
185193323Sed  // or null if it is not known.
186193323Sed  static const PassInfo *lookupPassInfo(intptr_t TI);
187193323Sed
188198090Srdivacky  // lookupPassInfo - Return the pass info object for the pass with the given
189198090Srdivacky  // argument string, or null if it is not known.
190199481Srdivacky  static const PassInfo *lookupPassInfo(StringRef Arg);
191198090Srdivacky
192193323Sed  /// getAnalysisIfAvailable<AnalysisType>() - Subclasses use this function to
193193323Sed  /// get analysis information that might be around, for example to update it.
194193323Sed  /// This is different than getAnalysis in that it can fail (if the analysis
195193323Sed  /// results haven't been computed), so should only be used if you can handle
196193323Sed  /// the case when the analysis is not available.  This method is often used by
197193323Sed  /// transformation APIs to update analysis results for a pass automatically as
198193323Sed  /// the transform is performed.
199193323Sed  ///
200193323Sed  template<typename AnalysisType> AnalysisType *
201193323Sed    getAnalysisIfAvailable() const; // Defined in PassAnalysisSupport.h
202193323Sed
203193323Sed  /// mustPreserveAnalysisID - This method serves the same function as
204193323Sed  /// getAnalysisIfAvailable, but works if you just have an AnalysisID.  This
205193323Sed  /// obviously cannot give you a properly typed instance of the class if you
206193323Sed  /// don't have the class name available (use getAnalysisIfAvailable if you
207193323Sed  /// do), but it can tell you if you need to preserve the pass at least.
208193323Sed  ///
209193323Sed  bool mustPreserveAnalysisID(const PassInfo *AnalysisID) const;
210193323Sed
211193323Sed  /// getAnalysis<AnalysisType>() - This function is used by subclasses to get
212193323Sed  /// to the analysis information that they claim to use by overriding the
213193323Sed  /// getAnalysisUsage function.
214193323Sed  ///
215193323Sed  template<typename AnalysisType>
216193323Sed  AnalysisType &getAnalysis() const; // Defined in PassAnalysisSupport.h
217193323Sed
218193323Sed  template<typename AnalysisType>
219198090Srdivacky  AnalysisType &getAnalysis(Function &F); // Defined in PassAnalysisSupport.h
220193323Sed
221193323Sed  template<typename AnalysisType>
222193323Sed  AnalysisType &getAnalysisID(const PassInfo *PI) const;
223193323Sed
224193323Sed  template<typename AnalysisType>
225193323Sed  AnalysisType &getAnalysisID(const PassInfo *PI, Function &F);
226193323Sed};
227193323Sed
228193323Sed
229193323Sed//===----------------------------------------------------------------------===//
230193323Sed/// ModulePass class - This class is used to implement unstructured
231193323Sed/// interprocedural optimizations and analyses.  ModulePasses may do anything
232193323Sed/// they want to the program.
233193323Sed///
234193323Sedclass ModulePass : public Pass {
235193323Sedpublic:
236193323Sed  /// runOnModule - Virtual method overriden by subclasses to process the module
237193323Sed  /// being operated on.
238193323Sed  virtual bool runOnModule(Module &M) = 0;
239193323Sed
240193323Sed  virtual void assignPassManager(PMStack &PMS,
241193323Sed                                 PassManagerType T = PMT_ModulePassManager);
242193323Sed
243193323Sed  ///  Return what kind of Pass Manager can manage this pass.
244200581Srdivacky  virtual PassManagerType getPotentialPassManagerType() const;
245193323Sed
246202878Srdivacky  explicit ModulePass(intptr_t pid) : Pass(PT_Module, pid) {}
247202878Srdivacky  explicit ModulePass(const void *pid) : Pass(PT_Module, pid) {}
248193323Sed  // Force out-of-line virtual method.
249193323Sed  virtual ~ModulePass();
250193323Sed};
251193323Sed
252193323Sed
253193323Sed//===----------------------------------------------------------------------===//
254193323Sed/// ImmutablePass class - This class is used to provide information that does
255193323Sed/// not need to be run.  This is useful for things like target information and
256193323Sed/// "basic" versions of AnalysisGroups.
257193323Sed///
258193323Sedclass ImmutablePass : public ModulePass {
259193323Sedpublic:
260193323Sed  /// initializePass - This method may be overriden by immutable passes to allow
261193323Sed  /// them to perform various initialization actions they require.  This is
262193323Sed  /// primarily because an ImmutablePass can "require" another ImmutablePass,
263193323Sed  /// and if it does, the overloaded version of initializePass may get access to
264193323Sed  /// these passes with getAnalysis<>.
265193323Sed  ///
266200581Srdivacky  virtual void initializePass();
267193323Sed
268202878Srdivacky  virtual ImmutablePass *getAsImmutablePass() { return this; }
269202878Srdivacky
270193323Sed  /// ImmutablePasses are never run.
271193323Sed  ///
272193323Sed  bool runOnModule(Module &) { return false; }
273193323Sed
274193323Sed  explicit ImmutablePass(intptr_t pid) : ModulePass(pid) {}
275193323Sed  explicit ImmutablePass(const void *pid)
276193323Sed  : ModulePass(pid) {}
277193323Sed
278193323Sed  // Force out-of-line virtual method.
279193323Sed  virtual ~ImmutablePass();
280193323Sed};
281193323Sed
282193323Sed//===----------------------------------------------------------------------===//
283193323Sed/// FunctionPass class - This class is used to implement most global
284193323Sed/// optimizations.  Optimizations should subclass this class if they meet the
285193323Sed/// following constraints:
286193323Sed///
287193323Sed///  1. Optimizations are organized globally, i.e., a function at a time
288193323Sed///  2. Optimizing a function does not cause the addition or removal of any
289193323Sed///     functions in the module
290193323Sed///
291193323Sedclass FunctionPass : public Pass {
292193323Sedpublic:
293202878Srdivacky  explicit FunctionPass(intptr_t pid) : Pass(PT_Function, pid) {}
294202878Srdivacky  explicit FunctionPass(const void *pid) : Pass(PT_Function, pid) {}
295193323Sed
296193323Sed  /// doInitialization - Virtual method overridden by subclasses to do
297193323Sed  /// any necessary per-module initialization.
298193323Sed  ///
299200581Srdivacky  virtual bool doInitialization(Module &);
300198090Srdivacky
301193323Sed  /// runOnFunction - Virtual method overriden by subclasses to do the
302193323Sed  /// per-function processing of the pass.
303193323Sed  ///
304193323Sed  virtual bool runOnFunction(Function &F) = 0;
305193323Sed
306193323Sed  /// doFinalization - Virtual method overriden by subclasses to do any post
307193323Sed  /// processing needed after all passes have run.
308193323Sed  ///
309200581Srdivacky  virtual bool doFinalization(Module &);
310193323Sed
311193323Sed  /// runOnModule - On a module, we run this pass by initializing,
312193323Sed  /// ronOnFunction'ing once for every function in the module, then by
313193323Sed  /// finalizing.
314193323Sed  ///
315193323Sed  virtual bool runOnModule(Module &M);
316193323Sed
317193323Sed  /// run - On a function, we simply initialize, run the function, then
318193323Sed  /// finalize.
319193323Sed  ///
320193323Sed  bool run(Function &F);
321193323Sed
322193323Sed  virtual void assignPassManager(PMStack &PMS,
323193323Sed                                 PassManagerType T = PMT_FunctionPassManager);
324193323Sed
325193323Sed  ///  Return what kind of Pass Manager can manage this pass.
326200581Srdivacky  virtual PassManagerType getPotentialPassManagerType() const;
327193323Sed};
328193323Sed
329193323Sed
330193323Sed
331193323Sed//===----------------------------------------------------------------------===//
332193323Sed/// BasicBlockPass class - This class is used to implement most local
333193323Sed/// optimizations.  Optimizations should subclass this class if they
334193323Sed/// meet the following constraints:
335193323Sed///   1. Optimizations are local, operating on either a basic block or
336193323Sed///      instruction at a time.
337193323Sed///   2. Optimizations do not modify the CFG of the contained function, or any
338193323Sed///      other basic block in the function.
339193323Sed///   3. Optimizations conform to all of the constraints of FunctionPasses.
340193323Sed///
341193323Sedclass BasicBlockPass : public Pass {
342193323Sedpublic:
343202878Srdivacky  explicit BasicBlockPass(intptr_t pid) : Pass(PT_BasicBlock, pid) {}
344202878Srdivacky  explicit BasicBlockPass(const void *pid) : Pass(PT_BasicBlock, pid) {}
345193323Sed
346193323Sed  /// doInitialization - Virtual method overridden by subclasses to do
347193323Sed  /// any necessary per-module initialization.
348193323Sed  ///
349200581Srdivacky  virtual bool doInitialization(Module &);
350193323Sed
351193323Sed  /// doInitialization - Virtual method overridden by BasicBlockPass subclasses
352193323Sed  /// to do any necessary per-function initialization.
353193323Sed  ///
354200581Srdivacky  virtual bool doInitialization(Function &);
355193323Sed
356193323Sed  /// runOnBasicBlock - Virtual method overriden by subclasses to do the
357193323Sed  /// per-basicblock processing of the pass.
358193323Sed  ///
359193323Sed  virtual bool runOnBasicBlock(BasicBlock &BB) = 0;
360193323Sed
361193323Sed  /// doFinalization - Virtual method overriden by BasicBlockPass subclasses to
362193323Sed  /// do any post processing needed after all passes have run.
363193323Sed  ///
364200581Srdivacky  virtual bool doFinalization(Function &);
365193323Sed
366193323Sed  /// doFinalization - Virtual method overriden by subclasses to do any post
367193323Sed  /// processing needed after all passes have run.
368193323Sed  ///
369200581Srdivacky  virtual bool doFinalization(Module &);
370193323Sed
371193323Sed
372193323Sed  // To run this pass on a function, we simply call runOnBasicBlock once for
373193323Sed  // each function.
374193323Sed  //
375193323Sed  bool runOnFunction(Function &F);
376193323Sed
377193323Sed  virtual void assignPassManager(PMStack &PMS,
378193323Sed                                 PassManagerType T = PMT_BasicBlockPassManager);
379193323Sed
380193323Sed  ///  Return what kind of Pass Manager can manage this pass.
381200581Srdivacky  virtual PassManagerType getPotentialPassManagerType() const;
382193323Sed};
383193323Sed
384193323Sed/// If the user specifies the -time-passes argument on an LLVM tool command line
385193323Sed/// then the value of this boolean will be true, otherwise false.
386193323Sed/// @brief This is the storage for the -time-passes option.
387193323Sedextern bool TimePassesIsEnabled;
388193323Sed
389193323Sed} // End llvm namespace
390193323Sed
391193323Sed// Include support files that contain important APIs commonly used by Passes,
392193323Sed// but that we want to separate out to make it easier to read the header files.
393193323Sed//
394193323Sed#include "llvm/PassSupport.h"
395193323Sed#include "llvm/PassAnalysisSupport.h"
396193323Sed
397193323Sed#endif
398