[Mlir-commits] [mlir] Add minor doc improvements (PR #70984)

[Jeremy Kun]

https://github.com/j2kun created https://github.com/llvm/llvm-project/pull/70984

- Document legacy ops lowered by `convert-func-to-llvm` and link it to a GH issue
- Document the need for bufferization before `convert-linalg-to-loops`
- Document the ops lowered by `expand-strided-metadata`.

>From a52f5e41bebd0f8fb0be525679001fb2590cbfa4 Mon Sep 17 00:00:00 2001
From: Jeremy Kun <jkun at google.com>
Date: Wed, 1 Nov 2023 14:03:41 -0700
Subject: [PATCH 1/3] Link func-to-llvm TODO to a new issue and document it

---
 mlir/include/mlir/Conversion/Passes.td        | 4 ++++
 mlir/lib/Conversion/FuncToLLVM/FuncToLLVM.cpp | 3 ++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/mlir/include/mlir/Conversion/Passes.td b/mlir/include/mlir/Conversion/Passes.td
index d7253212e5fe3f8..08ad52e7a778c64 100644
--- a/mlir/include/mlir/Conversion/Passes.td
+++ b/mlir/include/mlir/Conversion/Passes.td
@@ -391,6 +391,10 @@ def ConvertFuncToLLVMPass : Pass<"convert-func-to-llvm", "ModuleOp"> {
     1 value is returned, packed into an LLVM IR struct type. Function calls and
     returns are updated accordingly. Block argument types are updated to use
     LLVM IR types.
+
+    Note that until https://github.com/llvm/llvm-project/issues/70982 is resolved,
+    this pass includes patterns that lower `arith` and `cf` to LLVM. This is legacy
+    code due to when they were all converted in the same pass.
   }];
   let dependentDialects = ["LLVM::LLVMDialect"];
   let options = [
diff --git a/mlir/lib/Conversion/FuncToLLVM/FuncToLLVM.cpp b/mlir/lib/Conversion/FuncToLLVM/FuncToLLVM.cpp
index 3126d1dee32cbc5..84e145c98e971e7 100644
--- a/mlir/lib/Conversion/FuncToLLVM/FuncToLLVM.cpp
+++ b/mlir/lib/Conversion/FuncToLLVM/FuncToLLVM.cpp
@@ -804,7 +804,8 @@ struct ConvertFuncToLLVMPass
     RewritePatternSet patterns(&getContext());
     populateFuncToLLVMConversionPatterns(typeConverter, patterns, symbolTable);
 
-    // TODO: Remove these in favor of their dedicated conversion passes.
+    // TODO(https://github.com/llvm/llvm-project/issues/70982): Remove these in
+    // favor of their dedicated conversion passes.
     arith::populateArithToLLVMConversionPatterns(typeConverter, patterns);
     cf::populateControlFlowToLLVMConversionPatterns(typeConverter, patterns);
 

>From 998ecf2477c5d8b6db0283e6969a159899c241ed Mon Sep 17 00:00:00 2001
From: Jeremy Kun <jkun at google.com>
Date: Wed, 1 Nov 2023 14:04:07 -0700
Subject: [PATCH 2/3] Document need for bufferization before
 convert-linalg-to-loops

---
 mlir/include/mlir/Dialect/Linalg/Passes.td | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/mlir/include/mlir/Dialect/Linalg/Passes.td b/mlir/include/mlir/Dialect/Linalg/Passes.td
index 3093604af63e338..cca50e21d5ce0bd 100644
--- a/mlir/include/mlir/Dialect/Linalg/Passes.td
+++ b/mlir/include/mlir/Dialect/Linalg/Passes.td
@@ -69,6 +69,13 @@ def LinalgLowerToAffineLoops : Pass<"convert-linalg-to-affine-loops"> {
 
 def LinalgLowerToLoops : Pass<"convert-linalg-to-loops"> {
   let summary = "Lower the operations from the linalg dialect into loops";
+  let description = [{
+    Lowers the `linalg` ops to loop nests using `scf.for`.
+
+    Pre-condition: the operands used by the `linalg` ops have buffer semantics,
+    i.e., tensor operands and results must be converted to memrefs via
+    bufferization.
+  }];
   let constructor = "mlir::createConvertLinalgToLoopsPass()";
   let dependentDialects = [
     "linalg::LinalgDialect",

>From a88b204b47d2453c1e51176d8d6b991eb4e235a6 Mon Sep 17 00:00:00 2001
From: Jeremy Kun <jkun at google.com>
Date: Wed, 1 Nov 2023 14:04:37 -0700
Subject: [PATCH 3/3] document the ops lowered by expand-strided-metadata

This will make it easier to index from the op you want to lower
to the pass that can lower it.

Ideally there is a more robust long-term solution to this,
but for now a quick doc update can't hurt.
---
 mlir/include/mlir/Dialect/MemRef/Transforms/Passes.td | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/mlir/include/mlir/Dialect/MemRef/Transforms/Passes.td b/mlir/include/mlir/Dialect/MemRef/Transforms/Passes.td
index d7ee492b9e990e0..651ee05ae1f3cf2 100644
--- a/mlir/include/mlir/Dialect/MemRef/Transforms/Passes.td
+++ b/mlir/include/mlir/Dialect/MemRef/Transforms/Passes.td
@@ -196,6 +196,14 @@ def ExpandStridedMetadata : Pass<"expand-strided-metadata"> {
     In particular, this pass transforms operations into explicit sequence of
     operations that model the effect of this operation on the different metadata.
     This pass uses affine constructs to materialize these effects.
+
+    Supported ops include:
+
+    - `memref.collapse_shape`
+    - `memref.expand_shape`
+    - `memref.extract_aligned_pointer_as_index`
+    - `memref.extract_strided_metadata`
+    - `memref.subview`
   }];
   let constructor = "mlir::memref::createExpandStridedMetadataPass()";
   let dependentDialects = [