[mlir-reduce] Add doc for usage of mlir-reduce

[jpienaar]

Quick pass 🙂

mlir/docs/Tools/MLIRREDUCE.md

1

Could the filename of the doc match the file name of the tool?

5

Let's consistently capitalize MLIR

5

trigger bugs? Unexpected behavior feels passive :-) We want to be able to reduce the size of a reproducer for a bug.

12

One of the largest ones (the largest?) is simply deleting code not required to reproduce an error. Which is done very heuristically/without maintaining any semantics. I think that's important to have early that it's not an optimization, this changes the program in a way that is "wrong" but useful.

14

Let's explain interesting right after.

[Chia-hungDuan]

Addressed review comments

[jpienaar]

mlir/docs/Tools/mlir-reduce.md

5 ↗

(On Diff #350238)

An MLIR input ? (it need not be a Module)

7–8 ↗

(On Diff #350238)

describes mlir-reduce, a tool that can reduce the size of the input needed to trigger the error.

10 ↗

(On Diff #350238)

This whole document is about MLIR reduce, so I think you can remove this heading

12–13 ↗

(On Diff #350238)

s/.../including/ ?

15 ↗

(On Diff #350238)

s/a module/an input/g (just to be more general, any top level input could work)

15–16 ↗

(On Diff #350238)

s/.../is interesting, e.g., exhibits the characteristics that you would like to focus on/ (shorten and combine with next sentence)

18 ↗

(On Diff #350238)

s/.../invocation fails/ ? (just a little bit more general but I think specific enough still)

20–21 ↗

(On Diff #350238)

I feel this could go close to the start, just before the last sentence in first paragraph.

23 ↗

(On Diff #350238)

Lets tag this section with a heading "Available reducer passes" or some such

I would consider doing an example invocation here to show usage before explaining all the different reducers

25 ↗

(On Diff #350238)

You may have to clarify here what you mean with redundant. I believe it is meant as extraneous to interestingness (e.g., we can remove them and the case remains interesting, rather than they are redundant to the semantics of the input)

26 ↗

(On Diff #350238)

s/way//

27 ↗

(On Diff #350238)

s/.../as long as it/

27 ↗

(On Diff #350238)

Is this true now? I thought we now ran verification too, so the output is still valid.

33 ↗

(On Diff #350238)

It isn't necessarily that one knows this, it is more that the pattern will be attempted and if it doesn't retain the problem, it will just be discarded (e.g., it would naturally not be explored further wherever the pattern does not retain the interestingness)

39 ↗

(On Diff #350238)

s/abundant// :) (or potentially we could just say MLIR does not have a fixed set of dialects)

39 ↗

(On Diff #350238)

In a way all is custom and so nothing is custom. There aren't 2 tiers here, how its defined is uniform. So I'd drop this. Or you could say "dialect specific rewrite patterns"

62 ↗

(On Diff #350238)

Perhaps, you can freely intermix regular optimization passes (that retain semantics) with reducer specific passes?

78 ↗

(On Diff #350238)

s/hint/specify/ ?

94 ↗

(On Diff #350238)

[for follow up] That is a bit surprising. Could we change that? standard in or positional argument is how mlir-opt and the other tools work. Being able to pipe the result from a tool into reduce would be nice too (but I don't know if the input file is too hard coded).

98 ↗

(On Diff #350238)

And this is only needed if 1) one uses custom syntax, 2) failure is due to verification in dialect, 3) there is dialect-specific reducer patterns?

117 ↗

(On Diff #350238)

reduce

120 ↗

(On Diff #350238)

You mean somewhere on disk? Perhaps lets rephrase this, the feature we want is that it should produce the most optimal result thus far when interrupted.

123 ↗

(On Diff #350238)

OOC why does this matter? As long as it is interesting model, the tool just trying all the things seems OK (potentially inefficient if we know some won't help, but not sure beyond that)

[Chia-hungDuan]

mlir/docs/Tools/mlir-reduce.md

25 ↗

(On Diff #350238)

Agree, the redundant may be confusing. Removed

27 ↗

(On Diff #350238)

Yes, mlir-reduce now only accepts/outputs valid file. Explained in down below, "To avoid that...". Just want to remind that the user also needs to provide valid input.

39 ↗

(On Diff #350238)

Removed. Yes, I think it'll be simpler.

62 ↗

(On Diff #350238)

Yes, I'm thinking of merging the two passes into one, this may be easier for the user's perspective(only choose the tree traversal strategies, don't bother with the set of regular optimization passes)

I'm planning that now and will have solution soon. We can keep the doc in sync with it during the review.

94 ↗

(On Diff #350238)

Revisiting this part, will update this afterwards

98 ↗

(On Diff #350238)

Add the explanation of when we need a custom one.

123 ↗

(On Diff #350238)

I was uncertain for this one, was thinking the case like, we knew that some patterns won't work then we can exclude them for getting shorter reduce time.

Now I think we should let the user as easy as possible to use it. the item is removed.

[Chia-hungDuan]

Addressed review comments

[Chia-hungDuan]

Remove description of -opt-reduction-pass which will be removed soon.

[jpienaar]

Nice, thanks!

mlir/docs/Tools/mlir-reduce.md

6 ↗

(On Diff #354450)

"we" or perhaps even better "developers"

[Chia-hungDuan]

Addressed review comment and fixed the syntax

mlir/docs/Tools/MLIRREDUCE.md

+# MLIR Reduce
+
+[TOC]
+
+A mlir module may contain unexpected behaviors after series of transformations.
+To root cause the problem or help verification after fixes, we may want to have
+a smaller case to work with. This document describes how we can narrow down a
+mlir module.
+
+## MLIR Reduce
+
+`mlir-reduce` supports reducing the module in several ways, e.g., rewrite
+complicated patterns into simpler form. To use it, the first thing you need to
+do is, provide a command which tells if a module is still the interesting case
+as the original module. Afterwards, select your reduction strategy then
+`mlir-reduce` will do the remining works for you. It's similar to
+[bugpoint](https://llvm.org/docs/CommandGuide/bugpoint.html).
+
+### Remove redundant operations
+
+`mlir-reduce` will try to remove a redundant operation by either eliminating it
+directly or applying some patterns. This is the most aggressive reduction way
+as it may result in an invalid module and we may end up retaining the error
+message. To avoid that, `mlir-reduce` always checks the validity and it expects
+the user will provide a valid module as well.
+
+### Reduce complicated patterns into simpler forms
+
+In some cases, you may want to rewrite an operation into a form you know which
+will not affect the problem you're debugging and it's simpler and smaller. For
+example, you may want to rewrite a tensor<?xindex> with unknown rank into a
+constant rank one like tensor<1xi32>. This may introduce further reduction
+chances because of precise type information.
+
+MLIR supports abundant dialects and `mlir-reduce` supports custom rewrite
+patterns for every dialect as well. To do that, you need to implement the
+`DialectReductionPatternInterface`. For example,
+
+```c++
+#include "mlir/Reducer/ReductionPatternInterface.h"
+
+struct MyReductionPatternInterface : public DialectReductionPatternInterface {
+  virtual void
+  populateReductionPatterns(RewritePatternSet &patterns) const final {
+    populateMyReductionPatterns(patterns);
+  }
+}
+```
+
+`mlir-reduce` will call `populateReductionPatterns` to collect the reduction
+rewrite patterns provided by each dialect. Here's a hint, if you use
+[DRR](../DeclarativeRewrites.md) to write the reduction patterns, you can
+leverage the method `populateWithGenerated` generated by `mlir-tblgen`.
+
+### Reduce with built-in passes
+
+MLIR provides amount of tranformation passes and some of them are useful for
+reducing the module size, e.g., Symbol-DCE. You can just use them to reduce the
+module.
+
+## How to Use it
+
+So far we provide two modes, the first one is reduction-tree, it will generate
+several reduced modules and try to do further reduction in between them. It will
+form a tree structure which tells how each intermediate module is reduced.
+According to different tree traversal mode, it may lead to different result. You
+can run with `-reduction-tree='traversal-mode=0'` for example.
+
+The second mode is opt-reduction-pass, it applies the given passes to reduce the
+module. Run it with arg `-opt-reduction-pass='opt-pass=symbol-dce'`.
+
+### Write the script for testing interesting
+
+As mentioned, you need to provide a command to hint `mlir-reduce` which case
+you're intersting. For each intermediate module generated during reduction,
+`mlir-reduce` will run the command over the intermediate module, return 1 for
+interesting case, 0 otherwise. The sample script,
+
+```shell
+mlir-opt -convert-vector-to-spirv $1 | grep "failed to materialize"
+if [[ $? -eq 0 ]]; then
+  exit 1
+else
+  exit 0
+fi
+```
+
+The sample command looks like `mlir-reduce $MLIR_MODULE
+-reduction-tree='traversal-mode=0 test=$TEST_SCRIPT'` note that the `test`
+argument is part of the mode argument.
+
+### Use with custom dialects
+
+To run with custom dialects, you need to build your own `mlir-reduce` and load
+the desired dialects. You need to link it with `MLIRReduceLib` and implement it
+like,
+
+```c++
+#include "mlir/Tools/mlir-reduce/MlirReduceMain.h"
+using namespace mlir;
+
+int main(int argc, char **argv) {
+  DialectRegistry registry;
+  registerMyDialects(registry);
+  MLIRContext context(registry);
+  return failed(mlirReduceMain(argc, argv, context));
+}
+
+```
+
+## Future works
+
+`mlir-reudce` is missing several features,
+* `-reduction-tree` now only supports `Single-Path` traversal mode, extends it
+  with different traveral strategies may reduce the module better.
+* Doesn't keep the intermediate optimal reduced module. The reduction process
+  may take a quite long time, it'll be better to interrupt it and we still can
+  get a reduced module so far.
+* Can't select the reduction patterns through command-line. For different cases,
+  we may only want to apply the part of reduction patterns.