[Mlir-commits] [mlir] [MLIR] Add documentation page for `mlir-query` tool (PR #146535)

[llvmlistbot at llvm.org]

================
@@ -0,0 +1,355 @@
+`mlir-query` is an interactive tool designed to simplify IR exploration. It provides a REPL interface and supports an interactive query language for MLIR, enabling developers to query the MLIR IR dynamically.  
+The tool uses matchers as its core mechanism for performing queries over the MLIR IR, relying on simple matchers from `Matchers.h` and slicing-related matchers from `SliceMatchers.h`.  
+
+Through its IR exploration capabilities and the interactive query language, `mlir-query` serves both as a prototyping environment for pattern matchers and as a good debugging tool.
+
+## Usage
+
+### Query modes
+In order to prototype matchers, explore, test, or debug the MLIR IR, the tool provides two main usage modes:
+
+* **Run queries directly from the CLI:**
+    ```shell
+    ./mlir-query input.mlir -c "<your_query_1>" -c "<your_query_2>" ... -c "<your_query_N>"
+    ```
+    The commands are executed and the program exits immediately.
+
+* **Launch an interactive session:**
+    ```shell
+    ./mlir-query input.mlir
+    ```
+    Opens a REPL-like interface where you can type queries interactively.
+
+### Use with `mlir-opt`
+
+The tool can easily be used with the MLIR pass pipeline infrastructure by running a pass pipeline and passing the result as input to `mlir-query`. A command example is shown below:
+
+```shell
+./mlir-opt input.mlir -canonicalize | ./mlir-query - -c "<your_query_1>" -c "<your_query_2>" ... -c "<your_query_N>"
+```
+
+## Register custom matchers
+
+To register a custom matcher with `mlir-query`, define a structure that implements one of the following signatures: `bool match(Operation* op)` or `bool match(Operation* op, SetVector<Operation*> &matchedOps)` and then implement the desired matching logic. Next, link `MLIRQueryLib` and register the matcher.
+
+```cpp
+#include "mlir/Tools/mlir-query/MlirQueryMain.h"
+using namespace mlir;
+
+int main(int argc, char **argv) {
+
+  DialectRegistry dialectRegistry;
+  registerAllDialects(dialectRegistry);
+
+  query::matcher::Registry matcherRegistry;
+
+  // Replace <matcher_name> with your desired matcher identifier string.
+  matcherRegistry.registerMatcher("<matcher_name>", matcherInstance);
+
+  MLIRContext context(dialectRegistry);
+  return failed(mlirQueryMain(argc, argv, context, matcherRegistry));
+}
+```
+
+## Features
+### Autocompletion
+
+To simplify usage, `mlir-query` provides autocompletion in the REPL interface, enabling users to ease query input by pressing the Tab key. When autocompletion is first triggered, a list of available commands is displayed (e.g., `match`, `help`). Triggering autocompletion for the `match` command then shows a list of available matchers.
+<div style="overflow-x:auto; margin:1em 0;">
+  <img
+    src="https://i.imgur.com/3QiJgrU.gif"
+    alt="Autocompletion command list"
+    style="
+      display: block;
+      margin: 0 auto;
+      width: 1250px !important;
+      max-width: none !important;
+      height: auto !important;
+    "
+  />
+</div>
+The following GIF illustrates an autocompletion use case for constructing queries.
+<div style="overflow-x:auto; margin:1em 0;">
+  <img
+    src="https://i.imgur.com/bpMS9mf.gif"
+    alt="Autocompletion matcher"
+    style="
+      display: block;
+      margin: 0 auto;
+      width: 1250px !important;
+      max-width: none !important;
+      height: auto !important;
+    "
+  />
+</div>
+
+### Function extraction
+
+Results from a matcher can be isolated into a custom function using the `extract("functionName")` feature, facilitating further exploration or testing.
+
+#### Example
+
+The following is the initial function:
+
+```mlir
+func.func @slicing_memref_store_trivial() {
+  %0 = memref.alloc() : memref<10xf32>
+  %c0 = arith.constant 0 : index
+  %cst = arith.constant 0.000000e+00 : f32
+  affine.for %i1 = 0 to 10 {
+    %1 = affine.apply affine_map<()[s0] -> (s0)>()[%c0]
+    memref.store %cst, %0[%1] : memref<10xf32>
+    %2 = memref.load %0[%c0] : memref<10xf32>
+    %3 = affine.apply affine_map<()[] -> (0)>()[]
+    memref.store %cst, %0[%3] : memref<10xf32>
+    memref.store %2, %0[%c0] : memref<10xf32>
+  }
+  return
+}
+```
+
+The following command extracts the results of `getDefinitionsByPredicate` query:
+
+```shell
+./mlir-opt /home/user/llvm-project/mlir/test/mlir-query/slice-function-extraction.mlir "m getDefinitionsByPredicate(hasOpName(\"memref.store\"),hasOpName(\"memref.alloc\"),true,false,false).extract(\"backward_slice\")"
----------------
devajithvs wrote:

This is cool! I think it might be clearer to start with a simpler example for function extraction to show the basic idea, and then (if you want) follow up with a slightly more advanced one like this.

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