[Mlir-commits] [mlir] 26b9a17 - [mlir:doc] Clarify requirements on `RewritePatterns`. (#218351)

[llvmlistbot at llvm.org]

Author: Ingo Müller
Date: 2026-08-25T10:01:22Z
New Revision: 26b9a1717b84330ef0d508e618ec1ed4e4e117ac

URL: https://github.com/llvm/llvm-project/commit/26b9a1717b84330ef0d508e618ec1ed4e4e117ac
DIFF: https://github.com/llvm/llvm-project/commit/26b9a1717b84330ef0d508e618ec1ed4e4e117ac.diff

LOG: [mlir:doc] Clarify requirements on `RewritePatterns`. (#218351)

This PR clarifies and extends the documentation of what
`RewritePattern`s and folders are allowed to do. The most noteworthy
addition is the requirement that they must produce verifiable IR. While
this is enforced by `MLIR_ENABLE_EXPENSIVE_PATTERN_API_CHECKS`, it has
not been mentioned in the markdown docs yet. The other changes are
clarifications on edge cases that I have seen people misunderstand or
overlook. The change also adds a note to the build flag that enables the
API checks.

---------

Signed-off-by: Ingo Müller <ingomueller at google.com>

Added: 
    

Modified: 
    mlir/docs/Canonicalization.md
    mlir/docs/DialectConversion.md
    mlir/docs/PatternRewriter.md

Removed: 
    


################################################################################
diff  --git a/mlir/docs/Canonicalization.md b/mlir/docs/Canonicalization.md
index 6fbcf09c51df3..492674c4e3bb0 100644
--- a/mlir/docs/Canonicalization.md
+++ b/mlir/docs/Canonicalization.md
@@ -186,7 +186,9 @@ root operation may be replaced (but not erased). It allows for updating an
 operation in-place, or returning a set of pre-existing values (or attributes) to
 replace the operation with. This ensures that the `fold` method is a truly
 "local" transformation, and can be invoked without the need for a pattern
-rewriter.
+rewriter. A folder must always preserve always preserve IR verifiability
+(similar to [rewrite patterns](PatternRewriter.md#restrictions), where that
+property is highly recommended).
 
 In [ODS](DefiningDialects/Operations.md), an operation can set the `hasFolder` bit to generate
 a declaration for the `fold` method. This method takes on a 
diff erent form,

diff  --git a/mlir/docs/DialectConversion.md b/mlir/docs/DialectConversion.md
index b73aa04398103..7323f473802bf 100644
--- a/mlir/docs/DialectConversion.md
+++ b/mlir/docs/DialectConversion.md
@@ -559,8 +559,10 @@ to the entry block of the region. The types of the entry block arguments are
 often tied semantically to the operation, e.g., `func::FuncOp`, `AffineForOp`,
 etc.
 
-To convert the signature of just one given block, the
-`applySignatureConversion` hook can be used.
+To convert the signature of just one given block, the `applySignatureConversion`
+hook can be used. Note that `applySignatureConversion` replaces and erases the
+original block, so each block's signature can be converted at most once per
+conversion run.
 
 A signature conversion, `TypeConverter::SignatureConversion`, can be built
 programmatically:

diff  --git a/mlir/docs/PatternRewriter.md b/mlir/docs/PatternRewriter.md
index 105a554b95851..39605c7acb7fe 100644
--- a/mlir/docs/PatternRewriter.md
+++ b/mlir/docs/PatternRewriter.md
@@ -78,10 +78,26 @@ public:
     possible mutations that may take place within a pattern. For example, this
     means that an operation should not be erased via its `erase` method. To
     erase an operation, the appropriate `PatternRewriter` hook (in this case
-    `eraseOp`) should be used instead.
+    `eraseOp`) should be used instead. Note that changes to nested ops, regions,
+    and blocks need to go through the rewriter as well.
 *   The root operation is required to either be: updated in-place, replaced, or
     erased.
 *   `matchAndRewrite` must return "success" if and only if the IR was modified.
+    In particular, this means that the pattern is not allowed to have made any
+    modification if it returns "failure".
+
+Additionally, there are some best practices that patterns are advised to follow:
+
+*   Patterns *should* transform verifiable IR into verifiable IR, i.e., the IR
+    should remain verifiable after every pattern application. However, there are
+    cases where rewrites are best split into several patterns and ensuring
+    verifiability would be cumbersome, such as changing a function declaration
+    and its call sites. In such cases it may be acceptable to temporarily have
+    unverifiable IR.
+
+**Note:** These restrictions and best practices can be checked at runtime by
+building with `-DMLIR_ENABLE_EXPENSIVE_PATTERN_API_CHECKS=ON` (ideally paired
+with ASan).
 
 
 ### Application Recursion