[mlir][tensor] Document `dest` operand (#71726)

Based on the tips from @ubfx and @joker-eph in
https://github.com/llvm/llvm-project/issues/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.

---------

Co-authored-by: Matthias Springer <me@m-sp.org>
Co-authored-by: Mehdi Amini <joker.eph@gmail.com>
Co-authored-by: Felix Schneider <fx.schn@gmail.com>

1 files changed, 24 insertions, 20 deletions

diff --git a/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td b/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
index 1231c0a..9d0add9 100644
--- a/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
+++ b/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
@@ -18,31 +18,35 @@ 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 aim 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.
-
-    Thus, for the `tensor` dialect, we prefer for now to constrain the
-    scope as much 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.
+    - representing large, sparse aggregations of primitive types, suitable for
+      high-performance numerical computing.
 
+    Because of this broad element type support and because of the existence of
+    more dedicated dialects, such as the `sparse_tensor` and `linalg` dialects,
+    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.
+
+    On the `tensor` type itself, note that it is actually a builtin type (it
+    lives in the builtin dialect), and does not live in this dialect.
+    Furthermore, a `tensor` is an immutable object. For example, this means
+    that a copy will always be made of the `tensor` object when it is passed to
+    the `dest` operand used by some ops in this dialect. As an optimization,
+    an implementation can eliminate these copies during lowering when they
+    are redundant and perform in-place mutation, see the [Destination-Passing
+    Style](
+    https://mlir.llvm.org/docs/Bufferization/#destination-passing-style)
+    documentation for more information.
   }];
 
   let hasCanonicalizer = 1;