[mlir][tensor] Document dest operand

[rikhuijzer]

Based on the tips from @ubfx and @joker-eph in #70030, this patch suggest to introduce the dest operand in the tensor dialect description. To do so, this patch also suggests to move some things around to make it more clear how the paragraphs relate to each other.

[llvmbot]

@llvm/pr-subscribers-mlir-tensor

@llvm/pr-subscribers-mlir

Author: Rik Huijzer (rikhuijzer)

Changes

Based on the tips from @ubfx and @joker-eph in #70030, this patch suggest to introduce the dest operand in the tensor dialect description. To do so, this patch also suggests to move some things around to make it more clear how the paragraphs relate to each other.

---

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

1 Files Affected:

• (modified) mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td (+18-16)

diff --git a/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td b/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
index 1231c0a67bc305f..768edec27a755a6 100644
--- a/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
+++ b/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
@@ -18,31 +18,33 @@ def Tensor_Dialect : Dialect {
   let description = [{
     The `tensor` dialect is intended to hold core tensor creation and
     manipulation ops, which are not strongly associated with any particular
-    other dialect or domain abstraction. The primary smoke test of this is ops
-    that make sense for any tensor element type.
-
-    We leave it to other dialects to hold the vast swath of possible
-    computations one might want to do on a tensor.
-
-    The `tensor` type is (for better or for worse) used to represent all kinds
-    of things, and supports an open-ended set of element types. Examples:
+    other dialect or domain abstraction. The primary inclusion criteria for ops
+    in this dialect is that they make sense for any tensor element type. When
+    this is not the case, the op is left to live in other dialects. Examples of
+    element types that could be supported by the `tensor` dialect include:
 
     - representing large, dense aggregations of primitive types, suitable for
       high-performance numerical computing.
-    - representing shapes in the `shape` dialect, which consist of small
-      1D tensors of `index` data type.
+    - representing shapes in the `shape` dialect, which consist of small 1D
+      tensors of `index` data type.
     - representing aggregations of strings or “variant” types.
-    - representing large, sparse aggregations of primitive types, suitable
-      for high-performance numerical computing.
+    - representing large, sparse aggregations of primitive types, suitable for
+      high-performance numerical computing.
 
-    Thus, for the `tensor` dialect, we prefer for now to constrain the
-    scope as much as possible. The expectation is that at some point
+    Because of this broad element type support, we prefer for now to keep the
+    `tensor` dialect as small as possible. The expectation is that at some point
     in the future, the `tensor` dialect’s scope may be broadened through a
     careful discussion of the tradeoffs.
 
-    The `tensor` type is actually a builtin type (it lives in the builtin
-    dialect), and does not live in this dialect.
+    One exception to the above is the `tensor` type itself, which is actually a
+    builtin type (it lives in the builtin dialect), and does not live in this
+    dialect.
 
+    Finally, many ops in the the dialect use the `dest` operand. This is an
+    operand that is used to encode information for bufferization via the
+    `DestinationStyleOpInterface`, see the [Destination Passing Style](
+    https://mlir.llvm.org/docs/Bufferization/#destination-passing-style)
+    documentation for more information.
   }];
 
   let hasCanonicalizer = 1;

[rikhuijzer]

Ah sorry for being so dense before. I think destination-passing style finally clicked for me now. The tensor is immutable (and therefore copied), but the underlying storage may be mutated.

[joker-eph]

LG (with one edit)