[Mlir-commits] [mlir] [NFC][MLIR] Document better linalg morphism (PR #154313)

[Javed Absar]

================
@@ -10,6 +10,84 @@
 #define MLIR_DIALECT_LINALG_PASSES
 
 include "mlir/Pass/PassBase.td"
+include "mlir/IR/Constraints.td"
+
+// ------------------ Begin of "form" conversions
+//
+// These conversions allow for the transformation of linalg ops between different forms.
+// Structured ops can be represented in different forms, such as named ops, category ops, and generic ops.
+//
+// The operation tree is as follows:
+//   generic     category      named
+//  ---------|-------------|----------
+//  generic ---> contract ----> matmul
+//           |              \-> batch_matmul
+//           |              \-> batch_reduce_matmul
+//           |              \-> ...
+//           \-> elementwise -> add
+//                          \-> sub
+//                          \-> ...
+//
+// Morphisms between representations can happen in the following 6 ways:
+//  generic <---> category <---> named
+//      \-------------------------/
+//
+// generic subsumes category which subsumes named.
+// The generalization path is guaranteed, the specialization path is not.
+
+def LinalgMorphOpsPass : Pass<"linalg-morph-ops"> {
+  let summary = "Convert linalg ops between forms";
+
+  let description = [{
+    Convert a linalg op from one representation to another equivalent.
+    For example, a linalg named op `linalg.add` can also be written as an
+    category op `linalg.elementwise`, and can also be re-written as
+    a `linalg.generic`, giving the morphism:
+
+      named-op <--> category_op (elementwise, contraction, ..) <--> generic
+
+    Note that the set of `linalg.generic` subsumes named and category ops
+    and therefore not all `linalg.genric` can be converted to  named or
+    category op. Similarly, catgory ops subsume named ops.
+
+    Note:
+     Legacy converters:
+     `--linalg-generalize-named-ops` is the path `named-op --> generic-op`
+     `--linalg-specialize-generic-ops` is the path `named-op <-- generic-op`
+  }];
+  let dependentDialects = ["linalg::LinalgDialect"];
+
+  let options = [
+    // Generalization path is guaranteed.
+    Option<"namedToCategory", "named-to-category", "bool", /*default=*/"false",
+           "convert named ops to category op e.g. `linalg.elementwise`">,
+    Option<"categoryToGeneric", "category-to-generic", "bool", /*default=*/"false",
+           "convert category ops e.g. `linalg.elementwise` to `linalg.generic`">,
+    Option<"namedToGeneric", "named-to-generic", "bool", /*default=*/"false",
+           "convert named ops e.g. `linalg.add` to `linalg.generic`">,
+    
+    // Specialization path is not guaranteed.
+    Option<"genericToNamed", "generic-to-named", "bool", /*default=*/"false",
+           "convert linalg.generic to equivalent named ops"> ];
+    //  TODOs: `generic-to-category`, `category-to-named`
+}
+
+def LinalgGeneralizeNamedOpsPass : Pass<"linalg-generalize-named-ops">, Deprecated<"Use 'linalg-morph-ops' instead."> {
----------------
javedabsar1 wrote:

should we format it to 8 cols max?

https://github.com/llvm/llvm-project/pull/154313