From 446f0c609fcb304a7412123fdbcae803a4d61014 Mon Sep 17 00:00:00 2001
From: Matthias Springer <springerm@google.com>
Date: Mon, 10 Jan 2022 22:31:49 +0900
Subject: [PATCH] [mlir][linalg][bufferize][NFC] Update comments in
 BufferizableOpInterface

Differential Revision: https://reviews.llvm.org/D116932
---
 .../BufferizableOpInterface.h                 |  4 ++--
 .../BufferizableOpInterface.td                | 21 +++++++++++++++----
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.h b/mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.h
index 22bf5e645049..d67c4125a665 100644
--- a/mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.h
+++ b/mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.h
@@ -426,8 +426,8 @@ private:
 void replaceOpWithBufferizedValues(RewriterBase &rewriter, Operation *op,
                                    ValueRange values);
 
-/// Replace an op with a new op. Tensor OpResults must be replaced with memref
-/// values.
+/// Replace an op with a new op. The new op must have the same number of
+/// results as the replaced op. The new op may not return any tensor values.
 template <typename OpTy, typename... Args>
 OpTy replaceOpWithNewBufferizedOp(RewriterBase &rewriter, Operation *op,
                                   Args &&...args) {
diff --git a/mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.td b/mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.td
index 25bc9df0d6ce..0f642b6eedee 100644
--- a/mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.td
+++ b/mlir/include/mlir/Dialect/Linalg/ComprehensiveBufferize/BufferizableOpInterface.td
@@ -195,13 +195,26 @@ def BufferizableOpInterface : OpInterface<"BufferizableOpInterface"> {
       InterfaceMethod<
         /*desc=*/[{
           Bufferize this op, i.e., rewrite it into a memref-based equivalent.
-          Tensor values should be mapped to buffer values using `state`.
+          Buffers of tensor SSA values can be retrieved via `state.getBuffer`.
+          Uses of tensor results of the existing tensor op can be replaced with
+          `replaceOpWithBufferizedValues` or `replaceOpWithNewBufferizedOp`.
+          These two functions automatically handle the tensor-to-memref type
+          conversion.
 
-          Implementations are required to required to bufferize nested ops
-          before returning. Otherwise, nested ops will not be bufferized.
+          The implementation of this method must be consistent with the
+          remaining methods, in particular `getAliasingOpOperand`. I.e., a
+          tensor result `r` may only be replaced with:
+          a) A buffer that aliases one of buffers in getAliasingOpOperand(r).
+          b) Or: A newly allocated buffer.
+
+          Regions of an op should be inlined into the new op instead of cloning
+          them. This is not only more efficient, but also necessary so that no
+          analysis results are lost. (Bufferization decisions are tracked via
+          OpOperand pointers and cloned ops have new OpOperands.) If regions are
+          cloned instead of inlined, additional buffer copies may be inserted.
 
           This method will never be called on ops that do not have at least one
-          tensor operand/result or a region.
+          tensor operand/result.
         }],
         /*retType=*/"LogicalResult",
         /*methodName=*/"bufferize",