Launching Host and Kernel Debug - 2020.2 English

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

Document ID
UG1393
Release Date
2021-03-22
Version
2020.2 English
In software emulation, to better model the hardware accelerator, the execution of the FPGA binary is spawned as a separate process. If you are using GDB to debug the host code, breakpoints set in kernel code are not encountered because the kernel code is not run within the host code process. To support the concurrent debugging of the host and kernel code, the Vitis debugger provides a system to attach to spawned kernels through the use of the debug server (xrt_server). To connect the host and kernel code to the debug server, you must open three terminal windows using the following process.
Tip: This flow should also work while using a graphical front-end for GDB, such as the data display debugger (DDD) available from GNU. The following steps are the instructions for launching GDB.
  1. Open three terminal windows, and set up each window as described in Setting Up the Vitis Environment. The three windows are for:
    • Running xrt_server
    • Running GDB (xgdb) on the Host Code
    • Running GDB (xgdb) on the Kernel Code
  2. In the first terminal, after setting up the terminal environment, start the Vitis debug server using the following command:
    xrt_server --sdx-url

    The debug server listens for debug commands from the host and kernel, connecting the two processes to create a single debug environment. The xrt_server returns a listener port <num> on standard out. Keep track of the listener port number returned as this port is used by GDB to debug the kernel process. To control this process, you must start new GDB instances and connect to the xrt_server. You will do this in the next steps.

    Important: With the xrt_server running, all spawned GDB processes wait for control from you. If no GDB ever attaches to the xrt_server, or provides commands, the kernel code appears to hang.
  3. In a second terminal, after setting up the terminal environment, launch GDB for the host code as described in the following steps:
    1. Set the ENABLE_KERNEL_DEBUG environment variable. For example, in a C-shell use the following:
      setenv ENABLE_KERNEL_DEBUG true
    2. Set the XCL_EMULATION_MODE environment variable to sw_emu mode as described in Running the Application Hardware Build. For example, in a C-shell use the following:
      setenv XCL_EMULATION_MODE sw_emu
    3. The runtime debug feature must be enabled using an entry in the xrt.ini file, as described in xrt.ini File. Create an xrt.ini file in the same directory as your host executable, and include the following lines:
      [Debug]
      app_debug=true
      

      This informs the runtime library that the kernel has been compiled for debug, and that XRT library should enable debug features.

    4. Start gdb through the Xilinx wrapper:
      xgdb --args <host> <xclbin>
      Where <host> is the name of your host executable, and <xclbin> is the name of the FPGA binary. For example:
      xgdb --args host.exe vadd.xclbin

      Launching GDB from the xgdb wrapper performs the following setup steps for the Vitis debugger:

      • Loads GDB with the specified host program.
      • Sources the Python script from the GDB command prompt to enable the Vitis debugger extensions:
        gdb> source ${XILINX_XRT}/share/appdebug/appdebug.py
  4. In a third terminal, after setting up the terminal environment, launch the xgdb command, and run the following commands from the (gdb) prompt:
    • For software emulation:
      file <Vitis_path>/data/emulation/unified/cpu_em/generic_pcie/model/genericpciemodel

      Where <Vitis_path> is the installation path of the Vitis core development kit. Using the $XILINX_VITIS environment variable will not work inside GDB.

    • For hardware emulation:
      1. Locate the xrt_server temporary directory:/tmp/sdx/$uid.
      2. Find the xrt_server process id (PID) containing the DWARF file of this debug session.
      3. At the gdb command line, run: file /tmp/sdx/$uid/$pid/NUM.DWARF.
    • In either case, connect to the kernel process:
      target remote :<num>

      Where <num> is the listener port number returned by the xrt_server.

    Tip: When debugging software/hardware emulation kernels in the Vitis IDE, these steps are handled automatically and the kernel process is automatically attached, providing multiple contexts to debug both the host code and kernel code simultaneously.

With the three terminal windows running the xrt_server, GDB for the host, and GDB for the kernels, you can set breakpoints on your host or kernels as needed, run the continue command, and debug your application. When the all kernel invocations have finished, the host code continues and the xrt_server connection drops.

Important: For both software and hardware emulation flows, there are restrictions with respect to the accelerated kernel code debug interactions. Because this code is preprocessed in the software emulation flow, and translated to RTL in the hardware emulation flow, it is not always possible to set breakpoints at all locations. Only a limited number of breakpoints such as preserved loops and functions are supported, especially for hardware emulation. Nevertheless, this setup is useful for debugging the interface of the host code with the kernels.