Building and Running the System Project - 2024.1 English

Vitis Tutorials: Getting Started

Document ID
Release Date
2024.1 English

With the System Project as the active element in the Flow Navigator, you can see there are three different build targets as described below:

  • Software Emulation: The kernel code and host application are compiled to run on the X86 processor rather than the embedded processor of the platform. The new Vitis unified IDE uses the PS on X86 emulation flow as previously discussed. The software emulation target allows quick iterative algorithm refinement through fast build-and-run loops. This target is useful for identifying syntax errors, performing source-level debugging of the kernel code running together with application, and verifying the behavior of the system.

  • Hardware Emulation: The kernel code is compiled into a hardware model (RTL), which is run in the Vivado logic simulator. The host application runs on an emulation environment (QEMU) version of the embedded processor. This build-and-run loop takes longer but provides a detailed, cycle-accurate view of kernel activity. This target is useful for testing the functionality of the logic that will go into the Programmable Logic (PL) region of the device and getting initial performance estimates.

  • Hardware: The kernel code is compiled into a hardware model (RTL) and then implemented on the device, resulting in a binary that will run on the actual hardware. In the Embedded Processor platform, the host application, xclbin, and required support files are written to an SD card (for instance) and then used to boot and configure the system.

Here, you will walk through the Hardware Emulation build as an exercise in building and running the system.

  1. From the Flow Navigator, select the Build All command under the Hardware Emulation header.

TIP: You can run the Build All command as two separate commands to Build Binary Container and Build Package. This could be useful when debugging build errors.

The tool will alert you if some components have not been built, and ask if you like to build them. Enable the checkbox for any components that have not been built, or select them all if you prefer. After the build is complete you can review the Reports under the Link and Package headings. The reports offer a summary view as well as additional details of the build process.

After building, you will need to create a launch configuration for the Run or Debug commands.

  1. From the Vitis Components Explorer open the launch.json under the Settings folder of the System Project.

  2. Create a Hardware Emulation launch config by clicking on the + New Launch Configuration command, and select Hardware Emulation as the type.

Unified IDE - Launch Config

This will create a new launch configuration with the default name of System_project_hw_emu_new. You might need to setup the arguments for the launch configuration as described in Launching Run or Debug of the System Project. You can rename the launch configuration by using the Edit command link next to the Launch config name field. Use the Append XCLBINs which will copy ./vadd.xclbin to the Cmd line args field. You can specify other command line arguments as required by your application.

  1. In the Flow Navigator click Start Emulator to configure and run the QEMU environment for the specified platform.

TIP: Wait until the QEMU environment prompt shows up before starting the Run command. You should see something similar to zynqmp-common-20231:/mnt# in the Output window before proceeding.

  1. With the Emulator running, click Run under HARDWARE EMULATION header to start the system project running in the QEMU environment. You can alternatively select Debug to use the QEMU environment to debug the System project.

You will see a result like the following screen when the emulation run has finished.

Unified IDE - HW-EMU

After running or debugging the system you will need to stop the emulator by hovering your mouse over the Start Emulator command in the Flow Navigator and clicking the X.