Building and Packaging the System - 2023.2 English

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

Document ID
Release Date
2023.2 English

With the elements of the heterogeneous embedded system design available, you are ready to build the system using the Vitis tools. The v++ --link command is a key part of the system build process, as is the v++ --package command. Both of these commands are shown in the figure below, which highlights the different elements of the system, and how they fit together. At the top of the figure are the extensible platform (.xpfm) or hardware .xsa file, the embedded software program (.elf), the PL kernels (.xo), and the AI Engine graph (libadf.a) that are elements of the heterogeneous system. Below those are the linking and packaging commands that build the system.

Figure 1. Building and Packaging the Embedded System Design

System Linking

After the various elements of the embedded system design become available, at least in some initial state, the system can be built using the v++ --link command. The Vitis compiler links the kernel .xo files of the PL kernels and the libadf.a of the AI Engine with the extensible platform (.xpfm) or hardware design (.xsa) in one of two ways:

  • The Vitis integrated flow in which the v++ --link command links the elements of the system, synthesizes the design, builds the placed and routed hardware, and produces a device executable (.xclbin) file for AMD Kria™ SOM, and Zynq MPSoC devices, or a fixed platform (.xsa) for Versal adaptive SoC devices. This integrated flow is required for designs based on standard platforms, such as Alveo Data Center accelerator cards or embedded system platforms such as the vck190_base.
  • The Vitis Export to Vivado flow that uses the v++ --link --export_archive command to create a linked system design and export it to a Vitis MetaData Archive (.vma) file that can be imported into the Vivado Design Suite for further design. The Vitis Export to Vivado flow is only supported for system designs on custom Versal platforms specifically designed to take advantage of this flow.

Both of the flows described above use the Vivado Design Suite for synthesis and implementation of the linked system design. The Vitis integrated flow launches synthesis and place and route automatically as part of the linking process. The Vitis Export to Vivado flow exports the linked system design as a .vma file, letting you import the file into your Vivado project and continue to design and achieve timing closure directly within the Vivado tool.

The Vitis integrated flow is automated as described in Linking the System, though does offer some opportunity for manual intervention. The linking, synthesis, and implementation processes are broken down into a series of major steps, that can be interrupted to enable customization as explained in Working with Vivado in the Vitis Integrated Flow.

The Export to Vivado flow supports a more hands-on approach for experienced RTL designers as described in Vitis Export to Vivado Flow. This is the recommended approach for developers working with custom Versal platforms; using the Vitis tools to develop and link the AI Engine graph application and connect PL kernels, while using the Vivado tools for greater control over the placement, routing, and timing resolution of the system.

Both of these flows lead into the packaging step described next.

Packaging the System

Meanwhile, in the Vitis tools the v++ --package command packages the final product at the end of system design, and configures the boot system for the device. As stated in Packaging the System, the v++ --package command will also generate the device binary (.xclbin) for Versal platform designs.

The package command controls several aspects of the completed system. For example, in the case of AI Engine designs, the --package.defer_aie_run command indicates that the graph application in the libadf.a should not be started at boot time, and should instead wait until called expressly from a software application. The --package.boot_mode indicates that the system is booted from an SD card, or QSPI/OSPI, and the output produced by the package process is generated accordingly. Refer to --package Options for a complete list of options.

Finally, the --package command lets you define the required files for all platforms to boot and run the embedded system design for software or hardware emulation, or to create an SD card to run your system on hardware. For an embedded system design this process is described in Packaging for Embedded Platforms.

Booting and Running the System

When running the application, you can run software emulation, hardware emulation, or run on the actual physical platform. Running the application on embedded processor platforms is different from running on data center accelerator cards. For more information, refer to Running the System on Hardware or Simulating the Application with the Emulation Flow.

  • When the build target is software or hardware emulation, the QEMU environment models the hardware device. The Vitis compiler generates simulation models of the kernels in the device binary and running the application runs in the QEMU model of the system. As described in Working with Build Targets, emulation targets let you build, run, and iterate the design over relatively quick cycles; debugging the application and evaluating performance.
  • When the build target is the hardware system, the target platform is the physical device. The Vitis compiler generates the .xclbin using the Vivado Design Suite to run synthesis and implementation, and resolve timing. Running the application runs your system on the hardware.