Finish documenting tiling exploration examples

programming_examples/basic/tiling_exploration/per_tile/README.md

@@ -10,7 +10,7 @@
 
 # Tiling Exploration
 
-This IRON design flow example, called "Tiling Exploration: Per Tile", demonstrates how data may be `tiled` into smaller chunks and send/received through the `runtime_sequence`. This is a common data transformation pattern, and this example is meant to be interactive.
+This IRON design flow example, called "Tiling Exploration: Per Tile", demonstrates how data may be `tiled` into smaller chunks and sent/received through the `runtime_sequence`. This is a common data transformation pattern, and this example is meant to be interactive.
 
 ## Source Files Overview
 

programming_examples/basic/tiling_exploration/single_transform/Makefile → programming_examples/basic/tiling_exploration/tile_group/Makefile

@@ -12,10 +12,10 @@ srcdir := $(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
 
 include ${srcdir}/../../../makefile-common
 
-tensor_height = 32
-tensor_width = 32
-tile_height = 4
-tile_width = 4
+tensor_height = 8
+tensor_width = 8
+tile_height = 2
+tile_width = 2
 data_str=${tensor_height}_${tensor_width}_${tile_height}_${tile_width}
 
 .PHONY: all template clean
@@ -35,5 +35,9 @@ build/final_${data_str}.xclbin: build/aie_${data_str}.mlir
 run: build/final_${data_str}.xclbin build/insts_${data_str}.txt
 	${powershell} python3 ${srcdir}/test.py -x build/final_${data_str}.xclbin -i build/insts_${data_str}.txt -k MLIR_AIE --tensor-height ${tensor_height} --tensor-width ${tensor_width} --tile-height ${tile_height} --tile-width ${tile_width}
 
+generate_access_map: ${srcdir}/aie2.py
+	mkdir -p ${@D}
+	python3 $< --tensor-height ${tensor_height} --tensor-width ${tensor_width} --tile-height ${tile_height} --tile-width ${tile_width} --generate-access-map ${M} ${K}
+
 clean:
 	rm -rf build

programming_examples/basic/tiling_exploration/tile_group/README.md

@@ -0,0 +1,45 @@
+<!---//===- README.md -----------------------------------------*- Markdown -*-===//
+//
+// This file is licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (C) 2024, Advanced Micro Devices, Inc.
+// 
+//===----------------------------------------------------------------------===//-->
+
+# Tiling Exploration
+
+This IRON design flow example, called "Tiling Exploration: Single Transform", demonstrates how data may be `tiled` into smaller chunks and grouped into collections of tiles and sent/received through the `runtime_sequence`. This is a common data transformation pattern, and this example is meant to be interactive.
+
+## Source Files Overview
+
+1. `aie2.py`: A Python script that defines the AIE array structural design using MLIR-AIE operations and the `TensorTiler` to specify 'tiles' of data to be transferred out of the design. The file generates MLIR that is then compiled using `aiecc.py` to produce design binaries (ie. XCLBIN and inst.txt for the NPU in Ryzen™ AI). 
+
+1. `test.py`: This Python code is responsible for loading the compiled XCLBIN file, configuring the AIE module, providing input data, and executing the AIE design on the NPU. After executing, the script verifies the results against expected output.
+
+## Design Overview
+
+This design has no inputs; it produces a single output tensor. The single core used in this design touches each element in the output tensor seemingly sequentially. However, due to the data transformation (via `TensorTile`s) in the `runtime_sequence`, the output data is in 'tiled' order, as seen in the picture below.
+
+<p align="center">
+  <img
+    src="per_tile.png">
+    <h3 align="center"> Visualization of the Per-Tile Data Movement 
+ </h3> 
+</p>
+
+## Usage
+
+Modify tensor and tile dimensions in the `Makefile`.
+
+To compile and run the design for NPU:
+```bash
+make clean
+make run
+```
+
+To generate a data visualization (like that above), run:
+```bash
+make generate_access_map
+```

programming_examples/basic/tiling_exploration/single_transform/aie2.py → programming_examples/basic/tiling_exploration/tile_group/aie2.py

@@ -17,14 +17,26 @@
 from aie.helpers.tensortiler import TensorTiler2D
 
 
-def generate_module(tensor_height, tensor_width, tile_height, tile_width):
+def generate_module(
+    tensor_height, tensor_width, tile_height, tile_width, generate_access_map=False
+):
+    # define types
+    dtype = np.int32
+    tensor_size = tensor_height * tensor_width
+    flattened_tensor = np.ndarray[(tensor_size,), np.dtype[dtype]]
+
+    t = TensorTiler2D.group_tiler(
+        (tensor_height, tensor_width),
+        (tile_height, tile_width),
+        (tensor_height // tile_height, tensor_width // tile_width),
+    )[0]
+
+    if generate_access_map:
+        t.visualize(show_arrows=True, file_path="tile_group.png")
+        return
+
     @device(AIEDevice.npu1_1col)
     def device_body():
-        # define types
-        dtype = np.int32
-        tensor_size = tensor_height * tensor_width
-        flattened_tensor = np.ndarray[(tensor_size,), np.dtype[dtype]]
-
         # Tile declarations
         ShimTile = tile(0, 0)
         ComputeTile2 = tile(0, 2)
@@ -46,11 +58,6 @@ def core_body():
 
         @runtime_sequence(flattened_tensor)
         def sequence(access_count):
-            t = TensorTiler2D.group_tiler(
-                (tensor_height, tensor_width),
-                (tile_height, tile_width),
-                (tensor_height // tile_height, tensor_width // tile_width),
-            )[0]
             npu_dma_memcpy_nd(
                 metadata=of_out,
                 bd_id=1,
@@ -63,9 +70,14 @@ def sequence(access_count):
 def main(opts):
     with mlir_mod_ctx() as ctx:
         generate_module(
-            opts.tensor_height, opts.tensor_width, opts.tile_height, opts.tile_width
+            opts.tensor_height,
+            opts.tensor_width,
+            opts.tile_height,
+            opts.tile_width,
+            opts.generate_access_map,
         )
-        print(ctx.module)
+        if not opts.generate_access_map:
+            print(ctx.module)
 
 
 def get_arg_parser():
@@ -74,6 +86,11 @@ def get_arg_parser():
     p.add_argument("--tensor-width", required=True, help="Tensor width", type=int)
     p.add_argument("--tile-height", required=True, help="Tile height", type=int)
     p.add_argument("--tile-width", required=True, help="Tile width", type=int)
+    p.add_argument(
+        "--generate-access-map",
+        action="store_true",
+        help="Produce a file showing data access order",
+    )
     return p