[Mlir-commits] [mlir] [mlir][tensor] Document `dest` operand (PR #71726)

[Rik Huijzer]

https://github.com/rikhuijzer updated https://github.com/llvm/llvm-project/pull/71726

>From 3f34a440abef46c5c6280fdcdf0c29e05dda4565 Mon Sep 17 00:00:00 2001
From: Rik Huijzer <github at huijzer.xyz>
Date: Wed, 8 Nov 2023 20:10:41 +0100
Subject: [PATCH 1/2] [mlir][tensor] Document `dest` operand

---
 .../mlir/Dialect/Tensor/IR/TensorBase.td      | 34 ++++++++++---------
 1 file changed, 18 insertions(+), 16 deletions(-)

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;

>From a72c2b5b5a2d0bad4203e4085255c95829dee7dd Mon Sep 17 00:00:00 2001
From: Rik Huijzer <github at huijzer.xyz>
Date: Thu, 9 Nov 2023 17:08:59 +0100
Subject: [PATCH 2/2] Try to implement suggestion

---
 mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td b/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
index 768edec27a755a6..9d5c7cdaea0465a 100644
--- a/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
+++ b/mlir/include/mlir/Dialect/Tensor/IR/TensorBase.td
@@ -36,15 +36,14 @@ def Tensor_Dialect : Dialect {
     in the future, the `tensor` dialect’s scope may be broadened through a
     careful discussion of the tradeoffs.
 
-    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](
+    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 the `dest`
+    operand used by some ops in this dialect does not mean that the `tensor` is
+    mutated in place, but rather that the operand can be used as bufferization
+    hint. For more information, see the [Destination Passing Style](
     https://mlir.llvm.org/docs/Bufferization/#destination-passing-style)
-    documentation for more information.
+    documentation.
   }];
 
   let hasCanonicalizer = 1;