This section describes how the hardware design and software applications can be combined to form a complete integrated system. A prerequisite for software application development is the information about the hardware design and their corresponding address map, which is the hardware specification. The software applications are compiled to binaries, then packaged together with hardware configuration data into device images, which also contain boot instructions.
The packaging process consists of two steps:
- The first step involves generating loadable images from the Vivado hardware design and AI Engine handoffs into a binary container using Vitis packager. Also, in this step, a draft BIF file is created.
- In the second step, the binary containers and software executables are collected and assembled into a delivery package which contains instructions for the boot process loading. This delivery package can be an SD card, QSPI flash image, or other similar type of package. This second step can be performed either using Vitis packager or Bootgen.
During the system integration packaging process, several different types of files are used as listed in the following table:
| Input File Type | Name | Description | Applicable Devices |
|---|---|---|---|
| XSA | AMD Shell 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 is used by Bootgen to determine how to generate boot images, configure them in a PDI file. | Versal adaptive SoC / Zynq / Zynq UltraScale+ |
| PDI | Programmable Device Image | Output of Bootgen. It is the image file containing bootloader,, descriptions and partitions related to processing input data files (ELF, PL configuration and other binary files). | Versal adaptive SoC |
| XCLBIN | XCLBIN | Enhanced PDI container with metadata on PL kernels and AI Engine. XCLBIN is exclusive to XRT API usage on the Linux OS. | Versal adaptive SoC / Zynq / Zynq UltraScale+ |
| CDO | Configuration data objects | List of commands executed in sequence to configure various components in the system. | Versal adaptive SoC |
| libadf.a | AI Engine graph library |
|
Versal adaptive SoC |
| FSBL | First stage bootloader | Image for PL bitstream, code and data to start the initial design. This can bring up the entire design or pass on to a second bootloader to finalize the boot. | Zynq / Zynq UltraScale+ |
| DTSI | Devicetree system includes | Adding user settings to override devicetree defaults like MAC address, UART baud rates, etc on hardware devices. | Versal adaptive SoC / Zynq / Zynq UltraScale+ |
| qemu_args.txt / pmc_args.txt | QEMU command arguments file | Command line arguments used when launching QEMU as the DTB for emulation differs from Linux device tree. | Versal adaptive SoC |
The package process varies depending on the domain selected, as this has an impact on the boot order and how the hardware specification is extracted for the host application. The following sections discuss these variants.
The first package step require using Vitis package, while the second step can use either Vitis package or Bootgen. It's recommended to be familiar with the boot components and how the BIF setup the boot order described in Software Platform. Advanced users should consider using Bootgen User Guide (UG1283) for details and custom packaging control options. The sections below describe using the Vitis package.
--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 low level drivers. Additionally drivers for frequently used services like ethernet, file handling, FPGA management, etc., can added via BSP (board support package).
The hardware specification is extracted from the fixed XSA, and
when creating the Vitis platform component for bare
metal or RTOS domains, the xparameters.h file is
generated. See
Board Support
Package Settings Page in the
Vitis
Unified Software Platform Documentation: Embedded Software
Development (UG1400)
on how to add and configure Bare-metal and RTOS domains. If changes to hardware
affect the hardware specification, the BSP and xparameters.h needs to be regenerated.
Alternatively, PetaLinux tools for multiconfig can be used to regenerate BSP: Building multiconfig Applications in the PetaLinux Tools Documentation: Reference Guide (UG1144).
First, generate a loadable PDI and extract the AI Engine CDO below.
v++ -p -s -f <fixed.xsa> <libadf.a> --temp-dir <temp_dir> --save-temps--save-temps option
as shown above to preserve the files needed by Bootgen.Next, integrate the hardware and software platform using 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>Full details on command line options for v++ are described in
v++ Command in the
Vitis Reference Guide (UG1702)
.
Packaging Process for Linux Applications
There are two ways that Linux applications can use drivers: the standard driver approach with the system device tree, or the XRT API.
With the XRT API, drivers executed 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.
Refer to Software Platform for system device tree drivers that need to be regenerated using the fixed XSA.
User specific settings to the Linux drivers are adjusted through DTSI, see Device Tree Configuration in the PetaLinux Tools Documentation: Reference Guide (UG1144).
Once the device tree and configurations are set up, packaging is done similar to Bare-metal and RTOS packaging.
Packaging and Boot Configuration using Bootgen
After the first packaging step, the AMD Vitis™ packager collects and assembles the binaries and executables to boot and run a design on AMD SoC devices using the BIF file. Details on device specific boot and configuration are available in the following user guides:
- Versal adaptive SoC: Boot and Configuration
- Zynq UltraScale+ : System Boot and Configuration
- Zynq : Boot and Configuration
Packaging Specifies for Versal Designs
The Versal AI Engine compiler generates output in the form of a library file, libadf.a, which contains ELF and CDO files, as well as tool-specific data and metadata, for hardware and hardware emulation flows. To create a loadable image binary, this data must be combined with PL-based configuration data, boot loaders, and other binaries. The Vitis packager performs this function, combining information from libadf.a and the Vitis linker generated XSA file.
For Versal adaptive SoCs, the
programmable device image (PDI) file is used to boot and program the hardware
device. For hardware emulation the --package
command adds the PDI, EMULATION_DATA sections and the XSA file, and outputs an
XCLBIN file. For hardware builds, the package process creates an XCLBIN file
containing ELF files and 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 structure for the target platform
- IP layout
- Defines layout information for the implemented hardware design
- Metadata
- Various elements of platform meta data to let the tool load and run the XCLBIN file on the target platform