contrib/llvm/include/llvm/Passes/PassBuilder.h

   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