xrt_server
). To connect the host and kernel code to the debug server, you must
open three terminal windows using the following process. - 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
- Running
- 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 alistener port <num>
on standard out. To control this process, you must start new GDB instances and connect to thexrt_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 thexrt_server
running, all spawned GDB processes wait for control from you. If no GDB ever attaches to thexrt_server
, or provides commands, the kernel code appears to hang. - In a second terminal, after setting up the terminal environment, launch GDB
for the host code as described in the following steps:
- Set the
ENABLE_KERNEL_DEBUG
environment variable. For example, in a C-shell use the following:setenv ENABLE_KERNEL_DEBUG true
- Set the
XCL_EMULATION_MODE
environment variable tosw_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
- 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.
- 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
When you run the host application in
gdb
, it spawns off the software emulation process. The software emulation process detects thatxrt_server
is running and connects to it. At that point, a listener port for the kernelgdb
is created and the software emulation process waits until it receives commands. Now, you should connect the kernelgdb
to thexrt_server
listener port as described in the next step. - Set the
- 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 thexrt_server
.
- For software
emulation:
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.