1 //===- InstVisitor.h - Instruction visitor templates ------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
10 #ifndef LLVM_IR_INSTVISITOR_H
11 #define LLVM_IR_INSTVISITOR_H
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"
21 // We operate on opaque instruction classes, so forward declare all instruction
24 #define HANDLE_INST(NUM, OPCODE, CLASS) class CLASS;
25 #include "llvm/IR/Instruction.def"
27 #define DELEGATE(CLASS_TO_VISIT) \
28 return static_cast<SubClass*>(this)-> \
29 visit##CLASS_TO_VISIT(static_cast<CLASS_TO_VISIT&>(I))
32 /// Base class for instruction visitors
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).
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.
43 /// For example, here is a visitor that counts the number of malloc
44 /// instructions processed:
46 /// /// Declare the class. Note that we derive from InstVisitor instantiated
47 /// /// with _our new subclasses_ type.
49 /// struct CountAllocaVisitor : public InstVisitor<CountAllocaVisitor> {
51 /// CountAllocaVisitor() : Count(0) {}
53 /// void visitAllocaInst(AllocaInst &AI) { ++Count; }
56 /// And this class would be used like this:
57 /// CountAllocaVisitor CAV;
58 /// CAV.visit(function);
59 /// NumAllocas = CAV.Count;
61 /// The defined has 'visit' methods for Instruction, and also for BasicBlock,
62 /// Function, and Module, which recursively process all contained instructions.
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.
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!.
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
77 template<typename SubClass, typename RetTy=void>
79 //===--------------------------------------------------------------------===//
80 // Interface code - This is the public interface of the InstVisitor that you
81 // use to visit instructions...
85 // Generic visit method - Allow visitation to all instructions in a range
86 template<class Iterator>
87 void visit(Iterator Start, Iterator End) {
89 static_cast<SubClass*>(this)->visit(*Start++);
92 // Define visitors for functions and basic blocks...
94 void visit(Module &M) {
95 static_cast<SubClass*>(this)->visitModule(M);
96 visit(M.begin(), M.end());
98 void visit(Function &F) {
99 static_cast<SubClass*>(this)->visitFunction(F);
100 visit(F.begin(), F.end());
102 void visit(BasicBlock &BB) {
103 static_cast<SubClass*>(this)->visitBasicBlock(BB);
104 visit(BB.begin(), BB.end());
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); }
113 // visit - Finally, code to visit an instruction...
115 RetTy visit(Instruction &I) {
116 static_assert(std::is_base_of<InstVisitor, SubClass>::value,
117 "Must pass the derived type to this template!");
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"
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.
138 // When visiting a module, function or basic block directly, these methods get
139 // called to indicate when transitioning into a new unit.
141 void visitModule (Module &M) {}
142 void visitFunction (Function &F) {}
143 void visitBasicBlock(BasicBlock &BB) {}
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.
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); \
161 #include "llvm/IR/Instruction.def"
163 // Specific Instruction type classes... note that all of the casts are
164 // necessary because we use the instruction classes as opaque types...
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); }
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); }
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);
229 RetTy visitBranchInst(BranchInst &I) {
230 return static_cast<SubClass *>(this)->visitTerminator(I);
232 RetTy visitSwitchInst(SwitchInst &I) {
233 return static_cast<SubClass *>(this)->visitTerminator(I);
235 RetTy visitIndirectBrInst(IndirectBrInst &I) {
236 return static_cast<SubClass *>(this)->visitTerminator(I);
238 RetTy visitResumeInst(ResumeInst &I) {
239 return static_cast<SubClass *>(this)->visitTerminator(I);
241 RetTy visitUnreachableInst(UnreachableInst &I) {
242 return static_cast<SubClass *>(this)->visitTerminator(I);
244 RetTy visitCleanupReturnInst(CleanupReturnInst &I) {
245 return static_cast<SubClass *>(this)->visitTerminator(I);
247 RetTy visitCatchReturnInst(CatchReturnInst &I) {
248 return static_cast<SubClass *>(this)->visitTerminator(I);
250 RetTy visitCatchSwitchInst(CatchSwitchInst &I) {
251 return static_cast<SubClass *>(this)->visitTerminator(I);
253 RetTy visitTerminator(Instruction &I) { DELEGATE(Instruction);}
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...
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);}
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);
271 DELEGATE(Instruction);
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.
278 // Note that you MUST override this function if your return type is not void.
280 void visitInstruction(Instruction &I) {} // Ignore unhandled instructions
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;
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");
316 } // End llvm namespace