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

[Jacques Pienaar]

================
@@ -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\")"
+```
+
+The resulting function from the previous query is:
+
+
+```mlir
+func.func @backward_slice(%arg0: memref<10xf32>) -> (f32, index, index, f32, index, index, f32) {
+  %cst = arith.constant 0.000000e+00 : f32
+  %c0 = arith.constant 0 : index
+  %0 = affine.apply affine_map<()[s0] -> (s0)>()[%c0]
+  memref.store %cst, %arg0[%0] : memref<10xf32>
+  %cst_0 = arith.constant 0.000000e+00 : f32
+  %1 = affine.apply affine_map<() -> (0)>()
+  memref.store %cst_0, %arg0[%1] : memref<10xf32>
+  %c0_1 = arith.constant 0 : index
+  %2 = memref.load %arg0[%c0_1] : memref<10xf32>
+  memref.store %2, %arg0[%c0_1] : memref<10xf32>
+  return %cst, %c0, %0, %cst_0, %1, %c0_1, %2 : f32, index, index, f32, index, index, f32
+}
+```
+## Matcher overview
+
+This section details the current matchers and their capabilities. It does not include examples of every matcher but rather aims to showcase and explain the types of matchers, along with useful examples that should be sufficient for comprehension. For a detailed explanation of each matcher's functionality and its parameters, please refer to the matchers reference section.
+
+### Simple matchers
+
+The tool supports a variety of simple matchers, including `isConstantOp`, which finds all constant operations, `hasOpName`, which finds all operations with a given name and `hasOpAttrName`, which finds all operations with a certain attribute.
+
+#### Example
+The following IR is used to demonstrate a simple matcher.
+```mlir
----------------
jpienaar wrote:

newline above

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