LLVM API Documentation

PassSupport.h

Go to the documentation of this file.
00001 //===- llvm/PassSupport.h - Pass Support code -------------------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file was developed by the LLVM research group and is distributed under
00006 // the University of Illinois Open Source License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file defines stuff that is used to define and "use" Passes.  This file
00011 // is automatically #included by Pass.h, so:
00012 //
00013 //           NO .CPP FILES SHOULD INCLUDE THIS FILE DIRECTLY
00014 //
00015 // Instead, #include Pass.h.
00016 //
00017 // This file defines Pass registration code and classes used for it.
00018 //
00019 //===----------------------------------------------------------------------===//
00020 
00021 #ifndef LLVM_PASS_SUPPORT_H
00022 #define LLVM_PASS_SUPPORT_H
00023 
00024 // No need to include Pass.h, we are being included by it!
00025 
00026 namespace llvm {
00027 
00028 class TargetMachine;
00029 
00030 //===---------------------------------------------------------------------------
00031 /// PassInfo class - An instance of this class exists for every pass known by
00032 /// the system, and can be obtained from a live Pass by calling its
00033 /// getPassInfo() method.  These objects are set up by the RegisterPass<>
00034 /// template, defined below.
00035 ///
00036 class PassInfo {
00037   const char           *PassName;      // Nice name for Pass
00038   const char           *PassArgument;  // Command Line argument to run this pass
00039   const std::type_info &TypeInfo;      // type_info object for this Pass class
00040   unsigned char PassType;              // Set of enums values below...
00041   std::vector<const PassInfo*> ItfImpl;// Interfaces implemented by this pass
00042 
00043   Pass *(*NormalCtor)();               // No argument ctor
00044   Pass *(*TargetCtor)(TargetMachine&);   // Ctor taking TargetMachine object...
00045 
00046 public:
00047   /// PassType - Define symbolic constants that can be used to test to see if
00048   /// this pass should be listed by analyze or opt.  Passes can use none, one or
00049   /// many of these flags or'd together.  It is not legal to combine the
00050   /// AnalysisGroup flag with others.
00051   ///
00052   enum {
00053     Analysis = 1, Optimization = 2, AnalysisGroup = 4
00054   };
00055 
00056   /// PassInfo ctor - Do not call this directly, this should only be invoked
00057   /// through RegisterPass.
00058   PassInfo(const char *name, const char *arg, const std::type_info &ti,
00059            unsigned char pt, Pass *(*normal)() = 0,
00060            Pass *(*targetctor)(TargetMachine &) = 0)
00061     : PassName(name), PassArgument(arg), TypeInfo(ti), PassType(pt),
00062       NormalCtor(normal), TargetCtor(targetctor)  {
00063   }
00064 
00065   /// getPassName - Return the friendly name for the pass, never returns null
00066   ///
00067   const char *getPassName() const { return PassName; }
00068   void setPassName(const char *Name) { PassName = Name; }
00069 
00070   /// getPassArgument - Return the command line option that may be passed to
00071   /// 'opt' that will cause this pass to be run.  This will return null if there
00072   /// is no argument.
00073   ///
00074   const char *getPassArgument() const { return PassArgument; }
00075 
00076   /// getTypeInfo - Return the type_info object for the pass...
00077   ///
00078   const std::type_info &getTypeInfo() const { return TypeInfo; }
00079 
00080   /// getPassType - Return the PassType of a pass.  Note that this can be
00081   /// several different types or'd together.  This is _strictly_ for use by opt,
00082   /// analyze and llc for deciding which passes to use as command line options.
00083   ///
00084   unsigned getPassType() const { return PassType; }
00085 
00086   /// getNormalCtor - Return a pointer to a function, that when called, creates
00087   /// an instance of the pass and returns it.  This pointer may be null if there
00088   /// is no default constructor for the pass.
00089   ///
00090   Pass *(*getNormalCtor() const)() {
00091     return NormalCtor;
00092   }
00093   void setNormalCtor(Pass *(*Ctor)()) {
00094     NormalCtor = Ctor;
00095   }
00096 
00097   /// createPass() - Use this method to create an instance of this pass.
00098   Pass *createPass() const {
00099     assert((PassType != AnalysisGroup || NormalCtor) &&
00100            "No default implementation found for analysis group!");
00101     assert(NormalCtor &&
00102            "Cannot call createPass on PassInfo without default ctor!");
00103     return NormalCtor();
00104   }
00105 
00106   /// getTargetCtor - Return a pointer to a function that creates an instance of
00107   /// the pass and returns it.  This returns a constructor for a version of the
00108   /// pass that takes a TargetMachine object as a parameter.
00109   ///
00110   Pass *(*getTargetCtor() const)(TargetMachine &) {
00111     return TargetCtor;
00112   }
00113 
00114   /// addInterfaceImplemented - This method is called when this pass is
00115   /// registered as a member of an analysis group with the RegisterAnalysisGroup
00116   /// template.
00117   ///
00118   void addInterfaceImplemented(const PassInfo *ItfPI) {
00119     ItfImpl.push_back(ItfPI);
00120   }
00121 
00122   /// getInterfacesImplemented - Return a list of all of the analysis group
00123   /// interfaces implemented by this pass.
00124   ///
00125   const std::vector<const PassInfo*> &getInterfacesImplemented() const {
00126     return ItfImpl;
00127   }
00128 };
00129 
00130 
00131 //===---------------------------------------------------------------------------
00132 /// RegisterPass<t> template - This template class is used to notify the system
00133 /// that a Pass is available for use, and registers it into the internal
00134 /// database maintained by the PassManager.  Unless this template is used, opt,
00135 /// for example will not be able to see the pass and attempts to create the pass
00136 /// will fail. This template is used in the follow manner (at global scope, in
00137 /// your .cpp file):
00138 ///
00139 /// static RegisterPass<YourPassClassName> tmp("passopt", "My Pass Name");
00140 ///
00141 /// This statement will cause your pass to be created by calling the default
00142 /// constructor exposed by the pass.  If you have a different constructor that
00143 /// must be called, create a global constructor function (which takes the
00144 /// arguments you need and returns a Pass*) and register your pass like this:
00145 ///
00146 /// Pass *createMyPass(foo &opt) { return new MyPass(opt); }
00147 /// static RegisterPass<PassClassName> tmp("passopt", "My Name", createMyPass);
00148 ///
00149 struct RegisterPassBase {
00150   /// getPassInfo - Get the pass info for the registered class...
00151   ///
00152   const PassInfo *getPassInfo() const { return &PIObj; }
00153 
00154   RegisterPassBase(const char *Name, const char *Arg, const std::type_info &TI,
00155                    unsigned char PT, Pass *(*Normal)() = 0,
00156                    Pass *(*TargetCtor)(TargetMachine &) = 0)
00157     : PIObj(Name, Arg, TI, PT, Normal, TargetCtor) {
00158     registerPass();
00159   }
00160   RegisterPassBase(const std::type_info &TI, unsigned char PT)
00161     : PIObj("", "", TI, PT, 0, 0) {
00162     // This ctor may only be used for analysis groups: it does not auto-register
00163     // the pass.
00164     assert(PT == PassInfo::AnalysisGroup && "Not an AnalysisGroup!");
00165   }
00166   
00167   ~RegisterPassBase() {   // Intentionally non-virtual.
00168     // Analysis groups are registered/unregistered by their dtor.
00169     if (PIObj.getPassType() != PassInfo::AnalysisGroup)
00170       unregisterPass();
00171   }
00172 
00173 protected:
00174   PassInfo PIObj;       // The PassInfo object for this pass
00175   void registerPass();
00176   void unregisterPass();
00177 
00178   /// setOnlyUsesCFG - Notice that this pass only depends on the CFG, so
00179   /// transformations that do not modify the CFG do not invalidate this pass.
00180   ///
00181   void setOnlyUsesCFG();
00182 };
00183 
00184 template<typename PassName>
00185 Pass *callDefaultCtor() { return new PassName(); }
00186 
00187 template<typename PassName>
00188 struct RegisterPass : public RegisterPassBase {
00189 
00190   // Register Pass using default constructor...
00191   RegisterPass(const char *PassArg, const char *Name, unsigned char PassTy = 0)
00192   : RegisterPassBase(Name, PassArg, typeid(PassName), PassTy,
00193                      callDefaultCtor<PassName>) {}
00194 
00195   // Register Pass using default constructor explicitly...
00196   RegisterPass(const char *PassArg, const char *Name, unsigned char PassTy,
00197                Pass *(*ctor)()) 
00198   : RegisterPassBase(Name, PassArg, typeid(PassName), PassTy, ctor) {}
00199 
00200   // Register Pass using TargetMachine constructor...
00201   RegisterPass(const char *PassArg, const char *Name, unsigned char PassTy,
00202                Pass *(*targetctor)(TargetMachine &))
00203   : RegisterPassBase(Name, PassArg, typeid(PassName), PassTy,
00204                      0, targetctor) {}
00205 
00206   // Generic constructor version that has an unknown ctor type...
00207   template<typename CtorType>
00208   RegisterPass(const char *PassArg, const char *Name, unsigned char PassTy,
00209                CtorType *Fn)
00210   : RegisterPassBase(Name, PassArg, typeid(PassName), PassTy, 0) {}
00211 };
00212 
00213 /// RegisterOpt - Register something that is to show up in Opt, this is just a
00214 /// shortcut for specifying RegisterPass...
00215 ///
00216 template<typename PassName>
00217 struct RegisterOpt : public RegisterPassBase {
00218   RegisterOpt(const char *PassArg, const char *Name, bool CFGOnly = false)
00219   : RegisterPassBase(Name, PassArg, typeid(PassName), PassInfo::Optimization,
00220                      callDefaultCtor<PassName>) {
00221     if (CFGOnly) setOnlyUsesCFG();
00222   }
00223 
00224   /// Register Pass using default constructor explicitly...
00225   ///
00226   RegisterOpt(const char *PassArg, const char *Name, Pass *(*ctor)(),
00227               bool CFGOnly = false) 
00228   : RegisterPassBase(Name, PassArg, typeid(PassName),
00229                      PassInfo::Optimization, ctor) {
00230     if (CFGOnly) setOnlyUsesCFG();
00231   }
00232 
00233   /// Register FunctionPass using default constructor explicitly...
00234   ///
00235   RegisterOpt(const char *PassArg, const char *Name, FunctionPass *(*ctor)(),
00236               bool CFGOnly = false)
00237   : RegisterPassBase(Name, PassArg, typeid(PassName), PassInfo::Optimization,
00238                      static_cast<Pass*(*)()>(ctor)) {
00239     if (CFGOnly) setOnlyUsesCFG();
00240   }
00241 
00242   /// Register Pass using TargetMachine constructor...
00243   ///
00244   RegisterOpt(const char *PassArg, const char *Name,
00245                Pass *(*targetctor)(TargetMachine &), bool CFGOnly = false)
00246   : RegisterPassBase(Name, PassArg, typeid(PassName),
00247                      PassInfo::Optimization, 0, targetctor) {
00248     if (CFGOnly) setOnlyUsesCFG();
00249   }
00250 
00251   /// Register FunctionPass using TargetMachine constructor...
00252   ///
00253   RegisterOpt(const char *PassArg, const char *Name,
00254               FunctionPass *(*targetctor)(TargetMachine &),
00255               bool CFGOnly = false)
00256   : RegisterPassBase(Name, PassArg, typeid(PassName), PassInfo::Optimization, 0,
00257                      static_cast<Pass*(*)(TargetMachine&)>(targetctor)) {
00258     if (CFGOnly) setOnlyUsesCFG();
00259   }
00260 };
00261 
00262 /// RegisterAnalysis - Register something that is to show up in Analysis, this
00263 /// is just a shortcut for specifying RegisterPass...  Analyses take a special
00264 /// argument that, when set to true, tells the system that the analysis ONLY
00265 /// depends on the shape of the CFG, so if a transformation preserves the CFG
00266 /// that the analysis is not invalidated.
00267 ///
00268 template<typename PassName>
00269 struct RegisterAnalysis : public RegisterPassBase {
00270   RegisterAnalysis(const char *PassArg, const char *Name,
00271                    bool CFGOnly = false)
00272   : RegisterPassBase(Name, PassArg, typeid(PassName), PassInfo::Analysis,
00273                      callDefaultCtor<PassName>) {
00274     if (CFGOnly) setOnlyUsesCFG();
00275   }
00276 };
00277 
00278 
00279 /// RegisterAnalysisGroup - Register a Pass as a member of an analysis _group_.
00280 /// Analysis groups are used to define an interface (which need not derive from
00281 /// Pass) that is required by passes to do their job.  Analysis Groups differ
00282 /// from normal analyses because any available implementation of the group will
00283 /// be used if it is available.
00284 ///
00285 /// If no analysis implementing the interface is available, a default
00286 /// implementation is created and added.  A pass registers itself as the default
00287 /// implementation by specifying 'true' as the third template argument of this
00288 /// class.
00289 ///
00290 /// In addition to registering itself as an analysis group member, a pass must
00291 /// register itself normally as well.  Passes may be members of multiple groups
00292 /// and may still be "required" specifically by name.
00293 ///
00294 /// The actual interface may also be registered as well (by not specifying the
00295 /// second template argument).  The interface should be registered to associate
00296 /// a nice name with the interface.
00297 ///
00298 class RegisterAGBase : public RegisterPassBase {
00299   PassInfo *InterfaceInfo;
00300   const PassInfo *ImplementationInfo;
00301   bool isDefaultImplementation;
00302 protected:
00303   RegisterAGBase(const std::type_info &Interface,
00304                  const std::type_info *Pass = 0,
00305                  bool isDefault = false);
00306   void setGroupName(const char *Name);
00307 public:
00308   ~RegisterAGBase();
00309 };
00310 
00311 
00312 template<typename Interface, typename DefaultImplementationPass = void,
00313          bool Default = false>
00314 struct RegisterAnalysisGroup : public RegisterAGBase {
00315   RegisterAnalysisGroup() : RegisterAGBase(typeid(Interface),
00316                                            &typeid(DefaultImplementationPass),
00317                                            Default) {
00318   }
00319 };
00320 
00321 /// Define a specialization of RegisterAnalysisGroup that is used to set the
00322 /// name for the analysis group.
00323 ///
00324 template<typename Interface>
00325 struct RegisterAnalysisGroup<Interface, void, false> : public RegisterAGBase {
00326   RegisterAnalysisGroup(const char *Name)
00327     : RegisterAGBase(typeid(Interface)) {
00328     setGroupName(Name);
00329   }
00330 };
00331 
00332 
00333 
00334 //===---------------------------------------------------------------------------
00335 /// PassRegistrationListener class - This class is meant to be derived from by
00336 /// clients that are interested in which passes get registered and unregistered
00337 /// at runtime (which can be because of the RegisterPass constructors being run
00338 /// as the program starts up, or may be because a shared object just got
00339 /// loaded).  Deriving from the PassRegistationListener class automatically
00340 /// registers your object to receive callbacks indicating when passes are loaded
00341 /// and removed.
00342 ///
00343 struct PassRegistrationListener {
00344 
00345   /// PassRegistrationListener ctor - Add the current object to the list of
00346   /// PassRegistrationListeners...
00347   PassRegistrationListener();
00348 
00349   /// dtor - Remove object from list of listeners...
00350   ///
00351   virtual ~PassRegistrationListener();
00352 
00353   /// Callback functions - These functions are invoked whenever a pass is loaded
00354   /// or removed from the current executable.
00355   ///
00356   virtual void passRegistered(const PassInfo *P) {}
00357   virtual void passUnregistered(const PassInfo *P) {}
00358 
00359   /// enumeratePasses - Iterate over the registered passes, calling the
00360   /// passEnumerate callback on each PassInfo object.
00361   ///
00362   void enumeratePasses();
00363 
00364   /// passEnumerate - Callback function invoked when someone calls
00365   /// enumeratePasses on this PassRegistrationListener object.
00366   ///
00367   virtual void passEnumerate(const PassInfo *P) {}
00368 };
00369 
00370 
00371 //===---------------------------------------------------------------------------
00372 /// IncludeFile class - This class is used as a hack to make sure that the
00373 /// implementation of a header file is included into a tool that uses the
00374 /// header.  This is solely to overcome problems linking .a files and not
00375 /// getting the implementation of passes we need.
00376 ///
00377 struct IncludeFile {
00378   IncludeFile(void *);
00379 };
00380 
00381 } // End llvm namespace
00382 
00383 #endif