[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.
----------------
matthias-springer wrote:

This example was probably chosen because it could trip up the bufferization analysis (and cause less efficient codegen). Destination-style was originally introduced to help with bufferization and I think there is currently no consensus on whether such "hints"/IR structures should be preserved by canonicalization.

The reader of this section may not know about destination style. Maybe a better example: rewriting a multiplication into a sequence of additions?


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