Running Software Emulation from the Command Line - 2023.1 English

With the Software Emulation build complete, you can use the following steps to debug the system. This process will launch a new terminal that will allow for gdb commands to be used, as well as visual of the files for code stepping.

1. Launch QEMU emulator environment using launch_sw_emu.sh script that is generated during the v++ --package process.
2. Using a specific command-line option, -kernel-dbg and set it to true.
3. Specify the kernels, PL or AI Engine kernels.
4. Launch the 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 in the Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).

   • 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 packaging process.
     • -kernel-dbg true will setup the emulator to run gdb at the execution of the application.
5. Run the following commands in the QEMU shell once you see the qemu% prompt.

   export LD_LIBRARY_PATH=/mnt/sd*1:/tmp:$LD_LIBRARY_PATH
   export XCL_EMULATION_MODE=sw_emu
   export XILINX_XRT=/usr

6. Run the PS application. For example, ./host.exe a.xclbin.
   This will start running the host application and launch gdb in a separate terminal. Here you can do all the debug activities such as, breakpoint, next (step), and continue on PL kernels and AI Engine kernels.

   Note: To get a textual user interface of gdb, select with Ctrl + X, Ctrl + A.