XSDB Flow - 2024.1 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID

UG1076

Release Date

2024-06-27

Version

2024.1 English

The XSDB flow is as follows:

Set up xsdb as described in the following steps to connect to the device hardware.
When running the application, the trace data is stored in DDR memory by the debugging and profiling IP. To capture and evaluate this data, you must connect to the hardware device using xsdb. This command is typically used to program the device and debug bare-metal applications. Connect your system to the hardware platform or device over JTAG, launch the xsdb command in a command shell, and run the following sequence of commands:
```
xsdb% connect
xsdb% ta
xsdb% ta 1
xsdb% source $::env(XILINX_VITIS)/scripts/vitis/util/aie_trace.tcl
xsdb% aietrace start -graphs mygraph -work-dir ./Work -link-summary $PROJECT/xsa.link_summary -base-address 0x900000000 -depth 0x800000 -tile-based-aie-tile-metrics "all:functions; {4,1}:{6,2}:all_stalls" 

# Execute the PS host application (.elf) on Linux
## After the application completes processing.
xsdb% aietrace stop
```
where, the source $::env(XILINX_VITIS)/scripts/vitis/util/aie_trace.tcl command sources the Tcl trace command to set up the xsdb environment.
Run the design on hardware to trace hardware events.
Offload the captured trace data.
Launch the Vitis IDE to import and analyze data with this command.
```
vitis -a aie_trace_profile.run_summary
```

Table 1. XSDB Trace Options
Option	Description
`start`	Start the event trace and initializes the DPA IP to begin capturing trace data.
`stop`	Stop the event trace and instructs the DPA IP to offload the trace event data from the DDR memory . This command must wait until after the application completes. The data is written to the event_trace<N>.txt file in the current working directory from where `xsdb` was launched. An `aie_trace_profile.run_summary` file is also created. It can be opened in the Vitis IDE as explained in Viewing the Run Summary in the Vitis IDE. Tip: If you do not remove the `event_trace<N>.txt` when running the graph again, the old files will be overwritten by the new run results.
`-link-summary`	Specify the path to the link summary generated during design linking phase. This is a mandatory option.
`-start-type time\|iteration\|kernel_event0`	Specifies different trace delaying approaches like time, iteration or user-defined event. To use the `-start-type kernel_event0` option, you must add `event0()` intrinsic in the kernel code that generates core event 0 for profiling. `-start-type time\|iteration` option should be combined with the `-start-time` and `-start-iteration` options respectively as explained below. For more information on delayed event trace, refer to the topic Using the Delayed Event Trace.
`-start-time`	Specifies the start delay of event trace in terms of either AI Engine clock cycles or time in sec, ms, us or ns. If no units are specified, the value is assumed to be in AI Engine clock cycles. This option should be used in combination with `-start-type time`.
`-start-iteration`	Starts the event trace based on the graph iteration count. To use this type of event trace start, you must re-compile the AI Engine design with an `graph-iterator-event` option. This option should only be used in combination with `-start-type iteration` .
`-work-dir <Work Directory>`	Specify working directory. This is a mandatory option.
`-base-address <address>`	Starting address in the DDR from which the Trace data will be stored. Important: The DDR memory address used in `-base-address` must be a high address to limit any chance of running into memory conflicts with the OS on the Versal platform or the application. For a custom platform, make sure you know how much DDR memory is being used and plan accordingly.
`-depth <size>`	Length of the memory that will be used in the DDR. This is a required option.
`-tile-based-aie-tile-metrics`	Sets which AI Engine event to store for specified tiles.
`-graph-based-aie-tile-metrics`	Sets which AI Engine event to store for specified kernels/graphs.
`-graph-based-memory-tile-metrics`	Note: This option only applies to AI Engine-ML devices. Sets which Memory Tile metrics to store for specified buffer/graph
`-tile-based-memory-tile-metrics`	Note: This option only applies to AI Engine-ML devices. Sets which Memory Tile metrics to store for specified Memory Tiles.

For the event specifications each option is essentially a combination string of all settings separated by semi-colon. For example:

# Sets event trace to "all_stall" for the tile range column 4 to
# 6 and row 1 to 2, and overides to "functions" for tile (4,1)
-tile-based-aie-metrics "{4,1}:{6,2}:all_stalls; {4,1}:functions"

# Sets event trace to "functions" for kernel k1 in graph myGraph
-graph-based-aie-tile-metrics "myGraph:k1:functions"

# Sets event trace to "functions" for all kernels in hierarchical graph
# myGraph->subgraph1->subgraph2
-graph-based-aie-tile-metrics "myGraph.subgraph1.subgraph2:all:functions"

#Examples on Delayed event trace

# Sets event trace to "functions" for kernel k1 in graph myGraph delayed 
# by 1.5ms
-start-type time -start-time 1.5ms -graph-based-aie-tile-metrics "myGraph:k1:functions"

# Sets event trace to "functions" for kernel k1 in graph myGraph delayed
# by 10 graph iterations
-start-type iteration -start-iteration 10 -graph-based-aie-tile-metrics "myGraph:k1:functions"

# Sets event trace to "functions" for kernel k1 in graph myGraph delayed
# by user defined event
-start-type kernel_event0 -graph-based-aie-tile-metrics "myGraph:k1:functions"

Note: Metrics <functions_all_stalls> and <functions_partial_stalls> are renamed to all_stalls and partial_stalls respectively for runtime configuration.