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 /// Build a per-module default optimization pipeline. 196 /// 197 /// This provides a good default optimization pipeline for per-module 198 /// optimization and code generation without any link-time optimization. It 199 /// typically correspond to frontend "-O[123]" options for optimization 200 /// levels \c O1, \c O2 and \c O3 resp. 201 /// 202 /// Note that \p Level cannot be `O0` here. The pipelines produced are 203 /// only intended for use when attempting to optimize code. If frontends 204 /// require some transformations for semantic reasons, they should explicitly 205 /// build them. 206 ModulePassManager buildPerModuleDefaultPipeline(OptimizationLevel Level, 207 bool DebugLogging = false); 208 209 /// Build a pre-link, LTO-targeting default optimization pipeline to a pass 210 /// manager. 211 /// 212 /// This adds the pre-link optimizations tuned to work well with a later LTO 213 /// run. It works to minimize the IR which needs to be analyzed without 214 /// making irreversible decisions which could be made better during the LTO 215 /// run. 216 /// 217 /// Note that \p Level cannot be `O0` here. The pipelines produced are 218 /// only intended for use when attempting to optimize code. If frontends 219 /// require some transformations for semantic reasons, they should explicitly 220 /// build them. 221 ModulePassManager buildLTOPreLinkDefaultPipeline(OptimizationLevel Level, 222 bool DebugLogging = false); 223 224 /// Build an LTO default optimization pipeline to a pass manager. 225 /// 226 /// This provides a good default optimization pipeline for link-time 227 /// optimization and code generation. It is particularly tuned to fit well 228 /// when IR coming into the LTO phase was first run through \c 229 /// addPreLinkLTODefaultPipeline, and the two coordinate closely. 230 /// 231 /// Note that \p Level cannot be `O0` here. The pipelines produced are 232 /// only intended for use when attempting to optimize code. If frontends 233 /// require some transformations for semantic reasons, they should explicitly 234 /// build them. 235 ModulePassManager buildLTODefaultPipeline(OptimizationLevel Level, 236 bool DebugLogging = false); 237 238 /// Build the default `AAManager` with the default alias analysis pipeline 239 /// registered. 240 AAManager buildDefaultAAPipeline(); 241 242 /// \brief Parse a textual pass pipeline description into a \c ModulePassManager. 243 /// 244 /// The format of the textual pass pipeline description looks something like: 245 /// 246 /// module(function(instcombine,sroa),dce,cgscc(inliner,function(...)),...) 247 /// 248 /// Pass managers have ()s describing the nest structure of passes. All passes 249 /// are comma separated. As a special shortcut, if the very first pass is not 250 /// a module pass (as a module pass manager is), this will automatically form 251 /// the shortest stack of pass managers that allow inserting that first pass. 252 /// So, assuming function passes 'fpassN', CGSCC passes 'cgpassN', and loop passes 253 /// 'lpassN', all of these are valid: 254 /// 255 /// fpass1,fpass2,fpass3 256 /// cgpass1,cgpass2,cgpass3 257 /// lpass1,lpass2,lpass3 258 /// 259 /// And they are equivalent to the following (resp.): 260 /// 261 /// module(function(fpass1,fpass2,fpass3)) 262 /// module(cgscc(cgpass1,cgpass2,cgpass3)) 263 /// module(function(loop(lpass1,lpass2,lpass3))) 264 /// 265 /// This shortcut is especially useful for debugging and testing small pass 266 /// combinations. Note that these shortcuts don't introduce any other magic. If 267 /// the sequence of passes aren't all the exact same kind of pass, it will be 268 /// an error. You cannot mix different levels implicitly, you must explicitly 269 /// form a pass manager in which to nest passes. 270 bool parsePassPipeline(ModulePassManager &MPM, StringRef PipelineText, 271 bool VerifyEachPass = true, bool DebugLogging = false); 272 273 /// Parse a textual alias analysis pipeline into the provided AA manager. 274 /// 275 /// The format of the textual AA pipeline is a comma separated list of AA 276 /// pass names: 277 /// 278 /// basic-aa,globals-aa,... 279 /// 280 /// The AA manager is set up such that the provided alias analyses are tried 281 /// in the order specified. See the \c AAManaager documentation for details 282 /// about the logic used. This routine just provides the textual mapping 283 /// between AA names and the analyses to register with the manager. 284 /// 285 /// Returns false if the text cannot be parsed cleanly. The specific state of 286 /// the \p AA manager is unspecified if such an error is encountered and this 287 /// returns false. 288 bool parseAAPipeline(AAManager &AA, StringRef PipelineText); 289 290 private: 291 /// A struct to capture parsed pass pipeline names. 292 struct PipelineElement { 293 StringRef Name; 294 std::vector<PipelineElement> InnerPipeline; 295 }; 296 297 static Optional<std::vector<PipelineElement>> 298 parsePipelineText(StringRef Text); 299 300 bool parseModulePass(ModulePassManager &MPM, const PipelineElement &E, 301 bool VerifyEachPass, bool DebugLogging); 302 bool parseCGSCCPass(CGSCCPassManager &CGPM, const PipelineElement &E, 303 bool VerifyEachPass, bool DebugLogging); 304 bool parseFunctionPass(FunctionPassManager &FPM, const PipelineElement &E, 305 bool VerifyEachPass, bool DebugLogging); 306 bool parseLoopPass(LoopPassManager &LPM, const PipelineElement &E, 307 bool VerifyEachPass, bool DebugLogging); 308 bool parseAAPassName(AAManager &AA, StringRef Name); 309 310 bool parseLoopPassPipeline(LoopPassManager &LPM, 311 ArrayRef<PipelineElement> Pipeline, 312 bool VerifyEachPass, bool DebugLogging); 313 bool parseFunctionPassPipeline(FunctionPassManager &FPM, 314 ArrayRef<PipelineElement> Pipeline, 315 bool VerifyEachPass, bool DebugLogging); 316 bool parseCGSCCPassPipeline(CGSCCPassManager &CGPM, 317 ArrayRef<PipelineElement> Pipeline, 318 bool VerifyEachPass, bool DebugLogging); 319 bool parseModulePassPipeline(ModulePassManager &MPM, 320 ArrayRef<PipelineElement> Pipeline, 321 bool VerifyEachPass, bool DebugLogging); 322 }; 323 } 324 325 #endif 326
