[Mlir-commits] [mlir] [mlir][NFC] Move and improve ownership-based buffer dellocation docs (PR #89196)

[Martin Erhart]

================
@@ -0,0 +1,619 @@
+# Ownership-based Buffer Deallocation
+
+[TOC]
+
+One-Shot Bufferize does not deallocate any buffers that it allocates. After
+running One-Shot Bufferize, the resulting IR may have a number of `memref.alloc`
+ops, but no `memref.dealloc` ops. Buffer dellocation is delegated to the
+`-ownership-based-buffer-deallocation` pass. This pass supersedes the now
+deprecated `-buffer-deallocation` pass, which does not work well with
+One-Shot Bufferize.
+
+On a high level, buffers are "owned" by a basic block. Ownership materializes
+as an `i1` SSA value and can be thought of as "responsibility to deallocate". It
+is conceptually similar to `std::unique_ptr` in C++.
+
+There are few additional preprocessing and postprocessing passes that should be
+run together with the ownership-based buffer deallocation pass. The recommended
+compilation pipeline is as follows:
+
+```
+one-shot-bufferize
+       |          it's recommended to perform all bufferization here at latest,
+       |       <- any allocations inserted after this point have to be handled
+       V          manually
+expand-realloc
+       V
+ownership-based-buffer-deallocation
+       V
+  canonicalize <- mostly for scf.if simplifications
+       V
+buffer-deallocation-simplification
+       V       <- from this point onwards no tensor values are allowed
+lower-deallocations
+       V
+      CSE
+       V
+  canonicalize
+```
+
+The entire deallocation pipeline (excluding `-one-shot-bufferize`) is exposed
+as `-buffer-deallocation-pipeline`.
+
+The ownership-based buffer deallocation pass processes operations implementing
+`FunctionOpInterface` one-by-one without analysing the call-graph.
+This means that there have to be [some rules](#function-boundary-abi) on how
+MemRefs are handled when being passed from one function to another. The rest of
+the pass revolves heavily around the `bufferization.dealloc` operation which is
+inserted at the end of each basic block with appropriate operands and should be
+optimized using the Buffer Deallocation Simplification pass
+(`--buffer-deallocation-simplification`) and the regular canonicalizer
+(`--canonicalize`). Lowering the result of the
+`-ownership-based-buffer-deallocation` pass directly using
+`--convert-bufferization-to-memref` without beforehand optimization is not
+recommended as it will lead to very inefficient code (the runtime-cost of
+`bufferization.dealloc` is `O(|memrefs|^2+|memref|*|retained|)`).
+
+## Function boundary ABI
+
+The Buffer Deallocation pass operates on the level of operations implementing
+the `FunctionOpInterface`. Such operations can take MemRefs as arguments, but
+also return them. To ensure compatibility among all functions (including
+external ones), some rules have to be enforced:
+*   When a MemRef is passed as a function argument, ownership is never acquired.
+    It is always the caller's responsibility to deallocate such MemRefs.
+*   Returning a MemRef from a function always passes ownership to the caller,
+    i.e., it is also the caller's responsibility to deallocate memrefs returned
+    from a called function.
+*   A function must not return a MemRef with the same allocated base buffer as
+    one of its arguments (in this case a copy has to be created). Note that in
+    this context two subviews of the same buffer that don't overlap are also
+    considered to alias.
+
+For external functions (e.g., library functions written externally in C), the
+externally provided implementation has to adhere to these rules and they are
+just assumed by the buffer deallocation pass. Functions on which the
+deallocation pass is applied and fow which the implementation is accessible are
----------------
maerhart wrote:

```suggestion
deallocation pass is applied and for which the implementation is accessible are
```

https://github.com/llvm/llvm-project/pull/89196