[mlir][docs] Guide on generating alias for type/attribute

[ZenithalHourlyRate]

This is part of https://discourse.llvm.org/t/rfc-introduce-opasm-type-attr-interface-for-pretty-print-in-asmprinter/83792.

Verbose printing of commonly used type/attribute that is long could severely reduce the readablity of the resulting assembly, and it has been asked several times in the LLVM discourse how to generate alias.

Cc @ftynse

Discussion

• I am not sure where to put the markdown, so I put it in mlir/docs/.
• Documentation on OpAsmOpInterface (controlling AsmResultName/BlockArgName/etc) could also be added in this markdown, so I used the title Customizing AsmPrinter Behavior and let further PR to update the content.

[llvmbot]

@llvm/pr-subscribers-mlir

Author: Hongren Zheng (ZenithalHourlyRate)

Changes

This is part of https://discourse.llvm.org/t/rfc-introduce-opasm-type-attr-interface-for-pretty-print-in-asmprinter/83792.

Verbose printing of commonly used type/attribute that is long could severely reduce the readablity of the resulting assembly, and it has been asked several times in the LLVM discourse how to generate alias.

Cc @ftynse

Discussion

• I am not sure where to put the markdown, so I put it in mlir/docs/.
• Documentation on OpAsmOpInterface (controlling AsmResultName/BlockArgName/etc) could also be added in this markdown, so I used the title Customizing AsmPrinter Behavior and let further PR to update the content.

---

Full diff: https://github.com/llvm/llvm-project/pull/121698.diff

1 Files Affected:

• (added) mlir/docs/AsmPrinter.md (+49)

diff --git a/mlir/docs/AsmPrinter.md b/mlir/docs/AsmPrinter.md
new file mode 100644
index 00000000000000..24c9914399a68b
--- /dev/null
+++ b/mlir/docs/AsmPrinter.md
@@ -0,0 +1,49 @@
+# Customizing AsmPrinter Behavior
+
+[TOC]
+
+## Generating Aliases
+
+To reduce verbosity in the resulting assembly, `AsmPrinter` can generate aliases for frequently used types and attributes.
+
+For example, `!my_dialect.type<a=3,b=4,c=5,d=tuple,e=another_type>` and `#my_dialect.attr<a=3>` can be aliased to `!my_dialect_type` and `#my_dialect_attr`, simplifying further references.
+
+To enable this, the owning dialect of these types/attributes can define an interface to hook into the `AsmPrinter`. This is effective only when the assembly is not printed in generic form.
+
+```cpp
+struct MyDialectOpAsmDialectInterface : public OpAsmDialectInterface {
+ public:
+  using OpAsmDialectInterface::OpAsmDialectInterface;
+
+  AliasResult getAlias(Type type, raw_ostream& os) const override {
+    if (mlir::isa<MyType>(type)) {
+      os << "my_dialect_type";
+      // Could return OverridableAlias when
+      // allowing other dialect to override the alias.
+      //
+      // Other dialects are allowed to provide alias for
+      // type/attribute not owned by them
+      // but the final result would depend on the registration order
+      // of these dialects in the MLIRContext
+      return AliasResult::FinalAlias;
+    }
+    return AliasResult::NoAlias;
+  }
+
+  AliasResult getAlias(Attribute attr, raw_ostream& os) const override {
+    if (mlir::isa<MyAttribute>(attr)) {
+      os << "my_dialect_attr";
+      return AliasResult::FinalAlias;
+    }
+    return AliasResult::NoAlias;
+  }
+};
+
+void MyDialect::initialize() {
+  // register the interface to the dialect
+  addInterface<MyDialectOpAsmDialectInterface>();
+}
+```
+
+* If `getAlias` provides an alias with a trailing digit, `AsmPrinter` appends an underscore to avoid conflicts with autogenerated IDs.
+* If multiple types/attributes have the same alias from `getAlias`, a number is appended to the alias to avoid conflicts.
\ No newline at end of file

[ftynse]

I'd put it under docs/DefiningDialects/, rather than at the top level. And also put a reference to the code location where the interface is defined. Standalone textual documentation has a tendency to become stale as the code evolves and having a link to double-check would help. LGTM otherwise.

[ZenithalHourlyRate]

I'd put it under docs/DefiningDialects/, rather than at the top level. And also put a reference to the code location where the interface is defined.

Comments addressed.