--package Options - 2025.1 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2025-07-08
Version
2025.1 English

Introduction

As described in Packaging for Vitis Flow in the Embedded Design Development Using Vitis (UG1701), the v++ --package, or -p step, generates and packages the final product at the end of the v++ compile and link build process. This is a required step for all embedded platforms, including Versal devices, AI Engine, and AMD Zynq™ UltraScale+™ MPSoC devices.

The syntax of the --package command for Versal platforms is as follows: 
v++ --package -t < hw_emu | hw> --platform <platform> input.xsa \
[ -o output.xclbin --package.<options> ]
Tip: Package command options can be specified in a configuration file for use with the --config option, as discussed in the Vitis Compiler Configuration File.
For non-Versal platforms the syntax for the --package command is: 
v++ --package -t < hw_emu | hw> --platform <platform> input.xclbin \
[ -o output.xclbin --package.<options> ]

The various options to specify as --package.<options> as shown in the syntax above include the following:

--package.aie_debug_port

--package.aie_debug_port <arg>

Where <arg> specifies a TCP port in which the emulator listens for incoming connections from the debugger to debug Versal AI Engine cores. The default port value is 10100.

For example: 

v++ -l --package.aie_debug_port 1440

--package.bl31_elf

--package.bl31_elf <arg>

Where <arg> specifies the absolute or relative path to Arm trusted FW ELF that executes on A72 #0 core. If this option is not specified, then the Vitis compiler searches for the bl31 in the platform.

For example: 

v++ -l --package.bl31_elf ./arm_trusted.elf

--package.boot_mode

--package.boot_mode <arg>
Where <arg> specifies the <ospi | qspi | sd> boot mode used for running the application in emulation or on hardware. For embedded platforms, the default boot mode is SD. Custom platforms boot mode can be configured to use QSPI or OSPI as appropriate.
Tip: The xilinx_vck190_v202410_1 embedded base platform provided by AMD does not support the QSPI option.

For example: 

v++ -l --package.boot_mode sd

--package.defer_aie_run

--package.defer_aie_run

Where this option specifies that the Versal AI Engine cores are enabled by an embedded processor (PS) application. When not specified, the tool generates CDO commands to enable the AI Engine cores during PDI load instead. By default this option is disabled, or FALSE.

For example: 

v++ -l --package.defer_aie_run

--package.domain

--package.domain <arg>

Where <arg> specifies a domain name. If this option is not specified, then the Vitis compiler picks up the default domain from the software platform (SPFM) file. For AI Engine designs, this should always be aiengine.

For example: 

v++ -l --package.domain xrt

--package.dtb

--package.dtb <arg>

Where <arg> specifies the absolute or relative path to device tree binary (DTB) used for loading Linux on the APU. If this options is not specified, then Vitis compiler searches for the dtb in the platform.

For example: 

v++ -l --package.dtb ./device_tree.image

--package.enable_aie_debug

--package.enable_aie_debug

When enabled, the tool generates CDO commands to halt the AI Engine cores during the PDI load, forcing them into debug halt mode. Once debugger connected, the user can debug the AI Engine cores step by step. By default this option is disabled, or FALSE.

For example: 

v++ -l --package.enable_aie_debug

--package.image_format

--package.image_format <arg>

Where <arg> specifies <ext4 | fat32> output image file format used on the SD card. For embedded platforms with a Linux domain, the default image format is ext4. For all others, the image format is fat32.

  • ext4: Linux file system
  • fat32: Windows file system
Important: EXT4 format is not supported on Windows.

For example:

v++ -l --package.image_format fat32

--package.kernel_image

--package.kernel_image <arg>

Where <arg> specifies the absolute or relative path to a Linux kernel image file. Overrides the existing image available in the platform. The platform image file is available for download from xilinx.com. Refer to the Vitis Software Platform Installation in the Vitis Software Platform Release Notes (UG1742) for more information. If this option is not specified, then the Vitis compiler copies the Linux image from the platform to the SD card folder.

For example:

v++ -l --package.kernel_image ./kernel_image

--package.no_image

--package.no_image

Bypass SD card image creation. Valid for --package.boot_mode sd. By default this option is disabled, or FALSE.

--package.out_dir

--package.out_dir <arg>

Where <arg> specifies the absolute or relative path to the output directory of the --package command. The default output directory is the directory from which the Vitis compiler is launched.

For example: 

v++ -l --package.out_dir ./out_dir

--package.ps_debug_port

--package.ps_debug_port <arg>

Where <arg> specifies the TCP port where emulator listens for incoming connections from the debugger to debug PS cores.

For example: 

v++ -l --package.debug_port 3200

--package.ps_elf

--package.ps_elf <arg>

Where <arg> specifies <path_to_elf_file,core>.

  • path_to_elf_file: Specifies the ELF file for the PS core.
  • core: Indicates the PS core it should run on.

Used when a baremetal ELF file is running on a device processor core. This option specifies an ELF file and processor core pair to be included in the boot image. The available processors for supported devices are listed below:

  • Versal processor core values include: a72-0, a72-1, a72-2, and a72-3.
  • Zynq UltraScale+ MPSoC processor core values include: a53-0, a53-1, a53-2, a53-3, r5-0, and r5-1.
  • Zynq 7000 processor core values include: a9-0 and a9-1.
Tip: Specify the option separately for each ELF/Core pair.

For example: 

v++ -l --package.ps_elf a53_0.elf,a53-0 --package.ps_elf r5_0.elf,r5-0

--package.rootfs

--package.rootfs <arg>

Where <arg> specifies the absolute or relative path to a processed Linux root file system file. The platform RootFS file is available for download from Xilinx.com. Refer to the Vitis Software Platform Installation in the Vitis Software Platform Release Notes (UG1742) for more information. If this option is not specified, then the Vitis compiler picks up the default rootfs path from the software platform (SPFM) file.

For example: 

v++ -l --package.rootfs ./rootfs.ext4

--package.sd_dir

--package.sd_dir <arg>

Where <arg> specifies a folder to package into the sd_card directory/image. The contents of the directory are copied to a sub-folder of the sd_card folder.

For example: 

v++ -l --package.sd_dir ./test_data

--package.sd_file

--package.sd_file <arg>

Where <arg> specifies an ELF or other data file to package into the sd_card directory/image. This option can be used repeatedly to specify multiple files to add to the sd_card. The .xclbin and libadf.a files are automatically copied to the out-dir or sd_card folder.

For example: 

v++ -l --package.sd_file ./arm_trusted.elf

--package.uboot

--package.uboot <arg>

Where <arg> specifies a path to U-Boot ELF file which overrides a platform U-Boot. If this option is not specified, then the Vitis compiler searches for the uboot in the platform.

For example:

v++ -l --package.uboot ./uboot.elf