Extensible XSA - 2025.2 English - UG1701

Embedded Design Development Using Vitis User Guide (UG1701)
Document ID
UG1701
Release Date
2025-11-20
Version
2025.2 English

The extensible hardware design (.xsa) is created in Vivado and contains platform interfaces that allow the addition of programmable components such as AI Engine, PL kernels and subsystem features. The extensible .xsa is a container that is used by the Vitis linker command in both the Vitis Integrated Flow, and Vitis Export to Vivado Flow. This XSA file must be generated in Vivado prior to use by the Vitis linker.

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

  1. Export XSA for hardware only: used to export extensible XSA to support hardware flow only.
  2. Export XSA for hardware emulation only: used to export extensible XSA to support hardware emulation flow only.
  3. Export XSA for hardware and hardware emulation: used to export extensible XSAs for both hardware and hardware emulation flows.
Note: For hardware emulation, if you have an IP which does not have a simulation model (does not support hardware emulation), you can remove that IP to create a hardware emulation XSA for the complete project except for that IP. Create another hardware XSA for the Vivado project with that IP, and create an xpfm to merge both XSAs into .xpfm.

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

Important: The block design must have an HDL wrapper and have output targets generated to export the platform XSA. Use the Create HDL Wrapper from the right-click menu in the Sources window to create the wrapper, and Generate Block Design from the Flow Navigator in the Vivado Design Suite.

Export Extensible XSA

  1. Generate the Block Diagram.
    1. Click Generate Block Diagram from the Flow Navigator window.

    2. Select Synthesis Options to Global to save generation time. Click the Generate button.

  2. Export the hardware platform with the following scripts.
    1. Click File > Export > Export Platform. Alternatively, you can select from the Flow Navigator window: IP Integrator > Export Platform, or the Export Platform button at the bottom of the Platform Setup tab.
    2. Click Next from the Export Hardware Platform screen.
    3. Select Hardware. If there are IPs that don't support simulation, the Hardware XSA and Hardware Emulation XSA need to be generated separately. Click Next.
    4. Select Pre-synthesis, as a DFX platform is not being created. Click Next.
    5. Input the name and click Next.
    6. Update the filename and click Next.
    7. Review the summary and click Finish.

You can also perform this in the command line using the following command:

set_property pfm_name {vendor:board:name:version} [get_files <bd_file>]
write_hw_platform -hw -force <XSA file>
Note: The emulation design should match the hardware in most cases. For large and complex designs, it might require decomposition for faster emulation. To ensure emulation equivalence, ensure the two design 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>
Commands can be used to export the XSA file for only the DFX platform.

#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 DFX and BDC hardware design, use the following code.
For DFX design, RP BD should have the PLATFORM.NAME. Static BD should not have this property set.
For BDC design, child BD should have the PLATFORM.NAME. Parent BD should not have this propert set.