Flow Details and Implementation - 2023.2 English

This section explains the Vitis Export flow as shown in the following diagram. The complete flow (from hardware design creation to export .xclbin) is divided into 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 requires block-design container (BDC) designs as described in Generate XSA file, and does not support flat designs. You can use HLS-based components, or RTL-based packaged IP, or standard IP from the IP catalog in your Vivado design.

   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>.xsa
2. In the Vitis tool, the exported .xsa becomes the platform of choice, and the system design is completed.
   • Compile the AI Engine graph (libadf.a)
   • Compile PL kernels (.xo)
   • Update system.cfg file for connectivity
   • Run v++ linker with --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 cannot be used with the --target (or -t) command. An error is returned.
3. Open the Vivado project after generating the .vma file from the Vitis tools. Import the .vma file in the Vivado project, or new 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 be done in Vivado only. 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 to 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 related to Vivado only, 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

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

   The fixed XSA generated from the preceding command can be used to test the design on the hardware target only. If you want to run hardware emulation, generate the XSA using the following command instead:

   write_hw_platform -fixed -include_sim_content ./<fixed_xsa>.xsa

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.

Guidelines for Revision Control

It is recommended to revision control the project sources while developing the design using the Vitis and Vivado tools. In this flow, a number of design iterations are required for the hardware design development. You can adopt revision control mechanism according to your standards. The following files are recommended for revision control:

• C++ source files
• AI Engine graphs (.libadf)
• Config files
• Tcl scripts
• *.vma
• *.xsa