format

Author: fifield

lib/CAPI/Translation.cpp

@@ -95,7 +95,7 @@ MlirOperation aieTranslateBinaryToTxn(MlirContext ctx, MlirStringRef binary) {
 }
 
 MlirOperation aieTranslateBinaryToControlPackets(MlirContext ctx,
-                                                  MlirStringRef binary) {
+                                                 MlirStringRef binary) {
   std::vector<uint8_t> binaryData(binary.data, binary.data + binary.length);
   auto mod = convertControlPacketBinaryToMLIR(unwrap(ctx), binaryData);
   if (!mod)

lib/Conversion/AIEToConfiguration/AIEToConfiguration.cpp

@@ -53,10 +53,10 @@ struct TransactionBinaryOperation {
 // A ControlPacketOperation encapsulates a parsed control packet including
 // stream header, control packet header, and optional data payload.
 struct ControlPacketOperation {
-  uint32_t streamHeader;   // word 0: parity + pkt_type + pkt_id
-  uint32_t packetHeader;   // word 1: parity + stream_id + opcode + beats + addr
-  std::vector<uint32_t> data;  // payload words (if opcode is write/blockwrite)
-  
+  uint32_t streamHeader; // word 0: parity + pkt_type + pkt_id
+  uint32_t packetHeader; // word 1: parity + stream_id + opcode + beats + addr
+  std::vector<uint32_t> data; // payload words (if opcode is write/blockwrite)
+
   // Decoded fields
   uint8_t pktType;
   uint8_t pktId;
@@ -88,90 +88,92 @@ static bool checkParity(uint32_t word) {
 static std::optional<std::vector<ControlPacketOperation>>
 parseControlPacket(const std::vector<uint8_t> &data) {
   std::vector<ControlPacketOperation> ops;
-  
+
   size_t i = 0;
-  
+
   auto requireBytes = [&](size_t offset, size_t length) -> bool {
     if (offset + length > data.size()) {
       llvm::errs() << "Control packet binary truncated\n";
       return false;
     }
     return true;
   };
-  
+
   auto read32 = [&](size_t offset) -> uint32_t {
     uint32_t value;
     std::memcpy(&value, data.data() + offset, sizeof(uint32_t));
     return value;
   };
-  
-  while (i + 8 <= data.size()) {  // Need at least 2 words (stream hdr + pkt hdr)
+
+  while (i + 8 <= data.size()) { // Need at least 2 words (stream hdr + pkt hdr)
     ControlPacketOperation op;
-    
+
     // Read stream header (word 0)
     op.streamHeader = read32(i);
-    
+
     // Read control packet header (word 1)
     op.packetHeader = read32(i + 4);
-    
+
     // Verify parity
     if (!checkParity(op.streamHeader)) {
-      llvm::errs() << "Stream header parity check failed at offset " << i << "\n";
+      llvm::errs() << "Stream header parity check failed at offset " << i
+                   << "\n";
       return std::nullopt;
     }
     if (!checkParity(op.packetHeader)) {
-      llvm::errs() << "Packet header parity check failed at offset " << i + 4 << "\n";
+      llvm::errs() << "Packet header parity check failed at offset " << i + 4
+                   << "\n";
       return std::nullopt;
     }
-    
+
     // Decode stream header fields
     op.pktType = (op.streamHeader >> 12) & 0x7;
     op.pktId = op.streamHeader & 0xFF;
-    
+
     // Decode control packet header fields
     op.streamId = (op.packetHeader >> 24) & 0x7F;
     op.opcode = (op.packetHeader >> 22) & 0x3;
     op.beats = (op.packetHeader >> 20) & 0x3;
     op.address = op.packetHeader & 0xFFFFF;
-    
-    i += 8;  // consumed 2 words
-    
+
+    i += 8; // consumed 2 words
+
     LLVM_DEBUG(llvm::dbgs() << "Control packet at offset " << (i - 8)
                             << ": opcode=" << static_cast<int>(op.opcode)
                             << " stream_id=" << static_cast<int>(op.streamId)
                             << " addr=0x" << llvm::format("%05X", op.address)
                             << " beats=" << static_cast<int>(op.beats) << "\n");
-    
+
     // Read data payload if present (opcode 0x0=write or 0x2=blockwrite)
     if (op.opcode == 0x0 || op.opcode == 0x2) {
       uint32_t numDataWords = op.beats + 1;
       if (!requireBytes(i, numDataWords * 4)) {
         llvm::errs() << "Truncated data payload\n";
         return std::nullopt;
       }
-      
+
       op.data.resize(numDataWords);
       for (uint32_t j = 0; j < numDataWords; j++) {
         op.data[j] = read32(i + j * 4);
       }
       i += numDataWords * 4;
-      
-      LLVM_DEBUG(llvm::dbgs() << "  Data: [";
-                 for (size_t j = 0; j < op.data.size(); j++) {
-                   if (j > 0) llvm::dbgs() << ", ";
-                   llvm::dbgs() << op.data[j];
-                 }
-                 llvm::dbgs() << "]\n");
+
+      LLVM_DEBUG(llvm::dbgs() << "  Data: ["; for (size_t j = 0;
+                                                   j < op.data.size(); j++) {
+        if (j > 0)
+          llvm::dbgs() << ", ";
+        llvm::dbgs() << op.data[j];
+      } llvm::dbgs() << "]\n");
     }
-    
+
     ops.push_back(std::move(op));
   }
-  
+
   if (i != data.size()) {
-    llvm::errs() << "Warning: " << (data.size() - i) 
+    llvm::errs() << "Warning: " << (data.size() - i)
                  << " bytes remaining after parsing control packets\n";
   }
-  
+
   return ops;
 }
 
@@ -619,11 +621,11 @@ xilinx::AIE::convertControlPacketBinaryToMLIR(mlir::MLIRContext *ctx,
       uint32_t colInt = (op.address >> targetModel.getColumnShift()) & 0x1f;
       uint32_t rowInt = (op.address >> targetModel.getRowShift()) & 0x1f;
       tileMap[key] = std::make_pair(colInt, rowInt);
-      
+
       // Create tile and set controller_id attribute
       auto tile = TileOp::getOrCreate(builder, device, colInt, rowInt);
-      auto packetInfoAttr = AIE::PacketInfoAttr::get(
-          builder.getContext(), op.pktType, op.pktId);
+      auto packetInfoAttr =
+          AIE::PacketInfoAttr::get(builder.getContext(), op.pktType, op.pktId);
       tile->setAttr("controller_id", packetInfoAttr);
     }
   }
@@ -639,7 +641,7 @@ xilinx::AIE::convertControlPacketBinaryToMLIR(mlir::MLIRContext *ctx,
   for (const auto &op : operations) {
     IntegerAttr lengthAttr;
     DenseI32ArrayAttr dataAttr;
-    
+
     if (op.opcode == 0x0 || op.opcode == 0x2) {
       // Write or blockwrite - has data payload
       SmallVector<int32_t> dataVec;
@@ -651,14 +653,11 @@ xilinx::AIE::convertControlPacketBinaryToMLIR(mlir::MLIRContext *ctx,
       // Read - has length but no data
       lengthAttr = builder.getI32IntegerAttr(op.beats + 1);
     }
-    
+
     builder.create<AIEX::NpuControlPacketOp>(
-        loc,
-        builder.getUI32IntegerAttr(op.address),
-        lengthAttr,
+        loc, builder.getUI32IntegerAttr(op.address), lengthAttr,
         builder.getI32IntegerAttr(op.opcode),
-        builder.getI32IntegerAttr(op.streamId),
-        dataAttr);
+        builder.getI32IntegerAttr(op.streamId), dataAttr);
   }
 
   return module;

python/compiler/pkt2mlir/README.md

@@ -0,0 +1,117 @@
+# pkt2mlir - Control Packet Binary to MLIR Disassembler
+
+`pkt2mlir.py` is a tool that converts AIE NPU control packet binaries into human-readable MLIR format. This is useful for debugging, inspecting compiled configurations, and understanding the control packet operations sent to the NPU.
+
+## Overview
+
+The tool parses binary control packet files generated by `aie-translate --aie-ctrlpkt-to-bin` and reconstructs the equivalent MLIR module containing:
+- Device configuration (`aie.device`)
+- Tile controller_id attributes (`PacketInfoAttr`)
+- Runtime sequences with control packet operations (`aiex.control_packet`)
+
+## Usage
+
+```bash
+pkt2mlir.py -f <binary-file>
+```
+
+### Options
+
+- `-f`, `-file FILE` : Input control packet binary file (required)
+- `-h`, `--help` : Show help message and exit
+
+## Examples
+
+### Basic Control Packet Operations Round-trip
+
+Generate control packet binary and disassemble it:
+
+```bash
+# Create a simple MLIR file with control packets
+cat > control_packets.mlir << 'EOF'
+module {
+  aie.device(npu1) {
+    %tile00 = aie.tile(0, 0) {controller_id = #aie.packet_info<pkt_type = 2, pkt_id = 3>}
+    
+    aiex.runtime_sequence() {
+      aiex.control_packet {address = 0x0001F000 : ui32, opcode = 0 : i32, stream_id = 0 : i32, data = array<i32: 2>}
+      aiex.control_packet {address = 0x0001F020 : ui32, opcode = 2 : i32, stream_id = 9 : i32, data = array<i32: 3, 4, 5, 6>}
+      aiex.control_packet {address = 0x00000400 : ui32, opcode = 1 : i32, stream_id = 2 : i32, length = 4 : i32}
+    }
+  }
+}
+EOF
+
+# Compile to binary
+aie-translate --aie-ctrlpkt-to-bin control_packets.mlir -o control_packets.bin
+```
+
+View the raw control packet binary structure:
+
+```bash
+# Inspect binary structure (2 word header + optional data for each packet)
+hexdump -C control_packets.bin
+```
+
+```
+00000000  00 20 00 03 00 1f 00 00  02 00 00 00 00 20 00 03  |. .......... ..|
+00000010  09 b1 f0 20 03 00 00 00  04 00 00 00 05 00 00 00  |... ............|
+00000020  06 00 00 00 00 20 00 03  02 70 04 00              |..... ...p..|
+```
+
+Translate back to MLIR:
+
+```bash
+pkt2mlir.py -f control_packets.bin
+```
+
+```mlir
+module {
+  aie.device(npu1_1col) {
+    %shim_noc_tile_0_0 = aie.tile(0, 0) {controller_id = #aie.packet_info<pkt_type = 2, pkt_id = 3>}
+    
+    aiex.runtime_sequence @configure() {
+      aiex.control_packet {address = 126976 : ui32, data = array<i32: 2>, opcode = 0 : i32, stream_id = 0 : i32}
+      aiex.control_packet {address = 127008 : ui32, data = array<i32: 3, 4, 5, 6>, opcode = 2 : i32, stream_id = 9 : i32}
+      aiex.control_packet {address = 1024 : ui32, length = 4 : i32, opcode = 1 : i32, stream_id = 2 : i32}
+    }
+  }
+}
+```
+
+## Control Packet Binary Format
+
+Each control packet in the binary consists of:
+
+1. **Stream Header** (32 bits):
+   - Bit [31]: Even parity bit
+   - Bits [14:12]: Packet type (3 bits)
+   - Bits [7:0]: Packet ID (8 bits)
+
+2. **Control Packet Header** (32 bits):
+   - Bit [31]: Even parity bit
+   - Bits [30:24]: Stream ID (7 bits)
+   - Bits [23:22]: Opcode (2 bits)
+     - `0x0` = Write
+     - `0x1` = Read
+     - `0x2` = Block write
+   - Bits [21:20]: Beats (size-1, 2 bits)
+   - Bits [19:0]: Address (20 bits)
+
+3. **Data Payload** (optional, 32-bit words):
+   - Present for write (opcode 0x0) and block write (opcode 0x2)
+   - Number of words = beats + 1
+
+## Use Cases
+
+- **Debugging**: Inspect what control packets are being sent to the NPU
+- **Verification**: Compare generated binaries against expected values
+- **Reverse Engineering**: Understand control packet configurations
+- **Testing**: Validate round-trip conversion (MLIR → binary → MLIR)
+- **Documentation**: Generate human-readable documentation from binaries
+
+## See Also
+
+- `txn2mlir.py` - Transaction binary to MLIR disassembler
+- `aie-translate --aie-ctrlpkt-to-bin` - Generate control packet binaries
+- `aie-translate --aie-npu-to-binary` - Generate transaction binaries