[Mlir-commits] [mlir] [mlir][bufferization] Slightly clarify dest-passing docs (PR #70212)

[Rik Huijzer]

https://github.com/rikhuijzer created https://github.com/llvm/llvm-project/pull/70212

I was reading through the very well written Destination-Passing Style docs. Even though I know not much about compilers, I managed to understand it pretty well. A few things tripped me up though, which this PR suggests to rewrite:

1. Write `buffer(%0)` instead of buffer(`%0`). While reading, I first interpreted the text as "the buffer (%0)", whereas it should be interpreted as pseudocode for "a function that determines the buffer applied to %0". Quickly introducing it and moving the backticks around as this PR does should make this more clear. Also, I verified that MLIR does not contain any other occurences of `"buffer(<BACKTICK>"`. It does contain many occurences of `"buffer("` (without the backtick after the opening bracket), so this PR makes notation a bit more consistent.
2. Quotation marks slowed me down during reading, so I removed them. I think it's also clear without.
3. The `outs` from `linalg` was suddenly introduced. I've tried to clarify in as few words as possible that `outs` stands for `outputs` but suggestions are welcome.

>From 90259385a3b49a332b31142e7781c3d451491e00 Mon Sep 17 00:00:00 2001
From: Rik Huijzer <github at huijzer.xyz>
Date: Wed, 25 Oct 2023 16:01:41 +0200
Subject: [PATCH] [mlir][bufferization] Slightly clarify dest-passing docs

---
 mlir/docs/Bufferization.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/mlir/docs/Bufferization.md b/mlir/docs/Bufferization.md
index d9d0751cae8c9dd..4e2d4a69e74587c 100644
--- a/mlir/docs/Bufferization.md
+++ b/mlir/docs/Bufferization.md
@@ -110,13 +110,13 @@ As an example, consider the following op: `%0 = tensor.insert %cst into
 %t[%idx] : tensor<?xf32>`
 
 `%t` is the destination in this example. When choosing a buffer for the result
-`%0`, One-Shot Bufferize considers only two options:
+`%0`, denoted as `buffer(%0)`, One-Shot Bufferize considers only two options:
 
-1.  buffer(`%0`) = buffer(`%t`).
-2.  buffer(`%0`) is a newly allocated buffer.
+1.  `buffer(%0) = buffer(%t)`, or
+2.  `buffer(%0)` is a newly allocated buffer.
 
 There may be other buffers in the same function that could potentially be used
-for buffer(`%0`), but those are not considered by One-Shot Bufferize to keep the
+for `buffer(%0)`, but those are not considered by One-Shot Bufferize to keep the
 bufferization simple. One-Shot Bufferize could be extended to consider such
 buffers in the future to achieve a better quality of bufferization.
 
@@ -131,10 +131,10 @@ memory allocation. E.g.:
 } : tensor<?xf32>
 ```
 
-The result of `tensor.generate` does not have a "destination", so bufferization
-allocates a new buffer. This could be avoided by choosing an op such as
-`linalg.generic`, which can express the same computation with a destination
-("out") tensor:
+The result of `tensor.generate` does not have a destination operand, so
+bufferization allocates a new buffer. This could be avoided by choosing an
+op such as `linalg.generic`, which can express the same computation with a
+destination operand, as specified behind outputs (`outs`):
 
 ```mlir
 #map = affine_map<(i) -> (i)>
@@ -165,7 +165,7 @@ such as a subsequent read of `%s`).
 
 RaW conflicts are detected with an analysis of SSA use-def chains (details
 later). One-Shot Bufferize works best if there is a single SSA use-def chain,
-where the result of a tensor op is the "destination" operand of the next tensor
+where the result of a tensor op is the destination operand of the next tensor
 ops, e.g.:
 
 ```mlir
@@ -263,7 +263,7 @@ must be inserted due to a RaW conflict. E.g.:
 }
 ```
 
-In the above example, a buffer copy of buffer(`%another_tensor`) (with `%cst`
+In the above example, a buffer copy of `buffer(%another_tensor)` (with `%cst`
 inserted) is yielded from the "then" branch.
 
 Note: Buffer allocations that are returned from a function are not deallocated.