Command Line Project Source Code Debug with the Vitis IDE - 2023.1 English

This section uses the command line flow to build for hardware emulation.

Before starting this tutorial:

• It is expected that you cloned the git repository, and the design files are ready to build.

• It is expected that you have run the steps to set the environment variables as described in Introduction.

1. Navigate to the tutorial directory, cmd_src/, and open the Makefile.

2. To be able to debug the project, it is required to add the --pakcage.enable_aie_debug option in the packaging step as follows:

   package: guard-PLATFORM_REPO_PATHS guard-IMAGE guard-ROOTFS
       cd ./sw
       v++ -p -t ${TARGET} \
           -f ${BASE_PLATFORM} \
           --package.rootfs=${ROOTFS} \
           --package.image_format=ext4 \
           --package.boot_mode=sd \
           --package.kernel_image=${IMAGE} \
           --package.defer_aie_run \
           --package.sd_file embedded_exec.sh --package.enable_aie_debug \
           --package.sd_file host.exe ../tutorial.xsa ../libadf.a
   

3. Do make all TARGET=hw_emu.

   This step:

   • Compiles the AI Engine kernels and generates libadf.a.

   • Compiles the PL kernels s2mm,mm2s and generates .xo.

   • Hardware linking step to link AI Engine kernels and PL kernels using the system.cfg file. This generates the .xsa file.

   • Compiles the host application and generates the executable file host.exe.<

   • Packages libadf.a,.xsa, and host.exe files.

4. To debug the source code in the Vitis IDE, you need three Linux terminals.

5. From Terminal 1, set the tool path properly, and issue the command to launch the hardware emulator and boot up PetaLinux:

   ./launch_hw_emu.sh -add-env ENABLE_RDWR_DEBUG=true -add-env RDWR_DEBUG_PORT=10100 -pid-file emulation.pid -no-reboot -forward-port 1440 1534
   

   Command Option Explanation

   • -add-env RDWR_DEBUG_PORT=${aie_mem_sock_port}: Defines the port for communicating with the AI Engine domain. In the previous example, it is 10100.

   • -forward-port ${linux_tcf_agent_port} 1534: Defines the port for the Linux TCF agent. In the previous example, it is 1440, which is the default.

   NOTE:

   • launch_hw_emu.sh is generated properly when the project under debug is built and packaged with the hardware emulator correctly.

   • The previous command takes a few minutes to complete due to both the hardware emulator and PetaLinux are required to boot up properly.

   • Wait until both the hardware server and PetaLinux boot up BEFORE moving to the next steps.

6. From Terminal 2, set up the tool path properly, and issue the following command to launch the XRT server:

   xrt_server -I30000 -S -s tcp::4352
   

   Command Line Options Explanation:

   • -I30000: Defines an idle timeout in seconds, in which the server will quit if there is no response.

   • -S: Specifies the print server properties in JSON format to stdout.

   • -s tcp::${xrt_server_port}: Defines the agent listening protocol and port. It is 4352 in the example but can be any free port.

7. From Terminal 3, navigate to the sw/ directory where the host.exe and a.xclbin got generated, and issue the following command to launch the Vitis IDE after setting the tool path properly:

   vitis -debug -flow embedded_accel -target hw_emu -exe ./host.exe -program-args a.xclbin -port 1440
   

   Command Line Options Explanation

   • vitis -debug: Launches the Vitis IDE in standalone debug mode.

   • -flow embedded_accel: Specifies the embedded processor application acceleration flow.

   • -target hw_emu: Indicates the target build being debugged.

   • -exe ./host.exe: Indicates the PS application to run and debug.

   • -program-args a.xclbin: Refers to the location of the xclbin file to be loaded as an argument to the executable.

   • -port 1440: Specifies the ${linux_tcf_agent_port} as discussed previously.

8. The above command invokes the Vitis IDE in debug mode as follows waiting in the main function in host.cpp:

9. Open the debug configurations as follows:

   • Create a new Debug configuration by double-clicking the Single Application Debug.

   • Add the Debug type name, aie_application_debug, and Debug Type as Attach to running target.

     

   • Create a new target connection with the Target Name, Host, and Port details as follows, and hit OK:

   • Now, again in the Debug Configurations window, set up the execute script.(aie_app_debug_em.tcl. Check the following NOTE) for the newly created debug type by clicking the Browse button as highlighted above.

     NOTE: The script, aie_app_debug_em.tcl, is provided in this tutorial (under the HW_Emulation/directory) and needs to be updated to match your environment settings. For example, the ${PROJECT_PATH} variable should be the Work/ folder inside this lab, and similarly the ${XILINX_VITIS_PATH}/ variable should be pointing to your Vitis installation path.

10. Click Debug in the Debug Configurations window, wait for the aie_application_debug(xrt_server) to load in stack trace, and click the Continue/Resume button to run the <Process ID>host.exe (Suspended) thread.

11. This executes the host code before the AI Engine graph execution and waits at the automatic breakpoint in the AI Engine core main() function as follows:

    You can try adding add breakpoints in the host code and observe the values in the Variable window by doing step-in or step-over.

    

12. Click each AI Engine core and do Step-over to enter the compiler-generated AI Engine source code which in turn calls the actual user source code.