Runtime TXN generation

.gitignore

@@ -16,6 +16,8 @@ include/**/Makefile
 lib/**/Makefile
 
 CLAUDE.md
+AGENTS.md
+.codex/
 /platforms/vck190_bare/petalinux/build
 /platforms/vck190_bare/petalinux/components
 /platforms/vck190_bare/petalinux/images

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/kynan/nbstripout
-  rev: 0.8.0
+  rev: 0.8.1
   hooks:
     - id: nbstripout
       args: [--drop-empty-cells]
@@ -14,7 +14,7 @@ repos:
       stages: [pre-push]
 
 - repo: https://github.com/psf/black
-  rev: 24.10.0
+  rev: 26.3.1
   hooks:
     - id: black
       stages: [pre-push]

include/aie/Conversion/AIEXToEmitC/AIEXToEmitC.h

@@ -0,0 +1,25 @@
+//===- AIEXToEmitC.h - AIEX to EmitC conversion -----------------*- C++ -*-===//
+//
+// 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
+//
+// (c) Copyright 2025-2026 Advanced Micro Devices, Inc.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef AIE_CONVERSION_AIEXTOEMITC_AIEXTOEMITC_H
+#define AIE_CONVERSION_AIEXTOEMITC_AIEXTOEMITC_H
+
+#include "mlir/IR/BuiltinOps.h"
+#include "mlir/Pass/Pass.h"
+#include <memory>
+
+namespace xilinx {
+
+std::unique_ptr<mlir::OperationPass<mlir::ModuleOp>>
+createConvertAIEXToEmitCPass();
+
+} // namespace xilinx
+
+#endif // AIE_CONVERSION_AIEXTOEMITC_AIEXTOEMITC_H

include/aie/Conversion/Passes.h

@@ -13,6 +13,7 @@
 
 #include "aie/Conversion/AIEToConfiguration/AIEToConfiguration.h"
 #include "aie/Conversion/AIEVecToLLVM/AIEVecToLLVM.h"
+#include "aie/Conversion/AIEXToEmitC/AIEXToEmitC.h"
 #include "aie/Conversion/PassesEnums.h.inc"
 
 namespace xilinx {

include/aie/Conversion/Passes.td

@@ -104,4 +104,28 @@ def ConvertAIEToControlPackets : Pass<"convert-aie-to-control-packets",
   ];
 }
 
+//===----------------------------------------------------------------------===//
+// AIEXToEmitC
+//===----------------------------------------------------------------------===//
+
+def ConvertAIEXToEmitC : Pass<"convert-aiex-to-emitc", "mlir::ModuleOp"> {
+  let summary = "Convert AIEX dynamic runtime sequence ops to EmitC dialect";
+  let description = [{
+    This pass converts AIEX runtime sequence operations (write32, maskwrite32,
+    sync — including their dynamic operand forms) along with static NPU ops,
+    SCF control flow, and arith operations into EmitC dialect ops. The
+    resulting EmitC IR can be translated to C++ code via translateToCpp()
+    that calls functions from the standalone TxnEncoding.h library to
+    generate TXN binaries at runtime.
+  }];
+  let constructor = "xilinx::createConvertAIEXToEmitCPass()";
+  let dependentDialects = ["mlir::emitc::EmitCDialect",
+                           "mlir::arith::ArithDialect",
+                           "mlir::func::FuncDialect",
+                           "mlir::memref::MemRefDialect",
+                           "mlir::scf::SCFDialect",
+                           "xilinx::AIE::AIEDialect",
+                           "xilinx::AIEX::AIEXDialect"];
+}
+
 #endif // AIE_CONVERSION_PASSES

include/aie/Dialect/AIE/IR/AIEOps.td

