Skip to content

Commit

Permalink
[mlir][doc] Slightly clarify bufferization documentation (#70212)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
rikhuijzer committed Oct 26, 2023
1 parent 04ca1b6 commit d8a5215
Showing 1 changed file with 10 additions and 10 deletions.
20 changes: 10 additions & 10 deletions mlir/docs/Bufferization.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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)>
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit d8a5215

Please sign in to comment.