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