Extensible XSA - Extensible XSA - 2026.1 English - UG1701

Embedded Design Development Using Vitis User Guide (UG1701)
Document ID
UG1701
Release Date
2026-07-31
Version
2026.1 English

Vivado creates the extensible hardware design (.xsa). The .xsa contains platform interfaces that let you add AI Engine components, PL kernels, and subsystem features. The extensible .xsa acts as a container, and the Vitis linker uses it in the Vitis Integrated Flow and Vitis Export to Vivado Flow. You must generate the .xsa in Vivado before the Vitis linker uses it.

The Export Hardware Platform wizard in Vivado supports three types of extensible hardware designs:

  1. Export XSA for hardware only. Use this option to export an extensible XSA that supports the hardware flow only.
  2. Export XSA for hardware emulation only. Use this option to export an extensible XSA that supports the hardware emulation flow only.
  3. Export XSA for hardware and hardware emulation. Use this option to export extensible XSAs that support both the hardware and hardware emulation flows.
Note:

For hardware emulation, some IPs lack simulation models and do not support hardware emulation. You can remove the unsupported IP from the design to create a hardware emulation XSA for the remaining project logic. Then create another hardware XSA for the Vivado project that contains that IP, and create an .xpfm to merge both XSAs into a single .xpfm.

When you set the Vivado project type to Extensible Vitis platform, the Export Platform wizard is available from the File > Export > Export Platform menu.

Important: The block design must have an HDL wrapper, and output targets must be generated, before you can export the platform XSA. To create the wrapper, use Create HDL Wrapper from the right-click menu in the Sources window. The wrapper uses Verilog as the default HDL language. Then run Generate Block Design from the Flow Navigator in the Vivado Design Suite.

Adding Domain and Custom Overlays When Using a Prebuilt Embedded OS

To enable fast hardware development iterations while reusing a prebuilt embedded OS, you must apply device tree overlays and memory reservations during Vitis packaging. In addition, flat designs and hardware emulation require you to adapt the boot artifacts to the hardware updates. To achieve this, pass the boot artifacts, the domain description with memory reservations, and the user DTSI through the extensible XSA, and later through the fixed implemented XSA.

Add these files to a zip container named zocl.dtsi, and then add the container as an unspecified file in the Vivado project. The container must currently be organized as in the following VCK190 example:

# top folder
domain.yaml
zocl-template.dtsi
versal-vck190-reva.dtsi

# Include folder
include/versal-vmk180-reva.dtsi
include/gpio/gpio.h

# boot.bin-extracted folder from prebuilt Linux
boot.bin-extracted/cortexa72-linux.dtb
boot.bin-extracted/psmfw.elf
boot.bin-extracted/BOOT_bh.bin
boot.bin-extracted/bootbin-version-string-my-vck190-versal.txt
boot.bin-extracted/bootbin-rollback-counter-my-vck190-versal.bin
boot.bin-extracted/u-boot.elf
boot.bin-extracted/arm-trusted-firmware.elf
boot.bin-extracted/base-design.pdi
boot.bin-extracted/plmfw.elf
boot.bin-extracted/bootgen.bif
boot.bin-extracted/xilinx-bootbin-aggregate.manifest.json
boot.bin-extracted/cortexa72-linux.dtb.bak
boot.bin-extracted/base-design.pdi.bak

You can obtain boot.bin-extracted from AMD-provided prebuilt EDF boot artifacts, or from custom-built boot artifacts generated using EDF recipes.

Important: The top folder must contain only one each of domain.yaml, zocl-template.dtsi, and <board>.dtsi. Place any additional files in the include folder, and update the referring paths accordingly.

Add the zip file (renamed to zocl.dtsi) to the Vivado extensible project with the following command:

import_files -norecurse zocl.dtsi

This file is automatically carried over to the Vitis packager through the XSA, and is used to create overlays and boot artifacts for flat designs and hardware emulation. For segmented configuration designs, the boot artifacts are needed only for hardware emulation, because the first segment boots the operating system and the secondary segments load the PL and AIE. For more details about packaging, see Integrating the System.

Exporting an Extensible XSA

  1. Generate the block diagram:
    1. Click Generate Block Diagram from the Flow Navigator window.

    2. Set Synthesis Options to Global to save generation time, and then click Generate.

  2. Export the hardware platform:
    1. Click File > Export > Export Platform. Alternatively, in the Flow Navigator window, select IP Integrator > Export Platform, or click Export Platform at the bottom of the Platform Setup tab.
    2. Click Next on the Export Hardware Platform screen.
    3. Select Hardware. If some IPs do not support simulation, you must generate the Hardware XSA and the Hardware Emulation XSA separately. Click Next.
    4. Select Pre-synthesis, because you are not creating a DFX platform. Click Next.
    5. Enter the name and click Next.
    6. Update the file name and click Next.
    7. Review the summary and click Finish.

You can also export the platform from the command line, using the following commands:

set_property pfm_name {vendor:board:name:version} [get_files <bd_file>]
write_hw_platform -hw -force <XSA_file>
Note: In most cases, the emulation design should match the hardware. Large and complex designs might require decomposition for faster emulation. To ensure emulation equivalence, make sure the two designs are logically identical.

To create and combine a hardware XSA and a hardware emulation XSA, use the following commands:

write_hw_platform -hw <hw_platform>
write_hw_platform -hw_emu <hw_emu_platform>
combine_hw_platform -hw <hw_platform> -hw_emu <hw_emu_platform> -o <combined_platform>

You can also use commands to export the XSA file for the DFX platform only:

# Emulation XSA
set_property platform.platform_state "pre_synth" [current_project]
write_hw_platform -hw_emu -force -file vck190_custom_dfx_hw_emu.xsa

# Hardware and RP XSA
set_property platform.platform_state "impl" [current_project]
write_hw_platform -force -fixed -static -file vck190_custom_dfx_static.xsa
write_hw_platform -force -rp design_1_i/VitisRegion vck190_custom_dfx_rp.xsa
Note:

To export the XSA from a DFX or BDC hardware design, follow these rules:

  • For a DFX design, the RP BD must have the PLATFORM.NAME property set, and the static BD must not have it set.
  • For a BDC design, the child BD must have the PLATFORM.NAME property set, and the parent BD must not have it set.