1//===- llvm/IR/PassInstrumentation.h ----------------------*- 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/// \file
9///
10/// This file defines the Pass Instrumentation classes that provide
11/// instrumentation points into the pass execution by PassManager.
12///
13/// There are two main classes:
14/// - PassInstrumentation provides a set of instrumentation points for
15/// pass managers to call on.
16///
17/// - PassInstrumentationCallbacks registers callbacks and provides access
18/// to them for PassInstrumentation.
19///
20/// PassInstrumentation object is being used as a result of
21/// PassInstrumentationAnalysis (so it is intended to be easily copyable).
22///
23/// Intended scheme of use for Pass Instrumentation is as follows:
24/// - register instrumentation callbacks in PassInstrumentationCallbacks
25/// instance. PassBuilder provides helper for that.
26///
27/// - register PassInstrumentationAnalysis with all the PassManagers.
28/// PassBuilder handles that automatically when registering analyses.
29///
30/// - Pass Manager requests PassInstrumentationAnalysis from analysis manager
31/// and gets PassInstrumentation as its result.
32///
33/// - Pass Manager invokes PassInstrumentation entry points appropriately,
34/// passing StringRef identification ("name") of the pass currently being
35/// executed and IRUnit it works on. There can be different schemes of
36/// providing names in future, currently it is just a name() of the pass.
37///
38/// - PassInstrumentation wraps address of IRUnit into llvm::Any and passes
39/// control to all the registered callbacks. Note that we specifically wrap
40/// 'const IRUnitT*' so as to avoid any accidental changes to IR in
41/// instrumenting callbacks.
42///
43/// - Some instrumentation points (BeforePass) allow to control execution
44/// of a pass. For those callbacks returning false means pass will not be
45/// executed.
46///
47//===----------------------------------------------------------------------===//
48
49#ifndef LLVM_IR_PASSINSTRUMENTATION_H
50#define LLVM_IR_PASSINSTRUMENTATION_H
51
52#include "llvm/ADT/Any.h"
53#include "llvm/ADT/FunctionExtras.h"
54#include "llvm/ADT/SmallVector.h"
55#include "llvm/ADT/StringMap.h"
56#include <type_traits>
57
58namespace llvm {
59
60class PreservedAnalyses;
61class StringRef;
62
63/// This class manages callbacks registration, as well as provides a way for
64/// PassInstrumentation to pass control to the registered callbacks.
65class PassInstrumentationCallbacks {
66public:
67 // Before/After callbacks accept IRUnits whenever appropriate, so they need
68 // to take them as constant pointers, wrapped with llvm::Any.
69 // For the case when IRUnit has been invalidated there is a different
70 // callback to use - AfterPassInvalidated.
71 // We call all BeforePassFuncs to determine if a pass should run or not.
72 // BeforeNonSkippedPassFuncs are called only if the pass should run.
73 // TODO: currently AfterPassInvalidated does not accept IRUnit, since passing
74 // already invalidated IRUnit is unsafe. There are ways to handle invalidated
75 // IRUnits in a safe way, and we might pursue that as soon as there is a
76 // useful instrumentation that needs it.
77 using BeforePassFunc = bool(StringRef, Any);
78 using BeforeSkippedPassFunc = void(StringRef, Any);
79 using BeforeNonSkippedPassFunc = void(StringRef, Any);
80 using AfterPassFunc = void(StringRef, Any, const PreservedAnalyses &);
81 using AfterPassInvalidatedFunc = void(StringRef, const PreservedAnalyses &);
82 using BeforeAnalysisFunc = void(StringRef, Any);
83 using AfterAnalysisFunc = void(StringRef, Any);
84
85public:
86 PassInstrumentationCallbacks() {}
87
88 /// Copying PassInstrumentationCallbacks is not intended.
89 PassInstrumentationCallbacks(const PassInstrumentationCallbacks &) = delete;
90 void operator=(const PassInstrumentationCallbacks &) = delete;
91
92 template <typename CallableT>
93 void registerShouldRunOptionalPassCallback(CallableT C) {
94 ShouldRunOptionalPassCallbacks.emplace_back(std::move(C));
95 }
96
97 template <typename CallableT>
98 void registerBeforeSkippedPassCallback(CallableT C) {
99 BeforeSkippedPassCallbacks.emplace_back(std::move(C));
100 }
101
102 template <typename CallableT>
103 void registerBeforeNonSkippedPassCallback(CallableT C) {
104 BeforeNonSkippedPassCallbacks.emplace_back(std::move(C));
105 }
106
107 template <typename CallableT> void registerAfterPassCallback(CallableT C) {
108 AfterPassCallbacks.emplace_back(std::move(C));
109 }
110
111 template <typename CallableT>
112 void registerAfterPassInvalidatedCallback(CallableT C) {
113 AfterPassInvalidatedCallbacks.emplace_back(std::move(C));
114 }
115
116 template <typename CallableT>
117 void registerBeforeAnalysisCallback(CallableT C) {
118 BeforeAnalysisCallbacks.emplace_back(std::move(C));
119 }
120
121 template <typename CallableT>
122 void registerAfterAnalysisCallback(CallableT C) {
123 AfterAnalysisCallbacks.emplace_back(std::move(C));
124 }
125
126 /// Add a class name to pass name mapping for use by pass instrumentation.
127 void addClassToPassName(StringRef ClassName, StringRef PassName);
128 /// Get the pass name for a given pass class name.
129 StringRef getPassNameForClassName(StringRef ClassName);
130
131private:
132 friend class PassInstrumentation;
133
134 /// These are only run on passes that are not required. They return false when
135 /// an optional pass should be skipped.
136 SmallVector<llvm::unique_function<BeforePassFunc>, 4>
137 ShouldRunOptionalPassCallbacks;
138 /// These are run on passes that are skipped.
139 SmallVector<llvm::unique_function<BeforeSkippedPassFunc>, 4>
140 BeforeSkippedPassCallbacks;
141 /// These are run on passes that are about to be run.
142 SmallVector<llvm::unique_function<BeforeNonSkippedPassFunc>, 4>
143 BeforeNonSkippedPassCallbacks;
144 /// These are run on passes that have just run.
145 SmallVector<llvm::unique_function<AfterPassFunc>, 4> AfterPassCallbacks;
146 /// These are run passes that have just run on invalidated IR.
147 SmallVector<llvm::unique_function<AfterPassInvalidatedFunc>, 4>
148 AfterPassInvalidatedCallbacks;
149 /// These are run on analyses that are about to be run.
150 SmallVector<llvm::unique_function<BeforeAnalysisFunc>, 4>
151 BeforeAnalysisCallbacks;
152 /// These are run on analyses that have been run.
153 SmallVector<llvm::unique_function<AfterAnalysisFunc>, 4>
154 AfterAnalysisCallbacks;
155
156 StringMap<std::string> ClassToPassName;
157};
158
159/// This class provides instrumentation entry points for the Pass Manager,
160/// doing calls to callbacks registered in PassInstrumentationCallbacks.
161class PassInstrumentation {
162 PassInstrumentationCallbacks *Callbacks;
163
164 // Template argument PassT of PassInstrumentation::runBeforePass could be two
165 // kinds: (1) a regular pass inherited from PassInfoMixin (happen when
166 // creating a adaptor pass for a regular pass); (2) a type-erased PassConcept
167 // created from (1). Here we want to make case (1) skippable unconditionally
168 // since they are regular passes. We call PassConcept::isRequired to decide
169 // for case (2).
170 template <typename PassT>
171 using has_required_t = decltype(std::declval<PassT &>().isRequired());
172
173 template <typename PassT>
174 static std::enable_if_t<is_detected<has_required_t, PassT>::value, bool>
175 isRequired(const PassT &Pass) {
176 return Pass.isRequired();
177 }
178 template <typename PassT>
179 static std::enable_if_t<!is_detected<has_required_t, PassT>::value, bool>
180 isRequired(const PassT &Pass) {
181 return false;
182 }
183
184public:
185 /// Callbacks object is not owned by PassInstrumentation, its life-time
186 /// should at least match the life-time of corresponding
187 /// PassInstrumentationAnalysis (which usually is till the end of current
188 /// compilation).
189 PassInstrumentation(PassInstrumentationCallbacks *CB = nullptr)
190 : Callbacks(CB) {}
191
192 /// BeforePass instrumentation point - takes \p Pass instance to be executed
193 /// and constant reference to IR it operates on. \Returns true if pass is
194 /// allowed to be executed. These are only run on optional pass since required
195 /// passes must always be run. This allows these callbacks to print info when
196 /// they want to skip a pass.
197 template <typename IRUnitT, typename PassT>
198 bool runBeforePass(const PassT &Pass, const IRUnitT &IR) const {
199 if (!Callbacks)
200 return true;
201
202 bool ShouldRun = true;
203 if (!isRequired(Pass)) {
204 for (auto &C : Callbacks->ShouldRunOptionalPassCallbacks)
205 ShouldRun &= C(Pass.name(), llvm::Any(&IR));
206 }
207
208 if (ShouldRun) {
209 for (auto &C : Callbacks->BeforeNonSkippedPassCallbacks)
210 C(Pass.name(), llvm::Any(&IR));
211 } else {
212 for (auto &C : Callbacks->BeforeSkippedPassCallbacks)
213 C(Pass.name(), llvm::Any(&IR));
214 }
215
216 return ShouldRun;
217 }
218
219 /// AfterPass instrumentation point - takes \p Pass instance that has
220 /// just been executed and constant reference to \p IR it operates on.
221 /// \p IR is guaranteed to be valid at this point.
222 template <typename IRUnitT, typename PassT>
223 void runAfterPass(const PassT &Pass, const IRUnitT &IR,
224 const PreservedAnalyses &PA) const {
225 if (Callbacks)
226 for (auto &C : Callbacks->AfterPassCallbacks)
227 C(Pass.name(), llvm::Any(&IR), PA);
228 }
229
230 /// AfterPassInvalidated instrumentation point - takes \p Pass instance
231 /// that has just been executed. For use when IR has been invalidated
232 /// by \p Pass execution.
233 template <typename IRUnitT, typename PassT>
234 void runAfterPassInvalidated(const PassT &Pass,
235 const PreservedAnalyses &PA) const {
236 if (Callbacks)
237 for (auto &C : Callbacks->AfterPassInvalidatedCallbacks)
238 C(Pass.name(), PA);
239 }
240
241 /// BeforeAnalysis instrumentation point - takes \p Analysis instance
242 /// to be executed and constant reference to IR it operates on.
243 template <typename IRUnitT, typename PassT>
244 void runBeforeAnalysis(const PassT &Analysis, const IRUnitT &IR) const {
245 if (Callbacks)
246 for (auto &C : Callbacks->BeforeAnalysisCallbacks)
247 C(Analysis.name(), llvm::Any(&IR));
248 }
249
250 /// AfterAnalysis instrumentation point - takes \p Analysis instance
251 /// that has just been executed and constant reference to IR it operated on.
252 template <typename IRUnitT, typename PassT>
253 void runAfterAnalysis(const PassT &Analysis, const IRUnitT &IR) const {
254 if (Callbacks)
255 for (auto &C : Callbacks->AfterAnalysisCallbacks)
256 C(Analysis.name(), llvm::Any(&IR));
257 }
258
259 /// Handle invalidation from the pass manager when PassInstrumentation
260 /// is used as the result of PassInstrumentationAnalysis.
261 ///
262 /// On attempt to invalidate just return false. There is nothing to become
263 /// invalid here.
264 template <typename IRUnitT, typename... ExtraArgsT>
265 bool invalidate(IRUnitT &, const class llvm::PreservedAnalyses &,
266 ExtraArgsT...) {
267 return false;
268 }
269
270 template <typename CallableT>
271 void pushBeforeNonSkippedPassCallback(CallableT C) {
272 if (Callbacks)
273 Callbacks->BeforeNonSkippedPassCallbacks.emplace_back(std::move(C));
274 }
275 void popBeforeNonSkippedPassCallback() {
276 if (Callbacks)
277 Callbacks->BeforeNonSkippedPassCallbacks.pop_back();
278 }
279};
280
281bool isSpecialPass(StringRef PassID, const std::vector<StringRef> &Specials);
282
283} // namespace llvm
284
285#endif
286