Vitis Export to Vivado Flow Detailed Example - 2025.2 English - UG1701

This section explains the Vitis Export flow as shown in the following diagram. The complete flow (from hardware design creation to exporting .xclbin) has seven steps.

Figure 1. Vitis Export to Vivado Flow

You can execute the flow in the following steps.

1. Start by creating the Versal custom platform design. The Vitis export flow can use either a Flat Hardware Design Platform or a BDC Based Hardware Platform. You can use HLS-based components, or RTL-based packaged IP, or standard IP from the IP catalog in your Vivado design.
   Note: For details on exporting platform from Vivado to Vitis, see Exporting Platforms to Vitis in the Vivado Design Suite User Guide: Designing IP Subsystems Using IP Integrator (UG994) .

   After creating the platform, run synthesis to clean any issues related to hardware realization. Only use the flow for the Versal device platforms. Export the platform into extensible.xsa using following steps:

   1. Click on Export Platform under IP Integrator in the Flow Navigator.

      
      
      

      In Export Platform, select the Presynthesis option to generate the extensible.xsa.

      Tip: If the Export Platform option is disabled, go to Project Settings and select Project is an extensible Vitis Platform.
      
      
      
   2. From the Tcl console, enter the command write_hw_platform -f <filename>.xsato generate the extensible XSA.
2. In the Vitis tool, the exported extensible XSA from Vivado is used to compile the AI Engine graph, HLS kernels and run v++ link to export VMA. The steps are described below:
   • Compiles the AI Engine graph (libadf.a)
   • Compiles PL kernels (.xo)
   • Updates system.cfg file for connectivity
   • Runs v++ linker with the --export_archive option

   In the Vitis Export to Vivado flow, the system linking process occurs as usual, but the automatic launch of Vivado synthesis and place and route is skipped. Instead, the v++ --link --export_archive command is used to generate the Vitis metadata archive (.vma) to export to the Vivado Design Suite.

   v++ --link --export_archive --platform ../<>.xsa --config ../system.cfg \
   <>.xo ./libadf.a -o <vma_file>.vma

   Important: The --export_archive command supports either target=hw (--target hw) only, or without specifying either --target or -t). An error is reported if target = hw_emu is used.
3. Open the Vivado project after generating the .vma file from the Vitis tools. Import the .vma file in the Vivado project with the following Tcl procedure:

   vitis::import_archive ./vma_path/<vma_file>.vma 

   1. A new variant for the dynamic region block design container will be created by cloning the VMA's block design and made active.
   2. Within the dynamic region block design, Vitis content is encapsulated within a level of hierarchy that the user should consider essentially read-only whenever they intend to use XRT after implementing the design in Vivado. See the Vitis Export Flow Guidelines and Limitations section for more details on how to preserve XRT metadata consistency while updating the design in Vivado.
   3. The .vma region can be opened in Vivado. Alternatively, to rerun Vitis flows, you can re-export an extensible XSA after removing Vitis content via vitis::remove_archive_hierarchy.
4. After importing the .vma to the Vivado tools, design modifications can only be completed in Vivado. See the Vitis Export Flow Guidelines and Limitations section for more information.
   1. If there are changes to the .vma file, such as changes to the AI Engine design, PL kernels, or the PLIO boundary, go to Step 5 to regenerate the .xsa file and reiterate through the Vitis Export to Vivado flow.
   2. If the design changes are only related to Vivado, simulate the design, synthesize and implement the design to meet timing, and go to Step 6 for generating the fixed.xsa.
5. If the design requires changes related to the AI Engine, PL kernels, or updates in the PLIO boundary, these changes require updates to the linked system design, and regenerating the .vma in the Vitis tool. Thus, you must first remove the previously imported .vma from the Vivado project using one of two Tcl procedures:
   1. Use the vitis::remove_archive_hierarchy procedure to remove the imported .vma file while preserving any work done to the Vivado project after importing the .vma.
   2. Use the vitis::remove_archiveprocedure to restore the Vivado project to its state prior to importing the .vma file, removing both the .vma and any changes to the project.

   After removing .vma from the Vivado design, you can make any changes to the project. Vitis depends only upon the dynamic region block design and to potential connectivity points declared through PFM APIs. Update system.cfg to update the boundary connections. If there is a need to export the extensible.xsa for the second iteration or later from Vivado, use the vitis::remove_archive command and repeat Step 1 to export the extensible.vma; repeat Step 2 and 3 to export the VMA from Vitis and import VMA to Vivado respectively.

6. Once you have implemented your design, you can generate a fixed.xsa from the Vivado project by using the following command:

   write_hw_platform -fixed ./<fixed_xsa>.xsa

   You can use this XSA to perform application development for PetaLinux / Yocto or XRT-based apps development. You can use it to perform PS-based apps development through Vitis embedded software flow, or baremetal flow as it has been done traditionally.

   You can use the fixed XSA from the preceding command to test the design on the hardware target only. If you want to run hardware emulation, remove the VMA by the vitis::remove_archive command and generate the extensible XSA, then take the extensible XSA through the Vitis flow.

7. After modifying the design, you can test the design on hardware or run hardware emulation. Follow the steps below to generate the fixed XSA for testing the design on hardware and hardware emulation.

   To test the design on hardware, first run synthesis and implementation on the design. Use the command write_hw_platform -fixed ./<path to fixed.xsa> to generate fixed XSA.

   To run hardware emulation, follow the steps below to generate the fixed XSA:

   1. Re-generate the output products
   2. Execute the command launch_simulation -scripts only
   3. Run compile.sh
   4. Run elaborate.sh
   5. Execute the command write_hw_platform -fixed -include_sim_content <path to fixed xsa>
   When you are ready to run the design on the hardware target (-t=hw) or hardware emulation target (-t=hw_emu), run v++ --package to generate the .xclbin. To generate the xclbin for hardware and hardware emulation, use the respective fixed.xsa. Set the t= hw or hw_emu, then provide the required software binaries and files to generate the .xclbin.