--package Options - --package Options - 2026.1 English - UG1702

Introduction

The v++ --package, or -p step, generates and packages the final product at the end of the v++ compile and link build process. Further details are in Packaging with Vitis and EDF in the Embedded Design Development Using Vitis (UG1701). 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}

{Lij: i=1,…,P, any j} specifies libadf.a libraries whose metadata-only entries appear in the .xclbin file for independent control of 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}

Specifies that the package command need to include the aie.pdi file. Vitis uses aie.pdi for the positional argument libadf.a file to merge 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 you can dynamically load AIE 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>

Specify the AI Engine resources binary using the <arg> file.

--package.pl_metadata_only

--package.pl_metadata_only

Specifies that .xclbin file includes only PL metadata. PL hardware context for a loaded image requires the PL metadata. The default behavior is to include full PL configuration data and metadata.

Use Case: Creates a PL metadata-only .xclbin file for establishing a PL hardware context for a loaded image.

Use this option when the PL configuration is already loaded and runtime control requires only metadata.

Example:

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

You can combine this option with --package.aie_metadata_only to create a metadata-only .xclbin for runtime control. The runtime controls 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>

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

For example:

v++ -p --package.aie_debug_port 1440 

--package.bl31_elf

--package.bl31_elf <arg>

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

For example:

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

--package.boot_mode

--package.boot_mode <arg>

For example:

v++ -p --package.boot_mode sd 

--package.defer_aie_run

--package.defer_aie_run

Specifies that an embedded processor (PS) application enables the Versal AI Engine core. When not specified, the tool generates CDO commands to enable the AI Engine cores during PDI load instead. Vitis disables this option by default.

For example:

v++ -p --package.defer_aie_run

--package.domain

--package.domain <arg>

<arg> specifies a domain name. If you do not specify this option, the Vitis compiler picks up the default domain from the software platform (SPFM) file. For AI Engine designs, set to aiengine.

For example:

v++ -p --package.domain xrt

--package.dtb

--package.dtb <arg>

<arg> specifies the absolute or relative path to device tree binary (DTB) used for loading Linux on the APU. If you do not specify this option, the Vitis compiler searches for the dtb in the platform.

For example:

v++ -p --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. Vitis disables this option by default.

For example:

v++ -p --package.enable_aie_debug 

package.generate_sdcard

package.generate_sdcard

For Vitis designs that use PetaLinux to create the system software (SSW) files, this option enables SD card generation features in addition to generating BOOT.BIN, .pdi, and .xclbin files. Device tree files are not generated by v++ -p, but you can supply them as input through the package.dtb option.

When you generate SD card images, you typically specify additional v++ -p options, such as package.uboot and package.kernel_image.

By default, v++ -p assumes that you use Yocto or the Embedded Development Framework (EDF) to create SSW files and SD card images, and it generates the device tree (.dtb, .dtbo), BOOT.BIN, .pdi, and .xclbin files. To update .wic images with files generated by Vitis, use the Yocto wic cp or wic rm commands. Device tree and BOOT.BIN generation is data-driven and uses files contained in the fixed.xsa specified as the platform input to v++ -p, together with design-specific data. The following is an example.

v+ -p --package.generate_sdcard

--package.image_format

--package.image_format <arg>

<arg> specifies <ext4 | fat32> output image file format that the SD card uses. 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++ -p --package.image_format fat32 

--package.kernel_image

--package.kernel_image <arg>

<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 you do not specify this option, the Vitis compiler copies the Linux image from the platform to the SD card folder.

For example:

v++ -p --package.kernel_image ./kernel_image 

--package.no_image

--package.no_image

Bypasses SD card image creation. Valid for --package.boot_mode sd. Vitis disables this option by default.

--package.out_dir

--package.out_dir <arg>

<arg> specifies the absolute or relative path to the output directory of the --package command. The default output directory is the directory where Vitis launches the compiler.

For example:

v++ -p --package.out_dir ./out_dir 

--package.ps_debug_port

--package.ps_debug_port <arg>

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

For example:

v++ -p --package.debug_port 3200 

--package.ps_elf

--package.ps_elf <arg>

<arg> specifies <path_to_elf_file,core>.

• path_to_elf_file: Specifies the ELF file for the PS core.
• core: Specifies the PS core.

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 as follows:

• 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++ -p --package.ps_elf a53_0.elf,a53-0 --package.ps_elf r5_0.elf,r5-0

--package.rootfs

--package.rootfs <arg>

<arg> specifies the absolute or relative path to the processed Linux root 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 you do not specify this option, the Vitis compiler picks up the default rootfs path from the software platform (SPFM) file.

For example:

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

--package.sd_dir

--package.sd_dir <arg>

<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++ -p --package.sd_dir ./test_data 

--package.sd_file

--package.sd_file <arg>

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

For example:

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

--package.uboot

--package.uboot <arg>

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

For example:

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