Add documentation and fix BD Chain syntax tests (#1698)

Xilinx · Aug 16, 2024 · f53e923 · f53e923
1 parent d23a3ab
commit f53e923
Show file tree

Hide file tree

Showing 24 changed files with 76 additions and 9 deletions.
diff --git a/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/bad-1.mlir b/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/bad-1.mlir
@@ -9,6 +9,8 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-assign-runtime-sequence-bd-ids %s
 
+// This test ensures that the proper error is emitted if a user tries to reference not-yet-lowered BD chains in aiex.dma_await_task.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/bad-2.mlir b/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/bad-2.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-assign-runtime-sequence-bd-ids %s
 
+// This test ensures that the proper error is emitted if a user tries to use more buffer descriptors than
+// are availalbe in the current device.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/bad-3.mlir b/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/bad-3.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-assign-runtime-sequence-bd-ids %s
 
+// This test ensures that the proper error is issued if the user tries to reuse buffer descriptor IDs
+// withou explicit ops `aiex.dma_free_task` or `aiex.dma_await_task` between them.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/good-1.mlir b/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/good-1.mlir
@@ -9,6 +9,8 @@
 //
 // RUN: aie-opt --aie-materialize-bd-chains --aie-assign-runtime-sequence-bd-ids %s | FileCheck %s
 
+// This tests ensures that each `aie.dma_bd` operation below gets assigned a unique buffer descriptor ID.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)
@@ -28,7 +30,7 @@ module {
     aiex.runtime_sequence(%arg0: memref<8xi16>, %arg1: memref<12xi16>, %arg2: memref<8xi16>) {
       %t1 = aiex.dma_start_bd_chain @simple_chain(%arg0, %arg1, %arg2) : (memref<8xi16>, memref<12xi16>, memref<8xi16>)  
                                     on (%tile_0_0, MM2S, 0) 
-      // CHECK: %[[task1:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
+      // CHECK: %[[task1:.+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
       // CHECK:   aie.dma_bd(%arg0 : memref<8xi16>, 0, 8, [<size = 1, stride = 0>, <size = 2, stride = 2>, <size = 2, stride = 4>, <size = 2, stride = 1>]) {bd_id = 0 : i32}
       // CHECK:   aie.next_bd ^bb1
       // CHECK: ^bb1:
@@ -41,7 +43,7 @@ module {
       // CHECK: aiex.dma_start_task(%[[task1]])
       %t2 = aiex.dma_start_bd_chain @simple_chain(%arg2, %arg1, %arg0) : (memref<8xi16>, memref<12xi16>, memref<8xi16>)  
                                     on (%tile_0_0, MM2S, 1) 
-      // CHECK: %[[task2:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 1) {
+      // CHECK: %[[task2:.+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 1) {
       // CHECK:   aie.dma_bd(%arg2 : memref<8xi16>, 0, 8, [<size = 1, stride = 0>, <size = 2, stride = 2>, <size = 2, stride = 4>, <size = 2, stride = 1>]) {bd_id = 3 : i32}
       // CHECK:   aie.next_bd ^bb1
       // CHECK: ^bb1:
@@ -54,7 +56,7 @@ module {
       // CHECK: aiex.dma_start_task(%[[task2]])
       %t3 = aiex.dma_start_bd_chain @simple_chain(%arg0, %arg1, %arg0) : (memref<8xi16>, memref<12xi16>, memref<8xi16>)  
                                     on (%tile_0_0, S2MM, 0) 
-      // CHECK: %[[task3:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, S2MM, 0) {
+      // CHECK: %[[task3:.+]] = aiex.dma_configure_task(%tile_0_0, S2MM, 0) {
       // CHECK:   aie.dma_bd(%arg0 : memref<8xi16>, 0, 8, [<size = 1, stride = 0>, <size = 2, stride = 2>, <size = 2, stride = 4>, <size = 2, stride = 1>]) {bd_id = 6 : i32}
       // CHECK:   aie.next_bd ^bb1
       // CHECK: ^bb1:

diff --git a/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/good-2.mlir b/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/good-2.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --aie-assign-runtime-sequence-bd-ids %s | FileCheck %s
 
+// This tests ensures that buffer descriptor IDs assigned to `aie.dma_bd` ops are reused after
+// calls to aiex.dma_free_task and aiex.dma_await_task, but are unique otherwise.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/good-3.mlir b/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/good-3.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-assign-runtime-sequence-bd-ids %s
 
+// This test ensures that automatic buffer descriptor allocation does not collide 
+// when there are user-specified hard-coded BD IDs in the input.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/good-4.mlir b/test/bd-chains-and-dma-tasks/assign-runtime-sequence-bd-ids/good-4.mlir
@@ -9,6 +9,8 @@
 //
 // RUN: aie-opt --aie-assign-runtime-sequence-bd-ids %s | FileCheck %s
 
+// This test ensures that all available 16 buffer descriptors are used.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-1.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-1.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures that the proper error is emitted if the transfer length specified in a aie.dma_bd
+// op's dimensions and its overall transfer length do not match up.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-2.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-2.mlir
@@ -9,6 +9,10 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures that the proper error is emitted if the user attempts to sepcify more than
+// the architecturally possible number of data layout transformation dimensions in a `aie.dma_bd` 
+// operation inside the runtime sequence.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-3.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-3.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures that the correct error is emitted if an illegal data layout transformation is specified
+// in a `aie.dma_bd` operation inside the runtime sequence.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-4.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-4.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures that the correct error is emitted if an illegal data layout transformation is specified
+// in a `aie.dma_bd` operation inside the runtime sequence.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-5.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-5.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures that the correct error is emitted if the user tries to transfer 
+// fewer bytes than the architecture allows in a `aie.dma_bd` operation inside the runtime sequence.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-6.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-6.mlir
@@ -9,6 +9,8 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures that the proper error is emitted if the user specifies an illegal offset in a dma_bd operation inside the runtime sequence.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-7.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-7.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures the proper error message is emitted if the user tries to invoke the 
+// `--aie-dma-tasks-to-npu` pass without first lowering BD IDs for all `aie.dma_bd` ops.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-8.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-8.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures the proper error is emitted if a single block inside a `aiex.dma_configure_task` op
+// contains multiple `aie.dma_bd` operations -- only one such operation is allowed per basic block.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-9.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/bad-9.mlir
@@ -9,6 +9,8 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-dma-tasks-to-npu %s 
 
+// This test ensures the proper error is emitted if a task with no BDs are issued in the runtime sequence.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/good-1.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/good-1.mlir
@@ -9,6 +9,10 @@
 //
 // RUN: aie-opt --aie-dma-tasks-to-npu %s | FileCheck %s
 
+// This test ensures buffer descriptor configurations, as well as `aiex.dma_start_task`,
+// `aiex.dma_await_task` operations, issued from within the runtime sequence,
+// are lowered to the correct NPU instruction sequence instructions.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/good-2.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/good-2.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --aie-dma-tasks-to-npu %s | FileCheck %s
 
+// This test ensures that buffer descriptor configurations with chaining get
+// lowered to the correct NPU instruction sequence instructions.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/good-3.mlir b/test/bd-chains-and-dma-tasks/dma-tasks-to-npu/good-3.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --aie-dma-tasks-to-npu %s | FileCheck %s
 
+// This test ensures that buffer descriptor configurations with data layout transformations are
+// properly lowered to the correct NPU instruction sequence instructions.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/materialize-bd-chains/bad-1.mlir b/test/bd-chains-and-dma-tasks/materialize-bd-chains/bad-1.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-materialize-bd-chains %s
 
+// This test ensures that the correct error gets emitted when a BD "chain" is not
+// actually a proper chain, i.e. some blocks are not connected.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/materialize-bd-chains/bad-2.mlir b/test/bd-chains-and-dma-tasks/materialize-bd-chains/bad-2.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-materialize-bd-chains %s
 
+// This test ensures that the correct error is emitted if the types of 
+// the arguments in a BD chain definition and its usage site mismatch.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/materialize-bd-chains/bad-3.mlir b/test/bd-chains-and-dma-tasks/materialize-bd-chains/bad-3.mlir
@@ -9,6 +9,9 @@
 //
 // RUN: aie-opt --verify-diagnostics --aie-materialize-bd-chains %s
 
+// This test ensures the proper error gets emitted if the user attempts to
+// reference a BD chain that has not been defined.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)

diff --git a/test/bd-chains-and-dma-tasks/materialize-bd-chains/good-1.mlir b/test/bd-chains-and-dma-tasks/materialize-bd-chains/good-1.mlir
@@ -9,6 +9,10 @@
 //
 // RUN: aie-opt --aie-materialize-bd-chains %s | FileCheck %s
 
+// This test ensures that a BD chains get lowered to correct `aiex.dma_configure_task`
+// operations at their usage sites. We particularly ensure that the input arguments 
+// are correctly substituted.
+
 module {
   aie.device(npu1_4col) {
     %tile_0_0 = aie.tile(0, 0)
@@ -28,7 +32,7 @@ module {
     aiex.runtime_sequence(%arg0: memref<8xi16>, %arg1: memref<12xi16>, %arg2: memref<8xi16>) {
       %t1 = aiex.dma_start_bd_chain @simple_chain(%arg0, %arg1, %arg2) : (memref<8xi16>, memref<12xi16>, memref<8xi16>)  
                                     on (%tile_0_0, MM2S, 0) 
-      // CHECK: %[[task1:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
+      // CHECK: %[[task1:.+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
       // CHECK:   aie.dma_bd(%arg0 : memref<8xi16>, 0, 8, [<size = 1, stride = 0>, <size = 2, stride = 2>, <size = 2, stride = 4>, <size = 2, stride = 1>])
       // CHECK:   aie.next_bd ^bb1
       // CHECK: ^bb1:
@@ -41,7 +45,7 @@ module {
       // CHECK: aiex.dma_start_task(%[[task1]])
       %t2 = aiex.dma_start_bd_chain @simple_chain(%arg2, %arg1, %arg0) : (memref<8xi16>, memref<12xi16>, memref<8xi16>)  
                                     on (%tile_0_0, MM2S, 1) 
-      // CHECK: %[[task2:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 1) {
+      // CHECK: %[[task2:.+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 1) {
       // CHECK:   aie.dma_bd(%arg2 : memref<8xi16>, 0, 8, [<size = 1, stride = 0>, <size = 2, stride = 2>, <size = 2, stride = 4>, <size = 2, stride = 1>])
       // CHECK:   aie.next_bd ^bb1
       // CHECK: ^bb1:
@@ -54,7 +58,7 @@ module {
       // CHECK: aiex.dma_start_task(%[[task2]])
       %t3 = aiex.dma_start_bd_chain @simple_chain(%arg0, %arg1, %arg0) : (memref<8xi16>, memref<12xi16>, memref<8xi16>)  
                                     on (%tile_0_0, S2MM, 0) 
-      // CHECK: %[[task3:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, S2MM, 0) {
+      // CHECK: %[[task3:.+]] = aiex.dma_configure_task(%tile_0_0, S2MM, 0) {
       // CHECK:   aie.dma_bd(%arg0 : memref<8xi16>, 0, 8, [<size = 1, stride = 0>, <size = 2, stride = 2>, <size = 2, stride = 4>, <size = 2, stride = 1>])
       // CHECK:   aie.next_bd ^bb1
       // CHECK: ^bb1:

diff --git a/test/bd-chains-and-dma-tasks/materialize-bd-chains/good-2.mlir b/test/bd-chains-and-dma-tasks/materialize-bd-chains/good-2.mlir
@@ -40,7 +40,7 @@ module {
     aiex.runtime_sequence(%buf: memref<8xi16>) {
       %t1 = aiex.dma_start_bd_chain @simple_chain(%buf, %lock_0, %lock_1, %lock_2) : (memref<8xi16>, index, index, index)  
                                     on (%tile_0_0, MM2S, 0) 
-      // CHECK: %[[task1:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
+      // CHECK: %[[task1:.+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
       // CHECK:   aie.use_lock(%lock_0, "Acquire", 1)
       // CHECK:   aie.dma_bd(%buf : memref<8xi16>, 0, 8)
       // CHECK:   aie.use_lock(%lock_1, "Release", 1)
@@ -59,7 +59,7 @@ module {
       // CHECK: aiex.dma_start_task(%[[task1]])
       %t2 = aiex.dma_start_bd_chain @simple_chain(%buf, %lock_0, %lock_0, %lock_0) : (memref<8xi16>, index, index, index)  
                                     on (%tile_0_0, MM2S, 1) 
-      // CHECK: %[[task2:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
+      // CHECK: %[[task2:.+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
       // CHECK:   aie.use_lock(%lock_0, "Acquire", 1)
       // CHECK:   aie.dma_bd(%buf : memref<8xi16>, 0, 8)
       // CHECK:   aie.use_lock(%lock_0, "Release", 1)
@@ -78,7 +78,7 @@ module {
       // CHECK: aiex.dma_start_task(%[[task2]])
       %t3 = aiex.dma_start_bd_chain @simple_chain(%buf, %lock_2, %lock_1, %lock_0) : (memref<8xi16>, index, index, index)  
                                     on (%tile_0_0, S2MM, 0) 
-      // CHECK: %[[task3:[0-9]+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
+      // CHECK: %[[task3:.+]] = aiex.dma_configure_task(%tile_0_0, MM2S, 0) {
       // CHECK:   aie.use_lock(%lock_2, "Acquire", 1)
       // CHECK:   aie.dma_bd(%buf : memref<8xi16>, 0, 8)
       // CHECK:   aie.use_lock(%lock_1, "Release", 1)