Component Based Flow Design Debug - Component Based Flow Design Debug - 2026.1 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2026-06-23
Version
2026.1 English
The following steps illustrate component based flow design debug for hardware emulation.
  1. Start the QEMU emulation environment by selecting the Start Emulator command from the Flow Navigator.

    This action opens the following dialog box.

    Where:

    • Show Waveform: Enables the display of the Live Simulation Waveform view from within the Vivado Logic Simulator during the Emulation run. Allows you to you examine waveforms in real-time. This takes more time and resources to run.
    • Enable Trace: Enables capturing trace data from hardware emulation.
    • QEMU Configuration File: Specifies the QEMU boot configuration file (.qemuboot.conf) for the segmented configuration flow. Use the browse button to select the file. The Vitis Unified IDE passes this value to the launch_emulator utility as -qemu-config.
    • Application Run Script: Specifies the application script and any startup commands to run after QEMU boots. Use the browse button to select the .sh file. The Vitis Unified IDE passes this value to the launch_emulator utility as -run-app.
    • Additional Arguments: Passes additional arguments to the launch_emulator utility from the command line when starting QEMU. You can specify options to pass to the AI Engine simulator that runs the graph application. See AI Engine Simulator Options in AI Engine Tools and Flows User Guide (UG1076)).
    You can specify the options follows:

    -aie-sim-options ../aiesim_options.txt

    • Enable Profile: Enables profiling of the design. See Profiling the Application in the Data Center Acceleration using Vitis (UG1700).
    • Key/Value Pairs: Specifies parameters to use when running the application in the form of the parameter name and value.
    The Vitis Unified IDE recalls the values you last used in this dialog, including for user-managed projects.
  2. Click Start to launch the emulator. You must wait for the QEMU environment to boot the emulation system before starting your application.

    The TASK: EMULATION output terminal shows a transcript of the QEMU launch and boot process. When you see the /mnt# command prompt on the terminal window, the process is complete. From the command prompt, you can type commands in the QEMU environment, and review the transcript of the boot process for details.
    Important: Do not run the emulation from this window. The Vitis Unified IDE manages the application from the Run or Debug command in the Flow Navigator after the emulator has been started.
  3. After the QEMU starts, click Debug from the Flow Navigator. This opens the Debug view in the Vitis Unified IDE and connects to the PS application and AI Engine graph running on their respective cores in the QEMU. The application automatically breaks at the main() function for all the ELF files.

  4. Click Continue ▶ from the Control Panel to start the process.

From this point, you can perform debug activities such as step in, step over, viewing variables and plant break points in the emulation environment. Refer to Using the Debug Environment for more information.