include/llvm/IR/InstVisitor.h

   1 //===- InstVisitor.h - Instruction visitor templates ------------*- 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
  10 #ifndef LLVM_IR_INSTVISITOR_H
  11 #define LLVM_IR_INSTVISITOR_H
  12
  13 #include "llvm/IR/CallSite.h"
  14 #include "llvm/IR/Function.h"
  15 #include "llvm/IR/Instructions.h"
  16 #include "llvm/IR/IntrinsicInst.h"
  17 #include "llvm/IR/Intrinsics.h"
  18 #include "llvm/IR/Module.h"
  19 #include "llvm/Support/ErrorHandling.h"
  20
  21 namespace llvm {
  22
  23 // We operate on opaque instruction classes, so forward declare all instruction
  24 // types now...
  25 //
  26 #define HANDLE_INST(NUM, OPCODE, CLASS)   class CLASS;
  27 #include "llvm/IR/Instruction.def"
  28
  29 #define DELEGATE(CLASS_TO_VISIT) \
  30   return static_cast<SubClass*>(this)-> \
  31                visit##CLASS_TO_VISIT(static_cast<CLASS_TO_VISIT&>(I))
  32
  33
  34 /// Base class for instruction visitors
  35 ///
  36 /// Instruction visitors are used when you want to perform different actions
  37 /// for different kinds of instructions without having to use lots of casts
  38 /// and a big switch statement (in your code, that is).
  39 ///
  40 /// To define your own visitor, inherit from this class, specifying your
  41 /// new type for the 'SubClass' template parameter, and "override" visitXXX
  42 /// functions in your class. I say "override" because this class is defined
  43 /// in terms of statically resolved overloading, not virtual functions.
  44 ///
  45 /// For example, here is a visitor that counts the number of malloc
  46 /// instructions processed:
  47 ///
  48 ///  /// Declare the class.  Note that we derive from InstVisitor instantiated
  49 ///  /// with _our new subclasses_ type.
  50 ///  ///
  51 ///  struct CountAllocaVisitor : public InstVisitor<CountAllocaVisitor> {
  52 ///    unsigned Count;
  53 ///    CountAllocaVisitor() : Count(0) {}
  54 ///
  55 ///    void visitAllocaInst(AllocaInst &AI) { ++Count; }
  56 ///  };
  57 ///
  58 ///  And this class would be used like this:
  59 ///    CountAllocaVisitor CAV;
  60 ///    CAV.visit(function);
  61 ///    NumAllocas = CAV.Count;
  62 ///
  63 /// The defined has 'visit' methods for Instruction, and also for BasicBlock,
  64 /// Function, and Module, which recursively process all contained instructions.
  65 ///
  66 /// Note that if you don't implement visitXXX for some instruction type,
  67 /// the visitXXX method for instruction superclass will be invoked. So
  68 /// if instructions are added in the future, they will be automatically
  69 /// supported, if you handle one of their superclasses.
  70 ///
  71 /// The optional second template argument specifies the type that instruction
  72 /// visitation functions should return. If you specify this, you *MUST* provide
  73 /// an implementation of visitInstruction though!.
  74 ///
  75 /// Note that this class is specifically designed as a template to avoid
  76 /// virtual function call overhead.  Defining and using an InstVisitor is just
  77 /// as efficient as having your own switch statement over the instruction
  78 /// opcode.
  79 template<typename SubClass, typename RetTy=void>
  80 class InstVisitor {
  81   //===--------------------------------------------------------------------===//
  82   // Interface code - This is the public interface of the InstVisitor that you
  83   // use to visit instructions...
  84   //
  85
  86 public:
  87   // Generic visit method - Allow visitation to all instructions in a range
  88   template<class Iterator>
  89   void visit(Iterator Start, Iterator End) {
  90     while (Start != End)
  91       static_cast<SubClass*>(this)->visit(*Start++);
  92   }
  93
  94   // Define visitors for functions and basic blocks...
  95   //
  96   void visit(Module &M) {
  97     static_cast<SubClass*>(this)->visitModule(M);
  98     visit(M.begin(), M.end());
  99   }
 100   void visit(Function &F) {
 101     static_cast<SubClass*>(this)->visitFunction(F);
 102     visit(F.begin(), F.end());
 103   }
 104   void visit(BasicBlock &BB) {
 105     static_cast<SubClass*>(this)->visitBasicBlock(BB);
 106     visit(BB.begin(), BB.end());
 107   }
 108
 109   // Forwarding functions so that the user can visit with pointers AND refs.
 110   void visit(Module       *M)  { visit(*M); }
 111   void visit(Function     *F)  { visit(*F); }
 112   void visit(BasicBlock   *BB) { visit(*BB); }
 113   RetTy visit(Instruction *I)  { return visit(*I); }
 114
 115   // visit - Finally, code to visit an instruction...
 116   //
 117   RetTy visit(Instruction &I) {
 118     static_assert(std::is_base_of<InstVisitor, SubClass>::value,
 119                   "Must pass the derived type to this template!");
 120
 121     switch (I.getOpcode()) {
 122     default: llvm_unreachable("Unknown instruction type encountered!");
 123       // Build the switch statement using the Instruction.def file...
 124 #define HANDLE_INST(NUM, OPCODE, CLASS) \
 125     case Instruction::OPCODE: return \
 126            static_cast<SubClass*>(this)-> \
 127                       visit##OPCODE(static_cast<CLASS&>(I));
 128 #include "llvm/IR/Instruction.def"
 129     }
 130   }
 131
 132   //===--------------------------------------------------------------------===//
 133   // Visitation functions... these functions provide default fallbacks in case
 134   // the user does not specify what to do for a particular instruction type.
 135   // The default behavior is to generalize the instruction type to its subtype
 136   // and try visiting the subtype.  All of this should be inlined perfectly,
 137   // because there are no virtual functions to get in the way.
 138   //
 139
 140   // When visiting a module, function or basic block directly, these methods get
 141   // called to indicate when transitioning into a new unit.
 142   //
 143   void visitModule    (Module &M) {}
 144   void visitFunction  (Function &F) {}
 145   void visitBasicBlock(BasicBlock &BB) {}
 146
 147   // Define instruction specific visitor functions that can be overridden to
 148   // handle SPECIFIC instructions.  These functions automatically define
 149   // visitMul to proxy to visitBinaryOperator for instance in case the user does
 150   // not need this generality.
 151   //
 152   // These functions can also implement fan-out, when a single opcode and
 153   // instruction have multiple more specific Instruction subclasses. The Call
 154   // instruction currently supports this. We implement that by redirecting that
 155   // instruction to a special delegation helper.
 156 #define HANDLE_INST(NUM, OPCODE, CLASS) \
 157     RetTy visit##OPCODE(CLASS &I) { \
 158       if (NUM == Instruction::Call) \
 159         return delegateCallInst(I); \
 160       else \
 161         DELEGATE(CLASS); \
 162     }
 163 #include "llvm/IR/Instruction.def"
 164
 165   // Specific Instruction type classes... note that all of the casts are
 166   // necessary because we use the instruction classes as opaque types...
 167   //
 168   RetTy visitICmpInst(ICmpInst &I)                { DELEGATE(CmpInst);}
 169   RetTy visitFCmpInst(FCmpInst &I)                { DELEGATE(CmpInst);}
 170   RetTy visitAllocaInst(AllocaInst &I)            { DELEGATE(UnaryInstruction);}
 171   RetTy visitLoadInst(LoadInst     &I)            { DELEGATE(UnaryInstruction);}
 172   RetTy visitStoreInst(StoreInst   &I)            { DELEGATE(Instruction);}
 173   RetTy visitAtomicCmpXchgInst(AtomicCmpXchgInst &I) { DELEGATE(Instruction);}
 174   RetTy visitAtomicRMWInst(AtomicRMWInst &I)      { DELEGATE(Instruction);}
 175   RetTy visitFenceInst(FenceInst   &I)            { DELEGATE(Instruction);}
 176   RetTy visitGetElementPtrInst(GetElementPtrInst &I){ DELEGATE(Instruction);}
 177   RetTy visitPHINode(PHINode       &I)            { DELEGATE(Instruction);}
 178   RetTy visitTruncInst(TruncInst &I)              { DELEGATE(CastInst);}
 179   RetTy visitZExtInst(ZExtInst &I)                { DELEGATE(CastInst);}
 180   RetTy visitSExtInst(SExtInst &I)                { DELEGATE(CastInst);}
 181   RetTy visitFPTruncInst(FPTruncInst &I)          { DELEGATE(CastInst);}
 182   RetTy visitFPExtInst(FPExtInst &I)              { DELEGATE(CastInst);}
 183   RetTy visitFPToUIInst(FPToUIInst &I)            { DELEGATE(CastInst);}
 184   RetTy visitFPToSIInst(FPToSIInst &I)            { DELEGATE(CastInst);}
 185   RetTy visitUIToFPInst(UIToFPInst &I)            { DELEGATE(CastInst);}
 186   RetTy visitSIToFPInst(SIToFPInst &I)            { DELEGATE(CastInst);}
 187   RetTy visitPtrToIntInst(PtrToIntInst &I)        { DELEGATE(CastInst);}
 188   RetTy visitIntToPtrInst(IntToPtrInst &I)        { DELEGATE(CastInst);}
 189   RetTy visitBitCastInst(BitCastInst &I)          { DELEGATE(CastInst);}
 190   RetTy visitAddrSpaceCastInst(AddrSpaceCastInst &I) { DELEGATE(CastInst);}
 191   RetTy visitSelectInst(SelectInst &I)            { DELEGATE(Instruction);}
 192   RetTy visitVAArgInst(VAArgInst   &I)            { DELEGATE(UnaryInstruction);}
 193   RetTy visitExtractElementInst(ExtractElementInst &I) { DELEGATE(Instruction);}
 194   RetTy visitInsertElementInst(InsertElementInst &I) { DELEGATE(Instruction);}
 195   RetTy visitShuffleVectorInst(ShuffleVectorInst &I) { DELEGATE(Instruction);}
 196   RetTy visitExtractValueInst(ExtractValueInst &I){ DELEGATE(UnaryInstruction);}
 197   RetTy visitInsertValueInst(InsertValueInst &I)  { DELEGATE(Instruction); }
 198   RetTy visitLandingPadInst(LandingPadInst &I)    { DELEGATE(Instruction); }
 199   RetTy visitFuncletPadInst(FuncletPadInst &I) { DELEGATE(Instruction); }
 200   RetTy visitCleanupPadInst(CleanupPadInst &I) { DELEGATE(FuncletPadInst); }
 201   RetTy visitCatchPadInst(CatchPadInst &I)     { DELEGATE(FuncletPadInst); }
 202
 203   // Handle the special instrinsic instruction classes.
 204   RetTy visitDbgDeclareInst(DbgDeclareInst &I)    { DELEGATE(DbgVariableIntrinsic);}
 205   RetTy visitDbgValueInst(DbgValueInst &I)        { DELEGATE(DbgVariableIntrinsic);}
 206   RetTy visitDbgVariableIntrinsic(DbgVariableIntrinsic &I)
 207                                                   { DELEGATE(DbgInfoIntrinsic);}
 208   RetTy visitDbgLabelInst(DbgLabelInst &I)        { DELEGATE(DbgInfoIntrinsic);}
 209   RetTy visitDbgInfoIntrinsic(DbgInfoIntrinsic &I){ DELEGATE(IntrinsicInst); }
 210   RetTy visitMemSetInst(MemSetInst &I)            { DELEGATE(MemIntrinsic); }
 211   RetTy visitMemCpyInst(MemCpyInst &I)            { DELEGATE(MemTransferInst); }
 212   RetTy visitMemMoveInst(MemMoveInst &I)          { DELEGATE(MemTransferInst); }
 213   RetTy visitMemTransferInst(MemTransferInst &I)  { DELEGATE(MemIntrinsic); }
 214   RetTy visitMemIntrinsic(MemIntrinsic &I)        { DELEGATE(IntrinsicInst); }
 215   RetTy visitVAStartInst(VAStartInst &I)          { DELEGATE(IntrinsicInst); }
 216   RetTy visitVAEndInst(VAEndInst &I)              { DELEGATE(IntrinsicInst); }
 217   RetTy visitVACopyInst(VACopyInst &I)            { DELEGATE(IntrinsicInst); }
 218   RetTy visitIntrinsicInst(IntrinsicInst &I)      { DELEGATE(CallInst); }
 219
 220   // Call, Invoke and CallBr are slightly different as they delegate first
 221   // through a generic CallSite visitor.
 222   RetTy visitCallInst(CallInst &I) {
 223     return static_cast<SubClass*>(this)->visitCallSite(&I);
 224   }
 225   RetTy visitInvokeInst(InvokeInst &I) {
 226     return static_cast<SubClass*>(this)->visitCallSite(&I);
 227   }
 228   RetTy visitCallBrInst(CallBrInst &I) {
 229     return static_cast<SubClass *>(this)->visitCallSite(&I);
 230   }
 231
 232   // While terminators don't have a distinct type modeling them, we support
 233   // intercepting them with dedicated a visitor callback.
 234   RetTy visitReturnInst(ReturnInst &I) {
 235     return static_cast<SubClass *>(this)->visitTerminator(I);
 236   }
 237   RetTy visitBranchInst(BranchInst &I) {
 238     return static_cast<SubClass *>(this)->visitTerminator(I);
 239   }
 240   RetTy visitSwitchInst(SwitchInst &I) {
 241     return static_cast<SubClass *>(this)->visitTerminator(I);
 242   }
 243   RetTy visitIndirectBrInst(IndirectBrInst &I) {
 244     return static_cast<SubClass *>(this)->visitTerminator(I);
 245   }
 246   RetTy visitResumeInst(ResumeInst &I) {
 247     return static_cast<SubClass *>(this)->visitTerminator(I);
 248   }
 249   RetTy visitUnreachableInst(UnreachableInst &I) {
 250     return static_cast<SubClass *>(this)->visitTerminator(I);
 251   }
 252   RetTy visitCleanupReturnInst(CleanupReturnInst &I) {
 253     return static_cast<SubClass *>(this)->visitTerminator(I);
 254   }
 255   RetTy visitCatchReturnInst(CatchReturnInst &I) {
 256     return static_cast<SubClass *>(this)->visitTerminator(I);
 257   }
 258   RetTy visitCatchSwitchInst(CatchSwitchInst &I) {
 259     return static_cast<SubClass *>(this)->visitTerminator(I);
 260   }
 261   RetTy visitTerminator(Instruction &I)    { DELEGATE(Instruction);}
 262
 263   // Next level propagators: If the user does not overload a specific
 264   // instruction type, they can overload one of these to get the whole class
 265   // of instructions...
 266   //
 267   RetTy visitCastInst(CastInst &I)                { DELEGATE(UnaryInstruction);}
 268   RetTy visitUnaryOperator(UnaryOperator &I)      { DELEGATE(UnaryInstruction);}
 269   RetTy visitBinaryOperator(BinaryOperator &I)    { DELEGATE(Instruction);}
 270   RetTy visitCmpInst(CmpInst &I)                  { DELEGATE(Instruction);}
 271   RetTy visitUnaryInstruction(UnaryInstruction &I){ DELEGATE(Instruction);}
 272
 273   // The next level delegation for `CallBase` is slightly more complex in order
 274   // to support visiting cases where the call is also a terminator.
 275   RetTy visitCallBase(CallBase &I) {
 276     if (isa<InvokeInst>(I) || isa<CallBrInst>(I))
 277       return static_cast<SubClass *>(this)->visitTerminator(I);
 278
 279     DELEGATE(Instruction);
 280   }
 281
 282   // Provide a legacy visitor for a 'callsite' that visits calls, invokes,
 283   // and calbrs.
 284   //
 285   // Prefer overriding the type system based `CallBase` instead.
 286   RetTy visitCallSite(CallSite CS) {
 287     assert(CS);
 288     Instruction &I = *CS.getInstruction();
 289     DELEGATE(CallBase);
 290   }
 291
 292   // If the user wants a 'default' case, they can choose to override this
 293   // function.  If this function is not overloaded in the user's subclass, then
 294   // this instruction just gets ignored.
 295   //
 296   // Note that you MUST override this function if your return type is not void.
 297   //
 298   void visitInstruction(Instruction &I) {}  // Ignore unhandled instructions
 299
 300 private:
 301   // Special helper function to delegate to CallInst subclass visitors.
 302   RetTy delegateCallInst(CallInst &I) {
 303     if (const Function *F = I.getCalledFunction()) {
 304       switch (F->getIntrinsicID()) {
 305       default:                     DELEGATE(IntrinsicInst);
 306       case Intrinsic::dbg_declare: DELEGATE(DbgDeclareInst);
 307       case Intrinsic::dbg_value:   DELEGATE(DbgValueInst);
 308       case Intrinsic::dbg_label:   DELEGATE(DbgLabelInst);
 309       case Intrinsic::memcpy:      DELEGATE(MemCpyInst);
 310       case Intrinsic::memmove:     DELEGATE(MemMoveInst);
 311       case Intrinsic::memset:      DELEGATE(MemSetInst);
 312       case Intrinsic::vastart:     DELEGATE(VAStartInst);
 313       case Intrinsic::vaend:       DELEGATE(VAEndInst);
 314       case Intrinsic::vacopy:      DELEGATE(VACopyInst);
 315       case Intrinsic::not_intrinsic: break;
 316       }
 317     }
 318     DELEGATE(CallInst);
 319   }
 320
 321   // An overload that will never actually be called, it is used only from dead
 322   // code in the dispatching from opcodes to instruction subclasses.
 323   RetTy delegateCallInst(Instruction &I) {
 324     llvm_unreachable("delegateCallInst called for non-CallInst");
 325   }
 326 };
 327
 328 #undef DELEGATE
 329
 330 } // End llvm namespace
 331
 332 #endif