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>(Val: I) || isa<CallBrInst>(Val: 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

source code of llvm/include/llvm/IR/InstVisitor.h