1 //===- Parsing, selection, and construction of pass pipelines --*- C++ -*--===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
11 /// Interfaces for registering analysis passes, producing common pass manager
12 /// configurations, and parsing of pass pipelines.
14 //===----------------------------------------------------------------------===//
16 #ifndef LLVM_PASSES_PASSBUILDER_H
17 #define LLVM_PASSES_PASSBUILDER_H
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"
30 /// A struct capturing PGO tunables.
32 std::string ProfileGenFile = "";
33 std::string ProfileUseFile = "";
34 bool RunProfileGen = false;
35 bool SamplePGO = false;
38 /// \brief This class provides access to building LLVM's passes.
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
46 Optional<PGOOptions> PGOOpt;
49 /// \brief LLVM-provided high-level optimization levels.
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.
59 /// Optimize quickly without destroying debuggability.
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
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.
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.
79 /// Optimize for fast execution as much as possible without triggering
80 /// significant incremental compile time or code size growth.
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.
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.
93 /// This is expected to be a good default optimization level for the vast
94 /// majority of users.
97 /// Optimize for fast execution as much as possible.
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.
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
113 /// Similar to \c O2 but tries to optimize for small code size instead of
114 /// fast execution without triggering significant incremental execution
117 /// The logic here is exactly the same as \c O2, but with code size and
118 /// execution time metrics swapped.
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.
125 /// A very specialized mode that will optimize for code size at any and all
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.
135 explicit PassBuilder(TargetMachine *TM = nullptr,
136 Optional<PGOOptions> PGOOpt = None)
137 : TM(TM), PGOOpt(PGOOpt) {}
139 /// \brief Cross register the analysis managers through their proxies.
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);
148 /// \brief Registers all available module analysis passes.
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);
156 /// \brief Registers all available CGSCC analysis passes.
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);
164 /// \brief Registers all available function analysis passes.
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);
172 /// \brief Registers all available loop analysis passes.
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);
179 /// Construct the core LLVM function canonicalization and simplification
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.
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
192 buildFunctionSimplificationPipeline(OptimizationLevel Level,
193 bool DebugLogging = false);
195 /// Build a per-module default optimization pipeline.
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.
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
206 ModulePassManager buildPerModuleDefaultPipeline(OptimizationLevel Level,
207 bool DebugLogging = false);
209 /// Build a pre-link, LTO-targeting default optimization pipeline to a pass
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
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
221 ModulePassManager buildLTOPreLinkDefaultPipeline(OptimizationLevel Level,
222 bool DebugLogging = false);
224 /// Build an LTO default optimization pipeline to a pass manager.
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.
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
235 ModulePassManager buildLTODefaultPipeline(OptimizationLevel Level,
236 bool DebugLogging = false);
238 /// Build the default `AAManager` with the default alias analysis pipeline
240 AAManager buildDefaultAAPipeline();
242 /// \brief Parse a textual pass pipeline description into a \c ModulePassManager.
244 /// The format of the textual pass pipeline description looks something like:
246 /// module(function(instcombine,sroa),dce,cgscc(inliner,function(...)),...)
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:
255 /// fpass1,fpass2,fpass3
256 /// cgpass1,cgpass2,cgpass3
257 /// lpass1,lpass2,lpass3
259 /// And they are equivalent to the following (resp.):
261 /// module(function(fpass1,fpass2,fpass3))
262 /// module(cgscc(cgpass1,cgpass2,cgpass3))
263 /// module(function(loop(lpass1,lpass2,lpass3)))
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);
273 /// Parse a textual alias analysis pipeline into the provided AA manager.
275 /// The format of the textual AA pipeline is a comma separated list of AA
278 /// basic-aa,globals-aa,...
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.
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
288 bool parseAAPipeline(AAManager &AA, StringRef PipelineText);
291 /// A struct to capture parsed pass pipeline names.
292 struct PipelineElement {
294 std::vector<PipelineElement> InnerPipeline;
297 static Optional<std::vector<PipelineElement>>
298 parsePipelineText(StringRef Text);
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);
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);