Profile and Debug in Hardware Emulation - 2025.2 English

Embedded Design Development Using Vitis User Guide (UG1701)
Document ID
UG1701
Release Date
2025-11-20
Version
2025.2 English

While running emulation, you can specify a number of profile options as described in Enabling Profiling in Your Application to capture design data during runtime. Any reports generated during the run are collected into the xrt.run_summary file. This collection of reports can be viewed by opening the run_summary in Vitis analyzer, and includes a Summary report, System and Platform Diagrams to illustrate the hardware design, Run Guidance offering any suggestions for improving the performance of the system, and a Profile Summary and Timeline Trace when enabled in the xrt.ini file during runtime. Refer to Working with the Analysis View (Vitis Analyzer) in the Vitis Reference Guide (UG1702) for additional information.

The following table shows some specific techniques for debugging different scenarios in hardware emulation.

Table 1. Techniques for Debugging in Hardware Emulation
Debug Focus Description Steps
x86 host (XRT) Enable detailed XRT logs by updating xrt.ini.

Add the following to xrt.ini file. Run the test case with the updated xrt.ini. Review the generated xrt_hal.log. 

[runtime]hal_log=xrt_hal.log
AXI traffic on SystemC models like AI Engine, NOC, CIPS

The host transactions are routed through sim_qdma SystemC module. These transactions can be dumped into log file. If PL is also SystemC, then even PL transactions can be viewed there.

If PL is RTL, then boundary of PL can be viewed in waveform.

In xrt.ini add,

[Emulation]xtlm_aximm_log=true xtlm_axis_log=true

View file xsc_report.log.
Viewing DDR memory content

The DDR model saves its contents in a binary file. In the folder where simulation is run (package.hw_emu/sim/behav_waveform/xsim dir), look for files named like below. Each such binary file corresponds to a region of DDR memory at a particular offset.

qemu-memory-_ddr@0x00000000 or qemu-memory-_mem_0xc080000000@0xc080000000ULL

These files represent DDR/LPDDR memory contents in binary form.

There is a backdoor connection between QEMU to NOC_DDR model. Thus, users will not see any transactions in the waveform nor will they see any logs. The shared memory is directly updated. To view memory contents, users can directly dump the memory contents.

The contents of the memory can be seen by using hexdump command. an example command is shown below. 

hexdump qemu-memory-_mem_0x60000000000@0x60000000000ULL -s 0x80000000 -n 4096 -v -e '1/4 "%02X" "\n"' > dump_600.log
PS (QEMU) During firmware and software execution, the Arm APU can run into issues. You see details of various transactions and state on PS using these mechanisms.
  1. Setenv variable ENABLE_RP_LOGS=true in the shell where QEMU is being run. Look for a log file named sim/behav_waveform/xsim/qemu_rp.log. This contains transactions from PS to rest of the peripherals (other than DDR).
  2. Review package.hw_emu/qemu_output.log to see the output. This contains PS output to STDOUT (UART). If there is any error during PLM or other SW execution, those will be captured here. Look at the details of the error (CDO address, U-Boot stage etc) to narrow down which CDO is causing the error.
  3. Run launch_hw_emu.sh -enable_debug mode which will direct QEMU logs in its own xterm window.
AI Engine PDI is downloaded from PS to AI Engine through fast mode, thus transactions cannot be seen in the waveform. Users can enable logging all transactions at AI Engine AXI interfaces. There is a separate file per AXI interface
  1. Enable setenv ENABLE_AIE_DBG_TRACE. View transaction log in the simulation folder at aie_log/S00_AXI.txt file.
  2. Enable AI Engine VCD Dump and view contents in Vitis Analyzer by adding switch -aie-sim-options to launch_hw_emu.sh cmd line. See UG1076 for details of AI Engine-sim-options file. These are common between aiesim and hw_emu.
  3. Create a file (aie_sim_config.txt) to enable AI Engine simulation options.
    1. In this file, add "AIE_DEBUG_AXIMM=True"
    2. Pass this file on launch emulator cmd line:
       ./package.hw_emu/launch_hw_emu.sh -aie-sim-options <Absolute path to the options .txt file>
Dumping Waveform in DC flow (Batch Mode)

Make sure the design is linked with the -g option and you have run the design at least once in Xsim GUI mode to save the required .wcfg file and save the list of relevant signals.

Dump the waveform and open it in xsim along with saved .wcfg file

Update following options in xrt.ini option

[Emulation]
user_pre_sim_script=<use pre sim script absolute path>
Pre-simulation script is needed to enable signal dumping: 
log_wave -r *