[Mlir-commits] [mlir] [MLIR][Linalg][Docs] Add forms to Linalg rationale docs (PR #156859)

[Renato Golin]

================
@@ -506,6 +506,58 @@ potential by introducing lower-level IR ops and *smaller* Linalg ops.
 This gradually reduces the potential, all the way to Loops + VectorOps
 and LLVMIR.
 
+### Interchangeability of Forms<a name="forms"></a>
+
+#### The Linalg Forms
+
+The core Linalg operation tree has three forms:
+* **Generic:** Represented by `linalg.generic` and can encode all perfectly-nested
+loop operations.
+* **Category:** Represented by `linalg.contract` and `linalg.elementwise`,
+which are special (einsum) forms of the `generic` operation. In the future, other
+category operations are planned (e.g.: `linalg.convolution` and `linalg.pooling`).
+* **Named:** All _named_ forms that can lower to either _category_ or
+_generic_ forms. For example, `linalg.matmul`, `linalg.add`, etc.
+
+Unlike lowering to loops, the different Linalg forms that are derived from
+`linalg.generic` are *equivalent*. It should always be possible to convert
+a named operation into a generic and back to named, if the semantics are
+preserved. The various forms in the Linalg dialect are meant to facilitate
+pattern matching (single operations or DAGs) and to be able to consider
+different forms as *canonical* for different transforms.
+
+In addition to the three forms above, there's a separate class that does not
+belong to the tree, as it does not generalize. These are **composite:** operations
+that compose multiple Linalg operations, for example `linalg.softmax` and
+`linalg.winograd*`. These can be converted to a DAG of Linalg operations.
+
+Linalg's various forms (named, generic) also carry information, and that
+information should be preserved as much as possible during the progressive
+lowering. A `matmul` operation is a special case of a `contract` operation,
+which in turn is a special case of `generic` operation. Transformations on
+the more special forms should not be converted to the more generic ones
----------------
rengolin wrote:

This phrase seems outdated after the new changes. The keyword there (and you left out 😄 ) was _"unnecessarily"_. If you want to match against `linalg.matmul`, do not convert to `linalg.generic`. But now that meaning is obvious from the context and we can remove the phrase.

The relevant statement is indeed the lowering one and I'll leave that one, but remove the one about unnecessary conversion.

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