Software Emulation Debug for Embedded Processors - 2023.2 English - UG1393

You can use the following process to debug the system in software emulation for an embedded processor platform, such as an AMD Versal™ VCK190 or AMD Zynq™ UltraScale+™ MPSoC ZCU102 or ZCU102. This process launches a new terminal that allows for gdb commands to be used, in addition to visual of the files for code stepping.

1. After completing the sw_emu build process, launch the QEMU emulation environment with debug using one of the following methods:

   • If you are using PS on x86 flow, add kernel-dbg to the xrt.ini file as follows:

     [Emulation]
     kernel-dbg=true

     For more information on all options available in the xrt.ini file, see xrt.ini File.

   • Otherwise, use the following command from your build directory to launch the emulation environment with debug.

     ./emulation/launch_sw_emu.sh -kernel-dbg true

     Where,

     • ./emulation is the output directory of the v++ --package command.
     • -kernel-dbg true sets up the emulator to run gdb at the execution of the application kernels (PL, AI Engine).
2. As described in Running Emulation on an Embedded Processor Platform, run the following commands in the QEMU shell once you see the qemu% prompt:

   mount /dev/mmcblk0p1 /mnt
   cd /mnt
   export LD_LIBRARY_PATH=/mnt:/tmp:$LD_LIBRARY_PATH
   export XCL_EMULATION_MODE=sw_emu
   export XILINX_XRT=/usr
   

3. Run the PS application from the QEMU environment. For example: ./host.exe a.xclbin

   Launching the host application also launches gdb in a separate terminal to let you debug the PL and AI Engine kernels in the .xclbin. In gdb, you can perform all the typical activities to set up your debug environment, such as breakpoint insertion for PL and AI Engine kernels, and step or continue commands to walk through the code.

4. You can set a breakpoint on either function name or line number in gdb using this syntax. During execution, when it reaches that breakpoint, gdb automatically opens the file with the right line number, as long as it can locate the sources. For example,

   break <filename>:<function name>
   break <filename>:<line_num >

   Also, you can set a breakpoint for a kernel using a command such as b Vadd_A_B. This command pauses .xclbin execution in gdb at the invocation of the specified kernel, in this example the Vadd_A_B kernel. In an .xclbin file with multiple kernels, you can add breakpoints for all or specific kernels.

   Note: When you set the breakpoint in gdb, you will see a note that the function is not defined and prompting you to make the breakpoint pending on future load. Enter y to proceed.
5. In the gdb terminal, press r to run the application and step through the code, set variable values, and continue. To get a textual user interface of gdb, select with Ctrl + X, Ctrl + A. If the text interface is used the source code for the kernel is displayed.
6. Step through the code, or press c to let the code run through to completion. The results of your software emulation are displayed in the original command terminal.