1 //===- Parsing, selection, and construction of pass pipelines --*- C++ -*--===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 /// \file 10 /// 11 /// Interfaces for registering analysis passes, producing common pass manager 12 /// configurations, and parsing of pass pipelines. 13 /// 14 //===----------------------------------------------------------------------===// 15 16 #ifndef LLVM_PASSES_PASSBUILDER_H 17 #define LLVM_PASSES_PASSBUILDER_H 18 19 #include "llvm/ADT/Optional.h" 20 #include "llvm/Analysis/CGSCCPassManager.h" 21 #include "llvm/IR/PassManager.h" 22 #include "llvm/Transforms/Scalar/LoopPassManager.h" 23 #include <vector> 24 25 namespace llvm { 26 class StringRef; 27 class AAManager; 28 class TargetMachine; 29 30 /// A struct capturing PGO tunables. 31 struct PGOOptions { 32 std::string ProfileGenFile = ""; 33 std::string ProfileUseFile = ""; 34 bool RunProfileGen = false; 35 bool SamplePGO = false; 36 }; 37 38 /// \brief This class provides access to building LLVM's passes. 39 /// 40 /// It's members provide the baseline state available to passes during their 41 /// construction. The \c PassRegistry.def file specifies how to construct all 42 /// of the built-in passes, and those may reference these members during 43 /// construction. 44 class PassBuilder { 45 TargetMachine *TM; 46 Optional<PGOOptions> PGOOpt; 47 48 public: 49 /// \brief LLVM-provided high-level optimization levels. 50 /// 51 /// This enumerates the LLVM-provided high-level optimization levels. Each 52 /// level has a specific goal and rationale. 53 enum OptimizationLevel { 54 /// Disable as many optimizations as possible. This doesn't completely 55 /// disable the optimizer in all cases, for example always_inline functions 56 /// can be required to be inlined for correctness. 57 O0, 58 59 /// Optimize quickly without destroying debuggability. 60 /// 61 /// FIXME: The current and historical behavior of this level does *not* 62 /// agree with this goal, but we would like to move toward this goal in the 63 /// future. 64 /// 65 /// This level is tuned to produce a result from the optimizer as quickly 66 /// as possible and to avoid destroying debuggability. This tends to result 67 /// in a very good development mode where the compiled code will be 68 /// immediately executed as part of testing. As a consequence, where 69 /// possible, we would like to produce efficient-to-execute code, but not 70 /// if it significantly slows down compilation or would prevent even basic 71 /// debugging of the resulting binary. 72 /// 73 /// As an example, complex loop transformations such as versioning, 74 /// vectorization, or fusion might not make sense here due to the degree to 75 /// which the executed code would differ from the source code, and the 76 /// potential compile time cost. 77 O1, 78 79 /// Optimize for fast execution as much as possible without triggering 80 /// significant incremental compile time or code size growth. 81 /// 82 /// The key idea is that optimizations at this level should "pay for 83 /// themselves". So if an optimization increases compile time by 5% or 84 /// increases code size by 5% for a particular benchmark, that benchmark 85 /// should also be one which sees a 5% runtime improvement. If the compile 86 /// time or code size penalties happen on average across a diverse range of 87 /// LLVM users' benchmarks, then the improvements should as well. 88 /// 89 /// And no matter what, the compile time needs to not grow superlinearly 90 /// with the size of input to LLVM so that users can control the runtime of 91 /// the optimizer in this mode. 92 /// 93 /// This is expected to be a good default optimization level for the vast 94 /// majority of users. 95 O2, 96 97 /// Optimize for fast execution as much as possible. 98 /// 99 /// This mode is significantly more aggressive in trading off compile time 100 /// and code size to get execution time improvements. The core idea is that 101 /// this mode should include any optimization that helps execution time on 102 /// balance across a diverse collection of benchmarks, even if it increases 103 /// code size or compile time for some benchmarks without corresponding 104 /// improvements to execution time. 105 /// 106 /// Despite being willing to trade more compile time off to get improved 107 /// execution time, this mode still tries to avoid superlinear growth in 108 /// order to make even significantly slower compile times at least scale 109 /// reasonably. This does not preclude very substantial constant factor 110 /// costs though. 111 O3, 112 113 /// Similar to \c O2 but tries to optimize for small code size instead of 114 /// fast execution without triggering significant incremental execution 115 /// time slowdowns. 116 /// 117 /// The logic here is exactly the same as \c O2, but with code size and 118 /// execution time metrics swapped. 119 /// 120 /// A consequence of the different core goal is that this should in general 121 /// produce substantially smaller executables that still run in 122 /// a reasonable amount of time. 123 Os, 124 125 /// A very specialized mode that will optimize for code size at any and all 126 /// costs. 127 /// 128 /// This is useful primarily when there are absolute size limitations and 129 /// any effort taken to reduce the size is worth it regardless of the 130 /// execution time impact. You should expect this level to produce rather 131 /// slow, but very small, code. 132 Oz 133 }; 134 135 explicit PassBuilder(TargetMachine *TM = nullptr, 136 Optional<PGOOptions> PGOOpt = None) 137 : TM(TM), PGOOpt(PGOOpt) {} 138 139 /// \brief Cross register the analysis managers through their proxies. 140 /// 141 /// This is an interface that can be used to cross register each 142 // AnalysisManager with all the others analysis managers. 143 void crossRegisterProxies(LoopAnalysisManager &LAM, 144 FunctionAnalysisManager &FAM, 145 CGSCCAnalysisManager &CGAM, 146 ModuleAnalysisManager &MAM); 147 148 /// \brief Registers all available module analysis passes. 149 /// 150 /// This is an interface that can be used to populate a \c 151 /// ModuleAnalysisManager with all registered module analyses. Callers can 152 /// still manually register any additional analyses. Callers can also 153 /// pre-register analyses and this will not override those. 154 void registerModuleAnalyses(ModuleAnalysisManager &MAM); 155 156 /// \brief Registers all available CGSCC analysis passes. 157 /// 158 /// This is an interface that can be used to populate a \c CGSCCAnalysisManager 159 /// with all registered CGSCC analyses. Callers can still manually register any 160 /// additional analyses. Callers can also pre-register analyses and this will 161 /// not override those. 162 void registerCGSCCAnalyses(CGSCCAnalysisManager &CGAM); 163 164 /// \brief Registers all available function analysis passes. 165 /// 166 /// This is an interface that can be used to populate a \c 167 /// FunctionAnalysisManager with all registered function analyses. Callers can 168 /// still manually register any additional analyses. Callers can also 169 /// pre-register analyses and this will not override those. 170 void registerFunctionAnalyses(FunctionAnalysisManager &FAM); 171 172 /// \brief Registers all available loop analysis passes. 173 /// 174 /// This is an interface that can be used to populate a \c LoopAnalysisManager 175 /// with all registered loop analyses. Callers can still manually register any 176 /// additional analyses. 177 void registerLoopAnalyses(LoopAnalysisManager &LAM); 178 179 /// Construct the core LLVM function canonicalization and simplification 180 /// pipeline. 181 /// 182 /// This is a long pipeline and uses most of the per-function optimization 183 /// passes in LLVM to canonicalize and simplify the IR. It is suitable to run 184 /// repeatedly over the IR and is not expected to destroy important 185 /// information about the semantics of the IR. 186 /// 187 /// Note that \p Level cannot be `O0` here. The pipelines produced are 188 /// only intended for use when attempting to optimize code. If frontends 189 /// require some transformations for semantic reasons, they should explicitly 190 /// build them. 191 FunctionPassManager 192 buildFunctionSimplificationPipeline(OptimizationLevel Level, 193 bool DebugLogging = false); 194 195 /// Construct the core LLVM module canonicalization and simplification 196 /// pipeline. 197 /// 198 /// This pipeline focuses on canonicalizing and simplifying the entire module 199 /// of IR. Much like the function simplification pipeline above, it is 200 /// suitable to run repeatedly over the IR and is not expected to destroy 201 /// important information. It does, however, perform inlining and other 202 /// heuristic based simplifications that are not strictly reversible. 203 /// 204 /// Note that \p Level cannot be `O0` here. The pipelines produced are 205 /// only intended for use when attempting to optimize code. If frontends 206 /// require some transformations for semantic reasons, they should explicitly 207 /// build them. 208 ModulePassManager 209 buildModuleSimplificationPipeline(OptimizationLevel Level, 210 bool DebugLogging = false); 211 212 /// Construct the core LLVM module optimization pipeline. 213 /// 214 /// This pipeline focuses on optimizing the execution speed of the IR. It 215 /// uses cost modeling and thresholds to balance code growth against runtime 216 /// improvements. It includes vectorization and other information destroying 217 /// transformations. It also cannot generally be run repeatedly on a module 218 /// without potentially seriously regressing either runtime performance of 219 /// the code or serious code size growth. 220 /// 221 /// Note that \p Level cannot be `O0` here. The pipelines produced are 222 /// only intended for use when attempting to optimize code. If frontends 223 /// require some transformations for semantic reasons, they should explicitly 224 /// build them. 225 ModulePassManager buildModuleOptimizationPipeline(OptimizationLevel Level, 226 bool DebugLogging = false); 227 228 /// Build a per-module default optimization pipeline. 229 /// 230 /// This provides a good default optimization pipeline for per-module 231 /// optimization and code generation without any link-time optimization. It 232 /// typically correspond to frontend "-O[123]" options for optimization 233 /// levels \c O1, \c O2 and \c O3 resp. 234 /// 235 /// Note that \p Level cannot be `O0` here. The pipelines produced are 236 /// only intended for use when attempting to optimize code. If frontends 237 /// require some transformations for semantic reasons, they should explicitly 238 /// build them. 239 ModulePassManager buildPerModuleDefaultPipeline(OptimizationLevel Level, 240 bool DebugLogging = false); 241 242 /// Build a pre-link, ThinLTO-targeting default optimization pipeline to 243 /// a pass manager. 244 /// 245 /// This adds the pre-link optimizations tuned to prepare a module for 246 /// a ThinLTO run. It works to minimize the IR which needs to be analyzed 247 /// without making irreversible decisions which could be made better during 248 /// the LTO run. 249 /// 250 /// Note that \p Level cannot be `O0` here. The pipelines produced are 251 /// only intended for use when attempting to optimize code. If frontends 252 /// require some transformations for semantic reasons, they should explicitly 253 /// build them. 254 ModulePassManager 255 buildThinLTOPreLinkDefaultPipeline(OptimizationLevel Level, 256 bool DebugLogging = false); 257 258 /// Build an ThinLTO default optimization pipeline to a pass manager. 259 /// 260 /// This provides a good default optimization pipeline for link-time 261 /// optimization and code generation. It is particularly tuned to fit well 262 /// when IR coming into the LTO phase was first run through \c 263 /// addPreLinkLTODefaultPipeline, and the two coordinate closely. 264 /// 265 /// Note that \p Level cannot be `O0` here. The pipelines produced are 266 /// only intended for use when attempting to optimize code. If frontends 267 /// require some transformations for semantic reasons, they should explicitly 268 /// build them. 269 ModulePassManager buildThinLTODefaultPipeline(OptimizationLevel Level, 270 bool DebugLogging = false); 271 272 /// Build a pre-link, LTO-targeting default optimization pipeline to a pass 273 /// manager. 274 /// 275 /// This adds the pre-link optimizations tuned to work well with a later LTO 276 /// run. It works to minimize the IR which needs to be analyzed without 277 /// making irreversible decisions which could be made better during the LTO 278 /// run. 279 /// 280 /// Note that \p Level cannot be `O0` here. The pipelines produced are 281 /// only intended for use when attempting to optimize code. If frontends 282 /// require some transformations for semantic reasons, they should explicitly 283 /// build them. 284 ModulePassManager buildLTOPreLinkDefaultPipeline(OptimizationLevel Level, 285 bool DebugLogging = false); 286 287 /// Build an LTO default optimization pipeline to a pass manager. 288 /// 289 /// This provides a good default optimization pipeline for link-time 290 /// optimization and code generation. It is particularly tuned to fit well 291 /// when IR coming into the LTO phase was first run through \c 292 /// addPreLinkLTODefaultPipeline, and the two coordinate closely. 293 /// 294 /// Note that \p Level cannot be `O0` here. The pipelines produced are 295 /// only intended for use when attempting to optimize code. If frontends 296 /// require some transformations for semantic reasons, they should explicitly 297 /// build them. 298 ModulePassManager buildLTODefaultPipeline(OptimizationLevel Level, 299 bool DebugLogging = false); 300 301 /// Build the default `AAManager` with the default alias analysis pipeline 302 /// registered. 303 AAManager buildDefaultAAPipeline(); 304 305 /// \brief Parse a textual pass pipeline description into a \c ModulePassManager. 306 /// 307 /// The format of the textual pass pipeline description looks something like: 308 /// 309 /// module(function(instcombine,sroa),dce,cgscc(inliner,function(...)),...) 310 /// 311 /// Pass managers have ()s describing the nest structure of passes. All passes 312 /// are comma separated. As a special shortcut, if the very first pass is not 313 /// a module pass (as a module pass manager is), this will automatically form 314 /// the shortest stack of pass managers that allow inserting that first pass. 315 /// So, assuming function passes 'fpassN', CGSCC passes 'cgpassN', and loop passes 316 /// 'lpassN', all of these are valid: 317 /// 318 /// fpass1,fpass2,fpass3 319 /// cgpass1,cgpass2,cgpass3 320 /// lpass1,lpass2,lpass3 321 /// 322 /// And they are equivalent to the following (resp.): 323 /// 324 /// module(function(fpass1,fpass2,fpass3)) 325 /// module(cgscc(cgpass1,cgpass2,cgpass3)) 326 /// module(function(loop(lpass1,lpass2,lpass3))) 327 /// 328 /// This shortcut is especially useful for debugging and testing small pass 329 /// combinations. Note that these shortcuts don't introduce any other magic. If 330 /// the sequence of passes aren't all the exact same kind of pass, it will be 331 /// an error. You cannot mix different levels implicitly, you must explicitly 332 /// form a pass manager in which to nest passes. 333 bool parsePassPipeline(ModulePassManager &MPM, StringRef PipelineText, 334 bool VerifyEachPass = true, bool DebugLogging = false); 335 336 /// Parse a textual alias analysis pipeline into the provided AA manager. 337 /// 338 /// The format of the textual AA pipeline is a comma separated list of AA 339 /// pass names: 340 /// 341 /// basic-aa,globals-aa,... 342 /// 343 /// The AA manager is set up such that the provided alias analyses are tried 344 /// in the order specified. See the \c AAManaager documentation for details 345 /// about the logic used. This routine just provides the textual mapping 346 /// between AA names and the analyses to register with the manager. 347 /// 348 /// Returns false if the text cannot be parsed cleanly. The specific state of 349 /// the \p AA manager is unspecified if such an error is encountered and this 350 /// returns false. 351 bool parseAAPipeline(AAManager &AA, StringRef PipelineText); 352 353 private: 354 /// A struct to capture parsed pass pipeline names. 355 struct PipelineElement { 356 StringRef Name; 357 std::vector<PipelineElement> InnerPipeline; 358 }; 359 360 static Optional<std::vector<PipelineElement>> 361 parsePipelineText(StringRef Text); 362 363 bool parseModulePass(ModulePassManager &MPM, const PipelineElement &E, 364 bool VerifyEachPass, bool DebugLogging); 365 bool parseCGSCCPass(CGSCCPassManager &CGPM, const PipelineElement &E, 366 bool VerifyEachPass, bool DebugLogging); 367 bool parseFunctionPass(FunctionPassManager &FPM, const PipelineElement &E, 368 bool VerifyEachPass, bool DebugLogging); 369 bool parseLoopPass(LoopPassManager &LPM, const PipelineElement &E, 370 bool VerifyEachPass, bool DebugLogging); 371 bool parseAAPassName(AAManager &AA, StringRef Name); 372 373 bool parseLoopPassPipeline(LoopPassManager &LPM, 374 ArrayRef<PipelineElement> Pipeline, 375 bool VerifyEachPass, bool DebugLogging); 376 bool parseFunctionPassPipeline(FunctionPassManager &FPM, 377 ArrayRef<PipelineElement> Pipeline, 378 bool VerifyEachPass, bool DebugLogging); 379 bool parseCGSCCPassPipeline(CGSCCPassManager &CGPM, 380 ArrayRef<PipelineElement> Pipeline, 381 bool VerifyEachPass, bool DebugLogging); 382 bool parseModulePassPipeline(ModulePassManager &MPM, 383 ArrayRef<PipelineElement> Pipeline, 384 bool VerifyEachPass, bool DebugLogging); 385 }; 386 } 387 388 #endif 389
