Packaging for Embedded Platforms - 2023.2 English

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

Document ID
UG1393
Release Date
2023-12-13
Version
2023.2 English

For AMD Zynq™ UltraScale+™ MPSoC and AMD 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 ]
Note: If the output option (-o) is not specified, the tool creates an output file with the default name of a.xclbin.

For Versal devices the v++ --link command creates an .xsa file instead of the .xclbin file. In this case the .xsa must be provided to the package process to generate the .xclbin file. The --package command line for Versal devices is as follows:

v++ --package -t [sw_emu | hw_emu | hw] --platform <platform> input.xsa [ -o output.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, as described in Packaging Versal Designs.

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:

v++ --package --config package.cfg ./aie_graph/libadf.a \
./project.xsa -o aie_graph.xclbin

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 an example configuration file:

platform=xilinx_vck190_base_202310_1
target=hw_emu
save-temps=1

[package]
boot_mode=sd
out_dir=./emulation
enable_aie_debug=1
rootfs=<path_to_platform>/sw/versal/xilinx-versal-common-v2023.1/rootfs.ext4
image_format=ext4
kernel_image=<path_to_platform>/sw/versal/xilinx-versal-common-v2023.1/Image
sd_file=host.exe

For software and hardware emulation, the command takes the .xclbin or .xsa 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 --package.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. The following is an example of the packaging output for hardware emulation:

|-- BOOT_bh.bin	//Boot header
|-- BOOT.BIN			 //Boot File
|-- boot_image.bif
|-- launch_hw_emu.sh	   //Hardware emulation launch script
|-- libadf                  //AIE emulation data folder
|   `-- cfg
|       |-- aie.control.config.json
|       |-- aie.partial.aiecompile_summary
|       |-- aie.shim.solution.aiesol
|       |-- aie.sim.config.txt
|       `-- aie.xpe
|-- plm.bin                 //PLM boot file
|-- pmc_args.txt            //PMC command argument specification file
|-- pmc_cdo.bin             //PMC boot file
|-- qemu_args.txt           //QEMU command argument specification file
|-- sd_card
|   |-- BOOT.BIN
|   |-- boot.scr
|   |-- aie_graph.xclbin
|   |-- host.exe
|   |-- Image
|-- sd_card.img
`-- sim                      //Vivado simulation folder

After creating the sd_card folder for the hardware build, copy the contents to an SD card to create the boot image for your physical device.

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 AMD device.