Decouple registring passes from specifying argument/description

[mehdi_amini]

Summary

This patch changes the (not recommended) static registration API from:

static PassRegistration<MyPass> reg("my-pass", "My Pass Description.");

to:

static PassRegistration<MyPass> reg;

And the explicit registration from:

void registerPass("my-pass", "My Pass Description.",
                  [] { return createMyPass(); });

To:

void registerPass([] { return createMyPass(); });

It is expected that Pass implementations overrides the getArgument() method
instead. This will ensure that pipeline description can be printed and parsed
back.

[rriddle]

We should update the docs as well.

[mehdi_amini]

Update documentation

[rriddle]

mlir/docs/PassManagement.md

564–568

I think we need to explicitly call out the getArgument/getDescription methods. I don't think it would be clear right now that they are used for registration.

[mehdi_amini]

Document more the getArgument()/getDescription()

mlir/docs/PassManagement.md

void runOnOperation() override {
     });
   }
 };
 } // end anonymous namespace
 
 /// Register this pass so that it can be built via from a textual pass pipeline.
 /// (Pass registration is discussed more below)
 void registerMyPass() {
-  PassRegistration<MyFunctionPass>(
-    "flag-name-to-invoke-pass-via-mlir-opt", "Pass description here");
+  PassRegistration<MyFunctionPass>();
 }
 ```
 
 ### OperationPass : Op-Agnostic
 
 An `op-agnostic` pass operates on the operation type of the pass manager that it
 is added to. This means that passes of this type may operate on several
 different operation types. Passes of this type are generally written generically

 An example is shown below:
 
 ```c++
 struct MyPass ... {
   /// Make sure that we have a valid default constructor and copy constructor to
   /// ensure that the options are initialized properly.
   MyPass() = default;
   MyPass(const MyPass& pass) {}
-
+  StringRef getArgument() const final {
+    // This is the argument used to refer to the pass in
+    // the textual format (on the commandline for example).
+    return "argument";
+  }
+  StringRef getDescription() const final {
+    // This is a brief description of the pass.
+    return  "description";
+  }
   /// Define the statistic to track during the execution of MyPass.
   Statistic exampleStat{this, "exampleStat", "An example statistic"};
 
   void runOnOperation() {
     ...
 
     // Update the statistic after some invariant was hit.
     ++exampleStat;
===-------------------------------------------------------------------------===
                          ... Pass statistics report ...
 ===-------------------------------------------------------------------------===
 MyPass
   (S) 21 exampleStat - An example statistic
 ```
 
 ## Pass Registration
 
 Briefly shown in the example definitions of the various pass types is the
 `PassRegistration` class. This mechanism allows for registering pass classes so
 that they may be created within a
 [textual pass pipeline description](#textual-pass-pipeline-specification). An
 example registration is shown below:
 
 ```c++
 void registerMyPass() {
-  PassRegistration<MyPass>("argument", "description");
+  PassRegistration<MyPass>();
 }
 ```
 
 *   `MyPass` is the name of the derived pass class.
-*   "argument" is the argument used to refer to the pass in the textual format.
-*   "description" is a brief description of the pass.
+*   The pass `getArgument()` method is used to get the identifier that will be
+    used to refer to the pass.
+*   The pass `getDescription()` method provides a short summary describing the
+    pass.
 
 For passes that cannot be default-constructed, `PassRegistration` accepts an
-optional third argument that takes a callback to create the pass:
+optional argument that takes a callback to create the pass:
 
 ```c++
 void registerMyPass() {
   PassRegistration<MyParametricPass>(
-    "argument", "description",
     []() -> std::unique_ptr<Pass> {
       std::unique_ptr<Pass> p = std::make_unique<MyParametricPass>(/*options*/);
       /*... non-trivial-logic to configure the pass ...*/;
       return p;
     });
 }
 ```
 

 
 /// Expose this pass to the outside world.
 std::unique_ptr<Pass> foo::createMyPass() {
   return std::make_unique<MyPass>();
 }
 
 /// Register this pass.
 void foo::registerMyPass() {
-  PassRegistration<MyPass>("my-pass", "My pass summary");
+  PassRegistration<MyPass>();
 }
 ```
 
 This pass may be specified declaratively as so:
 
 ```tablegen
 def MyPass : Pass<"my-pass", "ModuleOp"> {
   let summary = "My Pass Summary";

mlir/include/mlir/Pass/Pass.h

public:
 
   /// Register dependent dialects for the current pass.
   /// A pass is expected to register the dialects it will create entities for
   /// (Operations, Types, Attributes), other than dialect that exists in the
   /// input. For example, a pass that converts from Linalg to Affine would
   /// register the Affine dialect but does not need to register Linalg.
   virtual void getDependentDialects(DialectRegistry &registry) const {}
 
-  /// Returns the command line argument used when registering this pass. Return
+  /// Return the command line argument used when registering this pass. Return
   /// an empty string if one does not exist.
   virtual StringRef getArgument() const { return ""; }
 
+  /// Return the command line description used when registering this pass.
+  /// Return an empty string if one does not exist.
+  virtual StringRef getDescription() const { return ""; }
+
   /// Returns the name of the operation that this pass operates on, or None if
   /// this is a generic OperationPass.
   Optional<StringRef> getOpName() const { return opName; }
 
   //===--------------------------------------------------------------------===//
   // Options
   //===--------------------------------------------------------------------===//
 

mlir/include/mlir/Pass/PassRegistry.h

 /// typically used through the PassPipelineRegistration template.
 void registerPassPipeline(
     StringRef arg, StringRef description, const PassRegistryFunction &function,
     std::function<void(function_ref<void(const detail::PassOptions &)>)>
         optHandler);
 
 /// Register a specific dialect pass allocator function with the system,
 /// typically used through the PassRegistration template.
+/// Deprecated: please use the alternate version below.
 void registerPass(StringRef arg, StringRef description,
                   const PassAllocatorFunction &function);
 
+/// Register a specific dialect pass allocator function with the system,
+/// typically used through the PassRegistration template.
+void registerPass(const PassAllocatorFunction &function);
+
 /// PassRegistration provides a global initializer that registers a Pass
-/// allocation routine for a concrete pass instance. The third argument is
+/// allocation routine for a concrete pass instance. The argument is
 /// optional and provides a callback to construct a pass that does not have
 /// a default constructor.
 ///
 /// Usage:
 ///
 ///   /// At namespace scope.
-///   static PassRegistration<MyPass> reg("my-pass", "My Pass Description.");
+///   static PassRegistration<MyPass> reg;
 ///
 template <typename ConcretePass> struct PassRegistration {
+  PassRegistration(const PassAllocatorFunction &constructor) {
+    registerPass(constructor);
+  }
+  PassRegistration()
+      : PassRegistration([] { return std::make_unique<ConcretePass>(); }) {}
+
+  /// Constructor below are deprecated.
+
   PassRegistration(StringRef arg, StringRef description,
                    const PassAllocatorFunction &constructor) {
     registerPass(arg, description, constructor);
   }
 
   PassRegistration(StringRef arg, StringRef description)
       : PassRegistration(arg, description,
                          [] { return std::make_unique<ConcretePass>(); }) {}

mlir/include/mlir/Transforms/Passes.td

def PrintCFG : FunctionPass<"print-cfg-graph"> {
   let constructor = "mlir::createPrintCFGGraphPass()";
 }
 
 def PrintOpStats : Pass<"print-op-stats"> {
   let summary = "Print statistics of operations";
   let constructor = "mlir::createPrintOpStatsPass()";
 }
 
-def PrintOp : Pass<"print-op-graph", "ModuleOp"> {
-  let summary = "Print op graph per-Region";
-  let constructor = "mlir::createPrintOpGraphPass()";
-}
-
 def SCCP : Pass<"sccp"> {
   let summary = "Sparse Conditional Constant Propagation";
   let description = [{
     This pass implements a general algorithm for sparse conditional constant
     propagation. This algorithm detects values that are known to be constant and
     optimistically propagates this throughout the IR. Any values proven to be
     constant are replaced, and removed if possible.
 

mlir/lib/Pass/PassRegistry.cpp

void mlir::registerPass(StringRef arg, StringRef description,
   TypeID entryTypeID = function()->getTypeID();
   auto it = passRegistryTypeIDs->try_emplace(arg, entryTypeID).first;
   if (it->second != entryTypeID) {
     llvm_unreachable("pass allocator creates a different pass than previously "
                      "registered");
   }
 }
 
+void mlir::registerPass(const PassAllocatorFunction &function) {
+  std::unique_ptr<Pass> pass = function();
+  StringRef arg = pass->getArgument();
+  if (arg.empty())
+    llvm::report_fatal_error(
+        "Trying to register a pass that does not override `getArgument()`");
+  registerPass(arg, pass->getDescription(), function);
+}
+
 /// Returns the pass info for the specified pass argument or null if unknown.
 const PassInfo *mlir::Pass::lookupPassInfo(StringRef passArg) {
   auto it = passRegistry->find(passArg);
   return it == passRegistry->end() ? nullptr : &it->second;
 }
 
 //===----------------------------------------------------------------------===//
 // PassOptions

mlir/test/Transforms/print-op-graph.mlir

-// RUN: mlir-opt -allow-unregistered-dialect -mlir-elide-elementsattrs-if-larger=2 -print-op-graph %s -o %t 2>&1 | FileCheck %s
+// RUN: mlir-opt -allow-unregistered-dialect -mlir-elide-elementsattrs-if-larger=2 -view-op-graph %s -o %t 2>&1 | FileCheck %s
 
 // CHECK-LABEL: digraph "merge_blocks"
 // CHECK{LITERAL}: value: [[...]] : tensor\<2x2xi32\>}
 // CHECK{LITERAL}: value: dense\<1\> : tensor\<5xi32\>}
 // CHECK{LITERAL}: value: dense\<[[0, 1]]\> : tensor\<1x2xi32\>}
 func @merge_blocks(%arg0: i32, %arg1 : i32) -> () {
   %0 = constant dense<[[0, 1], [2, 3]]> : tensor<2x2xi32>
   %1 = constant dense<1> : tensor<5xi32>

mlir/test/python/pass_manager.py

 run(testParseFail)
 
 
 # Verify failure on incorrect level of nesting.
 # CHECK-LABEL: TEST: testInvalidNesting
 def testInvalidNesting():
   with Context():
     try:
-      pm = PassManager.parse("func(print-op-graph)")
+      pm = PassManager.parse("func(view-op-graph)")
     except ValueError as e:
       # CHECK: Can't add pass 'ViewOpGraphPass' restricted to 'module' on a PassManager intended to run on 'func', did you intend to nest?
-      # CHECK: ValueError exception: invalid pass pipeline 'func(print-op-graph)'.
+      # CHECK: ValueError exception: invalid pass pipeline 'func(view-op-graph)'.
       log("ValueError exception:", e)
     else:
       log("Exception not produced")
 run(testInvalidNesting)
 
 
 # Verify that a pass manager can execute on IR
 # CHECK-LABEL: TEST: testRun

mlir/tools/mlir-tblgen/PassGen.cpp

public:
   {0}Base(const {0}Base &) : {1}(::mlir::TypeID::get<DerivedT>()) {{}
 
   /// Returns the command-line argument attached to this pass.
   static constexpr ::llvm::StringLiteral getArgumentName() {
     return ::llvm::StringLiteral("{2}");
   }
   ::llvm::StringRef getArgument() const override { return "{2}"; }
 
+  ::llvm::StringRef getDescription() const override { return "{3}"; }
+
   /// Returns the derived pass name.
   static constexpr ::llvm::StringLiteral getPassName() {
     return ::llvm::StringLiteral("{0}");
   }
   ::llvm::StringRef getName() const override { return "{0}"; }
 
   /// Support isa/dyn_cast functionality for the derived pass class.
   static bool classof(const ::mlir::Pass *pass) {{
     return pass->getTypeID() == ::mlir::TypeID::get<DerivedT>();
   }
 
   /// A clone method to create a copy of this pass.
   std::unique_ptr<::mlir::Pass> clonePass() const override {{
     return std::make_unique<DerivedT>(*static_cast<const DerivedT *>(this));
   }
 
   /// Return the dialect that must be loaded in the context before this pass.
   void getDependentDialects(::mlir::DialectRegistry &registry) const override {
-    {3}
+    {4}
   }
 
 protected:
 )";
 
 /// Registration for a single dependent dialect, to be inserted for each
 /// dependent dialect in the `getDependentDialects` above.
 const char *const dialectRegistrationTemplate = R"(
static void emitPassDecl(const Pass &pass, raw_ostream &os) {
   std::string dependentDialectRegistrations;
   {
     llvm::raw_string_ostream dialectsOs(dependentDialectRegistrations);
     for (StringRef dependentDialect : pass.getDependentDialects())
       dialectsOs << llvm::formatv(dialectRegistrationTemplate,
                                   dependentDialect);
   }
   os << llvm::formatv(passDeclBegin, defName, pass.getBaseClass(),
-                      pass.getArgument(), dependentDialectRegistrations);
+                      pass.getArgument(), pass.getSummary(),
+                      dependentDialectRegistrations);
   emitPassOptionDecls(pass, os);
   emitPassStatisticDecls(pass, os);
   os << "};\n";
 }
 
 /// Emit the code for registering each of the given passes with the global
 /// PassRegistry.
 static void emitPassDecls(ArrayRef<Pass> passes, raw_ostream &os) {

 /// {2): The summary of the pass.
 /// {3}: The code for constructing the pass.
 const char *const passRegistrationCode = R"(
 //===----------------------------------------------------------------------===//
 // {0} Registration
 //===----------------------------------------------------------------------===//
 
 inline void register{0}Pass() {{
-  ::mlir::registerPass("{1}", "{2}", []() -> std::unique_ptr<::mlir::Pass> {{
-    return {3};
+  ::mlir::registerPass([]() -> std::unique_ptr<::mlir::Pass> {{
+    return {1};
   });
 }
 )";
 
 /// {0}: The name of the pass group.
 const char *const passGroupRegistrationCode = R"(
 //===----------------------------------------------------------------------===//
 // {0} Registration
 //===----------------------------------------------------------------------===//
 
 inline void register{0}Passes() {{
 )";
 
 /// Emit the code for registering each of the given passes with the global
 /// PassRegistry.
 static void emitRegistration(ArrayRef<Pass> passes, raw_ostream &os) {
   os << "#ifdef GEN_PASS_REGISTRATION\n";
   for (const Pass &pass : passes) {
     os << llvm::formatv(passRegistrationCode, pass.getDef()->getName(),
-                        pass.getArgument(), pass.getSummary(),
                         pass.getConstructor());
   }
 
   os << llvm::formatv(passGroupRegistrationCode, groupName);
   for (const Pass &pass : passes)
     os << "  register" << pass.getDef()->getName() << "Pass();\n";
   os << "}\n";
   os << "#undef GEN_PASS_REGISTRATION\n";