Command Line Project Source Code Debug with the Vitis Unified IDE - Command Line Project Source Code Debug with the Vitis Unified IDE - 2026.1 English - XD100

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

Before starting this tutorial:

• Make sure that you cloned the git repository and the design files are ready to build.

• Make sure that you set the environment variables as described in Introduction.

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

2. To debug the project, 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. Open the workspace in Vitis IDE: {project_path}/cmd_src, and select Set Workspace

4. Right click in the CMD_SRC section in EXPLORER, and select Edit Build Configuration

   Enter the make command to build the system and clean the generated outputs in the Build command and Clean command, respectively.

   Right click in the CMD_SRC section in EXPLORER, and select Build.

   The build step performs the following:

   • 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.

   The following message indicates that the emulation package is created and the build completed successfully.

   COMPLETE: emulation package created.
   Build Finished successfully
   

5. To launch emulation: Right click in the CMD_SRC section in EXPLORER, and select Edit Launch Configurations

   Select the host.exe and a.xclbin paths correctly. Start the Emulator by right-clicking in the CMD_SRC and selecting Start Emulator. Run the script embedded_exec.sh from /mnt as shown below. Check the log to confirm progress.

   

   Test Result: TEST PASSED indicates that launch emulation result. Close the emulation.

6. Steps to debug host.cpp in Vitis IDE:

   a. Start the Emulator as shown in step 5, and wait for emulation to finish.

   b. Click the Debug icon in launch.json. The Vitis IDE enters debug mode as follows and waits in the main function in host.cpp:

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

   

Refer to Debugging the System Project and AI Engine in Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393) for more details to debug AI Engine.