Launching Host and Kernel Debug - 2020.2 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. 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.