Tracing - 2024.1 English

AI Engine System Software Driver Reference Manual (UG1642)

Document ID
UG1642
Release Date
2024-05-30
Version
2024.1 English

Both the memory module and the core module have trace units. Each trace unit can trace up to eight events. The trace units output trace packets to AXI4-Streams. The trace streams can be connected to tile stream switches. The stream switch needs to be configured as packet-switched for trace streams. The trace unit can operate in different modes:

  • AI Engine core module: Event-time, Event-PC, and Execution trace
  • AI Engine memory module: Event-time
  • AI Engine PL module: Event-time

When building the AI Engine application on host, the AI Engine compiler has the option to enable tracing. When the tracing option is enabled, the AI Engine compiler routes the trace streams to a dedicated debug IP in PL or AI Engine interface tiles DMA. The events to trace can be set either at compile time or runtime.

The AI Engine driver provides the following APIs for tracing:

  • Configure events to trace
  • Configure AI Engine interface tiles DMA if AI Engine interface tiles DMA is used to capture trace stream.

The AI Engine system software trace module API functions are as follows:

`XAie_TraceEvent`
This API is used to configure trace event register with event number at the given slot index.
`XAie_TraceStartEvent`
This API is used to configure trace control register with event number to start tracing.
`XAie_TraceStopEvent`
This API is used to configure trace control register with event number to stop tracing.
`XAie_TraceModeConfig`
This API is used to configure trace event register with event number at a particular slot index.
`XAie_TraceGetState`
This API is used to read the current state of trace module.

Because of xbutil, exercises for these system software API’s for collecting the generated event trace data allow developers to review the design execution on the hardware. It is also possible to report an error using xbutil. The error report accumulates all the errors from the various classes and sorts them by a time stamp. You can issue the command xbutil examine -r error -d 0 in the hardware Linux console and observe the error report as follows.

Figure 1. xbutilExamine_output

The following is the runtime debug and trace configuration flow.

  • Applications allocate trace buffers.
  • Call the AI Engine driver API to configure events to trace.
  • Call the AI Engine driver API to configure AI Engine interface tiles DMA to capture trace stream if AI Engine interface tiles DMA is used to capture data. If it is PL IP to capture the trace packets, applications need to configure the PL debug IP to capture the trace stream.
  • Applications run the graph.
  • Analysis tool parses the trace packets.