Importing Vitis Metadata Archive to Vivado - 2024.1 English

Flow

The Vitis tools extend a Vivado design through a platform abstraction built upon the IP Integrator data model, where the block design declares available bus interfaces for connections into the base platform. The Vitis tool compiles user C++ kernel and graph code targeting AI Engine and PL through high-level synthesis, and links the compiled objects into the base target platform by creating connections through the IP Integrator.

While the Vitis tool automatically runs Vivado simulation, synthesis, and implementation, and you can prefer to work in the Vivado Design Suite for further design iterations and to achieve timing closure. For example, even when there are no additional design changes needed, Vivado is often better suited for timing closure iterations.

For Versal adaptive SoC designs, the Vitis Export to Vivado flow provides a well-defined interface from Vitis to Vivado that enables iterative workflows between the tools. The hardware platform (.xsa) can be created through the Export Platform flow command in IP integrator, or through the write_hw_platform Tcl proc. An exported .xsa contains a 'dynamic region' block design, in which the Vitis tools will extend the hardware by linking in the PL kernels and AI Engine connections. To enable the Vitis Export to Vivado flow, the dynamic region must be a block design container, , as described in Creating Block Design Containers.

The Vitis v++ --link --export_archive option will link the hardware and export a Vitis Metadata Archive (.vma) that contains the updated block design, an IP repository for added IPs, and design metadata that can be used to support operations including emulation, debug / profiling and Xilinx Runtime (XRT) processing. The .vma file is imported into the original Vivado project using the vitis::import_archive Tcl procedure, which binds the VMA file to the project, adds the IP repository to the project, and adds the updated dynamic region block design as a new active variant of the block design container. Thereafter, the user can continue design work in Vivado.

The hardware design comprising the base platform hardware is often co-developed with the Vitis AI Engine graphs and PL kernels, possibly by different teams. The combination of Vivado Export Platform and Vitis Export to Vivado enables teams to work with loose coupling, sharing system design updates at convenient check points.

See Chapter 19 of Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393) for more details.

In the extensible platform design shown above, the .xsa comes back from the Vitis tools with added PL kernels and AIE graph application in the form of the .vma file. In the .vma file, the RP.bd design has a new variant as shown below.

With the .vma imported into the Vivado project you are free to make modifications to the platform or the block design. However, none of the IP or connections in the Vitis region should be modified or deleted to avoid invalidating bindings to the XRT metadata. You can add constraints to help resolve timing, or otherwise change the original Vivado project. As long as the connections to the BDC do not change, pretty much any change outside the BDC are fair game.

Occasionally you might want to re-export the hardware platform (.xsa) to the Vitis tools and relink the system design. This requires removing the .vma content from the Vivado project prior to exporting the .xsa. There are two Tcl procedures provided to help you do this: vitis::remove_archive_hierarchy, and vitis::remove_archive. The first lets you remove only the .vma hierarchy from the updated Vivado design, thus keeping any changes made because importing the .vma file. The second lets you rest the state of the Vivado project prior to importing the .vma file, thus removing the .vma and all subsequent changes. After this, you can re-export the hardware platform (.xsa), re-link the system design using v++, and reimport an updated .vma into the Vivado project.

When the design is complete, in Vivado, you can generate a fixed hardware platform (fixed.xsa) for the design using the write_hw_platform -fixed command. The fixed hardware platform can be used by the v++ --package command to generate the device binary (.xclbin) for the Versal platform, or used by the Vitis embedded software development flow for application development.