[Mlir-commits] [mlir] [mlir][docs] Update documentation for canonicalize. (PR #99753)

[Matthias Springer]

================
@@ -51,6 +55,61 @@ Some important things to think about w.r.t. canonicalization patterns:
 *   It is always good to eliminate operations entirely when possible, e.g. by
     folding known identities (like "x + 0 = x").
 
+*   Canonicalization isn't a great place to put pattens with expensive running
+    time (i.e. have O(n) complexity) or complicated cost models.
+
+*   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
+
+```
+  %0 = tensor.insert_slice %slice into
+     %x[0, 0, 0, 0, 0][1, 1, 1, 16, 32][1, 1, 1, 1, 1] :
+     tensor<16x32xf32> into tensor<1x1x1x16x32xf32>
+```
+
+to
+
+```
+  %0 = tensor.expand_shape %slice[[0,1,2,3], [4]] :
+           tensor<16x32xf32> into tensor<1x1x1x16x32xf32>
+```
+
+is not a good canonicalize pattern because it lose the destination style
+semantic.
+
+
+A pattern that transform (linalg.transpose is only use of %broadcast)
----------------
matthias-springer wrote:

This pattern would work even if `%broadcast` has multiple users. By creating a new broadcast instead of modifying the existing one in-place. If the old broadcast actually had only a single user, it would then DCE away. If not, we now have two broadcasts (which may not be a bad thing).

Swapping patterns/bubble-up patterns/bubble-down pattern are a common class of patterns. It would be nice to clarify if they are suitable for canonicalization.

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