Packaging the System

After compiling and linking your kernel code to build the .xclbin, you need to package the device binary, along with any required supporting files, to build a package that can be run for software or hardware emulation, or can be booted and run on the hardware device. The v++ --package step, or -p, packages the final product at the end of the v++ compile and link process. This is a required step for all Versal™ platforms, including AI Engine platforms, and embedded processor platforms.

As described in --package Options, this command lets you package your design and define various files required for booting and configuring the Xilinx® device for use during emulation or in production systems. It collects the various elements to create an SD card, or other means to program the device, to define the operating system, and to load the application and kernel code.

Packaging for Embedded Platforms

For embedded platforms, the --package command supports a variety of tool flows and platforms, including Versal, AI Engine, and Zynq® devices. The command line is shown below:

v++ --package -t [sw_emu | hw_emu | hw] --platform <platform> input.xclbin [ -o output.xclbin ]

Note: If the output option (-o) is not specified, the tool creates an output file with the default name of a.xclbin.

In the case of AI Engine platforms, the package process also takes the libadf.a file produced by the aiecompiler command and integrates it into the output device binary. For more information, refer to the Versal ACAP AI Engine Programming Environment User Guide (UG1076).

The --package command has a range of options for use with the different platforms and build targets supported by the Vitis tools. In the Vitis IDE, the package process is automated and the tool creates the required files as needed. However, in the command line flow, you must specify the v++ --package command or add the [package] tag in the config file with the right options for the job. The following is an example command for hardware emulation that runs the package process for a ZCU104 based application:

v++ --package -t hw_emu --platform xilinx_zcu104_base_202010_1 --save-temps \
./input.xclbin ./output.xclbin --config package.cfg

Where, the --config package.cfg option specifies a configuration file for the Vitis compiler with the various options specified for the package process. The following is the content of an example configuration file:

[package]
out_dir=sd_card
boot_mode=sd
image_format=ext4
rootfs=/tmp/platforms/sw/zynqmp/xilinx-zynqmp-common-v2020.1/rootfs.ext4
sd_file=/tmp/platforms/sw/zynqmp/xilinx-zynqmp-common-v2020.1/Image
sd_file=host.elf
sd_file=output.xclbin
sd_file=xrt.ini
sd_file=launch_app.sh

For software and hardware emulation, the command takes the .xclbin file as input, produces a script to launch emulation (launch_sw_emu.sh or launch_hw_emu.sh), and writes needed support files to a specified output folder, --package.out_dir.

Additional files required for running the application, such as data files needed as input or to validate the application, or the xrt.ini file for profiling and debug, must be included in the output files, and can be transferred individually using the sd_file option, or transferred as a directory using the sd_dir option as explained in --package Options.

For hardware builds, the --package command creates an sd_card folder, or the QSPI.img depending on the boot mode specified with the --package.boot_mode option.

TIP: For bare metal ELF files running on PS cores, you should also add the following option to the command line:

--package.ps_elf <elf>,<core>

The package command creates an output folder called sd_card, that contains all of the files needed to run hardware emulation for the application, modeling the boot process of an sd_card. For hardware builds, it contains the files required for creating an SD card to boot the device.

After creating the sd_card folder, copy the contents to an SD card to create the boot image.

Note: On Windows OS you must use a third-party tool, such as Etcher, to write on the SD card for use in booting the Xilinx device.

After the package process completes you can use the Vitis analyzer tool to visualize and navigate the relevant reports or log files by running the following command:

vitis_analyzer ./<output>.package_summary

Packaging for Data Center Platforms

TIP: The --package command is not required for Data Center accelerator cards.

The --package command essentially copies the device binary (.xclbin) to produce the output .xclbin. The command line is shown below:

v++ --package -t [sw_emu | hw_emu | hw] --platform <platform> input.xclbin [ -o output.xclbin ]

If the output option (-o) is not specified, the tool creates an output file with the default name of a.xclbin.

After the package process completes, you can use the Vitis analyzer tool to visualize and navigate the relevant reports or log files by running the following command:

vitis_analyzer ./<output>.package_summary