[llvm-branch-commits] [mlir] d8a5215 - [mlir][doc] Slightly clarify bufferization documentation (#70212)

[via llvm-branch-commits]

Author: Rik Huijzer
Date: 2023-10-25T19:01:33-07:00
New Revision: d8a5215728322d1c72bafa6c84cd54936102b174

URL: https://github.com/llvm/llvm-project/commit/d8a5215728322d1c72bafa6c84cd54936102b174
DIFF: https://github.com/llvm/llvm-project/commit/d8a5215728322d1c72bafa6c84cd54936102b174.diff

LOG: [mlir][doc] Slightly clarify bufferization documentation (#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.

Added: 
    

Modified: 
    mlir/docs/Bufferization.md

Removed: 
    


################################################################################
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.