@@ -2228,8 +2228,8 @@ def AIE_BDChainOp: AIE_Op<"bd_chain", [Symbol, SkipAccessibilityCheckTrait]> {
 
 def AIE_RuntimeSequenceOp : AIE_Op<"runtime_sequence", [
   Symbol,
-  NoTerminator, 
-  HasParent<"DeviceOp">, 
+  NoTerminator,
+  HasParent<"DeviceOp">,
 ]> {
   let summary = "Program the configuration co-processor of the AI Engine array";
   let description = [{
@@ -2238,6 +2238,11 @@ def AIE_RuntimeSequenceOp : AIE_Op<"runtime_sequence", [
 
     Typically, these instructions include configuring the data transfers between host and AIE array on the shims.
     The input arguments are arguments passed in from the host at kernel invocation time. This may include buffers on the host.
+
+    Note: This op is NOT `IsolatedFromAbove` — it can reference values defined
+    in the parent `DeviceOp`. However, the EmitC (C++ codegen) path only
+    supports capturing `arith.constant` values from the outer scope. Referencing
+    other external value types will produce errors during the EmitC conversion.
   }];
   let arguments = (
     ins DefaultValuedAttr<SymbolNameAttr, "getDefaultRuntimeSequenceName()">:$sym_name

include/aie/Dialect/AIEX/IR/AIEX.td

@@ -666,6 +666,17 @@ def AIE_NpuDmaMemcpyNdOp: AIEX_Op<"npu.dma_memcpy_nd", [
   let arguments = (
     ins AnyRankedOrUnrankedMemRef:$memref,
         // NOTE: these are in reverse order: offset3, offset2, ...
+        //
+        // TODO(future PR): tighten these to Variadic<I32> to match the NPU
+        // descriptor register field width. The dynamic runtime_sequence
+        // Python wrapper currently casts SSA i32 values up to i64 at the
+        // IR boundary so the static-IR corpus (which uses `arith.constant
+        // N : i64`) keeps parsing. AIEDmaToNpu's getAsValue already does
+        // width coercion in either direction, so the eventual switch to
+        // i32 will be a one-line change here once all hand-written MLIR
+        // test inputs (test/aiecc, test/npu-xrt, programming_examples)
+        // and any out-of-tree consumers have been migrated off i64 SSA
+        // constants.
         Variadic<I64>:$offsets,
         Variadic<I64>:$sizes,
         Variadic<I64>:$strides,
@@ -762,13 +773,19 @@ def AIE_NpuWriteRTPOp: AIEX_Op<"npu.rtp_write", []> {
   let arguments = (
     ins FlatSymbolRefAttr:$buffer,
         UI32Attr:$index,
-        I32Attr:$value
+        OptionalAttr<I32Attr>:$value,
+        Optional<I32>:$dyn_value
   );
   let results = (outs );
-  let assemblyFormat = [{ `(` $buffer `,` $index `,` $value `)` attr-dict
-  }];
+  let hasCustomAssemblyFormat = 1;
+  let hasVerifier = 1;
   let description = [{
-    rtp write operator
+    rtp write operator.
+    When `dyn_value` is provided, it supplies the RTP value at runtime
+    instead of the static `value` attribute.
+  }];
+  let extraClassDeclaration = [{
+    bool hasDynamicValue() { return getDynValue() != nullptr; }
   }];
 }
 
@@ -795,19 +812,20 @@ def AIE_NpuPushQueueOp: AIEX_Op<"npu.push_queue", []> {
 }
 
 // WRITE32
-def AIE_NpuWrite32Op: AIEX_Op<"npu.write32", []> {
+def AIE_NpuWrite32Op: AIEX_Op<"npu.write32", [AttrSizedOperandSegments]> {
   let summary = "write32 operator";
   let arguments = (
     ins UI32Attr:$address,
         UI32Attr:$value,
         OptionalAttr<FlatSymbolRefAttr>:$buffer,
         OptionalAttr<I32Attr>:$column,
-        OptionalAttr<I32Attr>:$row
+        OptionalAttr<I32Attr>:$row,
+        Optional<AnySignlessInteger>:$dyn_address,
+        Optional<AnySignlessInteger>:$dyn_value
   );
   let results = (outs );
-  let assemblyFormat = [{
-    attr-dict
-  }];
+  let hasCustomAssemblyFormat = 1;
+  let hasVerifier = 1;
   let description = [{
     NPU write32 operator writes a 32bit value to the AIE array.
     If 'buffer' is present then 'address' is interpreted as an offset into the
@@ -816,27 +834,57 @@ def AIE_NpuWrite32Op: AIEX_Op<"npu.write32", []> {
     into the memory space of aie.tile(column, row).
     If 'buffer' is not present and 'column' and 'row' are not present then
     'address' is interpreted as a full 32-bit address in the AIE array.
+
+    Optionally, SSA values can be provided for 'dyn_address' and 'dyn_value'
+    to enable runtime-parameterized sequences. When dynamic operands are present,
+    the static attributes serve as placeholders (typically 0) and the SSA values
+    are used instead.
+
+    Static syntax: `aiex.npu.write32 {address = 123 : ui32, value = 456 : ui32}`
+    Dynamic syntax: `aiex.npu.write32(%addr, %val) {address = 0 : ui32, value = 0 : ui32} : i32, i32`
   }];
   let extraClassDeclaration = [{
     std::optional<uint32_t> getAbsoluteAddress();
+    bool hasDynamicOperands() { return getDynAddress() != nullptr; }
   }];
+  let builders = [
+    OpBuilder<(ins "uint32_t":$address, "uint32_t":$value,
+               "mlir::FlatSymbolRefAttr":$buffer,
+               "mlir::IntegerAttr":$column, "mlir::IntegerAttr":$row), [{
+      build($_builder, $_state,
+            $_builder.getUI32IntegerAttr(address),
+            $_builder.getUI32IntegerAttr(value),
+            buffer, column, row,
+            /*dyn_address=*/Value(), /*dyn_value=*/Value());
+    }]>,
+    OpBuilder<(ins "mlir::IntegerAttr":$address, "mlir::IntegerAttr":$value,
+               "mlir::FlatSymbolRefAttr":$buffer,
+               "mlir::IntegerAttr":$column, "mlir::IntegerAttr":$row), [{
+      build($_builder, $_state,
+            address, value,
+            buffer, column, row,
+            /*dyn_address=*/Value(), /*dyn_value=*/Value());
+    }]>
+  ];
 }
 
 // MASKWRITE
-def AIE_NpuMaskWrite32Op: AIEX_Op<"npu.maskwrite32", []> {
+def AIE_NpuMaskWrite32Op: AIEX_Op<"npu.maskwrite32", [AttrSizedOperandSegments]> {
   let summary = "Write a masked 32-bit value to the AIE array";
   let arguments = (
     ins UI32Attr:$address,
         UI32Attr:$value,
         UI32Attr:$mask,
         OptionalAttr<FlatSymbolRefAttr>:$buffer,
         OptionalAttr<I32Attr>:$column,
-        OptionalAttr<I32Attr>:$row
+        OptionalAttr<I32Attr>:$row,
+        Optional<AnySignlessInteger>:$dyn_address,
+        Optional<AnySignlessInteger>:$dyn_value,
+        Optional<AnySignlessInteger>:$dyn_mask
   );
   let results = (outs );
-  let assemblyFormat = [{
-    attr-dict
-  }];
+  let hasCustomAssemblyFormat = 1;
+  let hasVerifier = 1;
   let description = [{
     NPU mask write32 operator writes a masked 32bit value to the AIE array.
     If 'buffer' is present then 'address' is interpreted as an offset into the
@@ -845,10 +893,38 @@ def AIE_NpuMaskWrite32Op: AIEX_Op<"npu.maskwrite32", []> {
     into the memory space of aie.tile(column, row).
     If 'buffer' is not present and 'column' and 'row' are not present then
     'address' is interpreted as a full 32-bit address in the AIE array.
+
+    Optionally, SSA values can be provided for 'dyn_address', 'dyn_value', and
+    'dyn_mask' to enable runtime-parameterized sequences.
+
+    Static syntax: `aiex.npu.maskwrite32 {address = 123 : ui32, ...}`
+    Dynamic syntax: `aiex.npu.maskwrite32(%addr, %val, %mask) {address = 0 : ui32, ...} : i32, i32, i32`
   }];
   let extraClassDeclaration = [{
     std::optional<uint32_t> getAbsoluteAddress();
+    bool hasDynamicOperands() { return getDynAddress() != nullptr; }
   }];
+  let builders = [
+    OpBuilder<(ins "uint32_t":$address, "uint32_t":$value, "uint32_t":$mask,
+               "mlir::FlatSymbolRefAttr":$buffer,
+               "mlir::IntegerAttr":$column, "mlir::IntegerAttr":$row), [{
+      build($_builder, $_state,
+            $_builder.getUI32IntegerAttr(address),
+            $_builder.getUI32IntegerAttr(value),
+            $_builder.getUI32IntegerAttr(mask),
+            buffer, column, row,
+            /*dyn_address=*/Value(), /*dyn_value=*/Value(), /*dyn_mask=*/Value());
+    }]>,
+    OpBuilder<(ins "mlir::IntegerAttr":$address, "mlir::IntegerAttr":$value,
+               "mlir::IntegerAttr":$mask,
+               "mlir::FlatSymbolRefAttr":$buffer,
+               "mlir::IntegerAttr":$column, "mlir::IntegerAttr":$row), [{
+      build($_builder, $_state,
+            address, value, mask,
+            buffer, column, row,
+            /*dyn_address=*/Value(), /*dyn_value=*/Value(), /*dyn_mask=*/Value());
+    }]>
+  ];
 }
 
 // BLOCKWRITE
@@ -881,28 +957,67 @@ def AIE_NpuBlockWriteOp: AIEX_Op<"npu.blockwrite", []> {
 }
 
 // OP_SYNC
-def AIE_NpuSyncOp: AIEX_Op<"npu.sync", []> {
+def AIE_NpuSyncOp: AIEX_Op<"npu.sync", [AttrSizedOperandSegments]> {
   let summary = "sync operator";
   let arguments = (
     ins I32Attr:$column,
         I32Attr:$row,
         I32Attr:$direction,
         I32Attr:$channel,
         I32Attr:$column_num,
-        I32Attr:$row_num
+        I32Attr:$row_num,
+        Optional<AnySignlessInteger>:$dyn_column,
+        Optional<AnySignlessInteger>:$dyn_row,
+        Optional<AnySignlessInteger>:$dyn_direction,
+        Optional<AnySignlessInteger>:$dyn_channel,
+        Optional<AnySignlessInteger>:$dyn_column_num,
+        Optional<AnySignlessInteger>:$dyn_row_num
   );
   let results = (outs );
-  let assemblyFormat = [{
-    attr-dict
-  }];
+  let hasCustomAssemblyFormat = 1;
+  let hasVerifier = 1;
   let description = [{
     The sync operation blocks execution of the instruction stream until a task-complete token (TCT) is received on `column`, `row`, channel `channel`, direction `direction` (where `0` is `S2MM` and `1` is `MM2S`).
 
     #### Troubleshooting
 
     If this operation appears to deadlock, ensure that at least one buffer descriptor is configured to issue a TCT on the channel you expect.
     By default, `dma_memcpy_nd` operations only issue tokens for `S2MM` channels, and `issue_token` must be set to `true` to issue tokens for `MM2S` channels.
+
+    Optionally, SSA values can be provided for all parameters to enable
+    runtime-parameterized sequences.
+
+    Static syntax (unchanged): `aiex.npu.sync {column = 0 : i32, ...}`
+    Dynamic syntax: `aiex.npu.sync(%col, %row, %dir, %chan, %ncol, %nrow) {column = 0 : i32, ...} : i32, i32, i32, i32, i32, i32`
   }];
+  let extraClassDeclaration = [{
+    bool hasDynamicOperands() { return getDynColumn() != nullptr; }
+  }];
+  let builders = [
+    OpBuilder<(ins "int32_t":$column, "int32_t":$row,
+               "int32_t":$direction, "int32_t":$channel,
+               "int32_t":$column_num, "int32_t":$row_num), [{
+      build($_builder, $_state,
+            $_builder.getI32IntegerAttr(column),
+            $_builder.getI32IntegerAttr(row),
+            $_builder.getI32IntegerAttr(direction),
+            $_builder.getI32IntegerAttr(channel),
+            $_builder.getI32IntegerAttr(column_num),
+            $_builder.getI32IntegerAttr(row_num),
+            /*dyn_column=*/Value(), /*dyn_row=*/Value(),
+            /*dyn_direction=*/Value(), /*dyn_channel=*/Value(),
+            /*dyn_column_num=*/Value(), /*dyn_row_num=*/Value());
+    }]>,
+    OpBuilder<(ins "mlir::IntegerAttr":$column, "mlir::IntegerAttr":$row,
+               "mlir::IntegerAttr":$direction, "mlir::IntegerAttr":$channel,
+               "mlir::IntegerAttr":$column_num, "mlir::IntegerAttr":$row_num), [{
+      build($_builder, $_state,
+            column, row, direction, channel, column_num, row_num,
+            /*dyn_column=*/Value(), /*dyn_row=*/Value(),
+            /*dyn_direction=*/Value(), /*dyn_channel=*/Value(),
+            /*dyn_column_num=*/Value(), /*dyn_row_num=*/Value());
+    }]>
+  ];
 }
 
 // XAIE_IO_CUSTOM_OP_BEGIN + 1 (address patch)
@@ -911,14 +1026,17 @@ def AIE_NpuAddressPatchOp: AIEX_Op<"npu.address_patch", []> {
   let arguments = (
     ins UI32Attr:$addr,
         I32Attr:$arg_idx,
-        I32Attr:$arg_plus
+        I32Attr:$arg_plus,
+        Optional<I32>:$dyn_arg_plus
   );
   let results = (outs );
   let assemblyFormat = [{
-    attr-dict
+    (`(` $dyn_arg_plus^ `:` type($dyn_arg_plus) `)`)? attr-dict
   }];
   let description = [{
-    address patch operator
+    address patch operator.
+    When `dyn_arg_plus` is provided, it is used instead of the static
+    `arg_plus` attribute. This enables runtime-parameterized buffer offsets.
   }];
 }
 
@@ -1029,6 +1147,7 @@ def AIE_NpuLoadPdiOp: AIEX_Op<"npu.load_pdi", []> {
   let hasCanonicalizeMethod = 1;
 }
 
+
 def AIE_DMAConfigureTaskOp : AIEX_Op<"dma_configure_task", [HasParent<"AIE::RuntimeSequenceOp">, TileElement]>, Results<(outs Index:$result)> {
   let summary = "Concrete Instantiation of a Buffer Descriptor Chain as a Task on a Channel and Direction on a Tile";
   let description = [{