Packaging the System for Hardware - 2023.1 English

AI Engine Tools and Flows User Guide (UG1076)
Document ID
UG1076
Release Date
2023-06-23
Version
2023.1 English

For both hardware and hardware emulation, the v++ --package command takes the XSA file and libadf.a as input, produces a script to launch hardware emulation (launch_hw_emu.sh), and writes the required support files. An example command line follows:

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 with the following options:

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

The following table explains the options for both hardware and hardware emulation.

Table 1. Hardware and Hardware Emulation Options
Command Line Flag Hardware Hardware Emulation Details
platform Target platform Target platform Either a base platform, or a custom platform that meets AI Engine flow requirements.
target hw hw_emu Specifies the hardware emulation build target. Specifying hw_emu as the target causes a number of files to be generated, including the PDI to boot the device, as well as files required for emulation. Specifying hw only generates the PDI file required to configure and boot the hardware.
save-temps     Causes the Vitis compiler to save intermediate files created during the build and package process.
Package Options
boot_mode 1 sd sd Indicates the device boots from an SD card or from a QSPI image in flash memory. Values can be: sd or qspi.
out-dir <path> <path> Specifies a directory where output files should be created. If out-dir is not specified, the files are written to the current working directory.
kernel_image <path>/Image <path>/Image Specifies the image file that is specified as part of the linking command. The file here should be the same for both targets.
rootfs <path>/rootfs.cpio <path>/rootfs.cpio Specifies the path to the Root FS file that is requires as part of the linking command. The file should be the same for both targets.
enable_aie_debug     Generate debug features for the AI Engine kernels. This can be used in both hardware and emulation builds.
defer_aie_run     The AI Engines will be enabled by the PS application. When unset, generate the CDO commands to enable AI Engines during PDI load instead. Only valid if libadf.a is an input file and the platform is of a Versal platform.
ps_elf <file>,core <file>,core Used only for bare-metal designs. Automatically programs the PS core to run. For example, host.elf, a72-0
domain aiengine aiengine Specifies the domain to be run. For AI Engine designs, this should always be aiengine.
sd_file <file> <file> Copies the ELF for the main application that will run on the Cortex-A72 processor for bare metal, and any files needed to run on Linux. The XCLBIN file is automatically copied to the out-dir or sd_card folder. To have more files copied to the sd_card folder, you must specify this option multiple times.
  1. The xilinx_vck190_v202310_1 platform does not support the qspi option. Custom platforms that are configured to support it will work.

The following table shows the output defined by -out-dir produced when building for both hardware and hardware emulation.

Table 2. Table of Outputs
Build Output
Hardware 
|-- BOOT.BIN
|-- boot_image.bif
|-- sd_card
|   |-- BOOT.BIN
|   |-- boot.scr
|   |-- aie_graph.xclbin
|   |-- host.exe
|   |-- Image
|-- sd_card.img
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

For hardware emulation, the key output file is the launch_hw_emu.sh script used to launch emulation. The sd_card.img image includes the BOOT.BIN (U-Boot to boot Linux, PDI boot data, etc.), Image (kernel image), XCLBIN file, user application (host.exe), and other files. For example, all generated files are placed in a folder called emulation.

To use the sd_card.img file on a Linux host, use the dd command to write the image to the SD card. If you are targeting Linux but with package.image_format=fat32, copy the sd_card folder to an SD card formatted for FAT32. This is not needed for hardware emulation.

Tip: The PS host application is included in the sd_card output, however, it is not incorporated into the rootfs . If you want to include the executable images in rootfs , you must rebuild the rootfs before running the v++ --package command.

If the design needs to be programmed to a local flash memory, make sure --package.boot_mode qspi is used. This allows the use of the program_flash command or the use of the Vitis IDE to program the device or program the flash memory, described in Using the Vitis IDE.