include/llvm/PassSupport.h

   1 //===- llvm/PassSupport.h - Pass Support code -------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by the LLVM research group and is distributed under
   6 // the University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file defines stuff that is used to define and "use" Passes.  This file
  11 // is automatically #included by Pass.h, so:
  12 //
  13 //           NO .CPP FILES SHOULD INCLUDE THIS FILE DIRECTLY
  14 //
  15 // Instead, #include Pass.h.
  16 //
  17 // This file defines Pass registration code and classes used for it.
  18 //
  19 //===----------------------------------------------------------------------===//
  20
  21 #ifndef LLVM_PASS_SUPPORT_H
  22 #define LLVM_PASS_SUPPORT_H
  23
  24 #include "llvm/System/IncludeFile.h"
  25 // No need to include Pass.h, we are being included by it!
  26
  27 namespace llvm {
  28
  29 class TargetMachine;
  30
  31 //===---------------------------------------------------------------------------
  32 /// PassInfo class - An instance of this class exists for every pass known by
  33 /// the system, and can be obtained from a live Pass by calling its
  34 /// getPassInfo() method.  These objects are set up by the RegisterPass<>
  35 /// template, defined below.
  36 ///
  37 class PassInfo {
  38   const char           *PassName;      // Nice name for Pass
  39   const char           *PassArgument;  // Command Line argument to run this pass
  40   const std::type_info &TypeInfo;      // type_info object for this Pass class
  41   unsigned char PassType;              // Set of enums values below...
  42   std::vector<const PassInfo*> ItfImpl;// Interfaces implemented by this pass
  43
  44   Pass *(*NormalCtor)();               // No argument ctor
  45   Pass *(*TargetCtor)(TargetMachine&);   // Ctor taking TargetMachine object...
  46
  47 public:
  48   /// PassType - Define symbolic constants that can be used to test to see if
  49   /// this pass should be listed by analyze or opt.  Passes can use none, one or
  50   /// many of these flags or'd together.  It is not legal to combine the
  51   /// AnalysisGroup flag with others.
  52   ///
  53   enum {
  54     Analysis = 1, Optimization = 2, AnalysisGroup = 4
  55   };
  56
  57   /// PassInfo ctor - Do not call this directly, this should only be invoked
  58   /// through RegisterPass.
  59   PassInfo(const char *name, const char *arg, const std::type_info &ti,
  60            unsigned char pt, Pass *(*normal)() = 0,
  61            Pass *(*targetctor)(TargetMachine &) = 0)
  62     : PassName(name), PassArgument(arg), TypeInfo(ti), PassType(pt),
  63       NormalCtor(normal), TargetCtor(targetctor)  {
  64   }
  65
  66   /// getPassName - Return the friendly name for the pass, never returns null
  67   ///
  68   const char *getPassName() const { return PassName; }
  69   void setPassName(const char *Name) { PassName = Name; }
  70
  71   /// getPassArgument - Return the command line option that may be passed to
  72   /// 'opt' that will cause this pass to be run.  This will return null if there
  73   /// is no argument.
  74   ///
  75   const char *getPassArgument() const { return PassArgument; }
  76
  77   /// getTypeInfo - Return the type_info object for the pass...
  78   ///
  79   const std::type_info &getTypeInfo() const { return TypeInfo; }
  80
  81   /// getPassType - Return the PassType of a pass.  Note that this can be
  82   /// several different types or'd together.  This is _strictly_ for use by opt,
  83   /// analyze and llc for deciding which passes to use as command line options.
  84   ///
  85   unsigned getPassType() const { return PassType; }
  86
  87   /// getNormalCtor - Return a pointer to a function, that when called, creates
  88   /// an instance of the pass and returns it.  This pointer may be null if there
  89   /// is no default constructor for the pass.
  90   ///
  91   Pass *(*getNormalCtor() const)() {
  92     return NormalCtor;
  93   }
  94   void setNormalCtor(Pass *(*Ctor)()) {
  95     NormalCtor = Ctor;
  96   }
  97
  98   /// createPass() - Use this method to create an instance of this pass.
  99   Pass *createPass() const {
 100     assert((PassType != AnalysisGroup || NormalCtor) &&
 101            "No default implementation found for analysis group!");
 102     assert(NormalCtor &&
 103            "Cannot call createPass on PassInfo without default ctor!");
 104     return NormalCtor();
 105   }
 106
 107   /// getTargetCtor - Return a pointer to a function that creates an instance of
 108   /// the pass and returns it.  This returns a constructor for a version of the
 109   /// pass that takes a TargetMachine object as a parameter.
 110   ///
 111   Pass *(*getTargetCtor() const)(TargetMachine &) {
 112     return TargetCtor;
 113   }
 114
 115   /// addInterfaceImplemented - This method is called when this pass is
 116   /// registered as a member of an analysis group with the RegisterAnalysisGroup
 117   /// template.
 118   ///
 119   void addInterfaceImplemented(const PassInfo *ItfPI) {
 120     ItfImpl.push_back(ItfPI);
 121   }
 122
 123   /// getInterfacesImplemented - Return a list of all of the analysis group
 124   /// interfaces implemented by this pass.
 125   ///
 126   const std::vector<const PassInfo*> &getInterfacesImplemented() const {
 127     return ItfImpl;
 128   }
 129 };
 130
 131
 132 //===---------------------------------------------------------------------------
 133 /// RegisterPass<t> template - This template class is used to notify the system
 134 /// that a Pass is available for use, and registers it into the internal
 135 /// database maintained by the PassManager.  Unless this template is used, opt,
 136 /// for example will not be able to see the pass and attempts to create the pass
 137 /// will fail. This template is used in the follow manner (at global scope, in
 138 /// your .cpp file):
 139 ///
 140 /// static RegisterPass<YourPassClassName> tmp("passopt", "My Pass Name");
 141 ///
 142 /// This statement will cause your pass to be created by calling the default
 143 /// constructor exposed by the pass.  If you have a different constructor that
 144 /// must be called, create a global constructor function (which takes the
 145 /// arguments you need and returns a Pass*) and register your pass like this:
 146 ///
 147 /// Pass *createMyPass(foo &opt) { return new MyPass(opt); }
 148 /// static RegisterPass<PassClassName> tmp("passopt", "My Name", createMyPass);
 149 ///
 150 struct RegisterPassBase {
 151   /// getPassInfo - Get the pass info for the registered class...
 152   ///
 153   const PassInfo *getPassInfo() const { return &PIObj; }
 154
 155   RegisterPassBase(const char *Name, const char *Arg, const std::type_info &TI,
 156                    unsigned char PT, Pass *(*Normal)() = 0,
 157                    Pass *(*TargetCtor)(TargetMachine &) = 0)
 158     : PIObj(Name, Arg, TI, PT, Normal, TargetCtor) {
 159     registerPass();
 160   }
 161   RegisterPassBase(const std::type_info &TI, unsigned char PT)
 162     : PIObj("", "", TI, PT, 0, 0) {
 163     // This ctor may only be used for analysis groups: it does not auto-register
 164     // the pass.
 165     assert(PT == PassInfo::AnalysisGroup && "Not an AnalysisGroup!");
 166   }
 167
 168   ~RegisterPassBase() {   // Intentionally non-virtual.
 169     // Analysis groups are registered/unregistered by their dtor.
 170     if (PIObj.getPassType() != PassInfo::AnalysisGroup)
 171       unregisterPass();
 172   }
 173
 174 protected:
 175   PassInfo PIObj;       // The PassInfo object for this pass
 176   void registerPass();
 177   void unregisterPass();
 178
 179   /// setOnlyUsesCFG - Notice that this pass only depends on the CFG, so
 180   /// transformations that do not modify the CFG do not invalidate this pass.
 181   ///
 182   void setOnlyUsesCFG();
 183 };
 184
 185 template<typename PassName>
 186 Pass *callDefaultCtor() { return new PassName(); }
 187
 188 template<typename PassName>
 189 struct RegisterPass : public RegisterPassBase {
 190
 191   // Register Pass using default constructor...
 192   RegisterPass(const char *PassArg, const char *Name, unsigned char PassTy = 0)
 193   : RegisterPassBase(Name, PassArg, typeid(PassName), PassTy,
 194                      callDefaultCtor<PassName>) {}
 195
 196   // Register Pass using default constructor explicitly...
 197   RegisterPass(const char *PassArg, const char *Name, unsigned char PassTy,
 198                Pass *(*ctor)())
 199   : RegisterPassBase(Name, PassArg, typeid(PassName), PassTy, ctor) {}
 200
 201   // Register Pass using TargetMachine constructor...
 202   RegisterPass(const char *PassArg, const char *Name, unsigned char PassTy,
 203                Pass *(*targetctor)(TargetMachine &))
 204   : RegisterPassBase(Name, PassArg, typeid(PassName), PassTy,
 205                      0, targetctor) {}
 206
 207   // Generic constructor version that has an unknown ctor type...
 208   template<typename CtorType>
 209   RegisterPass(const char *PassArg, const char *Name, unsigned char PassTy,
 210                CtorType *Fn)
 211   : RegisterPassBase(Name, PassArg, typeid(PassName), PassTy, 0) {}
 212 };
 213
 214 /// RegisterOpt - Register something that is to show up in Opt, this is just a
 215 /// shortcut for specifying RegisterPass...
 216 ///
 217 template<typename PassName>
 218 struct RegisterOpt : public RegisterPassBase {
 219   RegisterOpt(const char *PassArg, const char *Name, bool CFGOnly = false)
 220   : RegisterPassBase(Name, PassArg, typeid(PassName), PassInfo::Optimization,
 221                      callDefaultCtor<PassName>) {
 222     if (CFGOnly) setOnlyUsesCFG();
 223   }
 224
 225   /// Register Pass using default constructor explicitly...
 226   ///
 227   RegisterOpt(const char *PassArg, const char *Name, Pass *(*ctor)(),
 228               bool CFGOnly = false)
 229   : RegisterPassBase(Name, PassArg, typeid(PassName),
 230                      PassInfo::Optimization, ctor) {
 231     if (CFGOnly) setOnlyUsesCFG();
 232   }
 233
 234   /// Register FunctionPass using default constructor explicitly...
 235   ///
 236   RegisterOpt(const char *PassArg, const char *Name, FunctionPass *(*ctor)(),
 237               bool CFGOnly = false)
 238   : RegisterPassBase(Name, PassArg, typeid(PassName), PassInfo::Optimization,
 239                      static_cast<Pass*(*)()>(ctor)) {
 240     if (CFGOnly) setOnlyUsesCFG();
 241   }
 242
 243   /// Register Pass using TargetMachine constructor...
 244   ///
 245   RegisterOpt(const char *PassArg, const char *Name,
 246                Pass *(*targetctor)(TargetMachine &), bool CFGOnly = false)
 247   : RegisterPassBase(Name, PassArg, typeid(PassName),
 248                      PassInfo::Optimization, 0, targetctor) {
 249     if (CFGOnly) setOnlyUsesCFG();
 250   }
 251
 252   /// Register FunctionPass using TargetMachine constructor...
 253   ///
 254   RegisterOpt(const char *PassArg, const char *Name,
 255               FunctionPass *(*targetctor)(TargetMachine &),
 256               bool CFGOnly = false)
 257   : RegisterPassBase(Name, PassArg, typeid(PassName), PassInfo::Optimization, 0,
 258                      static_cast<Pass*(*)(TargetMachine&)>(targetctor)) {
 259     if (CFGOnly) setOnlyUsesCFG();
 260   }
 261 };
 262
 263 /// RegisterAnalysis - Register something that is to show up in Analysis, this
 264 /// is just a shortcut for specifying RegisterPass...  Analyses take a special
 265 /// argument that, when set to true, tells the system that the analysis ONLY
 266 /// depends on the shape of the CFG, so if a transformation preserves the CFG
 267 /// that the analysis is not invalidated.
 268 ///
 269 template<typename PassName>
 270 struct RegisterAnalysis : public RegisterPassBase {
 271   RegisterAnalysis(const char *PassArg, const char *Name,
 272                    bool CFGOnly = false)
 273   : RegisterPassBase(Name, PassArg, typeid(PassName), PassInfo::Analysis,
 274                      callDefaultCtor<PassName>) {
 275     if (CFGOnly) setOnlyUsesCFG();
 276   }
 277 };
 278
 279
 280 /// RegisterAnalysisGroup - Register a Pass as a member of an analysis _group_.
 281 /// Analysis groups are used to define an interface (which need not derive from
 282 /// Pass) that is required by passes to do their job.  Analysis Groups differ
 283 /// from normal analyses because any available implementation of the group will
 284 /// be used if it is available.
 285 ///
 286 /// If no analysis implementing the interface is available, a default
 287 /// implementation is created and added.  A pass registers itself as the default
 288 /// implementation by specifying 'true' as the third template argument of this
 289 /// class.
 290 ///
 291 /// In addition to registering itself as an analysis group member, a pass must
 292 /// register itself normally as well.  Passes may be members of multiple groups
 293 /// and may still be "required" specifically by name.
 294 ///
 295 /// The actual interface may also be registered as well (by not specifying the
 296 /// second template argument).  The interface should be registered to associate
 297 /// a nice name with the interface.
 298 ///
 299 class RegisterAGBase : public RegisterPassBase {
 300   PassInfo *InterfaceInfo;
 301   const PassInfo *ImplementationInfo;
 302   bool isDefaultImplementation;
 303 protected:
 304   RegisterAGBase(const std::type_info &Interface,
 305                  const std::type_info *Pass = 0,
 306                  bool isDefault = false);
 307   void setGroupName(const char *Name);
 308 public:
 309   ~RegisterAGBase();
 310 };
 311
 312
 313 template<typename Interface, typename DefaultImplementationPass = void,
 314          bool Default = false>
 315 struct RegisterAnalysisGroup : public RegisterAGBase {
 316   RegisterAnalysisGroup() : RegisterAGBase(typeid(Interface),
 317                                            &typeid(DefaultImplementationPass),
 318                                            Default) {
 319   }
 320 };
 321
 322 /// Define a specialization of RegisterAnalysisGroup that is used to set the
 323 /// name for the analysis group.
 324 ///
 325 template<typename Interface>
 326 struct RegisterAnalysisGroup<Interface, void, false> : public RegisterAGBase {
 327   RegisterAnalysisGroup(const char *Name)
 328     : RegisterAGBase(typeid(Interface)) {
 329     setGroupName(Name);
 330   }
 331 };
 332
 333
 334
 335 //===---------------------------------------------------------------------------
 336 /// PassRegistrationListener class - This class is meant to be derived from by
 337 /// clients that are interested in which passes get registered and unregistered
 338 /// at runtime (which can be because of the RegisterPass constructors being run
 339 /// as the program starts up, or may be because a shared object just got
 340 /// loaded).  Deriving from the PassRegistationListener class automatically
 341 /// registers your object to receive callbacks indicating when passes are loaded
 342 /// and removed.
 343 ///
 344 struct PassRegistrationListener {
 345
 346   /// PassRegistrationListener ctor - Add the current object to the list of
 347   /// PassRegistrationListeners...
 348   PassRegistrationListener();
 349
 350   /// dtor - Remove object from list of listeners...
 351   ///
 352   virtual ~PassRegistrationListener();
 353
 354   /// Callback functions - These functions are invoked whenever a pass is loaded
 355   /// or removed from the current executable.
 356   ///
 357   virtual void passRegistered(const PassInfo *P) {}
 358   virtual void passUnregistered(const PassInfo *P) {}
 359
 360   /// enumeratePasses - Iterate over the registered passes, calling the
 361   /// passEnumerate callback on each PassInfo object.
 362   ///
 363   void enumeratePasses();
 364
 365   /// passEnumerate - Callback function invoked when someone calls
 366   /// enumeratePasses on this PassRegistrationListener object.
 367   ///
 368   virtual void passEnumerate(const PassInfo *P) {}
 369 };
 370
 371
 372 } // End llvm namespace
 373
 374 #endif