LLVM 20.0.0git
PassInstrumentation.h
Go to the documentation of this file.
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"
55#include "llvm/ADT/DenseMap.h"
56#include "llvm/IR/PassManager.h"
57#include <type_traits>
58#include <vector>
59
60namespace llvm {
61
62class PreservedAnalyses;
63class StringRef;
64
65/// This class manages callbacks registration, as well as provides a way for
66/// PassInstrumentation to pass control to the registered callbacks.
68public:
69 // Before/After callbacks accept IRUnits whenever appropriate, so they need
70 // to take them as constant pointers, wrapped with llvm::Any.
71 // For the case when IRUnit has been invalidated there is a different
72 // callback to use - AfterPassInvalidated.
73 // We call all BeforePassFuncs to determine if a pass should run or not.
74 // BeforeNonSkippedPassFuncs are called only if the pass should run.
75 // TODO: currently AfterPassInvalidated does not accept IRUnit, since passing
76 // already invalidated IRUnit is unsafe. There are ways to handle invalidated
77 // IRUnits in a safe way, and we might pursue that as soon as there is a
78 // useful instrumentation that needs it.
88
89public:
91
92 /// Copying PassInstrumentationCallbacks is not intended.
95
96 template <typename CallableT>
98 ShouldRunOptionalPassCallbacks.emplace_back(std::move(C));
99 }
100
101 template <typename CallableT>
103 BeforeSkippedPassCallbacks.emplace_back(std::move(C));
104 }
105
106 template <typename CallableT>
108 BeforeNonSkippedPassCallbacks.emplace_back(std::move(C));
109 }
110
111 template <typename CallableT>
112 void registerAfterPassCallback(CallableT C, bool ToFront = false) {
113 if (ToFront)
114 AfterPassCallbacks.insert(AfterPassCallbacks.begin(), std::move(C));
115 else
116 AfterPassCallbacks.emplace_back(std::move(C));
117 }
118
119 template <typename CallableT>
120 void registerAfterPassInvalidatedCallback(CallableT C, bool ToFront = false) {
121 if (ToFront)
122 AfterPassInvalidatedCallbacks.insert(
123 AfterPassInvalidatedCallbacks.begin(), std::move(C));
124 else
125 AfterPassInvalidatedCallbacks.emplace_back(std::move(C));
126 }
127
128 template <typename CallableT>
130 BeforeAnalysisCallbacks.emplace_back(std::move(C));
131 }
132
133 template <typename CallableT>
134 void registerAfterAnalysisCallback(CallableT C, bool ToFront = false) {
135 if (ToFront)
136 AfterAnalysisCallbacks.insert(AfterAnalysisCallbacks.begin(),
137 std::move(C));
138 else
139 AfterAnalysisCallbacks.emplace_back(std::move(C));
140 }
141
142 template <typename CallableT>
144 AnalysisInvalidatedCallbacks.emplace_back(std::move(C));
145 }
146
147 template <typename CallableT>
149 AnalysesClearedCallbacks.emplace_back(std::move(C));
150 }
151
152 template <typename CallableT>
154 ClassToPassNameCallbacks.emplace_back(std::move(C));
155 }
156
157 /// Add a class name to pass name mapping for use by pass instrumentation.
159 /// Get the pass name for a given pass class name.
161
162private:
164
165 /// These are only run on passes that are not required. They return false when
166 /// an optional pass should be skipped.
168 ShouldRunOptionalPassCallbacks;
169 /// These are run on passes that are skipped.
171 BeforeSkippedPassCallbacks;
172 /// These are run on passes that are about to be run.
174 BeforeNonSkippedPassCallbacks;
175 /// These are run on passes that have just run.
177 /// These are run passes that have just run on invalidated IR.
179 AfterPassInvalidatedCallbacks;
180 /// These are run on analyses that are about to be run.
182 BeforeAnalysisCallbacks;
183 /// These are run on analyses that have been run.
185 AfterAnalysisCallbacks;
186 /// These are run on analyses that have been invalidated.
188 AnalysisInvalidatedCallbacks;
189 /// These are run on analyses that have been cleared.
191 AnalysesClearedCallbacks;
192
193 SmallVector<llvm::unique_function<void ()>, 4> ClassToPassNameCallbacks;
194 DenseMap<StringRef, std::string> ClassToPassName;
195};
196
197/// This class provides instrumentation entry points for the Pass Manager,
198/// doing calls to callbacks registered in PassInstrumentationCallbacks.
201
202 // Template argument PassT of PassInstrumentation::runBeforePass could be two
203 // kinds: (1) a regular pass inherited from PassInfoMixin (happen when
204 // creating a adaptor pass for a regular pass); (2) a type-erased PassConcept
205 // created from (1). Here we want to make case (1) skippable unconditionally
206 // since they are regular passes. We call PassConcept::isRequired to decide
207 // for case (2).
208 template <typename PassT>
209 using has_required_t = decltype(std::declval<PassT &>().isRequired());
210
211 template <typename PassT>
212 static std::enable_if_t<is_detected<has_required_t, PassT>::value, bool>
213 isRequired(const PassT &Pass) {
214 return Pass.isRequired();
215 }
216 template <typename PassT>
217 static std::enable_if_t<!is_detected<has_required_t, PassT>::value, bool>
218 isRequired(const PassT &Pass) {
219 return false;
220 }
221
222public:
223 /// Callbacks object is not owned by PassInstrumentation, its life-time
224 /// should at least match the life-time of corresponding
225 /// PassInstrumentationAnalysis (which usually is till the end of current
226 /// compilation).
228 : Callbacks(CB) {}
229
230 /// BeforePass instrumentation point - takes \p Pass instance to be executed
231 /// and constant reference to IR it operates on. \Returns true if pass is
232 /// allowed to be executed. These are only run on optional pass since required
233 /// passes must always be run. This allows these callbacks to print info when
234 /// they want to skip a pass.
235 template <typename IRUnitT, typename PassT>
236 bool runBeforePass(const PassT &Pass, const IRUnitT &IR) const {
237 if (!Callbacks)
238 return true;
239
240 bool ShouldRun = true;
241 if (!isRequired(Pass)) {
242 for (auto &C : Callbacks->ShouldRunOptionalPassCallbacks)
243 ShouldRun &= C(Pass.name(), llvm::Any(&IR));
244 }
245
246 if (ShouldRun) {
247 for (auto &C : Callbacks->BeforeNonSkippedPassCallbacks)
248 C(Pass.name(), llvm::Any(&IR));
249 } else {
250 for (auto &C : Callbacks->BeforeSkippedPassCallbacks)
251 C(Pass.name(), llvm::Any(&IR));
252 }
253
254 return ShouldRun;
255 }
256
257 /// AfterPass instrumentation point - takes \p Pass instance that has
258 /// just been executed and constant reference to \p IR it operates on.
259 /// \p IR is guaranteed to be valid at this point.
260 template <typename IRUnitT, typename PassT>
261 void runAfterPass(const PassT &Pass, const IRUnitT &IR,
262 const PreservedAnalyses &PA) const {
263 if (Callbacks)
264 for (auto &C : Callbacks->AfterPassCallbacks)
265 C(Pass.name(), llvm::Any(&IR), PA);
266 }
267
268 /// AfterPassInvalidated instrumentation point - takes \p Pass instance
269 /// that has just been executed. For use when IR has been invalidated
270 /// by \p Pass execution.
271 template <typename IRUnitT, typename PassT>
272 void runAfterPassInvalidated(const PassT &Pass,
273 const PreservedAnalyses &PA) const {
274 if (Callbacks)
275 for (auto &C : Callbacks->AfterPassInvalidatedCallbacks)
276 C(Pass.name(), PA);
277 }
278
279 /// BeforeAnalysis instrumentation point - takes \p Analysis instance
280 /// to be executed and constant reference to IR it operates on.
281 template <typename IRUnitT, typename PassT>
282 void runBeforeAnalysis(const PassT &Analysis, const IRUnitT &IR) const {
283 if (Callbacks)
284 for (auto &C : Callbacks->BeforeAnalysisCallbacks)
285 C(Analysis.name(), llvm::Any(&IR));
286 }
287
288 /// AfterAnalysis instrumentation point - takes \p Analysis instance
289 /// that has just been executed and constant reference to IR it operated on.
290 template <typename IRUnitT, typename PassT>
291 void runAfterAnalysis(const PassT &Analysis, const IRUnitT &IR) const {
292 if (Callbacks)
293 for (auto &C : Callbacks->AfterAnalysisCallbacks)
294 C(Analysis.name(), llvm::Any(&IR));
295 }
296
297 /// AnalysisInvalidated instrumentation point - takes \p Analysis instance
298 /// that has just been invalidated and constant reference to IR it operated
299 /// on.
300 template <typename IRUnitT, typename PassT>
301 void runAnalysisInvalidated(const PassT &Analysis, const IRUnitT &IR) const {
302 if (Callbacks)
303 for (auto &C : Callbacks->AnalysisInvalidatedCallbacks)
304 C(Analysis.name(), llvm::Any(&IR));
305 }
306
307 /// AnalysesCleared instrumentation point - takes name of IR that analyses
308 /// operated on.
310 if (Callbacks)
311 for (auto &C : Callbacks->AnalysesClearedCallbacks)
312 C(Name);
313 }
314
315 /// Handle invalidation from the pass manager when PassInstrumentation
316 /// is used as the result of PassInstrumentationAnalysis.
317 ///
318 /// On attempt to invalidate just return false. There is nothing to become
319 /// invalid here.
320 template <typename IRUnitT, typename... ExtraArgsT>
321 bool invalidate(IRUnitT &, const class llvm::PreservedAnalyses &,
322 ExtraArgsT...) {
323 return false;
324 }
325
326 template <typename CallableT>
328 if (Callbacks)
329 Callbacks->BeforeNonSkippedPassCallbacks.emplace_back(std::move(C));
330 }
332 if (Callbacks)
333 Callbacks->BeforeNonSkippedPassCallbacks.pop_back();
334 }
335
336 /// Get the pass name for a given pass class name.
338 if (Callbacks)
339 return Callbacks->getPassNameForClassName(ClassName);
340 return {};
341 }
342};
343
344bool isSpecialPass(StringRef PassID, const std::vector<StringRef> &Specials);
345
346/// Pseudo-analysis pass that exposes the \c PassInstrumentation to pass
347/// managers.
349 : public AnalysisInfoMixin<PassInstrumentationAnalysis> {
351 static AnalysisKey Key;
352
354
355public:
356 /// PassInstrumentationCallbacks object is shared, owned by something else,
357 /// not this analysis.
359 : Callbacks(Callbacks) {}
360
362
363 template <typename IRUnitT, typename AnalysisManagerT, typename... ExtraArgTs>
364 Result run(IRUnitT &, AnalysisManagerT &, ExtraArgTs &&...) {
365 return PassInstrumentation(Callbacks);
366 }
367};
368
369
370} // namespace llvm
371
372#endif
This file provides Any, a non-template class modeled in the spirit of std::any.
block Block Frequency Analysis
This file defines the DenseMap class.
std::string Name
This file provides a collection of function (or more generally, callable) type erasure utilities supp...
Legalize the Machine IR a function s Machine IR
Definition: Legalizer.cpp:81
This header defines various interfaces for pass management in LLVM.
This file defines the SmallVector class.
static const char PassName[]
Definition: Any.h:28
Pseudo-analysis pass that exposes the PassInstrumentation to pass managers.
Result run(IRUnitT &, AnalysisManagerT &, ExtraArgTs &&...)
PassInstrumentationAnalysis(PassInstrumentationCallbacks *Callbacks=nullptr)
PassInstrumentationCallbacks object is shared, owned by something else, not this analysis.
This class manages callbacks registration, as well as provides a way for PassInstrumentation to pass ...
void registerAfterPassInvalidatedCallback(CallableT C, bool ToFront=false)
void registerAnalysisInvalidatedCallback(CallableT C)
StringRef getPassNameForClassName(StringRef ClassName)
Get the pass name for a given pass class name.
void registerAfterAnalysisCallback(CallableT C, bool ToFront=false)
void(StringRef, const PreservedAnalyses &) AfterPassInvalidatedFunc
void(StringRef, Any) BeforeNonSkippedPassFunc
void registerBeforeNonSkippedPassCallback(CallableT C)
void registerBeforeSkippedPassCallback(CallableT C)
PassInstrumentationCallbacks(const PassInstrumentationCallbacks &)=delete
Copying PassInstrumentationCallbacks is not intended.
void addClassToPassName(StringRef ClassName, StringRef PassName)
Add a class name to pass name mapping for use by pass instrumentation.
void registerShouldRunOptionalPassCallback(CallableT C)
void(StringRef, Any) BeforeSkippedPassFunc
void operator=(const PassInstrumentationCallbacks &)=delete
void(StringRef, Any) AnalysisInvalidatedFunc
void(StringRef, Any, const PreservedAnalyses &) AfterPassFunc
void registerAfterPassCallback(CallableT C, bool ToFront=false)
This class provides instrumentation entry points for the Pass Manager, doing calls to callbacks regis...
void runAfterPassInvalidated(const PassT &Pass, const PreservedAnalyses &PA) const
AfterPassInvalidated instrumentation point - takes Pass instance that has just been executed.
void pushBeforeNonSkippedPassCallback(CallableT C)
PassInstrumentation(PassInstrumentationCallbacks *CB=nullptr)
Callbacks object is not owned by PassInstrumentation, its life-time should at least match the life-ti...
bool invalidate(IRUnitT &, const class llvm::PreservedAnalyses &, ExtraArgsT...)
Handle invalidation from the pass manager when PassInstrumentation is used as the result of PassInstr...
void runBeforeAnalysis(const PassT &Analysis, const IRUnitT &IR) const
BeforeAnalysis instrumentation point - takes Analysis instance to be executed and constant reference ...
void runAnalysisInvalidated(const PassT &Analysis, const IRUnitT &IR) const
AnalysisInvalidated instrumentation point - takes Analysis instance that has just been invalidated an...
void runAnalysesCleared(StringRef Name) const
AnalysesCleared instrumentation point - takes name of IR that analyses operated on.
StringRef getPassNameForClassName(StringRef ClassName) const
Get the pass name for a given pass class name.
void runAfterPass(const PassT &Pass, const IRUnitT &IR, const PreservedAnalyses &PA) const
AfterPass instrumentation point - takes Pass instance that has just been executed and constant refere...
void runAfterAnalysis(const PassT &Analysis, const IRUnitT &IR) const
AfterAnalysis instrumentation point - takes Analysis instance that has just been executed and constan...
bool runBeforePass(const PassT &Pass, const IRUnitT &IR) const
BeforePass instrumentation point - takes Pass instance to be executed and constant reference to IR it...
Pass interface - Implemented by all 'passes'.
Definition: Pass.h:94
A set of analyses that are preserved following a run of a transformation pass.
Definition: Analysis.h:111
reference emplace_back(ArgTypes &&... Args)
Definition: SmallVector.h:950
iterator insert(iterator I, T &&Elt)
Definition: SmallVector.h:818
This is a 'vector' (really, a variable-sized array), optimized for the case when the array is small.
Definition: SmallVector.h:1209
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
unique_function is a type-erasing functor similar to std::function.
@ C
The default llvm calling convention, compatible with C.
Definition: CallingConv.h:34
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
bool isSpecialPass(StringRef PassID, const std::vector< StringRef > &Specials)
A CRTP mix-in that provides informational APIs needed for analysis passes.
Definition: PassManager.h:92
A special type used by analysis passes to provide an address that identifies that particular analysis...
Definition: Analysis.h:28