Debug Techniques in Hardware Emulation

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
UG1393
Release Date
2023-07-17
Version
2023.1 English

The following table shows some specific techniques for debugging different situations 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 AIE, 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 content

The DDR model saves its contents in a binary file. In the folder where simulation is run (e.g. 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, please use these mechanisms.
  1. Setenv variable ENABLE_RP_LOGS=true in the shell where QEMU is being run. Look for a log file namedsim/behav_waveform/xsim/rp_log.txt. 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.
AIE PDI is downloaded from PS to AIE through fast mode, thus transactions cannot be seen in the waveform. Users can enable logging all transactions at AIE 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 AIE VCD Dump and view contents in VCD Analyzer by adding switch -aie-sim-options to launch_hw_emu.sh cmd line. See UG1076 for details of aie-sim-options file. These are common between aiesim and hw_emu.
  3. Create a file (aie_sim_config.txt) to enable AIE 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 *