[Mlir-commits] [mlir] [mlir][vector] Clarify the semantics of gather/scatter indexing (nfc) (PR #181357)

[Andrzej Warzyński]

================
@@ -2180,6 +2185,28 @@ def Vector_ScatterOp
     is stored regardless of the index, and the index is allowed to be
     out-of-bounds.
 
+    ```mlir
+      %base: memref<?x10x?xf32>, %ofs_0: index, %ofs_1: index, %ofs_2: index,
+      %indices: vector<2x3xi32>, %mask: vector<2x3xi1>,
+      %src: vector<2x3xf32>) -> memref<?x10x?xf32> {
+          %result = vector.scatter %base[%ofs_0, %ofs_1, %ofs_2]
+                                   [%indices], %mask, %src : [...]
+    ```
+    The indexing semantics are then,
+
+    ```
+    if mask[i,j] then
+      base[%ofs_0, %ofs_1, %ofs_2 + indices[i,j]] := valueToStore[i,j]
+    ```
+
+    Note, `indices` are element offsets - they are expressed in units of
+    elements (not bytes). The offset is added to the underlying memory address,
+    so if the resulting position exceeds the size of the innermost dimension,
+    it naturally advances into the next row and/or plane according to the
+    identity (row-major) layout of 3D `base` (col = dim 0, row = dim 1, plane
----------------
banach-space wrote:

The running example in the docs is 3D: https://mlir.llvm.org/docs/Dialects/Vector/#vectorgather-vectorgatherop

I can see how this could be confusing though, so let me tweak a bit.

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