Add event trace configuration to aie dialect

[fifield]

This PR is a proposal to add declarative event trace configuration to AIE dialect.

The current implementation:

Input code to describe the event trace configuration for one tile (what the user writes):

aie.device(npu1_1col) {
  %tile02 = aie.tile(0, 2)
  
    // Trace configuration for compute tile (0,2) - core events
    aie.trace @core_trace(%tile_0_2) {
      // Set trace mode (Event-Time captures timestamps)
      aie.trace.mode "Event-Time"

      // Configure packet routing (ID and type for packet-switched routing)
      aie.trace.packet id=1 type=core

      // Specify which events to capture (up to 8 events)
      aie.trace.event<"INSTR_EVENT_0">        // User event 0 (start marker)
      aie.trace.event<"INSTR_EVENT_1">        // User event 1 (end marker)
      aie.trace.event<"INSTR_VECTOR">         // Vector instructions
      aie.trace.event<"MEMORY_STALL">         // Memory access stalls
      aie.trace.event<"STREAM_STALL">         // Stream buffer stalls
      aie.trace.event<"LOCK_STALL">           // Lock acquisition stalls
      aie.trace.event<"PORT_RUNNING_0">       // DMA:0 S2MM running
      aie.trace.event<"PORT_IDLE_1">          // DMA:1 MM2S idle
      aie.trace.port<0> port=DMA channel=0 direction=S2MM
      aie.trace.port<1> port=DMA channel=0 direction=MM2S

      // Specify start/stop control (broadcast events)
      aie.trace.start event=<"BROADCAST_15">
      aie.trace.stop event=<"BROADCAST_14">
    }
  
  // Runtime sequence with trace invocation
  aiex.runtime_sequence @seq(%arg0: memref<32xi32>) {
    aie.trace.start_config @core_trace
    // ... other runtime operations
  }
}

Intermediate steps in the lowering where the aie.trace description has been lowered to an aie.trace.config sequence of register writes, then to npu.write32:

  // Intermediate representation (after -aie-trace-to-config)
  aie.trace.config @core_trace_config(%tile_0_2) packet_type = core {
    aie.trace.reg register = "Trace_Control0" field = "Mode" value = 0 : i32 comment = "trace mode"
    aie.trace.reg register = "Trace_Control1" field = "ID" value = 1 : i32 comment = "packet ID"
    aie.trace.reg register = "Trace_Control1" field = "Packet_Type" value = 0 : i32 comment = "packet type"
    aie.trace.reg register = "Trace_Control0" field = "Trace_Start_Event" value = 122 : i32 comment = "start event"
    aie.trace.reg register = "Trace_Control0" field = "Trace_Stop_Event" value = 121 : i32 comment = "stop event"
    aie.trace.reg register = "Stream_Switch_Event_Port_Selection_0" field = "Port_0_ID" value = "DMA:0" comment = "port 0 ID"
    aie.trace.reg register = "Stream_Switch_Event_Port_Selection_0" field = "Port_0_Master_Slave" value = 1 : i32 comment = "port 0 master/slave"
    aie.trace.reg register = "Stream_Switch_Event_Port_Selection_0" field = "Port_1_ID" value = "DMA:0" comment = "port 1 ID"
    aie.trace.reg register = "Stream_Switch_Event_Port_Selection_0" field = "Port_1_Master_Slave" value = 0 : i32 comment = "port 1 master/slave"
    aie.trace.reg register = "Trace_Event0" field = "Trace_Event0" value = 33 : i32 comment = "event slot 0"
    aie.trace.reg register = "Trace_Event0" field = "Trace_Event1" value = 34 : i32 comment = "event slot 1"
    aie.trace.reg register = "Trace_Event0" field = "Trace_Event2" value = 37 : i32 comment = "event slot 2"
    aie.trace.reg register = "Trace_Event0" field = "Trace_Event3" value = 23 : i32 comment = "event slot 3"
    aie.trace.reg register = "Trace_Event1" field = "Trace_Event4" value = 24 : i32 comment = "event slot 4"
    aie.trace.reg register = "Trace_Event1" field = "Trace_Event5" value = 26 : i32 comment = "event slot 5"
    aie.trace.reg register = "Trace_Event1" field = "Trace_Event6" value = 79 : i32 comment = "event slot 6"
    aie.trace.reg register = "Trace_Event1" field = "Trace_Event7" value = 78 : i32 comment = "event slot 7"
  }

  // Intermediate representation (after -aie-trace-pack-reg-writes)
  aie.trace.config @core_trace_config(%tile_0_2) packet_type = core {
    aie.trace.reg register = "Trace_Control0" value = 2038038528 : i32 mask = 2139029507 comment = "trace mode + start event + stop event"
    aie.trace.reg register = "Trace_Control1" value = 1 : i32 mask = 28703 comment = "packet ID + packet type"
    aie.trace.reg register = "Stream_Switch_Event_Port_Selection_0" value = 289 : i32 mask = 16191 comment = "port 0 ID + port 0 master/slave + port 1 ID + port 1 master/slave"
    aie.trace.reg register = "Trace_Event0" value = 388309537 : i32 mask = 2139062143 comment = "event slot 0 + event slot 1 + event slot 2 + event slot 3"
    aie.trace.reg register = "Trace_Event1" value = 1313806872 : i32 mask = 2139062143 comment = "event slot 4 + event slot 5 + event slot 6 + event slot 7"
  }

  // Final output (after -aiex-inline-trace-config)
  aiex.runtime_sequence @seq(%arg0: memref<32xi32>) {
    aiex.npu.write32 {address = 213200 : ui32, column = 0 : i32, row = 2 : i32, value = 2038038528 : ui32}
    aiex.npu.write32 {address = 213204 : ui32, column = 0 : i32, row = 2 : i32, value = 1 : ui32}
    aiex.npu.write32 {address = 261888 : ui32, column = 0 : i32, row = 2 : i32, value = 289 : ui32}
    aiex.npu.write32 {address = 213216 : ui32, column = 0 : i32, row = 2 : i32, value = 388309537 : ui32}
    aiex.npu.write32 {address = 213220 : ui32, column = 0 : i32, row = 2 : i32, value = 1313806872 : ui32}
    // Additional npu.write32 for other registers...
  }

