Integrating the System - Integrating the System - 2026.1 English - UG1701

Embedded Design Development Using Vitis User Guide (UG1701)
Document ID
UG1701
Release Date
2026-07-31
Version
2026.1 English

This section describes how to combine the hardware design and the software applications into a complete integrated system. A prerequisite for software application development is the hardware specification, which contains information about the hardware design and its address map. You compile the software applications to binaries, and then package the binaries with the hardware configuration data into device images that also contain boot instructions.

The packaging process consists of two steps:

  1. Use the Vitis packager to generate loadable images from the Vivado hardware design and the AI Engine handoffs, into a binary container. This step also creates a draft BIF file.
  2. Collect the binary containers and software executables, and assemble them into a delivery package that contains the boot-process instructions. The delivery package can be an SD card image, a QSPI flash image, or another similar package type. You can perform this step with either the Vitis packager or Bootgen.

The system integration packaging process uses the file types listed in the following table.

Table 1. System Integration Packaging Process Files
Input File Type Name Description Applicable Devices
XSA Support Archive Primary design handoff archive file from Vivado. The XSA file can be fixed or extensible. Versal adaptive SoC / Zynq / Zynq UltraScale+
BIF Boot Image Format File that Bootgen uses to determine how to generate boot images and how to configure them in a PDI file. Versal adaptive SoC / Zynq / Zynq UltraScale+
PDI Programmable Device Image Output of Bootgen. The image file contains the bootloader, descriptions, and partitions used to process the input data files (ELF, PL configuration, and other binary files). Versal adaptive SoC
XCLBIN XCLBIN Enhanced PDI container with metadata about PL kernels and the AI Engine. XCLBIN is used exclusively for the XRT API on the Linux OS. Versal adaptive SoC / Zynq / Zynq UltraScale+
CDO Configuration data object List of commands that are executed in sequence to configure various components in the system. Versal adaptive SoC
libadf.a AI Engine graph library
  • Output archive: libadf.a is the primary output of compiling an AI Engine graph. It contains the compiled program for the AI Engine, including the CDO and ELF files.
  • CDOs (configuration data objects): Define the setup and configuration of the AI Engine, including its resources and topology.
  • ELFs (Executable and Linkable Format): Contain the program instructions that the AI Engine tile processors execute.
  • Partitions: When enabled, the AI Engine divides the workload into partitions. Each partition targets a subset of the columns of the AI Engine array and generates its own libadf file.
  • libadf files: Contain the compiled program and the configuration for each partition. You must specify all of these files when you package a design that contains partitions.

For details, see Compiling AI Engine Graph for Independent Partitions in the AI Engine Tools and Flows User Guide (UG1076) .

 Versal adaptive SoC
FSBL First stage bootloader Image for the PL bitstream, code, and data that starts the initial design. The FSBL can bring up the entire design or pass on to a second bootloader to finalize the boot. Zynq / Zynq UltraScale+
DTSI Device tree system include Adds user settings that override device tree defaults, such as the MAC address and UART baud rates, on hardware devices. Versal adaptive SoC / Zynq / Zynq UltraScale+
zocl.dtsi Container for data-driven customization Contains the domain description, memory reservation, board DTSI, and user DTSI used to apply device tree overlays for Linux and the XRT drivers. For flat designs and hardware emulation, the container also requires boot artifacts from EDF (prebuilt or custom-built), so that the Vitis packager can call Bootgen to merge the boot PDI, the PL PDI, and, where applicable, the AIE binaries, into a single-stage boot. Versal adaptive SoC / Zynq UltraScale+
qemu_args.txt / pmc_args.txt QEMU command arguments file Command-line arguments used when you launch QEMU, because the DTB for emulation differs from the Linux device tree. Versal adaptive SoC

The packaging process varies depending on the domain you select, because the domain affects the boot order and how the hardware specification is extracted for the host application. The following sections describe these variants.

The first packaging step requires the Vitis packager, and the second step can use either the Vitis packager or Bootgen. Familiarize yourself with the boot components and the way the BIF sets up the boot order, as described in Software Platform. Advanced users can use Bootgen User Guide (UG1283) for details and custom packaging control options. The following sections describe how to use the Vitis packager.

