Launching Host and Kernel Debug - 2023.1 English

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. To control this process, you must start new GDB instances and connect to the xrt_server through the listener port. This is done in the next steps.

   Tip: The initial listener port should not be connected to as it is used for connection by TCF agents such as the Vitis IDE. In this command-line flow the first listener port should be ignored.
   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. 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 AMD 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

   When you run the host application in gdb, it spawns off the software emulation process. The software emulation process detects that xrt_server is running and connects to it. At that point, a listener port for the kernel gdb is created and the software emulation process waits until it receives commands. Now, you should connect the kernel gdb to the xrt_server listener port as described in the next step.

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 does not work inside GDB.

   • Connect to the kernel process:

     target remote :<num>

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

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.