Running Software Emulation from the Command Line - 2022.1 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID
Release Date
2022.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 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.
  1. To launch the emulation environment with debug use the following command from your build directory.
    ./emulation/ -kernel-dbg true


    • ./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.
  2. 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
  3. 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.