[Mlir-commits] [mlir] [MLIR] Introduce RemarkEngine + pluggable remark streaming (YAML/Bitstream) (PR #152474)

[Guray Ozen]

================
@@ -0,0 +1,91 @@
+# Remark Infrastructure
+
+[TOC]
+
+Optimization remarks are structured, machine- and human-readable notes emitted by passes to explain what was optimized, what was missed, and why. MLIR integrates LLVM’s **remarks** infrastructure to make these insights easy to produce and consume.
+
+**Key points**
+
+- **Opt-in**: Disabled by default. No cost unless enabled.
+- **Per-context**: Configured on `MLIRContext`.
+- **Formats**: YAML or LLVM remark bitstream.
+- **Kinds**: Pass, Missed, Failure, Analysis.
+- **API**: Lightweight stream interface (similar to diagnostics) with `<<`.
+
+## Enabling remarks
+
+Enable once per `MLIRContext` (e.g., in your tool, pass pipeline setup, or test):
+
+```c++
+#include "mlir/IR/MLIRContext.h"
+
+// Writes remarks to /tmp/remarks.yaml in YAML format and mirrors them to
+// the DiagnosticEngine as 'remark' diagnostics with the given category labels.
+context.setupOptimizationRemarks(
+    /*outputPath=*/"/tmp/remarks.yaml",
+    /*outputFormat=*/yaml,              // or "bitstream"
+    /*printAsEmitRemarks=*/true,
+    /*categoryPassName=*/"opt.pass",      // optional category labels for mirroring
+    /*categoryMissName=*/"opt.missed",
+    /*categoryAnalysisName=*/"opt.analysis",
+    /*categoryFailedName=*/"opt.failed");
+```
+
+### Emitting remarks from a pass
+
+The functions `reportOptimization*` return an in-flight remark object (like MLIR diagnostics). One can append strings and key–value pairs with <<. 
+
+```c++
+#include "mlir/IR/Remarks.h"
+
+using namespace mlir;
+
+LogicalResult MyPass::runOnOperation() {
+  Operation *op = getOperation();
+  Location loc = op->getLoc();
+
+  // PASS: something succeeded
+  reportOptimizationPass(loc, /*category=*/"vectorizer", /*passName=*/"MyPass")
+      << "vectorized loop with tripCount="
+      << RemarkBase::RemarkKeyValue("tripCount", 128);
----------------
grypp wrote:

Good point. I moved everything remark-related to `mlir::remark`.
I also changed `RemarkBase` to `Remark`.

> Do you explain somewhere the difference between << RemarkBase::RemarkKeyValue("tripCount", 128); and << 128;?





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