--package Options - 2025.2 English - UG1702

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.

v++ --package --platform fixed.xsa -o output.xclbin --package.<other options>

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_metadata_only

--package.aie_metadata_only {Lij: i=1,...,P, any j}

Where {Lij: i=1,...,P, any j} specifies the libadf.a library files for AIE partitions to include metadata only in the .xclbin file for independent control against a loaded image. The Lij represents libraries. The index i represents the ith partition and j can be any value. The default behavior is to include full AIE partition data and metadata.

Additional Outputs:

• aie.pdi
• aie.bif

Use Case: Creates a metadata-only .xclbin file for independent control against a loaded image. This allows runtime control of AIE partitions without including the full partition data in the .xclbin file.

Example:

v++ -p -f fixed.xsa --package.aie_metadata_only {Lij: i=1,...,P, any j} -o aie-meta.xclbin

--package.aie_overlay

--package.aie_overlay {Lij}

Where this option specifies that the package command should include the aie.pdi file for merged positional argument libadf.a files and set the LOAD_PDI action mask. The {Lij} must represent adjacent partitions. The default behavior is to not create an AIE overlay.

Additional Outputs:

• aie.pdi - Includes the PDI file for merged positional argument libadf.a files
• aie.bif - Boot Image Format file

Important: The Lij libraries must represent adjacent partitions for this option to work correctly.

Use Case: Enables AIE overlay functionality, allowing users to load a pl.xclbin and then load/reload any number of aie.xclbin overlays. This is particularly useful in DFX designs where AIE overlays can be dynamically loaded on top of a PL-only image.

Example:

v++ -p -f fixed.xsa {Lij} --package.aie_overlay -o aie.xclbin

--package.aie_resources_bin

--package.aie_resources_bin <arg>

Where <arg> specifies the AIE resources binary file.

--package.pl_metadata_only

--package.pl_metadata_only

Where this option specifies that only PL metadata should be included in the .xclbin file, required for PL hardware context for a loaded image. The default behavior is to include full PL configuration data and metadata.

Use Case: Creates a PL metadata-only .xclbin file that is required for establishing a PL hardware context for a loaded image. This is useful when the PL configuration has already been loaded and only the metadata is needed for runtime control.

Example:

v++ -p -f fixed.xsa --package.pl_metadata_only -o pl-meta.xclbin

Combined Use: This option can be combined with --package.aie_metadata_only to create a metadata-only .xclbin for runtime control of both PL and AIE components of a loaded image:

v++ -p --package.pl_metadata_only --package.aie_metadata_only {Lij: i=1,...,P, any j} -o pl_aie-metadata.xclbin

--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>

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

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.

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