Combo events:

aie.trace @my_trace(%tile02) {
  // Combo 0: lock stalled AND NOT DMA active
  aie.trace.combo_event<0> "LOCK_STALL" AND_NOT "DMA_S2MM_0_STALLED"
  
  // Combo 1: instruction event OR vector operation
  aie.trace.combo_event<1> "INSTR_EVENT_0" OR "INSTR_VECTOR"
  
  // Combo 2: (combo0) AND (combo1)
  aie.trace.combo_event<2> "COMBO_EVENT_0" AND "COMBO_EVENT_1"
  
  // Trace the combo results
  aie.trace.event<"COMBO_EVENT_0">
  aie.trace.event<"COMBO_EVENT_1">
  aie.trace.event<"COMBO_EVENT_2">
  ...
}

Edge Events:

aie.trace @my_trace(%tile02) {
  // Edge detector 0: count lock stalls (rising edges)
  aie.trace.edge_event<0> event="LOCK_STALL" trigger=RISING
  
  // Edge detector 1: count transitions (both edges)
  aie.trace.edge_event<1> event="LOCK_STALL" trigger=BOTH
  
  // Trace the edge-detected events
  aie.trace.event<"EDGE_DETECTION_EVENT_0">
  aie.trace.event<"EDGE_DETECTION_EVENT_1">
  ...
}

Depends on #2712 and #2696

[Copilot]

Pull request overview

This PR proposes a declarative event-trace configuration API in the AIE dialect (aie.trace and related ops), plus a lowering pipeline that converts those declarations into register writes and finally inlines them as aiex.npu.write32/maskwrite32-style operations in runtime sequences.

Changes:

• Adds new AIE trace ops/attrs (trace mode, packet routing, events, ports, combo/edge events, and runtime trace.start_config) with parsing/verification support.
• Introduces lowering passes: -aie-trace-to-config, -aie-trace-pack-reg-writes, and -aie-inline-trace-config.
• Adds MLIR tests and a full programming example (MLIR + host code + trace visualization tooling).

Reviewed changes

