update layout map examples in doc, drop stale ones

- add more examples for affine layout maps showing various use
  cases

- affine map range sizes were removed from code, but examples in
  LangRef weren't updated

Signed-off-by: Uday Bondhugula <uday@polymagelabs.com>
Closes tensorflow/mlir#142

COPYBARA_INTEGRATE_REVIEW=https://github.com/tensorflow/mlir/pull/142 from bondhugula:doc 3291a8784bc69883f7a7cead21445fc8118aaad2
PiperOrigin-RevId: 270548991

diff --git a/mlir/g3doc/LangRef.md b/mlir/g3doc/LangRef.md
index 98ad806..6f60cb4 100644 (file)
--- a/mlir/g3doc/LangRef.md
+++ b/mlir/g3doc/LangRef.md
@@ -756,36 +756,58 @@ Examples of memref static type
 
 ```mlir {.mlir}
 // Identity index/layout map
-#imapA = (d0, d1) -> (d0, d1) size (16, 32)
+#identity = (d0, d1) -> (d0, d1)
 
 // Column major layout.
-#imapB = (d0, d1, d2) [s0] -> (d2, d1, d0) size (s0, 4, 16)
+#col_major = (d0, d1, d2) -> (d2, d1, d0)
+
+// A 2-d tiled layout with tiles of size 128 x 256.
+#tiled_2d_128x256 = (d0, d1) -> (d0 div 128, d1 div 256, d0 mod 128, d0 mod 256)
+
+// A tiled data layout with non-constant tile sizes.
+#tiled_dynamic = (d0, d1)[s0, s1] -> (d0 floordiv s0, d1 floordiv s1,
+                              d0 mod s0, d1 mod s1)
+
+// A layout that yields a padding on two at either end of the minor dimension.
+#padded = (d0, d1) -> (d0, (d1 + 2) floordiv 2, (d1 + 2) mod 2)
+
 
 // The dimension list "16x32" defines the following 2D index space:
 //
 //   { (i, j) : 0 <= i < 16, 0 <= j < 32 }
 //
-memref<16x32xf32, #imapA, memspace0>
+memref<16x32xf32, #identity, memspace0>
+
 // The dimension list "16x4x?" defines the following 3D index space:
 //
 //   { (i, j, k) : 0 <= i < 16, 0 <= j < 4, 0 <= k < N }
 //
 // where N is a symbol which represents the runtime value of the size of
 // the third dimension.
-memref<16x4x?xf32, #imapB, memspace0>
-```
-
-Symbol capture example:
-
-```mlir {.mlir}
-// Affine map with symbol 's0' used as offset for first dimension.
-#imapA = (d0, d1) [s0] -> (d0 + s0, d1)
+//
+// %N here binds to the size of the third dimension.
+%A = alloc(%N) : memref<16x4x?xf32, #col_major, memspace0>
+
+// A 2-d dynamic shaped memref that also has a dynamically sized tiled layout.
+// The memref index space is of size %M x %N, while %B1 and %B2 bind to the
+// symbols s0, s1 respectively of the layout map #tiled_dynamic. Data tiles of
+// size %B1 x %B2 in the logical space will be stored contiguously in memory.
+// The allocation size will be (%M ceildiv %B1) * %B1 * (%N ceildiv %B2) * %B2 
+// f32 elements.
+%T = alloc(%M, %N) [%B1, %B2] : memref<?x?xf32, #tiled_dynamic>
+
+// A memref that has a two element padding at either end. The allocation size
+// will fit 16 * 68 float elements of data.
+%P = alloc() : memref<16x64xf32, #padded>
+
+// Affine map with symbol 's0' used as offset for the first dimension.
+#imapS = (d0, d1) [s0] -> (d0 + s0, d1)
 // Allocate memref and bind the following symbols:
 // '%n' is bound to the dynamic second dimension of the memref type.
 // '%o' is bound to the symbol 's0' in the affine map of the memref type.
 %n = ...
 %o = ...
-%A = alloc (%n)[%o] : <16x?xf32, #imapA>
+%A = alloc (%n)[%o] : <16x?xf32, #imapS>
 ```
 
 ##### Index Space
@@ -826,20 +848,6 @@ integral. In addition, an index map must specify the size of each of its range
 dimensions onto which it maps. Index map symbols must be listed in order with
 symbols for dynamic dimension sizes first, followed by other required symbols.
 
-Index map examples:
-
-```mlir {.mlir}
-// Index map from [MS, NS] slice index space to larger [M, N]
-// matrix index space at slice offset symbols OI, OJ:
-// Maps from [MS, NS] -> [M, N]
-#imap_slice = (i, j) [M, N, OI, OJ] -> (i + OI , j + OJ) size (M, N)
-
-// Index map from 4-dimensional tiled index space to
-// 2-dimensional index space.
-// Maps from [M/128, N/128, 128, 128] -> [M, N]
-#imap_tiled = (d0, d1, d2, d3) [M, N] -> (128 * d0 + d2, 128 * d1 + d3)
-                                         size (M, N)
-```
 
 ##### Layout Map
 
@@ -852,10 +860,13 @@ Layout map examples:
 
 ```mlir {.mlir}
 // MxN matrix stored in row major layout in memory:
-#layout_map_row_major = (i, j) [M, N] -> (i, j) size (M, N)
+#layout_map_row_major = (i, j) -> (i, j)
 
 // MxN matrix stored in column major layout in memory:
-#layout_map_col_major = (i, j) [M, N] -> (j, i) size (M, N)
+#layout_map_col_major = (i, j) -> (j, i)
+
+// MxN matrix stored in a 2-d blocked/tiled layout with 64x64 tiles.
+#layout_tiled = (i, j) -> (i floordiv 64, j floordiv 64, i mod 64, j mod 64)
 ```
 
 ##### Affine Map Composition