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 #include <vector> 58 59 namespace llvm { 60 61 class PreservedAnalyses; 62 class StringRef; 63 64 /// This class manages callbacks registration, as well as provides a way for 65 /// PassInstrumentation to pass control to the registered callbacks. 66 class PassInstrumentationCallbacks { 67 public: 68 // Before/After callbacks accept IRUnits whenever appropriate, so they need 69 // to take them as constant pointers, wrapped with llvm::Any. 70 // For the case when IRUnit has been invalidated there is a different 71 // callback to use - AfterPassInvalidated. 72 // We call all BeforePassFuncs to determine if a pass should run or not. 73 // BeforeNonSkippedPassFuncs are called only if the pass should run. 74 // TODO: currently AfterPassInvalidated does not accept IRUnit, since passing 75 // already invalidated IRUnit is unsafe. There are ways to handle invalidated 76 // IRUnits in a safe way, and we might pursue that as soon as there is a 77 // useful instrumentation that needs it. 78 using BeforePassFunc = bool(StringRef, Any); 79 using BeforeSkippedPassFunc = void(StringRef, Any); 80 using BeforeNonSkippedPassFunc = void(StringRef, Any); 81 using AfterPassFunc = void(StringRef, Any, const PreservedAnalyses &); 82 using AfterPassInvalidatedFunc = void(StringRef, const PreservedAnalyses &); 83 using BeforeAnalysisFunc = void(StringRef, Any); 84 using AfterAnalysisFunc = void(StringRef, Any); 85 using AnalysisInvalidatedFunc = void(StringRef, Any); 86 using AnalysesClearedFunc = void(StringRef); 87 88 public: 89 PassInstrumentationCallbacks() = default; 90 91 /// Copying PassInstrumentationCallbacks is not intended. 92 PassInstrumentationCallbacks(const PassInstrumentationCallbacks &) = delete; 93 void operator=(const PassInstrumentationCallbacks &) = delete; 94 95 template <typename CallableT> 96 void registerShouldRunOptionalPassCallback(CallableT C) { 97 ShouldRunOptionalPassCallbacks.emplace_back(std::move(C)); 98 } 99 100 template <typename CallableT> 101 void registerBeforeSkippedPassCallback(CallableT C) { 102 BeforeSkippedPassCallbacks.emplace_back(std::move(C)); 103 } 104 105 template <typename CallableT> 106 void registerBeforeNonSkippedPassCallback(CallableT C) { 107 BeforeNonSkippedPassCallbacks.emplace_back(std::move(C)); 108 } 109 110 template <typename CallableT> void registerAfterPassCallback(CallableT C) { 111 AfterPassCallbacks.emplace_back(std::move(C)); 112 } 113 114 template <typename CallableT> 115 void registerAfterPassInvalidatedCallback(CallableT C) { 116 AfterPassInvalidatedCallbacks.emplace_back(std::move(C)); 117 } 118 119 template <typename CallableT> 120 void registerBeforeAnalysisCallback(CallableT C) { 121 BeforeAnalysisCallbacks.emplace_back(std::move(C)); 122 } 123 124 template <typename CallableT> 125 void registerAfterAnalysisCallback(CallableT C) { 126 AfterAnalysisCallbacks.emplace_back(std::move(C)); 127 } 128 129 template <typename CallableT> 130 void registerAnalysisInvalidatedCallback(CallableT C) { 131 AnalysisInvalidatedCallbacks.emplace_back(std::move(C)); 132 } 133 134 template <typename CallableT> 135 void registerAnalysesClearedCallback(CallableT C) { 136 AnalysesClearedCallbacks.emplace_back(std::move(C)); 137 } 138 139 /// Add a class name to pass name mapping for use by pass instrumentation. 140 void addClassToPassName(StringRef ClassName, StringRef PassName); 141 /// Get the pass name for a given pass class name. 142 StringRef getPassNameForClassName(StringRef ClassName); 143 144 private: 145 friend class PassInstrumentation; 146 147 /// These are only run on passes that are not required. They return false when 148 /// an optional pass should be skipped. 149 SmallVector<llvm::unique_function<BeforePassFunc>, 4> 150 ShouldRunOptionalPassCallbacks; 151 /// These are run on passes that are skipped. 152 SmallVector<llvm::unique_function<BeforeSkippedPassFunc>, 4> 153 BeforeSkippedPassCallbacks; 154 /// These are run on passes that are about to be run. 155 SmallVector<llvm::unique_function<BeforeNonSkippedPassFunc>, 4> 156 BeforeNonSkippedPassCallbacks; 157 /// These are run on passes that have just run. 158 SmallVector<llvm::unique_function<AfterPassFunc>, 4> AfterPassCallbacks; 159 /// These are run passes that have just run on invalidated IR. 160 SmallVector<llvm::unique_function<AfterPassInvalidatedFunc>, 4> 161 AfterPassInvalidatedCallbacks; 162 /// These are run on analyses that are about to be run. 163 SmallVector<llvm::unique_function<BeforeAnalysisFunc>, 4> 164 BeforeAnalysisCallbacks; 165 /// These are run on analyses that have been run. 166 SmallVector<llvm::unique_function<AfterAnalysisFunc>, 4> 167 AfterAnalysisCallbacks; 168 /// These are run on analyses that have been invalidated. 169 SmallVector<llvm::unique_function<AnalysisInvalidatedFunc>, 4> 170 AnalysisInvalidatedCallbacks; 171 /// These are run on analyses that have been cleared. 172 SmallVector<llvm::unique_function<AnalysesClearedFunc>, 4> 173 AnalysesClearedCallbacks; 174 175 StringMap<std::string> ClassToPassName; 176 }; 177 178 /// This class provides instrumentation entry points for the Pass Manager, 179 /// doing calls to callbacks registered in PassInstrumentationCallbacks. 180 class PassInstrumentation { 181 PassInstrumentationCallbacks *Callbacks; 182 183 // Template argument PassT of PassInstrumentation::runBeforePass could be two 184 // kinds: (1) a regular pass inherited from PassInfoMixin (happen when 185 // creating a adaptor pass for a regular pass); (2) a type-erased PassConcept 186 // created from (1). Here we want to make case (1) skippable unconditionally 187 // since they are regular passes. We call PassConcept::isRequired to decide 188 // for case (2). 189 template <typename PassT> 190 using has_required_t = decltype(std::declval<PassT &>().isRequired()); 191 192 template <typename PassT> 193 static std::enable_if_t<is_detected<has_required_t, PassT>::value, bool> 194 isRequired(const PassT &Pass) { 195 return Pass.isRequired(); 196 } 197 template <typename PassT> 198 static std::enable_if_t<!is_detected<has_required_t, PassT>::value, bool> 199 isRequired(const PassT &Pass) { 200 return false; 201 } 202 203 public: 204 /// Callbacks object is not owned by PassInstrumentation, its life-time 205 /// should at least match the life-time of corresponding 206 /// PassInstrumentationAnalysis (which usually is till the end of current 207 /// compilation). 208 PassInstrumentation(PassInstrumentationCallbacks *CB = nullptr) 209 : Callbacks(CB) {} 210 211 /// BeforePass instrumentation point - takes \p Pass instance to be executed 212 /// and constant reference to IR it operates on. \Returns true if pass is 213 /// allowed to be executed. These are only run on optional pass since required 214 /// passes must always be run. This allows these callbacks to print info when 215 /// they want to skip a pass. 216 template <typename IRUnitT, typename PassT> 217 bool runBeforePass(const PassT &Pass, const IRUnitT &IR) const { 218 if (!Callbacks) 219 return true; 220 221 bool ShouldRun = true; 222 if (!isRequired(Pass)) { 223 for (auto &C : Callbacks->ShouldRunOptionalPassCallbacks) 224 ShouldRun &= C(Pass.name(), llvm::Any(&IR)); 225 } 226 227 if (ShouldRun) { 228 for (auto &C : Callbacks->BeforeNonSkippedPassCallbacks) 229 C(Pass.name(), llvm::Any(&IR)); 230 } else { 231 for (auto &C : Callbacks->BeforeSkippedPassCallbacks) 232 C(Pass.name(), llvm::Any(&IR)); 233 } 234 235 return ShouldRun; 236 } 237 238 /// AfterPass instrumentation point - takes \p Pass instance that has 239 /// just been executed and constant reference to \p IR it operates on. 240 /// \p IR is guaranteed to be valid at this point. 241 template <typename IRUnitT, typename PassT> 242 void runAfterPass(const PassT &Pass, const IRUnitT &IR, 243 const PreservedAnalyses &PA) const { 244 if (Callbacks) 245 for (auto &C : Callbacks->AfterPassCallbacks) 246 C(Pass.name(), llvm::Any(&IR), PA); 247 } 248 249 /// AfterPassInvalidated instrumentation point - takes \p Pass instance 250 /// that has just been executed. For use when IR has been invalidated 251 /// by \p Pass execution. 252 template <typename IRUnitT, typename PassT> 253 void runAfterPassInvalidated(const PassT &Pass, 254 const PreservedAnalyses &PA) const { 255 if (Callbacks) 256 for (auto &C : Callbacks->AfterPassInvalidatedCallbacks) 257 C(Pass.name(), PA); 258 } 259 260 /// BeforeAnalysis instrumentation point - takes \p Analysis instance 261 /// to be executed and constant reference to IR it operates on. 262 template <typename IRUnitT, typename PassT> 263 void runBeforeAnalysis(const PassT &Analysis, const IRUnitT &IR) const { 264 if (Callbacks) 265 for (auto &C : Callbacks->BeforeAnalysisCallbacks) 266 C(Analysis.name(), llvm::Any(&IR)); 267 } 268 269 /// AfterAnalysis instrumentation point - takes \p Analysis instance 270 /// that has just been executed and constant reference to IR it operated on. 271 template <typename IRUnitT, typename PassT> 272 void runAfterAnalysis(const PassT &Analysis, const IRUnitT &IR) const { 273 if (Callbacks) 274 for (auto &C : Callbacks->AfterAnalysisCallbacks) 275 C(Analysis.name(), llvm::Any(&IR)); 276 } 277 278 /// AnalysisInvalidated instrumentation point - takes \p Analysis instance 279 /// that has just been invalidated and constant reference to IR it operated 280 /// on. 281 template <typename IRUnitT, typename PassT> 282 void runAnalysisInvalidated(const PassT &Analysis, const IRUnitT &IR) const { 283 if (Callbacks) 284 for (auto &C : Callbacks->AnalysisInvalidatedCallbacks) 285 C(Analysis.name(), llvm::Any(&IR)); 286 } 287 288 /// AnalysesCleared instrumentation point - takes name of IR that analyses 289 /// operated on. 290 void runAnalysesCleared(StringRef Name) const { 291 if (Callbacks) 292 for (auto &C : Callbacks->AnalysesClearedCallbacks) 293 C(Name); 294 } 295 296 /// Handle invalidation from the pass manager when PassInstrumentation 297 /// is used as the result of PassInstrumentationAnalysis. 298 /// 299 /// On attempt to invalidate just return false. There is nothing to become 300 /// invalid here. 301 template <typename IRUnitT, typename... ExtraArgsT> 302 bool invalidate(IRUnitT &, const class llvm::PreservedAnalyses &, 303 ExtraArgsT...) { 304 return false; 305 } 306 307 template <typename CallableT> 308 void pushBeforeNonSkippedPassCallback(CallableT C) { 309 if (Callbacks) 310 Callbacks->BeforeNonSkippedPassCallbacks.emplace_back(std::move(C)); 311 } 312 void popBeforeNonSkippedPassCallback() { 313 if (Callbacks) 314 Callbacks->BeforeNonSkippedPassCallbacks.pop_back(); 315 } 316 }; 317 318 bool isSpecialPass(StringRef PassID, const std::vector<StringRef> &Specials); 319 320 } // namespace llvm 321 322 #endif 323