[MemProf] Templatize CallStackRadixTreeBuilder (NFC) (#117014)
[llvm-project.git] / mlir / docs / PassManagement.md
blob7b19a7bf6bf471eddbc04b6c3fc16b7219aacca1
1 # Pass Infrastructure
3 [TOC]
5 Passes represent the basic infrastructure for transformation and optimization.
6 This document provides an overview of the pass infrastructure in MLIR and how to
7 use it.
9 See [MLIR specification](LangRef.md) for more information about MLIR and its
10 core aspects, such as the IR structure and operations.
12 See [MLIR Rewrites](Tutorials/QuickstartRewrites.md) for a quick start on graph
13 rewriting in MLIR. If a transformation involves pattern matching operation DAGs,
14 this is a great place to start.
16 ## Operation Pass
18 In MLIR, the main unit of abstraction and transformation is an
19 [operation](LangRef.md/#operations). As such, the pass manager is designed to
20 work on instances of operations at different levels of nesting. In the following
21 paragraphs, we refer to the operation that a pass operates on as the "current
22 operation".
24 The structure of the [pass manager](#pass-manager), and the concept of nesting,
25 is detailed further below. All passes in MLIR derive from `OperationPass` and
26 adhere to the following restrictions; any noncompliance will lead to problematic
27 behavior in multithreaded and other advanced scenarios:
29 *   Must not inspect the state of operations that are siblings of the current
30     operation. Must neither access operations nested under those siblings.
31     *   Other threads may be modifying these operations in parallel.
32     *   Inspecting the state of ancestor/parent operations is permitted.
33 *   Must not modify the state of operations other than the operations that are
34     nested under the current operation. This includes adding, modifying or
35     removing other operations from an ancestor/parent block.
36     *   Other threads may be operating on these operations simultaneously.
37     *   As an exception, the attributes of the current operation may be modified
38         freely. This is the only way that the current operation may be modified.
39         (I.e., modifying operands, etc. is not allowed.)
40 *   Must not maintain mutable pass state across invocations of `runOnOperation`.
41     A pass may be run on many different operations with no guarantee of
42     execution order.
43     *   When multithreading, a specific pass instance may not even execute on
44         all operations within the IR. As such, a pass should not rely on running
45         on all operations.
46 *   Must not maintain any global mutable state, e.g. static variables within the
47     source file. All mutable state should be maintained by an instance of the
48     pass.
49 *   Must be copy-constructible
50     *   Multiple instances of the pass may be created by the pass manager to
51         process operations in parallel.
53 ### Op-Agnostic Operation Passes
55 By default, an operation pass is `op-agnostic`, meaning that it operates on the
56 operation type of the pass manager that it is added to. This means a pass may operate
57 on many different types of operations. Agnostic passes should be written such that
58 they do not make assumptions on the operation they run on. Examples of this type of pass are
59 [Canonicalization](Passes.md/#-canonicalize) and [Common Sub-Expression Elimination](Passes.md/#-cse).
61 To create an agnostic operation pass, a derived class must adhere to the following:
63 *   Inherit from the CRTP class `OperationPass`.
64 *   Override the virtual `void runOnOperation()` method.
66 A simple pass may look like:
68 ```c++
69 /// Here we utilize the CRTP `PassWrapper` utility class to provide some
70 /// necessary utility hooks. This is only necessary for passes defined directly
71 /// in C++. Passes defined declaratively use a cleaner mechanism for providing
72 /// these utilities.
73 struct MyOperationPass : public PassWrapper<MyOperationPass, OperationPass<>> {
74   void runOnOperation() override {
75     // Get the current operation being operated on.
76     Operation *op = getOperation();
77     ...
78   }
80 ```
82 ### Filtered Operation Pass
84 If a pass needs to constrain its execution to specific types or classes of operations,
85 additional filtering may be applied on top. This transforms a once `agnostic` pass into
86 one more specific to a certain context. There are various ways in which to filter the
87 execution of a pass, and different contexts in which filtering may apply:
89 ### Operation Pass: Static Schedule Filtering
91 Static filtering allows for applying additional constraints on the operation types a
92 pass may be scheduled on. This type of filtering generally allows for building more
93 constrained passes that can only be scheduled on operations that satisfy the necessary
94 constraints. For example, this allows for specifying passes that only run on operations
95 of a certain, those that provide a certain interface, trait, or some other constraint that
96 applies to all instances of that operation type. Below is an example of a pass that only
97 permits scheduling on operations that implement `FunctionOpInterface`:
99 ```c++
100 struct MyFunctionPass : ... {
101   /// This method is used to provide additional static filtering, and returns if the
102   /// pass may be scheduled on the given operation type.
103   bool canScheduleOn(RegisteredOperationName opInfo) const override {
104     return opInfo.hasInterface<FunctionOpInterface>();
105   }
107   void runOnOperation() {
108     // Here we can freely cast to FunctionOpInterface, because our `canScheduleOn` ensures
109     // that our pass is only executed on operations implementing that interface.
110     FunctionOpInterface op = cast<FunctionOpInterface>(getOperation()); 
111   }
115 When a pass with static filtering is added to an [`op-specific` pass manager](#oppassmanager),
116 it asserts that the operation type of the pass manager satisfies the static constraints of the
117 pass. When added to an [`op-agnostic` pass manager](#oppassmanager), that pass manager, and all
118 passes contained within, inherits the static constraints of the pass. For example, if the pass
119 filters on `FunctionOpInterface`, as in the `MyFunctionPass` example above, only operations that
120 implement `FunctionOpInterface` will be considered when executing **any** passes within the pass
121 manager. This invariant is important to keep in mind, as each pass added to an `op-agnostic` pass
122 manager further constrains the operations that may be scheduled on it. Consider the following example:
124 ```mlir
125 func.func @foo() {
126   // ...
127   return
130 module @someModule {
131   // ...
135 If we were to apply the op-agnostic pipeline, `any(cse,my-function-pass)`, to the above MLIR snippet
136 it would only run on the `foo` function operation. This is because the `my-function-pass` has a
137 static filtering constraint to only schedule on operations implementing `FunctionOpInterface`. Remember
138 that this constraint is inherited by the entire pass manager, so we never consider `someModule` for
139 any of the passes, including `cse` which normally can be scheduled on any operation.
141 #### Operation Pass: Static Filtering By Op Type
143 In the above section, we detailed a general mechanism for statically filtering the types of operations
144 that a pass may be scheduled on. Sugar is provided on top of that mechanism to simplify the definition
145 of passes that are restricted to scheduling on a single operation type. In these cases, a pass simply
146 needs to provide the type of operation to the `OperationPass` base class. This will automatically
147 instill filtering on that operation type:
149 ```c++
150 /// Here we utilize the CRTP `PassWrapper` utility class to provide some
151 /// necessary utility hooks. This is only necessary for passes defined directly
152 /// in C++. Passes defined declaratively use a cleaner mechanism for providing
153 /// these utilities.
154 struct MyFunctionPass : public PassWrapper<MyOperationPass, OperationPass<func::FuncOp>> {
155   void runOnOperation() {
156     // Get the current operation being operated on.
157     func::FuncOp op = getOperation();
158   }
162 #### Operation Pass: Static Filtering By Interface
164 In the above section, we detailed a general mechanism for statically filtering the types of operations
165 that a pass may be scheduled on. Sugar is provided on top of that mechanism to simplify the definition
166 of passes that are restricted to scheduling on a specific operation interface. In these cases, a pass
167 simply needs to inherit from the `InterfacePass` base class. This class is similar to `OperationPass`,
168 but expects the type of interface to operate on. This will automatically instill filtering on that
169 interface type:
171 ```c++
172 /// Here we utilize the CRTP `PassWrapper` utility class to provide some
173 /// necessary utility hooks. This is only necessary for passes defined directly
174 /// in C++. Passes defined declaratively use a cleaner mechanism for providing
175 /// these utilities.
176 struct MyFunctionPass : public PassWrapper<MyOperationPass, InterfacePass<FunctionOpInterface>> {
177   void runOnOperation() {
178     // Get the current operation being operated on.
179     FunctionOpInterface op = getOperation();
180   }
184 ### Dependent Dialects
186 Dialects must be loaded in the MLIRContext before entities from these dialects
187 (operations, types, attributes, ...) can be created. Dialects must also be
188 loaded before starting the execution of a multi-threaded pass pipeline. To this
189 end, a pass that may create an entity from a dialect that isn't guaranteed to
190 already be loaded must express this by overriding the `getDependentDialects()`
191 method and declare this list of Dialects explicitly.
192 See also the `dependentDialects` field in the
193 [TableGen Specification](#tablegen-specification).
195 ### Initialization
197 In certain situations, a Pass may contain state that is constructed dynamically,
198 but is potentially expensive to recompute in successive runs of the Pass. One
199 such example is when using [`PDL`-based](Dialects/PDLOps.md)
200 [patterns](PatternRewriter.md), which are compiled into a bytecode during
201 runtime. In these situations, a pass may override the following hook to
202 initialize this heavy state:
204 *   `LogicalResult initialize(MLIRContext *context)`
206 This hook is executed once per run of a full pass pipeline, meaning that it does
207 not have access to the state available during a `runOnOperation` call. More
208 concretely, all necessary accesses to an `MLIRContext` should be driven via the
209 provided `context` parameter, and methods that utilize "per-run" state such as
210 `getContext`/`getOperation`/`getAnalysis`/etc. must not be used.
211 In case of an error during initialization, the pass is expected to emit an error
212 diagnostic and return a `failure()` which will abort the pass pipeline execution.
214 ## Analysis Management
216 An important concept, along with transformation passes, are analyses. These are
217 conceptually similar to transformation passes, except that they compute
218 information on a specific operation without modifying it. In MLIR, analyses are
219 not passes but free-standing classes that are computed lazily on-demand and
220 cached to avoid unnecessary recomputation. An analysis in MLIR must adhere to
221 the following:
223 *   Provide a valid constructor taking either an `Operation*` or `Operation*`
224     and `AnalysisManager &`.
225     *   The provided `AnalysisManager &` should be used to query any necessary
226         analysis dependencies.
227 *   Must not modify the given operation.
229 An analysis may provide additional hooks to control various behavior:
231 *   `bool isInvalidated(const AnalysisManager::PreservedAnalyses &)`
233 Given a preserved analysis set, the analysis returns true if it should truly be
234 invalidated. This allows for more fine-tuned invalidation in cases where an
235 analysis wasn't explicitly marked preserved, but may be preserved (or
236 invalidated) based upon other properties such as analyses sets. If the analysis
237 uses any other analysis as a dependency, it must also check if the dependency
238 was invalidated.
240 ### Querying Analyses
242 The base `OperationPass` class provides utilities for querying and preserving
243 analyses for the current operation being processed.
245 *   OperationPass automatically provides the following utilities for querying
246     analyses:
247     *   `getAnalysis<>`
248         -   Get an analysis for the current operation, constructing it if
249             necessary.
250     *   `getCachedAnalysis<>`
251         -   Get an analysis for the current operation, if it already exists.
252     *   `getCachedParentAnalysis<>`
253         -   Get an analysis for a given parent operation, if it exists.
254     *   `getCachedChildAnalysis<>`
255         -   Get an analysis for a given child operation, if it exists.
256     *   `getChildAnalysis<>`
257         -   Get an analysis for a given child operation, constructing it if
258             necessary.
260 Using the example passes defined above, let's see some examples:
262 ```c++
263 /// An interesting analysis.
264 struct MyOperationAnalysis {
265   // Compute this analysis with the provided operation.
266   MyOperationAnalysis(Operation *op);
269 struct MyOperationAnalysisWithDependency {
270   MyOperationAnalysisWithDependency(Operation *op, AnalysisManager &am) {
271     // Request other analysis as dependency
272     MyOperationAnalysis &otherAnalysis = am.getAnalysis<MyOperationAnalysis>();
273     ...
274   }
276   bool isInvalidated(const AnalysisManager::PreservedAnalyses &pa) {
277     // Check if analysis or its dependency were invalidated
278     return !pa.isPreserved<MyOperationAnalysisWithDependency>() ||
279            !pa.isPreserved<MyOperationAnalysis>();
280   }
283 void MyOperationPass::runOnOperation() {
284   // Query MyOperationAnalysis for the current operation.
285   MyOperationAnalysis &myAnalysis = getAnalysis<MyOperationAnalysis>();
287   // Query a cached instance of MyOperationAnalysis for the current operation.
288   // It will not be computed if it doesn't exist.
289   auto optionalAnalysis = getCachedAnalysis<MyOperationAnalysis>();
290   if (optionalAnalysis)
291     ...
293   // Query a cached instance of MyOperationAnalysis for the parent operation of
294   // the current operation. It will not be computed if it doesn't exist.
295   auto optionalAnalysis = getCachedParentAnalysis<MyOperationAnalysis>();
296   if (optionalAnalysis)
297     ...
301 ### Preserving Analyses
303 Analyses that are constructed after being queried by a pass are cached to avoid
304 unnecessary computation if they are requested again later. To avoid stale
305 analyses, all analyses are assumed to be invalidated by a pass. To avoid
306 invalidation, a pass must specifically mark analyses that are known to be
307 preserved.
309 *   All Pass classes automatically provide the following utilities for
310     preserving analyses:
311     *   `markAllAnalysesPreserved`
312     *   `markAnalysesPreserved<>`
314 ```c++
315 void MyOperationPass::runOnOperation() {
316   // Mark all analyses as preserved. This is useful if a pass can guarantee
317   // that no transformation was performed.
318   markAllAnalysesPreserved();
320   // Mark specific analyses as preserved. This is used if some transformation
321   // was performed, but some analyses were either unaffected or explicitly
322   // preserved.
323   markAnalysesPreserved<MyAnalysis, MyAnalyses...>();
327 ## Pass Failure
329 Passes in MLIR are allowed to gracefully fail. This may happen if some invariant
330 of the pass was broken, potentially leaving the IR in some invalid state. If
331 such a situation occurs, the pass can directly signal a failure to the pass
332 manager via the `signalPassFailure` method. If a pass signaled a failure when
333 executing, no other passes in the pipeline will execute and the top-level call
334 to `PassManager::run` will return `failure`.
336 ```c++
337 void MyOperationPass::runOnOperation() {
338   // Signal failure on a broken invariant.
339   if (some_broken_invariant)
340     return signalPassFailure();
344 ## Pass Manager
346 The above sections introduced the different types of passes and their
347 invariants. This section introduces the concept of a PassManager, and how it can
348 be used to configure and schedule a pass pipeline. There are two main classes
349 related to pass management, the `PassManager` and the `OpPassManager`. The
350 `PassManager` class acts as the top-level entry point, and contains various
351 configurations used for the entire pass pipeline. The `OpPassManager` class is
352 used to schedule passes to run at a specific level of nesting. The top-level
353 `PassManager` also functions as an `OpPassManager`.
355 ### OpPassManager
357 An `OpPassManager` is essentially a collection of passes anchored to execute on
358 operations at a given level of nesting. A pass manager may be `op-specific`
359 (anchored on a specific operation type), or `op-agnostic` (not restricted to any
360 specific operation, and executed on any viable operation type). Operation types that
361 anchor pass managers must adhere to the following requirement:
363 *   Must be registered and marked
364     [`IsolatedFromAbove`](Traits/#isolatedfromabove).
366     *   Passes are expected not to modify operations at or above the current
367         operation being processed. If the operation is not isolated, it may
368         inadvertently modify or traverse the SSA use-list of an operation it is
369         not supposed to.
371 Passes can be added to a pass manager via `addPass`.
373 An `OpPassManager` is generally created by explicitly nesting a pipeline within
374 another existing `OpPassManager` via the `nest<OpT>` or `nestAny` methods. The
375 former method takes the operation type that the nested pass manager will operate on.
376 The latter method nests an `op-agnostic` pass manager, that may run on any viable
377 operation type. Nesting in this sense, corresponds to the
378 [structural](Tutorials/UnderstandingTheIRStructure.md) nesting within
379 [Regions](LangRef.md/#regions) of the IR.
381 For example, the following `.mlir`:
383 ```mlir
384 module {
385   spirv.module "Logical" "GLSL450" {
386     func @foo() {
387       ...
388     }
389   }
393 Has the nesting structure of:
396 `builtin.module`
397   `spirv.module`
398     `spirv.func`
401 Below is an example of constructing a pipeline that operates on the above
402 structure:
404 ```c++
405 // Create a top-level `PassManager` class.
406 auto pm = PassManager::on<ModuleOp>(ctx);
408 // Add a pass on the top-level module operation.
409 pm.addPass(std::make_unique<MyModulePass>());
411 // Nest a pass manager that operates on `spirv.module` operations nested
412 // directly under the top-level module.
413 OpPassManager &nestedModulePM = pm.nest<spirv::ModuleOp>();
414 nestedModulePM.addPass(std::make_unique<MySPIRVModulePass>());
416 // Nest a pass manager that operates on functions within the nested SPIRV
417 // module.
418 OpPassManager &nestedFunctionPM = nestedModulePM.nest<func::FuncOp>();
419 nestedFunctionPM.addPass(std::make_unique<MyFunctionPass>());
421 // Nest an op-agnostic pass manager. This will operate on any viable
422 // operation, e.g. func.func, spirv.func, spirv.module, builtin.module, etc.
423 OpPassManager &nestedAnyPM = nestedModulePM.nestAny();
424 nestedAnyPM.addPass(createCanonicalizePass());
425 nestedAnyPM.addPass(createCSEPass());
427 // Run the pass manager on the top-level module.
428 ModuleOp m = ...;
429 if (failed(pm.run(m)))
430     ... // One of the passes signaled a failure.
433 The above pass manager contains the following pipeline structure:
436 OpPassManager<ModuleOp>
437   MyModulePass
438   OpPassManager<spirv::ModuleOp>
439     MySPIRVModulePass
440     OpPassManager<func::FuncOp>
441       MyFunctionPass
442     OpPassManager<>
443       Canonicalizer
444       CSE
447 These pipelines are then run over a single operation at a time. This means that,
448 for example, given a series of consecutive passes on func::FuncOp, it will execute all
449 on the first function, then all on the second function, etc. until the entire
450 program has been run through the passes. This provides several benefits:
452 *   This improves the cache behavior of the compiler, because it is only
453     touching a single function at a time, instead of traversing the entire
454     program.
455 *   This improves multi-threading performance by reducing the number of jobs
456     that need to be scheduled, as well as increasing the efficiency of each job.
457     An entire function pipeline can be run on each function asynchronously.
459 ## Dynamic Pass Pipelines
461 In some situations it may be useful to run a pass pipeline within another pass,
462 to allow configuring or filtering based on some invariants of the current
463 operation being operated on. For example, the
464 [Inliner Pass](Passes.md/#-inline) may want to run
465 intraprocedural simplification passes while it is inlining to produce a better
466 cost model, and provide more optimal inlining. To enable this, passes may run an
467 arbitrary `OpPassManager` on the current operation being operated on or any
468 operation nested within the current operation via the `LogicalResult
469 Pass::runPipeline(OpPassManager &, Operation *)` method. This method returns
470 whether the dynamic pipeline succeeded or failed, similarly to the result of the
471 top-level `PassManager::run` method. A simple example is shown below:
473 ```c++
474 void MyModulePass::runOnOperation() {
475   ModuleOp module = getOperation();
476   if (hasSomeSpecificProperty(module)) {
477     OpPassManager dynamicPM("builtin.module");
478     ...; // Build the dynamic pipeline.
479     if (failed(runPipeline(dynamicPM, module)))
480       return signalPassFailure();
481   }
485 Note: though above the dynamic pipeline was constructed within the
486 `runOnOperation` method, this is not necessary and pipelines should be cached
487 when possible as the `OpPassManager` class can be safely copy constructed.
489 The mechanism described in this section should be used whenever a pass pipeline
490 should run in a nested fashion, i.e. when the nested pipeline cannot be
491 scheduled statically along with the rest of the main pass pipeline. More
492 specifically, a `PassManager` should generally never need to be constructed
493 within a `Pass`. Using `runPipeline` also ensures that all analyses,
494 [instrumentations](#pass-instrumentation), and other pass manager related
495 components are integrated with the dynamic pipeline being executed.
497 ## Instance Specific Pass Options
499 MLIR provides a builtin mechanism for passes to specify options that configure
500 its behavior. These options are parsed at pass construction time independently
501 for each instance of the pass. Options are defined using the `Option<>` and
502 `ListOption<>` classes, and generally follow the
503 [LLVM command line](https://llvm.org/docs/CommandLine.html) flag definition
504 rules. One major distinction from the LLVM command line functionality is that
505 all `ListOption`s are comma-separated, and delimited sub-ranges within individual
506 elements of the list may contain commas that are not treated as separators for the
507 top-level list.
509 ```c++
510 struct MyPass ... {
511   /// Make sure that we have a valid default constructor and copy constructor to
512   /// ensure that the options are initialized properly.
513   MyPass() = default;
514   MyPass(const MyPass& pass) {}
516   /// Any parameters after the description are forwarded to llvm::cl::list and
517   /// llvm::cl::opt respectively.
518   Option<int> exampleOption{*this, "flag-name", llvm::cl::desc("...")};
519   ListOption<int> exampleListOption{*this, "list-flag-name", llvm::cl::desc("...")};
523 For pass pipelines, the `PassPipelineRegistration` templates take an additional
524 template parameter for an optional `Option` struct definition. This struct
525 should inherit from `mlir::PassPipelineOptions` and contain the desired pipeline
526 options. When using `PassPipelineRegistration`, the constructor now takes a
527 function with the signature `void (OpPassManager &pm, const MyPipelineOptions&)`
528 which should construct the passes from the options and pass them to the pm:
530 ```c++
531 struct MyPipelineOptions : public PassPipelineOptions {
532   // The structure of these options is the same as those for pass options.
533   Option<int> exampleOption{*this, "flag-name", llvm::cl::desc("...")};
534   ListOption<int> exampleListOption{*this, "list-flag-name",
535                                     llvm::cl::desc("...")};
538 void registerMyPasses() {
539   PassPipelineRegistration<MyPipelineOptions>(
540     "example-pipeline", "Run an example pipeline.",
541     [](OpPassManager &pm, const MyPipelineOptions &pipelineOptions) {
542       // Initialize the pass manager.
543     });
547 ## Pass Statistics
549 Statistics are a way to keep track of what the compiler is doing and how
550 effective various transformations are. It is often useful to see what effect
551 specific transformations have on a particular input, and how often they trigger.
552 Pass statistics are specific to each pass instance, which allow for seeing the
553 effect of placing a particular transformation at specific places within the pass
554 pipeline. For example, they help answer questions like "What happens if I run
555 CSE again here?".
557 Statistics can be added to a pass by using the 'Pass::Statistic' class. This
558 class takes as a constructor arguments: the parent pass, a name, and a
559 description. This class acts like an atomic unsigned integer, and may be
560 incremented and updated accordingly. These statistics rely on the same
561 infrastructure as
562 [`llvm::Statistic`](http://llvm.org/docs/ProgrammersManual.html#the-statistic-class-stats-option)
563 and thus have similar usage constraints. Collected statistics can be dumped by
564 the [pass manager](#pass-manager) programmatically via
565 `PassManager::enableStatistics`; or via `-mlir-pass-statistics` and
566 `-mlir-pass-statistics-display` on the command line.
568 An example is shown below:
570 ```c++
571 struct MyPass ... {
572   /// Make sure that we have a valid default constructor and copy constructor to
573   /// ensure that the options are initialized properly.
574   MyPass() = default;
575   MyPass(const MyPass& pass) {}
576   StringRef getArgument() const final {
577     // This is the argument used to refer to the pass in
578     // the textual format (on the commandline for example).
579     return "argument";
580   }
581   StringRef getDescription() const final {
582     // This is a brief description of the pass.
583     return  "description";
584   }
585   /// Define the statistic to track during the execution of MyPass.
586   Statistic exampleStat{this, "exampleStat", "An example statistic"};
588   void runOnOperation() {
589     ...
591     // Update the statistic after some invariant was hit.
592     ++exampleStat;
594     ...
595   }
599 The collected statistics may be aggregated in two types of views:
601 A pipeline view that models the structure of the pass manager, this is the
602 default view:
604 ```shell
605 $ mlir-opt -pass-pipeline='any(func.func(my-pass,my-pass))' foo.mlir -mlir-pass-statistics
607 ===-------------------------------------------------------------------------===
608                          ... Pass statistics report ...
609 ===-------------------------------------------------------------------------===
610 'func.func' Pipeline
611   MyPass
612     (S) 15 exampleStat - An example statistic
613   VerifierPass
614   MyPass
615     (S)  6 exampleStat - An example statistic
616   VerifierPass
617 VerifierPass
620 A list view that aggregates the statistics of all instances of a specific pass
621 together:
623 ```shell
624 $ mlir-opt -pass-pipeline='any(func.func(my-pass,my-pass))' foo.mlir -mlir-pass-statistics -mlir-pass-statistics-display=list
626 ===-------------------------------------------------------------------------===
627                          ... Pass statistics report ...
628 ===-------------------------------------------------------------------------===
629 MyPass
630   (S) 21 exampleStat - An example statistic
633 ## Pass Registration
635 Briefly shown in the example definitions of the various pass types is the
636 `PassRegistration` class. This mechanism allows for registering pass classes so
637 that they may be created within a
638 [textual pass pipeline description](#textual-pass-pipeline-specification). An
639 example registration is shown below:
641 ```c++
642 void registerMyPass() {
643   PassRegistration<MyPass>();
647 *   `MyPass` is the name of the derived pass class.
648 *   The pass `getArgument()` method is used to get the identifier that will be
649     used to refer to the pass.
650 *   The pass `getDescription()` method provides a short summary describing the
651     pass.
653 For passes that cannot be default-constructed, `PassRegistration` accepts an
654 optional argument that takes a callback to create the pass:
656 ```c++
657 void registerMyPass() {
658   PassRegistration<MyParametricPass>(
659     []() -> std::unique_ptr<Pass> {
660       std::unique_ptr<Pass> p = std::make_unique<MyParametricPass>(/*options*/);
661       /*... non-trivial-logic to configure the pass ...*/;
662       return p;
663     });
667 This variant of registration can be used, for example, to accept the
668 configuration of a pass from command-line arguments and pass it to the pass
669 constructor.
671 Note: Make sure that the pass is copy-constructible in a way that does not share
672 data as the [pass manager](#pass-manager) may create copies of the pass to run
673 in parallel.
675 ### Pass Pipeline Registration
677 Described above is the mechanism used for registering a specific derived pass
678 class. On top of that, MLIR allows for registering custom pass pipelines in a
679 similar fashion. This allows for custom pipelines to be available to tools like
680 mlir-opt in the same way that passes are, which is useful for encapsulating
681 common pipelines like the "-O1" series of passes. Pipelines are registered via a
682 similar mechanism to passes in the form of `PassPipelineRegistration`. Compared
683 to `PassRegistration`, this class takes an additional parameter in the form of a
684 pipeline builder that modifies a provided `OpPassManager`.
686 ```c++
687 void pipelineBuilder(OpPassManager &pm) {
688   pm.addPass(std::make_unique<MyPass>());
689   pm.addPass(std::make_unique<MyOtherPass>());
692 void registerMyPasses() {
693   // Register an existing pipeline builder function.
694   PassPipelineRegistration<>(
695     "argument", "description", pipelineBuilder);
697   // Register an inline pipeline builder.
698   PassPipelineRegistration<>(
699     "argument", "description", [](OpPassManager &pm) {
700       pm.addPass(std::make_unique<MyPass>());
701       pm.addPass(std::make_unique<MyOtherPass>());
702     });
706 ### Textual Pass Pipeline Specification
708 The previous sections detailed how to register passes and pass pipelines with a
709 specific argument and description. Once registered, these can be used to
710 configure a pass manager from a string description. This is especially useful
711 for tools like `mlir-opt`, that configure pass managers from the command line,
712 or as options to passes that utilize
713 [dynamic pass pipelines](#dynamic-pass-pipelines).
715 To support the ability to describe the full structure of pass pipelines, MLIR
716 supports a custom textual description of pass pipelines. The textual description
717 includes the nesting structure, the arguments of the passes and pass pipelines
718 to run, and any options for those passes and pipelines. A textual pipeline is
719 defined as a series of names, each of which may in itself recursively contain a
720 nested pipeline description. The syntax for this specification is as follows:
722 ```ebnf
723 pipeline          ::= op-anchor `(` pipeline-element (`,` pipeline-element)* `)`
724 pipeline-element  ::= pipeline | (pass-name | pass-pipeline-name) options?
725 options           ::= '{' (key ('=' value)?)+ '}'
728 *   `op-anchor`
729     *   This corresponds to the mnemonic name that anchors the execution of the
730         pass manager. This is either the name of an operation to run passes on,
731         e.g. `func.func` or `builtin.module`, or `any`, for op-agnostic pass
732         managers that execute on any viable operation (i.e. any operation that
733         can be used to anchor a pass manager).
734 *   `pass-name` | `pass-pipeline-name`
735     *   This corresponds to the argument of a registered pass or pass pipeline,
736         e.g. `cse` or `canonicalize`.
737 *   `options`
738     *   Options are specific key value pairs representing options defined by a
739         pass or pass pipeline, as described in the
740         ["Instance Specific Pass Options"](#instance-specific-pass-options)
741         section. See this section for an example usage in a textual pipeline.
743 For example, the following pipeline:
745 ```shell
746 $ mlir-opt foo.mlir -cse -canonicalize -convert-func-to-llvm='use-bare-ptr-memref-call-conv=1'
749 Can also be specified as (via the `-pass-pipeline` flag):
751 ```shell
752 # Anchor the cse and canonicalize passes on the `func.func` operation.
753 $ mlir-opt foo.mlir -pass-pipeline='builtin.module(func.func(cse,canonicalize),convert-func-to-llvm{use-bare-ptr-memref-call-conv=1})'
755 # Anchor the cse and canonicalize passes on "any" viable root operation.
756 $ mlir-opt foo.mlir -pass-pipeline='builtin.module(any(cse,canonicalize),convert-func-to-llvm{use-bare-ptr-memref-call-conv=1})'
759 In order to support round-tripping a pass to the textual representation using
760 `OpPassManager::printAsTextualPipeline(raw_ostream&)`, override `StringRef
761 Pass::getArgument()` to specify the argument used when registering a pass.
763 ## Declarative Pass Specification
765 Some aspects of a Pass may be specified declaratively, in a form similar to
766 [operations](DefiningDialects/Operations.md). This specification simplifies several mechanisms
767 used when defining passes. It can be used for generating pass registration
768 calls, defining boilerplate pass utilities, and generating pass documentation.
770 Consider the following pass specified in C++:
772 ```c++
773 struct MyPass : PassWrapper<MyPass, OperationPass<ModuleOp>> {
774   MyPass() = default;
775   MyPass(const MyPass &) {}
777   ...
779   // Specify any options.
780   Option<bool> option{
781       *this, "example-option",
782       llvm::cl::desc("An example option"), llvm::cl::init(true)};
783   ListOption<int64_t> listOption{
784       *this, "example-list",
785       llvm::cl::desc("An example list option")};
787   // Specify any statistics.
788   Statistic statistic{this, "example-statistic", "An example statistic"};
791 /// Expose this pass to the outside world.
792 std::unique_ptr<Pass> foo::createMyPass() {
793   return std::make_unique<MyPass>();
796 /// Register this pass.
797 void foo::registerMyPass() {
798   PassRegistration<MyPass>();
802 This pass may be specified declaratively as so:
804 ```tablegen
805 def MyPass : Pass<"my-pass", "ModuleOp"> {
806   let summary = "My Pass Summary";
807   let description = [{
808     Here we can now give a much larger description of `MyPass`, including all of
809     its various constraints and behavior.
810   }];
812   // A constructor must be provided to specify how to create a default instance
813   // of MyPass. It can be skipped for this specific example, because both the
814   // constructor and the registration methods live in the same namespace.
815   let constructor = "foo::createMyPass()";
817   // Specify any options.
818   let options = [
819     Option<"option", "example-option", "bool", /*default=*/"true",
820            "An example option">,
821     ListOption<"listOption", "example-list", "int64_t",
822                "An example list option">
823   ];
825   // Specify any statistics.
826   let statistics = [
827     Statistic<"statistic", "example-statistic", "An example statistic">
828   ];
832 Using the `gen-pass-decls` generator, we can generate most of the boilerplate
833 above automatically. This generator takes as an input a `-name` parameter, that
834 provides a tag for the group of passes that are being generated. This generator
835 produces code with multiple purposes:
837 The first is to register the declared passes with the global registry. For
838 each pass, the generator produces a `registerPassName` where
839 `PassName` is the name of the definition specified in tablegen. It also
840 generates a `registerGroupPasses`, where `Group` is the tag provided via the
841 `-name` input parameter, that registers all of the passes present.
843 ```c++
844 // Tablegen options: -gen-pass-decls -name="Example"
846 // Passes.h
848 namespace foo {
849 #define GEN_PASS_REGISTRATION
850 #include "Passes.h.inc"
851 } // namespace foo
853 void registerMyPasses() {
854   // Register all of the passes.
855   foo::registerExamplePasses();
856   
857   // Or
859   // Register `MyPass` specifically.
860   foo::registerMyPass();
864 The second is to provide a way to configure the pass options. These classes are
865 named in the form of `MyPassOptions`, where `MyPass` is the name of the pass
866 definition in tablegen. The configurable parameters reflect the options declared
867 in the tablegen file. These declarations can be enabled for the whole group of
868 passes by defining the `GEN_PASS_DECL` macro, or on a per-pass basis by defining
869 `GEN_PASS_DECL_PASSNAME` where `PASSNAME` is the uppercase version of the name
870 specified in tablegen.
872 ```c++
873 // .h.inc
875 #ifdef GEN_PASS_DECL_MYPASS
877 struct MyPassOptions {
878     bool option = true;
879     ::llvm::ArrayRef<int64_t> listOption;
882 #undef GEN_PASS_DECL_MYPASS
883 #endif // GEN_PASS_DECL_MYPASS
886 If the `constructor` field has not been specified in the tablegen declaration,
887 then autogenerated file will also contain the declarations of the default
888 constructors.
890 ```c++
891 // .h.inc
893 #ifdef GEN_PASS_DECL_MYPASS
896 std::unique_ptr<::mlir::Pass> createMyPass();
897 std::unique_ptr<::mlir::Pass> createMyPass(const MyPassOptions &options);
899 #undef GEN_PASS_DECL_MYPASS
900 #endif // GEN_PASS_DECL_MYPASS
903 The last purpose of this generator is to emit a base class for each of the
904 passes, containing most of the boiler plate related to pass definitions. These
905 classes are named in the form of `MyPassBase` and are declared inside the
906 `impl` namespace, where `MyPass` is the name of the pass definition in
907 tablegen. We can update the original C++ pass definition as so:
909 ```c++
910 // MyPass.cpp
912 /// Include the generated base pass class definitions.
913 namespace foo {
914 #define GEN_PASS_DEF_MYPASS
915 #include "Passes.h.inc"
918 /// Define the main class as deriving from the generated base class.
919 struct MyPass : foo::impl::MyPassBase<MyPass> {
920   using MyPassBase::MyPassBase;
922   /// The definitions of the options and statistics are now generated within
923   /// the base class, but are accessible in the same way.
927 These definitions can be enabled on a per-pass basis by defining the appropriate
928 preprocessor `GEN_PASS_DEF_PASSNAME` macro, with `PASSNAME` equal to the
929 uppercase version of the name of the pass definition in tablegen.
930 If the `constructor` field has not been specified in tablegen, then the default
931 constructors are also defined and expect the name of the actual pass class to
932 be equal to the name defined in tablegen.
934 Using the `gen-pass-doc` generator, markdown documentation for each of the
935 passes can be generated. See [Passes.md](Passes.md) for example output of real
936 MLIR passes.
938 ### Tablegen Specification
940 The `Pass` class is used to begin a new pass definition. This class takes as an
941 argument the registry argument to attribute to the pass, as well as an optional
942 string corresponding to the operation type that the pass operates on. The class
943 contains the following fields:
945 *   `summary`
946     -   A short one-line summary of the pass, used as the description when
947         registering the pass.
948 *   `description`
949     -   A longer, more detailed description of the pass. This is used when
950         generating pass documentation.
951 *   `dependentDialects`
952     -   A list of strings representing the `Dialect` classes this pass may
953         introduce entities, Attributes/Operations/Types/etc., of.
954 *   `constructor`
955     -   A code block used to create a default instance of the pass.
956 *   `options`
957     -   A list of pass options used by the pass.
958 *   `statistics`
959     -   A list of pass statistics used by the pass.
961 #### Options
963 Options may be specified via the `Option` and `ListOption` classes. The `Option`
964 class takes the following template parameters:
966 *   C++ variable name
967     -   A name to use for the generated option variable.
968 *   argument
969     -   The argument name of the option.
970 *   type
971     -   The C++ type of the option.
972 *   default value
973     -   The default option value.
974 *   description
975     -   A one-line description of the option.
976 *   additional option flags
977     -   A string containing any additional options necessary to construct the
978         option.
980 ```tablegen
981 def MyPass : Pass<"my-pass"> {
982   let options = [
983     Option<"option", "example-option", "bool", /*default=*/"true",
984            "An example option">,
985   ];
989 The `ListOption` class takes the following fields:
991 *   C++ variable name
992     -   A name to use for the generated option variable.
993 *   argument
994     -   The argument name of the option.
995 *   element type
996     -   The C++ type of the list element.
997 *   description
998     -   A one-line description of the option.
999 *   additional option flags
1000     -   A string containing any additional options necessary to construct the
1001         option.
1003 ```tablegen
1004 def MyPass : Pass<"my-pass"> {
1005   let options = [
1006     ListOption<"listOption", "example-list", "int64_t",
1007                "An example list option">
1008   ];
1012 #### Statistic
1014 Statistics may be specified via the `Statistic`, which takes the following
1015 template parameters:
1017 *   C++ variable name
1018     -   A name to use for the generated statistic variable.
1019 *   display name
1020     -   The name used when displaying the statistic.
1021 *   description
1022     -   A one-line description of the statistic.
1024 ```tablegen
1025 def MyPass : Pass<"my-pass"> {
1026   let statistics = [
1027     Statistic<"statistic", "example-statistic", "An example statistic">
1028   ];
1032 ## Pass Instrumentation
1034 MLIR provides a customizable framework to instrument pass execution and analysis
1035 computation, via the `PassInstrumentation` class. This class provides hooks into
1036 the PassManager that observe various events:
1038 *   `runBeforePipeline`
1039     *   This callback is run just before a pass pipeline, i.e. pass manager, is
1040         executed.
1041 *   `runAfterPipeline`
1042     *   This callback is run right after a pass pipeline has been executed,
1043         successfully or not.
1044 *   `runBeforePass`
1045     *   This callback is run just before a pass is executed.
1046 *   `runAfterPass`
1047     *   This callback is run right after a pass has been successfully executed.
1048         If this hook is executed, `runAfterPassFailed` will *not* be.
1049 *   `runAfterPassFailed`
1050     *   This callback is run right after a pass execution fails. If this hook is
1051         executed, `runAfterPass` will *not* be.
1052 *   `runBeforeAnalysis`
1053     *   This callback is run just before an analysis is computed.
1054     *   If the analysis requested another analysis as a dependency, the
1055         `runBeforeAnalysis`/`runAfterAnalysis` pair for the dependency can be
1056         called from inside of the current `runBeforeAnalysis`/`runAfterAnalysis`
1057         pair.
1058 *   `runAfterAnalysis`
1059     *   This callback is run right after an analysis is computed.
1061 PassInstrumentation instances may be registered directly with a
1062 [PassManager](#pass-manager) instance via the `addInstrumentation` method.
1063 Instrumentations added to the PassManager are run in a stack like fashion, i.e.
1064 the last instrumentation to execute a `runBefore*` hook will be the first to
1065 execute the respective `runAfter*` hook. The hooks of a `PassInstrumentation`
1066 class are guaranteed to be executed in a thread-safe fashion, so additional
1067 synchronization is not necessary. Below in an example instrumentation that
1068 counts the number of times the `DominanceInfo` analysis is computed:
1070 ```c++
1071 struct DominanceCounterInstrumentation : public PassInstrumentation {
1072   /// The cumulative count of how many times dominance has been calculated.
1073   unsigned &count;
1075   DominanceCounterInstrumentation(unsigned &count) : count(count) {}
1076   void runAfterAnalysis(llvm::StringRef, TypeID id, Operation *) override {
1077     if (id == TypeID::get<DominanceInfo>())
1078       ++count;
1079   }
1082 MLIRContext *ctx = ...;
1083 PassManager pm(ctx);
1085 // Add the instrumentation to the pass manager.
1086 unsigned domInfoCount;
1087 pm.addInstrumentation(
1088     std::make_unique<DominanceCounterInstrumentation>(domInfoCount));
1090 // Run the pass manager on a module operation.
1091 ModuleOp m = ...;
1092 if (failed(pm.run(m)))
1093     ...
1095 llvm::errs() << "DominanceInfo was computed " << domInfoCount << " times!\n";
1098 ### Standard Instrumentations
1100 MLIR utilizes the pass instrumentation framework to provide a few useful
1101 developer tools and utilities. Each of these instrumentations are directly
1102 available to all users of the MLIR pass framework.
1104 #### Pass Timing
1106 The PassTiming instrumentation provides timing information about the execution
1107 of passes and computation of analyses. This provides a quick glimpse into what
1108 passes are taking the most time to execute, as well as how much of an effect a
1109 pass has on the total execution time of the pipeline. Users can enable this
1110 instrumentation directly on the PassManager via `enableTiming`. This
1111 instrumentation is also made available in mlir-opt via the `-mlir-timing` flag.
1112 The PassTiming instrumentation provides several different display modes for the
1113 timing results, each of which is described below:
1115 ##### List Display Mode
1117 In this mode, the results are displayed in a list sorted by total time with each
1118 pass/analysis instance aggregated into one unique result. This view is useful
1119 for getting an overview of what analyses/passes are taking the most time in a
1120 pipeline. This display mode is available in mlir-opt via
1121 `-mlir-timing-display=list`.
1123 ```shell
1124 $ mlir-opt foo.mlir -mlir-disable-threading -pass-pipeline='builtin.module(func.func(cse,canonicalize),convert-func-to-llvm)' -mlir-timing -mlir-timing-display=list
1126 ===-------------------------------------------------------------------------===
1127                          ... Execution time report ...
1128 ===-------------------------------------------------------------------------===
1129   Total Execution Time: 0.0135 seconds
1131   ----Wall Time----  ----Name----
1132     0.0135 (100.0%)  root
1133     0.0041 ( 30.1%)  Parser
1134     0.0018 ( 13.3%)  ConvertFuncToLLVMPass
1135     0.0011 (  8.2%)  Output
1136     0.0007 (  5.2%)  Pipeline Collection : ['func.func']
1137     0.0006 (  4.6%)  'func.func' Pipeline
1138     0.0005 (  3.5%)  Canonicalizer
1139     0.0001 (  0.9%)  CSE
1140     0.0001 (  0.5%)  (A) DataLayoutAnalysis
1141     0.0000 (  0.1%)  (A) DominanceInfo
1142     0.0058 ( 43.2%)  Rest
1143     0.0135 (100.0%)  Total
1146 The results can be displayed in JSON format via `-mlir-output-format=json`.
1148 ```shell
1149 $ mlir-opt foo.mlir -mlir-disable-threading -pass-pipeline='builtin.module(func.func(cse,canonicalize),convert-func-to-llvm)' -mlir-timing -mlir-timing-display=list -mlir-output-format=json
1152 {"wall": {"duration":   0.0135, "percentage": 100.0}, "name": "root"},
1153 {"wall": {"duration":   0.0041, "percentage":  30.1}, "name": "Parser"},
1154 {"wall": {"duration":   0.0018, "percentage":  13.3}, "name": "ConvertFuncToLLVMPass"},
1155 {"wall": {"duration":   0.0011, "percentage":   8.2}, "name": "Output"},
1156 {"wall": {"duration":   0.0007, "percentage":   5.2}, "name": "Pipeline Collection : ['func.func']"},
1157 {"wall": {"duration":   0.0006, "percentage":   4.6}, "name": "'func.func' Pipeline"},
1158 {"wall": {"duration":   0.0005, "percentage":   3.5}, "name": "Canonicalizer"},
1159 {"wall": {"duration":   0.0001, "percentage":   0.9}, "name": "CSE"},
1160 {"wall": {"duration":   0.0001, "percentage":   0.5}, "name": "(A) DataLayoutAnalysis"},
1161 {"wall": {"duration":   0.0000, "percentage":   0.1}, "name": "(A) DominanceInfo"},
1162 {"wall": {"duration":   0.0058, "percentage":  43.2}, "name": "Rest"},
1163 {"wall": {"duration":   0.0135, "percentage": 100.0}, "name": "Total"}
1167 ##### Tree Display Mode
1169 In this mode, the results are displayed in a nested pipeline view that mirrors
1170 the internal pass pipeline that is being executed in the pass manager. This view
1171 is useful for understanding specifically which parts of the pipeline are taking
1172 the most time, and can also be used to identify when analyses are being
1173 invalidated and recomputed. This is the default display mode.
1175 ```shell
1176 $ mlir-opt foo.mlir -mlir-disable-threading -pass-pipeline='builtin.module(func.func(cse,canonicalize),convert-func-to-llvm)' -mlir-timing
1178 ===-------------------------------------------------------------------------===
1179                          ... Execution time report ...
1180 ===-------------------------------------------------------------------------===
1181   Total Execution Time: 0.0127 seconds
1183   ----Wall Time----  ----Name----
1184     0.0038 ( 30.2%)  Parser
1185     0.0006 (  4.8%)  'func.func' Pipeline
1186     0.0001 (  0.9%)    CSE
1187     0.0000 (  0.1%)      (A) DominanceInfo
1188     0.0005 (  3.7%)    Canonicalizer
1189     0.0017 ( 13.7%)  ConvertFuncToLLVMPass
1190     0.0001 (  0.6%)    (A) DataLayoutAnalysis
1191     0.0010 (  8.2%)  Output
1192     0.0054 ( 42.5%)  Rest
1193     0.0127 (100.0%)  Total
1196 The results can be displayed in JSON format via `-mlir-output-format=json`.
1198 ```shell
1199 $ mlir-opt foo.mlir -mlir-disable-threading -pass-pipeline='builtin.module(func.func(cse,canonicalize),convert-func-to-llvm)' -mlir-timing -mlir-output-format=json
1202 {"wall": {"duration":   0.0038, "percentage":  30.2}, "name": "Parser", "passes": [
1203 {}]},
1204 {"wall": {"duration":   0.0006, "percentage":   4.8}, "name": "'func.func' Pipeline", "passes": [
1205   {"wall": {"duration":   0.0001, "percentage":   0.9}, "name": "CSE", "passes": [
1206     {"wall": {"duration":   0.0000, "percentage":   0.1}, "name": "(A) DominanceInfo", "passes": [
1207     {}]},
1208   {}]},
1209   {"wall": {"duration":   0.0005, "percentage":   3.7}, "name": "Canonicalizer", "passes": [
1210   {}]},
1211 {}]},
1212 {"wall": {"duration":   0.0017, "percentage":  13.7}, "name": "ConvertFuncToLLVMPass", "passes": [
1213   {"wall": {"duration":   0.0001, "percentage":   0.6}, "name": "(A) DataLayoutAnalysis", "passes": [
1214   {}]},
1215 {}]},
1216 {"wall": {"duration":   0.0010, "percentage":   8.2}, "name": "Output", "passes": [
1217 {}]},
1218 {"wall": {"duration":   0.0054, "percentage":  42.5}, "name": "Rest"},
1219 {"wall": {"duration":   0.0127, "percentage": 100.0}, "name": "Total"}
1223 ##### Multi-threaded Pass Timing
1225 When multi-threading is enabled in the pass manager the meaning of the display
1226 slightly changes. First, a new timing column is added, `User Time`, that
1227 displays the total time spent across all threads. Secondly, the `Wall Time`
1228 column displays the longest individual time spent amongst all of the threads.
1229 This means that the `Wall Time` column will continue to give an indicator on the
1230 perceived time, or clock time, whereas the `User Time` will display the total
1231 cpu time.
1233 ```shell
1234 $ mlir-opt foo.mlir -pass-pipeline='builtin.module(func.func(cse,canonicalize),convert-func-to-llvm)'  -mlir-timing
1236 ===-------------------------------------------------------------------------===
1237                       ... Pass execution timing report ...
1238 ===-------------------------------------------------------------------------===
1239   Total Execution Time: 0.0078 seconds
1241    ---User Time---   ---Wall Time---  --- Name ---
1242    0.0177 ( 88.5%)     0.0057 ( 71.3%)  'func.func' Pipeline
1243    0.0044 ( 22.0%)     0.0015 ( 18.9%)    CSE
1244    0.0029 ( 14.5%)     0.0012 ( 15.2%)      (A) DominanceInfo
1245    0.0038 ( 18.9%)     0.0015 ( 18.7%)    VerifierPass
1246    0.0089 ( 44.6%)     0.0025 ( 31.1%)    Canonicalizer
1247    0.0006 (  3.0%)     0.0002 (  2.6%)    VerifierPass
1248    0.0004 (  2.2%)     0.0004 (  5.4%)  VerifierPass
1249    0.0013 (  6.5%)     0.0013 ( 16.3%)  LLVMLoweringPass
1250    0.0006 (  2.8%)     0.0006 (  7.0%)  VerifierPass
1251    0.0200 (100.0%)     0.0081 (100.0%)  Total
1254 #### IR Printing
1256 When debugging it is often useful to dump the IR at various stages of a pass
1257 pipeline. This is where the IR printing instrumentation comes into play. This
1258 instrumentation allows for conditionally printing the IR before and after pass
1259 execution by optionally filtering on the pass being executed. This
1260 instrumentation can be added directly to the PassManager via the
1261 `enableIRPrinting` method. `mlir-opt` provides a few useful flags for utilizing
1262 this instrumentation:
1264 *   `mlir-print-ir-before=(comma-separated-pass-list)`
1265     *   Print the IR before each of the passes provided within the pass list.
1266 *   `mlir-print-ir-before-all`
1267     *   Print the IR before every pass in the pipeline.
1269 ```shell
1270 $ mlir-opt foo.mlir -pass-pipeline='func.func(cse)' -mlir-print-ir-before=cse
1272 *** IR Dump Before CSE ***
1273 func.func @simple_constant() -> (i32, i32) {
1274   %c1_i32 = arith.constant 1 : i32
1275   %c1_i32_0 = arith.constant 1 : i32
1276   return %c1_i32, %c1_i32_0 : i32, i32
1280 *   `mlir-print-ir-after=(comma-separated-pass-list)`
1281     *   Print the IR after each of the passes provided within the pass list.
1282 *   `mlir-print-ir-after-all`
1283     *   Print the IR after every pass in the pipeline.
1285 ```shell
1286 $ mlir-opt foo.mlir -pass-pipeline='func.func(cse)' -mlir-print-ir-after=cse
1288 *** IR Dump After CSE ***
1289 func.func @simple_constant() -> (i32, i32) {
1290   %c1_i32 = arith.constant 1 : i32
1291   return %c1_i32, %c1_i32 : i32, i32
1295 *   `mlir-print-ir-after-change`
1296     *   Only print the IR after a pass if the pass mutated the IR. This helps to
1297         reduce the number of IR dumps for "uninteresting" passes.
1298     *   Note: Changes are detected by comparing a hash of the operation before
1299         and after the pass. This adds additional run-time to compute the hash of
1300         the IR, and in some rare cases may result in false-positives depending
1301         on the collision rate of the hash algorithm used.
1302     *   Note: This option should be used in unison with one of the other
1303         'mlir-print-ir-after' options above, as this option alone does not enable
1304         printing.
1306 ```shell
1307 $ mlir-opt foo.mlir -pass-pipeline='func.func(cse,cse)' -mlir-print-ir-after=cse -mlir-print-ir-after-change
1309 *** IR Dump After CSE ***
1310 func.func @simple_constant() -> (i32, i32) {
1311   %c1_i32 = arith.constant 1 : i32
1312   return %c1_i32, %c1_i32 : i32, i32
1316 *   `mlir-print-ir-after-failure`
1317     *   Only print IR after a pass failure.
1318     *   This option should *not* be used with the other `mlir-print-ir-after` flags
1319         above.
1321 ```shell
1322 $ mlir-opt foo.mlir -pass-pipeline='func.func(cse,bad-pass)' -mlir-print-ir-after-failure
1324 *** IR Dump After BadPass Failed ***
1325 func.func @simple_constant() -> (i32, i32) {
1326   %c1_i32 = arith.constant 1 : i32
1327   return %c1_i32, %c1_i32 : i32, i32
1331 *   `mlir-print-ir-module-scope`
1332     *   Always print the top-level module operation, regardless of pass type or
1333         operation nesting level.
1334     *   Note: Printing at module scope should only be used when multi-threading
1335         is disabled(`-mlir-disable-threading`)
1337 ```shell
1338 $ mlir-opt foo.mlir -mlir-disable-threading -pass-pipeline='func.func(cse)' -mlir-print-ir-after=cse -mlir-print-ir-module-scope
1340 *** IR Dump After CSE ***  ('func.func' operation: @bar)
1341 func.func @bar(%arg0: f32, %arg1: f32) -> f32 {
1342   ...
1345 func.func @simple_constant() -> (i32, i32) {
1346   %c1_i32 = arith.constant 1 : i32
1347   %c1_i32_0 = arith.constant 1 : i32
1348   return %c1_i32, %c1_i32_0 : i32, i32
1351 *** IR Dump After CSE ***  ('func.func' operation: @simple_constant)
1352 func.func @bar(%arg0: f32, %arg1: f32) -> f32 {
1353   ...
1356 func.func @simple_constant() -> (i32, i32) {
1357   %c1_i32 = arith.constant 1 : i32
1358   return %c1_i32, %c1_i32 : i32, i32
1362 *   `mlir-print-ir-tree-dir=(directory path)`
1363     *   Without setting this option, the IR printed by the instrumentation will
1364         be printed to `stderr`. If you provide a directory using this option,
1365         the output corresponding to each pass will be printed to a file in the
1366         directory tree rooted at `(directory path)`. The path created for each
1367         pass reflects the nesting structure of the IR and the pass pipeline.
1368     *   The below example illustrates the file tree created by running a pass
1369         pipeline on IR that has two `func.func` located within two nested
1370         `builtin.module` ops.
1371     *   The subdirectories are given names that reflect the parent op names and
1372         the symbol names for those ops (if present).
1373     *   The printer keeps a counter associated with ops that are targeted by
1374         passes and their isolated-from-above parents. Each filename is given a
1375         numeric prefix using the counter value for the op that the pass is
1376         targeting. The counter values for each parent are then prepended. This
1377         gives a naming where it is easy to distinguish which passes may have run
1378         concurrently versus which have a clear ordering. In the below example,for
1379         both `1_1_pass4.mlir` files, the first 1 refers to the counter for the
1380         parent op, and the second refers to the counter for the respective
1381         function.
1384 $ pipeline="builtin.module(pass1,pass2,func.func(pass3,pass4),pass5)"
1385 $ mlir-opt foo.mlir -pass-pipeline="$pipeline" -mlir-print-ir-tree-dir=/tmp/pipeline_output
1386 $ tree /tmp/pipeline_output
1388 /tmp/pass_output
1389 ├── builtin_module_the_symbol_name
1390 │   ├── 0_pass1.mlir
1391 │   ├── 1_pass2.mlir
1392 │   ├── 2_pass5.mlir
1393 │   ├── func_func_my_func_name
1394 │   │   ├── 1_0_pass3.mlir
1395 │   │   ├── 1_1_pass4.mlir
1396 │   ├── func_func_my_other_func_name
1397 │   │   ├── 1_0_pass3.mlir
1398 │   │   ├── 1_1_pass4.mlir
1401 ## Crash and Failure Reproduction
1403 The [pass manager](#pass-manager) in MLIR contains a builtin mechanism to
1404 generate reproducibles in the event of a crash, or a
1405 [pass failure](#pass-failure). This functionality can be enabled via
1406 `PassManager::enableCrashReproducerGeneration` or via the command line flag
1407 `mlir-pass-pipeline-crash-reproducer`. In either case, an argument is provided that
1408 corresponds to the output `.mlir` file name that the reproducible should be
1409 written to. The reproducible contains the configuration of the pass manager that
1410 was executing, as well as the initial IR before any passes were run. The reproducer
1411 is stored within the assembly format as an external resource. A potential reproducible
1412 may have the form:
1414 ```mlir
1415 module {
1416   func.func @foo() {
1417     ...
1418   }
1422   external_resources: {
1423     mlir_reproducer: {
1424       pipeline: "builtin.module(func.func(cse,canonicalize),inline)",
1425       disable_threading: true,
1426       verify_each: true
1427     }
1428   }
1432 The configuration dumped can be passed to `mlir-opt` by specifying
1433 `-run-reproducer` flag. This will result in parsing the configuration of the reproducer
1434 and adjusting the necessary opt state, e.g. configuring the pass manager, context, etc.
1436 Beyond specifying a filename, one can also register a `ReproducerStreamFactory`
1437 function that would be invoked in the case of a crash and the reproducer written
1438 to its stream.
1440 ### Local Reproducer Generation
1442 An additional flag may be passed to
1443 `PassManager::enableCrashReproducerGeneration`, and specified via
1444 `mlir-pass-pipeline-local-reproducer` on the command line, that signals that the pass
1445 manager should attempt to generate a "local" reproducer. This will attempt to
1446 generate a reproducer containing IR right before the pass that fails. This is
1447 useful for situations where the crash is known to be within a specific pass, or
1448 when the original input relies on components (like dialects or passes) that may
1449 not always be available.
1451 Note: Local reproducer generation requires that multi-threading is
1452 disabled(`-mlir-disable-threading`)
1454 For example, if the failure in the previous example came from the `canonicalize` pass,
1455 the following reproducer would be generated:
1457 ```mlir
1458 module {
1459   func.func @foo() {
1460     ...
1461   }
1465   external_resources: {
1466     mlir_reproducer: {
1467       pipeline: "builtin.module(func.func(canonicalize))",
1468       disable_threading: true,
1469       verify_each: true
1470     }
1471   }