Copilot reviewed 48 out of 48 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
utils/generate_events_tablegen.py	Adjusts AIE1 event enum naming suffix generation used by TableGen.
test/dialect/AIEX/trace/test_trace_end_to_end.mlir	End-to-end trace lowering/inlining test for AIEX pipeline.
test/dialect/AIEX/trace/test_inline_trace_config_verify.mlir	Verifies diagnostics when inlining is run without packing pass.
test/dialect/AIEX/trace/test_inline_trace_config.mlir	Tests inlining trace config into runtime sequence.
test/dialect/AIE/trace/test_trace_verify.mlir	Verifier coverage for trace op constraints and typed-enum arch mismatches.
test/dialect/AIE/trace/test_trace_to_config_verify.mlir	Verifies lowering errors for unknown events during trace-to-config.
test/dialect/AIE/trace/test_trace_to_config.mlir	Checks aie-trace-to-config output register-field writes.
test/dialect/AIE/trace/test_trace_parse.mlir	Parser/pretty-printer coverage for trace ops.
test/Dialect/AIEX/trace/test_trace_port_end_to_end.mlir	End-to-end test for port tracing lowering/inlining.
test/Dialect/AIE/trace/test_trace_port_verify.mlir	Verifier coverage for port slot/channel constraints and duplicates.
test/Dialect/AIE/trace/test_trace_port_to_config.mlir	Checks port configuration lowering to aie.trace.reg field writes.
test/Dialect/AIE/trace/test_trace_port_parse.mlir	Parser/pretty-printer coverage for trace port syntax.
test/Dialect/AIE/combo_edge/test_edge_to_config.mlir	Checks edge-event lowering to register writes.
test/Dialect/AIE/combo_edge/test_combo_to_config.mlir	Checks combo-event lowering to register writes.
test/Dialect/AIE/combo_edge/test_combo_event_verify.mlir	Verifier coverage for combo/edge slot rules and invalid sources.
test/Dialect/AIE/combo_edge/test_combo_event_parse.mlir	Parser/pretty-printer coverage for combo/edge event syntax.
test/Dialect/AIE/combo_edge/test_combo_edge_full.mlir	Integrated lowering test combining combo + edge + standard trace config.
test/CppTests/register_database.cpp	Minor formatting tweaks in register database unit tests.
python/dialects/aie.py	Adds Python attribute builder for TraceEventAttr and a trace region-op helper.
python/compiler/aiecc/main.py	Adds trace lowering passes into the default aie.device pipeline.
programming_examples/basic/event_trace/visualize_trace.py	New script to render timeline PNG from parsed trace JSON.
programming_examples/basic/event_trace/vector_scalar_mul.cc	New kernel emitting event markers for tracing.
programming_examples/basic/event_trace/test.py	New Python host runner that captures and dumps trace.
programming_examples/basic/event_trace/test.cpp	New C++ host runner wired into repo test utilities.
programming_examples/basic/event_trace/run_strix_makefile.lit	Lit recipe to run the example on NPU2 (“strix”).
programming_examples/basic/event_trace/run_makefile.lit	Lit recipe to run the example on NPU1.
programming_examples/basic/event_trace/aie_trace.mlir	Full example MLIR using the new declarative trace syntax.
programming_examples/basic/event_trace/README.md	Documentation for the example and lowering pipeline.
programming_examples/basic/event_trace/Makefile	Build/run orchestration for the example (kernel, xclbin, host, parsing, viz).
programming_examples/basic/event_trace/CMakeLists.txt	Builds the example host executable against XRT and test utils.
lib/Dialect/AIEX/Transforms/CMakeLists.txt	Registers the new AIEX inline-trace-config transform source.
lib/Dialect/AIEX/Transforms/AIEInlineTraceConfig.cpp	New pass that inlines trace configs into runtime sequences as NPU writes.
lib/Dialect/AIE/Transforms/CMakeLists.txt	Registers new AIE trace-to-config transform source.
lib/Dialect/AIE/Transforms/AIETraceToConfig.cpp	New passes: trace-to-config lowering + packing/merging register writes.
lib/Dialect/AIE/IR/CMakeLists.txt	Adds trace ops implementation file to AIE IR library build.
lib/Dialect/AIE/IR/AIETraceOps.cpp	Implements parsing/printing/verification for trace ops/attrs.
lib/Dialect/AIE/IR/AIETargetModel.cpp	Adds event-module mapping tweaks and helpers for masks/port resolution.
lib/Dialect/AIE/IR/AIEDialect.cpp	Hooks custom parse/print helpers for trace-related attribute/value forms.
include/aie/Dialect/AIEX/Transforms/AIEXPasses.td	Declares aie-inline-trace-config pass.
include/aie/Dialect/AIEX/Transforms/AIEXPasses.h	Adds factory declaration for inline-trace-config pass.
include/aie/Dialect/AIE/Transforms/AIEPasses.td	Declares aie-trace-to-config and aie-trace-pack-reg-writes passes.
include/aie/Dialect/AIE/Transforms/AIEPasses.h	Adds factory declarations for new AIE trace passes.
include/aie/Dialect/AIE/IR/AIETraceOps.td	ODS/TableGen definitions for trace ops.
include/aie/Dialect/AIE/IR/AIETraceAttrs.td	ODS/TableGen definitions for trace attrs/enums.
include/aie/Dialect/AIE/IR/AIETargetModel.h	Adds APIs for stream-switch port index, field mask, and port resolution.
include/aie/Dialect/AIE/IR/AIEOps.td	Includes trace ops definitions into the AIE op set.
include/aie/Dialect/AIE/IR/AIEDialect.h	Exposes shared trace event parse/print helpers.
include/aie/Dialect/AIE/IR/AIEAttrs.td	Includes trace attrs and updates event enum include naming.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

aie-inline-trace-config currently discards the mask on packed aie.trace.reg writes and always emits aiex.npu.write32. If mask is not 0xFFFFFFFF, this will clobber unrelated bits in the target register. Consider emitting aiex.npu.maskwrite32 when regOp.getMask() is present (and only using write32 when the mask is full).

[fifield]

This is a good catch, but for the record this was an intentional design decision. It ends up producing the same code as one would write by hand, instead of more costly maskwrite32 (rmw) instructions masking off useless bits.