Example of Command Line Debugging

Example of Command Line Debugging - 2022.2 English

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

Document ID

UG1393

Release Date

2022-12-07

Version

2022.2 English

To help you get familiar with debugging using the command line flow, this example walks you through building and debugging the hello_world example available from the Xilinx GitHub.

In a terminal, set up your environment as described in Setting Up the Vitis Environment.
If you have not already done it, clone the Vitis Examples GitHub repository to acquire all of the Vitis examples:
```
git clone https://github.com/Xilinx/Vitis_Accel_Examples.git
```
This creates a Vitis_Examples directory which includes the IDCT example.
CD to the IDCT example directory:
```
cd Vitis_Accel_Examples/hello_world/
```
The host code is fully contained in src/host.cpp and the kernel code is part of src/vadd.cpp.
Build the kernel software for software emulation as discussed in Building the Device Binary.
1. Compile the kernel object file for debugging using the v++ compiler, where -g indicates that the code is compiled for debugging:
```
v++ -t sw_emu --platform <DEVICE> -g -c -k vadd \
-o vadd.xo ./src/vadd.cpp
```
2. Link the kernel object file, also specifying -g:
```
v++ -g -l -t sw_emu --platform <DEVICE> -o vadd.xclbin vadd.xo
```
Compile and link the host code for debugging using the GNU compiler chain, g++ as described in Building the Software Application:
Note: For embedded processor target platforms, use the GNU Arm cross-compiler as described in Compiling and Linking for Arm.
1. Compile host code C++ files for debugging using the -g option:
```
g++ -c -I${XILINX_XRT}/include -g -o host.o src/host.cpp 
```
2. Link the object files for debugging using -g:
```
g++ -g -lOpenCL -lpthread -lrt -lstdc++ -L${XILINX_XRT}/lib/ -o host host.o
```
As described in emconfigutil Utility, prepare the emulation environment using the following command:
```
emconfigutil --platform <device>
```
The actual emulation mode (sw_emu or hw_emu) then needs to be set through the XCL_EMULATION_MODE environment variable. In C-shell this would be as follows:
```
setenv XCL_EMULATION_MODE sw_emu
```
As described in xrt.ini File, you must setup the runtime for debug. In the same directory as the compiled host application, create an xrt.ini file with the following content:
```
[Debug]
app_debug=true
```
Run GDB on the host and kernel code. The following steps guide you through the command line debug process which requires three separate command terminals, setup as described in Setting Up the Vitis Environment.
1. In the first terminal, start the XRT debug server, which handles the transactions between the host and kernel code:
```
${XILINX_VITIS}/bin/xrt_server --sdx-url
```
2. In a second terminal, set the emulation mode:
```
setenv XCL_EMULATION_MODE sw_emu
```
  Run GDB by executing the following:
```
xgdb –-args host vadd.xclbin
```
  Enter the following on the gdb prompt:
```
run
```
3. In the third terminal, attach the software emulation model to GDB to allow stepping through the design. Start up another xgdb:
```
xgdb
```
  - For debugging in software emulation:
    - Type the following on the gdb prompt:
```
file <XILINX_VITIS>/data/emulation/unified/cpu_em/generic_pcie/model/genericpciemodel
```
      Note: Because GDB does not expand the environment variable, you must specify the path to the Vitis software platform installation as represented by <XILINX_VITIS>
  - Connect to the kernel process:
```
target remote :NUM
```
    Where NUM is the number returned by the xrt_server as the GDB listener port.
  At this point, debugging the host and kernel code can be done as usual with GDB, with the host code and the kernel code running in two different GDB sessions. This is common when dealing with different processes.
  
  Important: Be aware that the application might hit a breakpoint in one process before the next breakpoint in the other process is hit. In these cases, the debugging session in one terminal appears to hang, while the second terminal is waiting for input.