[MLIR][Docs] Add docs for Python-defined pass in Python bindings

[PragmaTwice]

Python-defined passes have been merged into the main branch for some time now. I believe adding a corresponding section in the documentation will help more users learn about this feature and understand how to use it.

This PR adds such a section to the docs of Python bindings, summarizing the feature and providing an example.

[llvmbot]

@llvm/pr-subscribers-mlir

Author: Twice (PragmaTwice)

Changes

Python-defined passes have been merged into the main branch for some time now. I believe adding a corresponding section in the documentation will help more users learn about this feature and understand how to use it.

This PR adds such a section to the docs of Python bindings, summarizing the feature and providing an example.

---

Full diff: https://github.com/llvm/llvm-project/pull/162833.diff

1 Files Affected:

• (modified) mlir/docs/Bindings/Python.md (+20)

diff --git a/mlir/docs/Bindings/Python.md b/mlir/docs/Bindings/Python.md
index 98ac635aa4ee2..893c6d48a88d2 100644
--- a/mlir/docs/Bindings/Python.md
+++ b/mlir/docs/Bindings/Python.md
@@ -1188,6 +1188,26 @@ which can be `import`ed  from the main dialect file, i.e.
 `python/mlir/dialects/<dialect-namespace>/passes.py` if it is undesirable to
 make the passes available along with the dialect.
 
+Passes can be defined as Python callables via the `PassManager.add` API.
+In such case, the callable is wrapped as an `mlir::Pass` internally and
+executed as part of the pass pipeline when `PassManager.run` is invoked.
+In the callable, the `op` parameter represents the current operation being transformed,
+while the `pass_` parameter provides access to the current `Pass` object,
+allowing actions such as `signalPassFailure()`.
+The lifetime of the callable is extended at least until the `PassManager` is destroyed.
+The following example code demonstrates how to define Python passes.
+
+```python
+def demo_pass(op, pass_):
+    # do something with the given op
+    pass
+
+pm = PassManager('any')
+pm.add(demo_pass)
+pm.add('some-cpp-defined-passes')
+...
+pm.run(some_op)
+```
 
 ### Other functionality
 

[makslevental]

Thanks!

[PragmaTwice]

Merging...