Vitis Export to Vivado Flow Detailed Example - Vitis Export to Vivado Flow Detailed Example - 2026.1 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 Vitis region is added to the project and made active by cloning the VMA's block design.
   2. The 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 continue with 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. Generate a RTL wrapper for the top when the edits are completed. By default the wrapper use Verilog as HDL language.
7. Run synthesis and implementation steps in the Vivado project to finalize the design implementation.
8. With the implemented your design, generate a fixed.xsa from the Vivado project by using the following command:

   write_hw_platform -fixed ./<fixed_xsa>.xsa

   The fixed XSA is delivered to the Embedded developer to perform application development for PetaLinux / Yocto, XRT-based, or baremetal applications development.

   You can use the fixed XSA from the preceding command to test the design on the hardware target only.

   Note: Hardware emulation is only possible with Vitis flow. Ensure to update the extensible XSA with any changes done post VMA import, then take the design through the Linking with the Vitis Integrated Flow using the -t hw_emu option. For details on hardware emulation refer to Application Verification Using Vitis Emulation Flow.
9. After modifying the design, you can test the design on hardware. Follow the steps below to generate the fixed XSA for testing the design on hardware.

   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.

   When you are ready to run the design on the hardware target (-t=hw), run v++ --package to generate the .xclbin. To generate the xclbin for hardware, use the fixed.xsa. Set the t= hw, then provide the required software binaries and files to generate the .xclbin.