XSDB Flow - 2022.2 English

XSDB Flow - 2022.2 English - UG1076

AI Engine Tools and Flows User Guide (UG1076)

Document ID

UG1076

Release Date

2022-10-19

Version

2022.2 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:memory_stalls; {4,1}:{6,2}:functions_all_stalls" 

# Execute the PS host application (.elf) on Linux
## After the application completes processing.
xsdb% aietrace stop
```
where:

connect

Launches the hw_server and connects xsdb to the device.

source $::env(XILINX_VITIS)/scripts/vitis/util/aie_trace.tcl

Sources the Tcl trace command to set up the xsdb environment.

aietrace start -graphs mygraph -link-summary PROJECT/xsa.link_summary -base-address 0x900000000 -depth 0x800000 -tile-based-aie-tile-metrics "all:functions:memory_stalls; {4,1}:{6,2}:functions_all_stalls"

Initializes the DPA IP to begin capturing trace data. The -graphs specifies the graph(s) to collect event trace data. If specific tiles are preferred, specify -tiles with list of tiles to collect event trace data. The-tile-based-aie-tile-metrics specifies on which tiles memory_stalls or functions_all_stalls event trace level will be captured. The values -base-address 0x900000000 -depth 0x800000 specify the starting address to write trace data into the AI Engine and the amount of data to store.

Important: The DDR memory address used in -base-address 0x900000000 must be a high address to limit any chance of running into memory conflicts with the OS on the xilinx_vck190_base_202220_1 platform or the application. For a custom platform, make sure you know how much DDR memory is being used and plan accordingly.

aietrace stop

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 Analyzer as explained in Viewing the Run Summary in the Vitis Analyzer.

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.
Run the design on hardware to trace hardware events.
Offload the captured trace data.
Launch the Vitis Analyzer to import and analyze data with this command.
```
vitis_analyzer aie_trace_profile.run_summary
```

Table 1. XSDB Trace Options
Option	Description
`start`	Start event trace
`stop`	stop event trace
`-work-dir <Work Directory>`	Specify working directory
`-graphs <Graph Name>`	This option allows you to specify which graph(s) should be subject to event trace.
`-base-address <address>`	Starting address in the DDR from which the Trace data will be stored.
`-depth <size>`	Length of the memory that will be used in the DDR.
`-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.
`-tile_based_interface_tile_metrics`	Sets which Interface Tile event to store for specified 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 "functions_all_stall:memory_stalls" 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}:functions_all_stalls:memory_stalls; {4,1}:functions"

# Sets event trace to "functions" for kernel k1 in graph myGraph
-graph_based_aie_tile_metrics "myGraph:k1:functions"