Packaging for Embedded Platforms - 2022.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)
Document ID
UG1393
Release Date
2022-12-07
Version
2022.2 English
For Zynq® UltraScale+™ MPSoC and Zynq®-7000 embedded platforms, the --package command line is shown below: 
v++ --package -t [sw_emu | hw_emu | hw] --platform <platform> input.xclbin [ -o output.xclbin ]
For Versal® platforms, the --package command line is as follows: 
v++ --package -t [sw_emu | hw_emu | hw] --platform <platform> input.xsa [ -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 Versal® platforms, the package process takes the .xsa file generated during the v++ --link command, and 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 AI Engine Tools and Flows 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-v2022.2/rootfs.ext4
sd_file=/tmp/platforms/sw/zynqmp/xilinx-zynqmp-common-v2022.2/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