Refactor the way that pass options are specified.

This change refactors pass options to be more similar to how statistics are modeled. More specifically, the options are specified directly on the pass instead of in a separate options class. (Note that the behavior and specification for pass pipelines remains the same.) This brings about several benefits:
* The specification of options is much simpler
* The round-trip format of a pass can be generated automatically
* This gives a somewhat deeper integration with "configuring" a pass, which we could potentially expose to users in the future.

PiperOrigin-RevId: 286953824

Author: River707

g3doc/WritingAPass.md

@@ -421,7 +421,8 @@ options           ::= '{' (key ('=' value)?)+ '}'
         pass pipeline, e.g. `cse` or `canonicalize`.
 *   `options`
     *   Options are pass specific key value pairs that are handled as described
-        in the instance specific pass options section.
+        in the [instance specific pass options](#instance-specific-pass-options)
+        section.
 
 For example, the following pipeline:
 
@@ -443,30 +444,47 @@ options in the format described above.
 ### Instance Specific Pass Options
 
 Options may be specified for a parametric pass. Individual options are defined
-using `llvm::cl::opt` flag definition rules. These options will then be parsed
-at pass construction time independently for each instance of the pass. The
-`PassRegistration` and `PassPipelineRegistration` templates take an additional
-optional template parameter that is the Option struct definition to be used for
-that pass. To use pass specific options, create a class that inherits from
-`mlir::PassOptions` and then add a new constructor that takes `const
-MyPassOptions&` and constructs the pass. When using `PassPipelineRegistration`,
-the constructor now takes a function with the signature `void (OpPassManager
-&pm, const MyPassOptions&)` which should construct the passes from the options
-and pass them to the pm. The user code will look like the following:
+using the [LLVM command line](https://llvm.org/docs/CommandLine.html) flag
+definition rules. These options will then be parsed at pass construction time
+independently for each instance of the pass. To provide options for passes, the
+`Option<>` and `OptionList<>` classes may be used:
 
 ```c++
-class MyPass ... {
-public:
-  MyPass(const MyPassOptions& options) ...
+struct MyPass ... {
+  /// Make sure that we have a valid default constructor and copy constructor to
+  /// make sure that the options are initialized properly.
+  MyPass() = default;
+  MyPass(const MyPass& pass) {}
+
+  // These just forward onto llvm::cl::list and llvm::cl::opt respectively.
+  Option<int> exampleOption{*this, "flag-name", llvm::cl::desc("...")};
+  ListOption<int> exampleListOption{*this, "list-flag-name",
+                                    llvm::cl::desc("...")};
 };
+```
 
-struct MyPassOptions : public PassOptions<MyPassOptions> {
+For pass pipelines, the `PassPipelineRegistration` templates take an additional
+optional template parameter that is the Option struct definition to be used for
+that pipeline. To use pipeline specific options, create a class that inherits
+from `mlir::PassPipelineOptions` that contains the desired options. When using
+`PassPipelineRegistration`, the constructor now takes a function with the
+signature `void (OpPassManager &pm, const MyPipelineOptions&)` which should
+construct the passes from the options and pass them to the pm:
+
+```c++
+struct MyPipelineOptions : public PassPipelineOptions {
   // These just forward onto llvm::cl::list and llvm::cl::opt respectively.
   Option<int> exampleOption{*this, "flag-name", llvm::cl::desc("...")};
-  List<int> exampleListOption{*this, "list-flag-name", llvm::cl::desc("...")};
+  ListOption<int> exampleListOption{*this, "list-flag-name",
+                                    llvm::cl::desc("...")};
 };
 
-static PassRegistration<MyPass, MyPassOptions> pass("my-pass", "description");
+
+static mlir::PassPipelineRegistration<MyPipelineOptions> pipeline(
+    "example-pipeline", "Run an example pipeline.",
+    [](OpPassManager &pm, const MyPipelineOptions &pipelineOptions) {
+      // Initialize the pass manager.
+    });
 ```
 
 ## Pass Statistics

include/mlir/Pass/Pass.h

@@ -61,12 +61,40 @@ class Pass {
   /// this is a generic OperationPass.
   Optional<StringRef> getOpName() const { return opName; }
 
+  //===--------------------------------------------------------------------===//
+  // Options
+  //===--------------------------------------------------------------------===//
+
+  /// This class represents a specific pass option, with a provided data type.
+  template <typename DataType>
+  struct Option : public detail::PassOptions::Option<DataType> {
+    template <typename... Args>
+    Option(Pass &parent, StringRef arg, Args &&... args)
+        : detail::PassOptions::Option<DataType>(parent.passOptions, arg,
+                                                std::forward<Args>(args)...) {}
+    using detail::PassOptions::Option<DataType>::operator=;
+  };
+  /// This class represents a specific pass option that contains a list of
+  /// values of the provided data type.
+  template <typename DataType>
+  struct ListOption : public detail::PassOptions::ListOption<DataType> {
+    template <typename... Args>
+    ListOption(Pass &parent, StringRef arg, Args &&... args)
+        : detail::PassOptions::ListOption<DataType>(
+              parent.passOptions, arg, std::forward<Args>(args)...) {}
+    using detail::PassOptions::ListOption<DataType>::operator=;
+  };
+
+  /// Attempt to initialize the options of this pass from the given string.
+  LogicalResult initializeOptions(StringRef options);
+
   /// Prints out the pass in the textual representation of pipelines. If this is
   /// an adaptor pass, print with the op_name(sub_pass,...) format.
-  /// Note: The default implementation uses the class name and does not respect
-  /// options used to construct the pass. Override this method to allow for your
-  /// pass to be to be round-trippable to the textual format.
-  virtual void printAsTextualPipeline(raw_ostream &os);
+  void printAsTextualPipeline(raw_ostream &os);
+
+  //===--------------------------------------------------------------------===//
+  // Statistics
+  //===--------------------------------------------------------------------===//
 
   /// This class represents a single pass statistic. This statistic functions
   /// similarly to an unsigned integer value, and may be updated and incremented
@@ -119,6 +147,10 @@ class Pass {
     return getPassState().analysisManager;
   }
 
+  /// Copy the option values from 'other', which is another instance of this
+  /// pass.
+  void copyOptionValuesFrom(const Pass *other);
+
 private:
   /// Forwarding function to execute this pass on the given operation.
   LLVM_NODISCARD
@@ -141,6 +173,9 @@ class Pass {
   /// The set of statistics held by this pass.
   std::vector<Statistic *> statistics;
 
+  /// The pass options registered to this pass instance.
+  detail::PassOptions passOptions;
+
   /// Allow access to 'clone' and 'run'.
   friend class OpPassManager;
 };
@@ -204,7 +239,9 @@ class PassModel : public BasePassT {
 
   /// A clone method to create a copy of this pass.
   std::unique_ptr<Pass> clone() const override {
-    return std::make_unique<PassT>(*static_cast<const PassT *>(this));
+    auto newInst = std::make_unique<PassT>(*static_cast<const PassT *>(this));
+    newInst->copyOptionValuesFrom(this);
+    return newInst;
   }
 
   /// Returns the analysis for the parent operation if it exists.

include/mlir/Pass/PassOptions.h

@@ -24,50 +24,202 @@
 
 namespace mlir {
 namespace detail {
-/// Base class for PassOptions<T> that holds all of the non-CRTP features.
-class PassOptionsBase : protected llvm::cl::SubCommand {
+/// Base container class and manager for all pass options.
+class PassOptions : protected llvm::cl::SubCommand {
+private:
+  /// This is the type-erased option base class. This provides some additional
+  /// hooks into the options that are not available via llvm::cl::Option.
+  class OptionBase {
+  public:
+    virtual ~OptionBase() = default;
+
+    /// Out of line virtual function to provide home for the class.
+    virtual void anchor();
+
+    /// Print the name and value of this option to the given stream.
+    virtual void print(raw_ostream &os) = 0;
+
+    /// Return the argument string of this option.
+    StringRef getArgStr() const { return getOption()->ArgStr; }
+
+  protected:
+    /// Return the main option instance.
+    virtual const llvm::cl::Option *getOption() const = 0;
+
+    /// Copy the value from the given option into this one.
+    virtual void copyValueFrom(const OptionBase &other) = 0;
+
+    /// Allow access to private methods.
+    friend PassOptions;
+  };
+
+  /// This is the parser that is used by pass options that use literal options.
+  /// This is a thin wrapper around the llvm::cl::parser, that exposes some
+  /// additional methods.
+  template <typename DataType>
+  struct GenericOptionParser : public llvm::cl::parser<DataType> {
+    using llvm::cl::parser<DataType>::parser;
+
+    /// Returns an argument name that maps to the specified value.
+    Optional<StringRef> findArgStrForValue(const DataType &value) {
+      for (auto &it : this->Values)
+        if (it.V.compare(value))
+          return it.Name;
+      return llvm::None;
+    }
+  };
+
+  /// The specific parser to use depending on llvm::cl parser used. This is only
+  /// necessary because we need to provide additional methods for certain data
+  /// type parsers.
+  /// TODO(riverriddle) We should upstream the methods in GenericOptionParser to
+  /// avoid the need to do this.
+  template <typename DataType>
+  using OptionParser =
+      std::conditional_t<std::is_base_of<llvm::cl::generic_parser_base,
+                                         llvm::cl::parser<DataType>>::value,
+                         GenericOptionParser<DataType>,
+                         llvm::cl::parser<DataType>>;
+
+  /// Utility methods for printing option values.
+  template <typename DataT>
+  static void printOptionValue(raw_ostream &os,
+                               GenericOptionParser<DataT> &parser,
+                               const DataT &value) {
+    if (Optional<StringRef> argStr = parser.findArgStrForValue(value))
+      os << argStr;
+    else
+      llvm_unreachable("unknown data value for option");
+  }
+  template <typename DataT, typename ParserT>
+  static void printOptionValue(raw_ostream &os, ParserT &parser,
+                               const DataT &value) {
+    os << value;
+  }
+  template <typename ParserT>
+  static void printOptionValue(raw_ostream &os, ParserT &parser,
+                               const bool &value) {
+    os << (value ? StringRef("true") : StringRef("false"));
+  }
+
 public:
   /// This class represents a specific pass option, with a provided data type.
-  template <typename DataType> struct Option : public llvm::cl::opt<DataType> {
+  template <typename DataType>
+  class Option : public llvm::cl::opt<DataType, /*ExternalStorage=*/false,
+                                      OptionParser<DataType>>,
+                 public OptionBase {
+  public:
     template <typename... Args>
-    Option(PassOptionsBase &parent, StringRef arg, Args &&... args)
-        : llvm::cl::opt<DataType>(arg, llvm::cl::sub(parent),
-                                  std::forward<Args>(args)...) {
+    Option(PassOptions &parent, StringRef arg, Args &&... args)
+        : llvm::cl::opt<DataType, /*ExternalStorage=*/false,
+                        OptionParser<DataType>>(arg, llvm::cl::sub(parent),
+                                                std::forward<Args>(args)...) {
       assert(!this->isPositional() && !this->isSink() &&
              "sink and positional options are not supported");
+      parent.options.push_back(this);
+    }
+    using llvm::cl::opt<DataType, /*ExternalStorage=*/false,
+                        OptionParser<DataType>>::operator=;
+    ~Option() override = default;
+
+  private:
+    /// Return the main option instance.
+    const llvm::cl::Option *getOption() const final { return this; }
+
+    /// Print the name and value of this option to the given stream.
+    void print(raw_ostream &os) final {
+      os << this->ArgStr << '=';
+      printOptionValue(os, this->getParser(), this->getValue());
+    }
+
+    /// Copy the value from the given option into this one.
+    void copyValueFrom(const OptionBase &other) final {
+      this->setValue(static_cast<const Option<DataType> &>(other).getValue());
     }
   };
 
   /// This class represents a specific pass option that contains a list of
   /// values of the provided data type.
-  template <typename DataType> struct List : public llvm::cl::list<DataType> {
+  template <typename DataType>
+  class ListOption : public llvm::cl::list<DataType, /*StorageClass=*/bool,
+                                           OptionParser<DataType>>,
+                     public OptionBase {
+  public:
     template <typename... Args>
-    List(PassOptionsBase &parent, StringRef arg, Args &&... args)
-        : llvm::cl::list<DataType>(arg, llvm::cl::sub(parent),
-                                   std::forward<Args>(args)...) {
+    ListOption(PassOptions &parent, StringRef arg, Args &&... args)
+        : llvm::cl::list<DataType, /*StorageClass=*/bool,
+                         OptionParser<DataType>>(arg, llvm::cl::sub(parent),
+                                                 std::forward<Args>(args)...) {
       assert(!this->isPositional() && !this->isSink() &&
              "sink and positional options are not supported");
+      parent.options.push_back(this);
+    }
+    ~ListOption() override = default;
+
+    /// Allow assigning from an ArrayRef.
+    ListOption<DataType> &operator=(ArrayRef<DataType> values) {
+      (*this)->assign(values.begin(), values.end());
+      return *this;
+    }
+
+    std::vector<DataType> *operator->() { return &*this; }
+
+  private:
+    /// Return the main option instance.
+    const llvm::cl::Option *getOption() const final { return this; }
+
+    /// Print the name and value of this option to the given stream.
+    void print(raw_ostream &os) final {
+      os << this->ArgStr << '=';
+      auto printElementFn = [&](const DataType &value) {
+        printOptionValue(os, this->getParser(), value);
+      };
+      interleave(*this, os, printElementFn, ",");
+    }
+
+    /// Copy the value from the given option into this one.
+    void copyValueFrom(const OptionBase &other) final {
+      (*this) = ArrayRef<DataType>((ListOption<DataType> &)other);
     }
   };
 
+  PassOptions() = default;
+
+  /// Copy the option values from 'other' into 'this', where 'other' has the
+  /// same options as 'this'.
+  void copyOptionValuesFrom(const PassOptions &other);
+
   /// Parse options out as key=value pairs that can then be handed off to the
   /// `llvm::cl` command line passing infrastructure. Everything is space
   /// separated.
   LogicalResult parseFromString(StringRef options);
+
+  /// Print the options held by this struct in a form that can be parsed via
+  /// 'parseFromString'.
+  void print(raw_ostream &os);
+
+private:
+  /// A list of all of the opaque options.
+  std::vector<OptionBase *> options;
 };
 } // end namespace detail
 
-/// Subclasses of PassOptions provide a set of options that can be used to
-/// initialize a pass instance. See PassRegistration for usage details.
+//===----------------------------------------------------------------------===//
+// PassPipelineOptions
+//===----------------------------------------------------------------------===//
+
+/// Subclasses of PassPipelineOptions provide a set of options that can be used
+/// to initialize a pass pipeline. See PassPipelineRegistration for usage
+/// details.
 ///
 /// Usage:
 ///
-/// struct MyPassOptions : PassOptions<MyPassOptions> {
-///   List<int> someListFlag{
+/// struct MyPipelineOptions : PassPipelineOptions<MyPassOptions> {
+///   ListOption<int> someListFlag{
 ///        *this, "flag-name", llvm::cl::MiscFlags::CommaSeparated,
 ///        llvm::cl::desc("...")};
 /// };
-template <typename T> class PassOptions : public detail::PassOptionsBase {
+template <typename T> class PassPipelineOptions : public detail::PassOptions {
 public:
   /// Factory that parses the provided options and returns a unique_ptr to the
   /// struct.
@@ -81,7 +233,8 @@ template <typename T> class PassOptions : public detail::PassOptionsBase {
 
 /// A default empty option struct to be used for passes that do not need to take
 /// any options.
-struct EmptyPassOptions : public PassOptions<EmptyPassOptions> {};
+struct EmptyPipelineOptions : public PassPipelineOptions<EmptyPipelineOptions> {
+};
 
 } // end namespace mlir