[Mlir-commits] [mlir] [mlir][docs] Add docs on canonicalizers being folders or patterns (PR #129517)

[Kunwar Grover]

https://github.com/Groverkss updated https://github.com/llvm/llvm-project/pull/129517

>From 63b5096c6092da04a31aecfdc636fcc316a1390e Mon Sep 17 00:00:00 2001
From: Kunwar Grover <groverkss at gmail.com>
Date: Mon, 3 Mar 2025 11:39:53 +0000
Subject: [PATCH 1/3] [mlir][docs] Add docs on canonicalizers being folders or
 patterns

---
 mlir/docs/Canonicalization.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/mlir/docs/Canonicalization.md b/mlir/docs/Canonicalization.md
index 6e59a4128093a..c0553d6698c6a 100644
--- a/mlir/docs/Canonicalization.md
+++ b/mlir/docs/Canonicalization.md
@@ -275,3 +275,26 @@ Operation *MyDialect::materializeConstant(OpBuilder &builder, Attribute value,
   ...
 }
 ```
+
+### Choosing between implementing a Folder or a `RewritePattern`
+
+When implementing a new canonicalization, an important thing to think about is
+if the canonicalization should be a folder or a `RewritePattern`. The generally
+accepted policy is:
+
+*   If a transformation should be a canonicalizer is a different question from
+    if a transformation should be a folder or a `RewritePattern`. A
+    transformation is promoted to a canonicalization as defined by the General
+    Design of canonicalizations.
+
+*   If a transformation is a canonicalization, there are two ways to implement
+    it: As a Folder or as a `RewritePattern`, both of which are implementation
+    details of how a canonicalization exists, with the difference being folders
+    have restrictions on what they can do. A `RewritePattern` can implement any
+    transformation a folder can.
+
+*   A canonicalization should always be implemented as a Folder if it fits
+    the "local" definition of a folder.
+
+*   If a canonicalization does not fit as a folder, it should be implemented
+    as a `RewritePattern`.

>From 3f23b4dbeaec87e3346414966870d33ea11d45ae Mon Sep 17 00:00:00 2001
From: Kunwar Grover <groverkss at gmail.com>
Date: Mon, 3 Mar 2025 16:22:57 +0000
Subject: [PATCH 2/3] Address comment

---
 mlir/docs/Canonicalization.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/mlir/docs/Canonicalization.md b/mlir/docs/Canonicalization.md
index c0553d6698c6a..cd5e54e806efd 100644
--- a/mlir/docs/Canonicalization.md
+++ b/mlir/docs/Canonicalization.md
@@ -294,7 +294,5 @@ accepted policy is:
     transformation a folder can.
 
 *   A canonicalization should always be implemented as a Folder if it fits
-    the "local" definition of a folder.
-
-*   If a canonicalization does not fit as a folder, it should be implemented
+    the "local" definition of a folder, otherwise it should be implemented
     as a `RewritePattern`.

>From d28d2f976deeb541021e54c622fedc6716ad29cb Mon Sep 17 00:00:00 2001
From: Kunwar Grover <groverkss at gmail.com>
Date: Wed, 5 Mar 2025 15:13:41 +0000
Subject: [PATCH 3/3] address comments

---
 mlir/docs/Canonicalization.md | 24 ++++--------------------
 1 file changed, 4 insertions(+), 20 deletions(-)

diff --git a/mlir/docs/Canonicalization.md b/mlir/docs/Canonicalization.md
index cd5e54e806efd..686e50025e9f0 100644
--- a/mlir/docs/Canonicalization.md
+++ b/mlir/docs/Canonicalization.md
@@ -276,23 +276,7 @@ Operation *MyDialect::materializeConstant(OpBuilder &builder, Attribute value,
 }
 ```
 
-### Choosing between implementing a Folder or a `RewritePattern`
-
-When implementing a new canonicalization, an important thing to think about is
-if the canonicalization should be a folder or a `RewritePattern`. The generally
-accepted policy is:
-
-*   If a transformation should be a canonicalizer is a different question from
-    if a transformation should be a folder or a `RewritePattern`. A
-    transformation is promoted to a canonicalization as defined by the General
-    Design of canonicalizations.
-
-*   If a transformation is a canonicalization, there are two ways to implement
-    it: As a Folder or as a `RewritePattern`, both of which are implementation
-    details of how a canonicalization exists, with the difference being folders
-    have restrictions on what they can do. A `RewritePattern` can implement any
-    transformation a folder can.
-
-*   A canonicalization should always be implemented as a Folder if it fits
-    the "local" definition of a folder, otherwise it should be implemented
-    as a `RewritePattern`.
+### When to use the `fold` method vs `RewriterPattern`s for canonicalizations
+
+A canonicalization should always be implemented as a `fold` method if it can
+be, otherwise it should be implemented as a `RewritePattern`.