Note: Packaging for hardware emulation requires that you link the design with --target hw_emu.

Packaging Process for Bare-Metal and RTOS Applications

Bare-metal applications interact with the hardware through registers defined in the hardware specification and through low-level drivers. You can also add drivers for frequently used services, such as Ethernet, file handling, and FPGA management, through a board support package (BSP).

The hardware specification is extracted from the fixed XSA. When you create the Vitis platform component for bare-metal or RTOS domains, the tool generates the xparameters.h file. For details about how to add and configure bare-metal and RTOS domains, see Board Support Package Settings Page in the Vitis Unified Software Platform Documentation: Embedded Software Development (UG1400) . If hardware changes affect the hardware specification, you must regenerate the BSP and xparameters.h.

Alternatively, you can use PetaLinux multiconfig tools to regenerate the BSP. See Building multiconfig Applications in the PetaLinux Tools Documentation: Reference Guide (UG1144).

First, generate a loadable PDI and extract the AI Engine CDO with the following command:

v++ -p -s -f <fixed.xsa> <libadf.a> --temp-dir <temp_dir> --save-temps
Important: If you use Bootgen for step 2, you must use the --save-temps option, as shown above, to preserve the files that Bootgen needs.

Next, integrate the hardware and software platform with the Vitis packager:

v++ -p -s -f <fixed.xsa> <libadf.a> --package.generate_sd_card --package.sd_file <pdi, elf, xclbin, etc.> --package.sd_dir <outdir>

For full details about the command-line options for v++, see v++ Command in the Vitis Reference Guide (UG1702).

Packaging Process for Linux Applications

Linux applications can use drivers in two ways: the standard driver approach with the system device tree, or the XRT API.

With the XRT API, drivers that run in user space query address information from the XCLBIN file. When design changes affect hardware specification registers on Vitis-managed components, the XCLBIN file is automatically updated during linking and packaging.

For AMD EDF-based Software Platform, a new data-driven approach regenerates the system device tree drivers for the fixed XSA. This approach enables faster design iterations by reducing the need to rebuild the embedded OS for hardware changes in the Vitis-managed region. The Vitis packager applies the data-driven settings by invoking SDTgen, Lopper, and Bootgen, using the descriptions and overlays from a zipped container currently named zocl.dtsi. For a detailed example of the container contents, see Adding Domain and Custom Overlays When Using a Prebuilt Embedded OS. For practical examples of how the container is used, see the Vitis Tutorials: System Design tutorials.

For the legacy PetaLinux flow, you adjust user-specific settings for the Linux drivers through DTSI. See Device Tree Configuration in the PetaLinux Tools Documentation: Reference Guide (UG1144).

After you set up the device tree and configurations, package the design in the same way as for bare-metal and RTOS applications.

Packaging and Boot Configuration Using Bootgen

After the first packaging step, the AMD Vitis™ packager collects and assembles the binaries and executables required to boot and run a design on AMD SoC devices, using the BIF file. For details about device-specific boot and configuration, see the following user guides:

Packaging Specifics for Versal Designs

The Versal AI Engine compiler generates a library file, libadf.a, which contains ELF and CDO files, along with tool-specific data and metadata, for hardware and hardware emulation flows. To create a loadable image binary, you must combine this data with PL-based configuration data, bootloaders, and other binaries. The Vitis packager performs this function by combining information from libadf.a and the XSA file generated by the Vitis linker.

For Versal adaptive SoCs, the programmable device image (PDI) file boots and programs the hardware device. For hardware emulation, the --package command adds the PDI, the EMULATION_DATA sections, and the XSA file, and outputs an XCLBIN file. For hardware builds, the package process creates an XCLBIN file that contains the ELF files and the graph configuration data objects (CDOs) for the AI Engine application. The XCLBIN file includes the following information:

PDI
Programming information for the AI Engine array.
Debug data
Debug information, when included in the build.
Memory topology
Defines the memory resources and the structure for the target platform.
IP layout
Defines the layout information for the implemented hardware design.
Metadata
Platform metadata that lets the tool load and run the XCLBIN file on the target platform.