[Mlir-commits] [mlir] [mlir][docs] Add more examples for the "canonical form" (PR #173667)

[Mehdi Amini]

================
@@ -63,30 +63,37 @@ Some important things to think about w.r.t. canonicalization patterns:
 *   Canonicalize shouldn't lose the semantic of original operation: the original
     information should always be recoverable from the transformed IR.
 
-For example, a pattern that transform
-
-```
-  %transpose = linalg.transpose
-      ins(%input : tensor<1x2x3xf32>)
-      outs(%init1 : tensor<2x1x3xf32>)
-      dimensions = [1, 0, 2]
-  %out = linalg.transpose
-      ins(%transpose: tensor<2x1x3xf32>)
-      outs(%init2 : tensor<3x1x2xf32>)
-      permutation = [2, 1, 0]
-```
-
-to
-
-```
-  %out= linalg.transpose
-      ins(%input : tensor<1x2x3xf32>)
-      outs(%init2: tensor<3x1x2xf32>)
-      permutation = [2, 0, 1]
-```
-
-is a good canonicalization pattern because it removes a redundant operation,
-making other analysis optimizations and more efficient.
+## What is the Canonical Form?
+
+There is no single formally defined canonical form in MLIR. Some dialects
+define multiple forms, depending on the transformation ([example](https://mlir.llvm.org/docs/Rationale/RationaleLinalgDialect/#interchangeability-of-formsa-nameformsa)).
+The de-facto canonical form keeps evolving, as canonicalization patterns and
+folders are getting added / removed / modified by the community.
+
+The canonicalizer pass is integral to many downstream projects but offers no
+fine-grained control over individual patterns or foldings, making changes to
+the canonical form potentially contentious. Whether a transformation belongs
+in the canonical form must be decided on a case-by-case basis, but common
+community-agreed canonicalizations include:
+
+* Identity / no-op elimination. E.g., folding `arith.addi %x, %c0` to `%x` or
+  erasing `memref.copy %x, %x`.
+* Constant folding. E.g., folding `arith.addi %c1, %c2` to `%c3`.
----------------
joker-eph wrote:

```suggestion
* Scalar constant folding. E.g., folding `arith.addi %c1, %c2` to `%c3`. Note: this isn't true for "large" tensors where constant folding can lead to an IR-size explosion.
```


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