MLIR  17.0.0git
PassRegistry.h
Go to the documentation of this file.
1 //===- PassRegistry.h - Pass Registration Utilities -------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This file contains utilities for registering information about compiler
10 // passes.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef MLIR_PASS_PASSREGISTRY_H_
15 #define MLIR_PASS_PASSREGISTRY_H_
16 
17 #include "mlir/Pass/PassOptions.h"
18 #include "mlir/Support/TypeID.h"
19 #include <functional>
20 #include <utility>
21 #include <optional>
22 
23 namespace mlir {
24 class OpPassManager;
25 class ParserConfig;
26 class Pass;
27 class PassManager;
28 
29 namespace detail {
30 class PassOptions;
31 } // namespace detail
32 
33 /// A registry function that adds passes to the given pass manager. This should
34 /// also parse options and return success() if parsing succeeded.
35 /// `errorHandler` is a functor used to emit errors during parsing.
36 /// parameter corresponds to the raw location within the pipeline string. This
37 /// should always return failure.
38 using PassRegistryFunction = std::function<LogicalResult(
39  OpPassManager &, StringRef options,
40  function_ref<LogicalResult(const Twine &)> errorHandler)>;
41 using PassAllocatorFunction = std::function<std::unique_ptr<Pass>()>;
42 
43 //===----------------------------------------------------------------------===//
44 // PassRegistry
45 //===----------------------------------------------------------------------===//
46 
47 /// Structure to group information about a passes and pass pipelines (argument
48 /// to invoke via mlir-opt, description, pass pipeline builder).
50 public:
51  /// Adds this pass registry entry to the given pass manager. `options` is
52  /// an opaque string that will be parsed by the builder. The success of
53  /// parsing will be returned.
56  function_ref<LogicalResult(const Twine &)> errorHandler) const {
57  assert(builder &&
58  "cannot call addToPipeline on PassRegistryEntry without builder");
59  return builder(pm, options, errorHandler);
60  }
61 
62  /// Returns the command line option that may be passed to 'mlir-opt' that will
63  /// cause this pass to run or null if there is no such argument.
64  StringRef getPassArgument() const { return arg; }
65 
66  /// Returns a description for the pass, this never returns null.
67  StringRef getPassDescription() const { return description; }
68 
69  /// Print the help information for this pass. This includes the argument,
70  /// description, and any pass options. `descIndent` is the indent that the
71  /// descriptions should be aligned.
72  void printHelpStr(size_t indent, size_t descIndent) const;
73 
74  /// Return the maximum width required when printing the options of this entry.
75  size_t getOptionWidth() const;
76 
77 protected:
79  StringRef arg, StringRef description, const PassRegistryFunction &builder,
80  std::function<void(function_ref<void(const detail::PassOptions &)>)>
81  optHandler)
82  : arg(arg), description(description), builder(builder),
83  optHandler(std::move(optHandler)) {}
84 
85 private:
86  /// The argument with which to invoke the pass via mlir-opt.
87  std::string arg;
88 
89  /// Description of the pass.
90  std::string description;
91 
92  /// Function to register this entry to a pass manager pipeline.
93  PassRegistryFunction builder;
94 
95  /// Function to invoke a handler for a pass options instance.
96  std::function<void(function_ref<void(const detail::PassOptions &)>)>
97  optHandler;
98 };
99 
100 /// A structure to represent the information of a registered pass pipeline.
102 public:
104  StringRef arg, StringRef description, const PassRegistryFunction &builder,
105  std::function<void(function_ref<void(const detail::PassOptions &)>)>
106  optHandler)
107  : PassRegistryEntry(arg, description, builder, std::move(optHandler)) {}
108 };
109 
110 /// A structure to represent the information for a derived pass class.
111 class PassInfo : public PassRegistryEntry {
112 public:
113  /// PassInfo constructor should not be invoked directly, instead use
114  /// PassRegistration or registerPass.
115  PassInfo(StringRef arg, StringRef description,
116  const PassAllocatorFunction &allocator);
117 };
118 
119 //===----------------------------------------------------------------------===//
120 // PassRegistration
121 //===----------------------------------------------------------------------===//
122 
123 /// Register a specific dialect pipeline registry function with the system,
124 /// typically used through the PassPipelineRegistration template.
126  StringRef arg, StringRef description, const PassRegistryFunction &function,
127  std::function<void(function_ref<void(const detail::PassOptions &)>)>
128  optHandler);
129 
130 /// Register a specific dialect pass allocator function with the system,
131 /// typically used through the PassRegistration template.
132 void registerPass(const PassAllocatorFunction &function);
133 
134 /// PassRegistration provides a global initializer that registers a Pass
135 /// allocation routine for a concrete pass instance. The argument is
136 /// optional and provides a callback to construct a pass that does not have
137 /// a default constructor.
138 ///
139 /// Usage:
140 ///
141 /// /// At namespace scope.
142 /// static PassRegistration<MyPass> reg;
143 ///
144 template <typename ConcretePass>
147  registerPass(constructor);
148  }
150  : PassRegistration([] { return std::make_unique<ConcretePass>(); }) {}
151 };
152 
153 /// PassPipelineRegistration provides a global initializer that registers a Pass
154 /// pipeline builder routine.
155 ///
156 /// Usage:
157 ///
158 /// // At namespace scope.
159 /// void pipelineBuilder(OpPassManager &pm) {
160 /// pm.addPass(new MyPass());
161 /// pm.addPass(new MyOtherPass());
162 /// }
163 ///
164 /// static PassPipelineRegistration Unused("unused", "Unused pass",
165 /// pipelineBuilder);
166 template <typename Options = EmptyPipelineOptions>
169  StringRef arg, StringRef description,
170  std::function<void(OpPassManager &, const Options &options)> builder) {
172  arg, description,
173  [builder](OpPassManager &pm, StringRef optionsStr,
174  function_ref<LogicalResult(const Twine &)> errorHandler) {
175  Options options;
176  if (failed(options.parseFromString(optionsStr)))
177  return failure();
178  builder(pm, options);
179  return success();
180  },
181  [](function_ref<void(const detail::PassOptions &)> optHandler) {
182  optHandler(Options());
183  });
184  }
185 };
186 
187 /// Convenience specialization of PassPipelineRegistration for EmptyPassOptions
188 /// that does not pass an empty options struct to the pass builder function.
189 template <>
192  StringRef arg, StringRef description,
193  const std::function<void(OpPassManager &)> &builder) {
195  arg, description,
196  [builder](OpPassManager &pm, StringRef optionsStr,
197  function_ref<LogicalResult(const Twine &)> errorHandler) {
198  if (!optionsStr.empty())
199  return failure();
200  builder(pm);
201  return success();
202  },
203  [](function_ref<void(const detail::PassOptions &)>) {});
204  }
205 };
206 
207 /// Parse the textual representation of a pass pipeline, adding the result to
208 /// 'pm' on success. Returns failure if the given pipeline was invalid.
209 /// 'errorStream' is the output stream used to emit errors found during parsing.
210 LogicalResult parsePassPipeline(StringRef pipeline, OpPassManager &pm,
211  raw_ostream &errorStream = llvm::errs());
212 
213 /// Parse the given textual representation of a pass pipeline, and return the
214 /// parsed pipeline on success. The given pipeline string should be wrapped with
215 /// the desired type of operation to root the created operation, i.e.
216 /// `builtin.module(cse)` over `cse`. Returns failure if the given pipeline was
217 /// invalid. 'errorStream' is the output stream used to emit errors found during
218 /// parsing.
219 FailureOr<OpPassManager>
220 parsePassPipeline(StringRef pipeline, raw_ostream &errorStream = llvm::errs());
221 
222 //===----------------------------------------------------------------------===//
223 // PassPipelineCLParser
224 //===----------------------------------------------------------------------===//
225 
226 namespace detail {
227 struct PassPipelineCLParserImpl;
228 } // namespace detail
229 
230 /// This class implements a command-line parser for MLIR passes. It registers a
231 /// cl option with a given argument and description. This parser will register
232 /// options for each of the passes and pipelines that have been registered with
233 /// the pass registry; Meaning that `-cse` will refer to the CSE pass in MLIR.
234 /// It also registers an argument, `pass-pipeline`, that supports parsing a
235 /// textual description of a pipeline. This option is mutually exclusive with
236 /// the individual pass options.
238 public:
239  /// Construct a pass pipeline parser with the given command line description.
240  /// Optionally registers an alias for the `pass-pipeline` option.
241  PassPipelineCLParser(StringRef arg, StringRef description);
242  PassPipelineCLParser(StringRef arg, StringRef description, StringRef alias);
244 
245  /// Returns true if this parser contains any valid options to add.
246  bool hasAnyOccurrences() const;
247 
248  /// Returns true if the given pass registry entry was registered at the
249  /// top-level of the parser, i.e. not within an explicit textual pipeline.
250  bool contains(const PassRegistryEntry *entry) const;
251 
252  /// Adds the passes defined by this parser entry to the given pass manager.
253  /// Returns failure() if the pass could not be properly constructed due
254  /// to options parsing.
257  function_ref<LogicalResult(const Twine &)> errorHandler) const;
258 
259 private:
260  std::unique_ptr<detail::PassPipelineCLParserImpl> impl;
261 
262  llvm::cl::opt<std::string> passPipeline;
263  std::optional<llvm::cl::alias> passPipelineAlias;
264 };
265 
266 /// This class implements a command-line parser specifically for MLIR pass
267 /// names. It registers a cl option with a given argument and description that
268 /// accepts a comma delimited list of pass names.
270 public:
271  /// Construct a parser with the given command line description.
272  PassNameCLParser(StringRef arg, StringRef description);
274 
275  /// Returns true if this parser contains any valid options to add.
276  bool hasAnyOccurrences() const;
277 
278  /// Returns true if the given pass registry entry was registered at the
279  /// top-level of the parser, i.e. not within an explicit textual pipeline.
280  bool contains(const PassRegistryEntry *entry) const;
281 
282 private:
283  std::unique_ptr<detail::PassPipelineCLParserImpl> impl;
284 };
285 
286 //===----------------------------------------------------------------------===//
287 // Pass Reproducer
288 //===----------------------------------------------------------------------===//
289 
291  /// Attach an assembly resource parser to 'config' that collects the MLIR
292  /// reproducer configuration into this instance.
293  void attachResourceParser(ParserConfig &config);
294 
295  /// Apply the reproducer options to 'pm' and its context.
296  LogicalResult apply(PassManager &pm) const;
297 
298 private:
299  std::optional<std::string> pipeline;
300  std::optional<bool> verifyEach;
301  std::optional<bool> disableThreading;
302 };
303 
304 } // namespace mlir
305 
306 #endif // MLIR_PASS_PASSREGISTRY_H_
static llvm::ManagedStatic< PassManagerOptions > options
This class represents a pass manager that runs passes on either a specific operation type,...
Definition: PassManager.h:52
This class represents a configuration for the MLIR assembly parser.
Definition: AsmState.h:458
A structure to represent the information for a derived pass class.
Definition: PassRegistry.h:111
PassInfo(StringRef arg, StringRef description, const PassAllocatorFunction &allocator)
PassInfo constructor should not be invoked directly, instead use PassRegistration or registerPass.
The main pass manager and pipeline builder.
Definition: PassManager.h:211
This class implements a command-line parser specifically for MLIR pass names.
Definition: PassRegistry.h:269
bool hasAnyOccurrences() const
Returns true if this parser contains any valid options to add.
PassNameCLParser(StringRef arg, StringRef description)
Construct a parser with the given command line description.
bool contains(const PassRegistryEntry *entry) const
Returns true if the given pass registry entry was registered at the top-level of the parser,...
This class implements a command-line parser for MLIR passes.
Definition: PassRegistry.h:237
bool hasAnyOccurrences() const
Returns true if this parser contains any valid options to add.
PassPipelineCLParser(StringRef arg, StringRef description)
Construct a pass pipeline parser with the given command line description.
LogicalResult addToPipeline(OpPassManager &pm, function_ref< LogicalResult(const Twine &)> errorHandler) const
Adds the passes defined by this parser entry to the given pass manager.
bool contains(const PassRegistryEntry *entry) const
Returns true if the given pass registry entry was registered at the top-level of the parser,...
A structure to represent the information of a registered pass pipeline.
Definition: PassRegistry.h:101
PassPipelineInfo(StringRef arg, StringRef description, const PassRegistryFunction &builder, std::function< void(function_ref< void(const detail::PassOptions &)>)> optHandler)
Definition: PassRegistry.h:103
Structure to group information about a passes and pass pipelines (argument to invoke via mlir-opt,...
Definition: PassRegistry.h:49
void printHelpStr(size_t indent, size_t descIndent) const
Print the help information for this pass.
LogicalResult addToPipeline(OpPassManager &pm, StringRef options, function_ref< LogicalResult(const Twine &)> errorHandler) const
Adds this pass registry entry to the given pass manager.
Definition: PassRegistry.h:55
size_t getOptionWidth() const
Return the maximum width required when printing the options of this entry.
PassRegistryEntry(StringRef arg, StringRef description, const PassRegistryFunction &builder, std::function< void(function_ref< void(const detail::PassOptions &)>)> optHandler)
Definition: PassRegistry.h:78
StringRef getPassDescription() const
Returns a description for the pass, this never returns null.
Definition: PassRegistry.h:67
StringRef getPassArgument() const
Returns the command line option that may be passed to 'mlir-opt' that will cause this pass to run or ...
Definition: PassRegistry.h:64
Base container class and manager for all pass options.
Definition: PassOptions.h:79
Include the generated interface declarations.
LogicalResult failure(bool isFailure=true)
Utility function to generate a LogicalResult.
Definition: LogicalResult.h:62
std::function< std::unique_ptr< Pass >()> PassAllocatorFunction
Definition: PassRegistry.h:41
void registerPass(const PassAllocatorFunction &function)
Register a specific dialect pass allocator function with the system, typically used through the PassR...
LogicalResult success(bool isSuccess=true)
Utility function to generate a LogicalResult.
Definition: LogicalResult.h:56
void registerPassPipeline(StringRef arg, StringRef description, const PassRegistryFunction &function, std::function< void(function_ref< void(const detail::PassOptions &)>)> optHandler)
Register a specific dialect pipeline registry function with the system, typically used through the Pa...
LogicalResult parsePassPipeline(StringRef pipeline, OpPassManager &pm, raw_ostream &errorStream=llvm::errs())
Parse the textual representation of a pass pipeline, adding the result to 'pm' on success.
bool failed(LogicalResult result)
Utility function that returns true if the provided LogicalResult corresponds to a failure value.
Definition: LogicalResult.h:72
std::function< LogicalResult(OpPassManager &, StringRef options, function_ref< LogicalResult(const Twine &)> errorHandler)> PassRegistryFunction
A registry function that adds passes to the given pass manager.
Definition: PassRegistry.h:40
A default empty option struct to be used for passes that do not need to take any options.
Definition: PassOptions.h:343
This class represents an efficient way to signal success or failure.
Definition: LogicalResult.h:26
PassPipelineRegistration(StringRef arg, StringRef description, const std::function< void(OpPassManager &)> &builder)
Definition: PassRegistry.h:191
PassPipelineRegistration provides a global initializer that registers a Pass pipeline builder routine...
Definition: PassRegistry.h:167
PassPipelineRegistration(StringRef arg, StringRef description, std::function< void(OpPassManager &, const Options &options)> builder)
Definition: PassRegistry.h:168
PassRegistration provides a global initializer that registers a Pass allocation routine for a concret...
Definition: PassRegistry.h:145
PassRegistration(const PassAllocatorFunction &constructor)
Definition: PassRegistry.h:146
void attachResourceParser(ParserConfig &config)
Attach an assembly resource parser to 'config' that collects the MLIR reproducer configuration into t...
LogicalResult apply(PassManager &pm) const
Apply the reproducer options to 'pm' and its context.