Skip to content

[MLIR] Improve Remark documentation to include mlir-opt usage #159284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

[MLIR] Improve Remark documentation to include mlir-opt usage #159284

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e4e2d1f
[MLIR] Remark more document
grypp Sep 17, 2025
cc673be
fx
grypp Sep 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 61 additions & 4 deletions mlir/docs/Remarks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,8 +96,16 @@ Neutral analysis results.

## Emitting Remarks

The `remark::*` helpers return an **in-flight remark**.
You append strings or key–value metrics using `<<`.
The `remark::*` helpers return an **`InFlightRemark`**. You can append strings
or key–value metrics using the `<<` operator.

By default, the remark is emitted as soon as the `InFlightRemark` object is
destroyed (typically at the end of its scope). However, it can sometimes be
useful to postpone emitting the remark until the end of the compilation—for example,
to collect all remarks, sort them, and emit them differently later.

If this behavior is desired, the `RemarkEngine` can be used to store postponed remarks.
[See this example of postponing remark emission](#example-postpone-remarks-emitting).

### Remark Options

Expand All @@ -108,8 +116,9 @@ When constructing a remark, you typically provide four fields that are `StringRe
3. **Sub-category** – more fine-grained classification
4. **Function name** – the function where the remark originates

### Examples

### Example
#### Emitting remarks

```c++
#include "mlir/IR/Remarks.h"
Expand Down Expand Up @@ -145,6 +154,19 @@ LogicalResult MyPass::runOnOperation() {
}
```

#### Example: Postpone remarks emitting

`RemarkOpts` has `postpone` option. When it is set, the remark emission will be
postponed until the end of the compilation.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should document when/why this is useful, not just "what". It's not obvious to me why a remark author would want to use this and when?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wrote it here:
https://github.com/grypp/llvm-project/blob/cc673be6642b49c2396e07b86c4e4e52c6b0e7a4/mlir/docs/Remarks.md?plain=1#L102-L105

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Postponing will be more useful with my new PR.

The new PR allows dropping or replacing earlier remarks when using postponing.
Here’s an example:

pass-early : remark(failed to unroll the loop)
pass-later : drop early remark, add remark(loop is unrolled)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's still not clear to me how this is a decision of the remark author, and the implicit coupling that can exist between the remark and the consumer here?


```c++

remark::passed(loc, remark::RemarkOpts::name("")
.category(categoryLoopunroll)
.subCategory(myPassname2)
.postpone()) << "loop is unrolled";
```

***

### Metrics and Shortcuts
Expand Down Expand Up @@ -189,7 +211,42 @@ metric("Remark", "vectorized loop")

***

## Enabling Remarks
## Enabling Remarks with `mlir-opt`

`mlir-opt` provides flags to enable and configure remarks. The available flags
are shown below:

```bash
$> mlir-opt --help
...
Remark Options:
Filter remarks by regular expression (llvm::Regex syntax).

--remark-format=<value> - Specify the format for remark output.
=emitRemark - Print as emitRemark to the command line
=yaml - Print as a YAML file
=bitstream - Print as a bitstream file
--remarks-filter=<string> - Show all remarks: passed, missed, failed, analysis
--remarks-filter-analyse=<string> - Show analysis remarks
--remarks-filter-failed=<string> - Show failed remarks
--remarks-filter-missed=<string> - Show missed remarks
--remarks-filter-passed=<string> - Show passed remarks
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is still the same issue with the help messages: "Show xxxx" is not well descriptive for something that is a filter.

--remarks-output-file=<string> - Output file for YAML and bitstream remark formats (default: mlir-remarks.yaml or mlir-remarks.bitstream)
```

There are five filter flags to select specific categories. The
`--remarks-filter` flag is a general shortcut that applies to all remark
categories. Their usage is as follows:

```bash
# This will only match remarks in the "my-interesting-category" category
mlir-opt --remarks-filter="my-interesting-category"

# You can also use "*" to match categories starting with "my"
mlir-opt --remarks-filter="my*"
```

## Enabling Remarks for downstream compilers via APIs

### 1. **With LLVMRemarkStreamer (YAML or Bitstream)**

Expand Down
Loading