Enabling Hardware Emulation for Extensible XSA - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
UG1393
Release Date
2023-12-13
Version
2023.2 English

The following steps are used for custom platform developers.

  1. Create a Vivado project with the necessary BD, RTL, test bench, and other sources.
    1. Note that in 2020.1, only BD can be used in HW EMU, but starting 2020.2, other sources will also be allowed.
    2. For Versal adaptive SoCs only, test bench needs to include BD wrapper instead of including BD directly, because Vitis does performs jobs on this level to insert NoC into simulation.
    3. For Versal adaptive SoCs only, to enable AI Engine in the Vitis platform, the AI Engine block needs to be configured to have only one slave AXI4 Memory-Mapped port enabled and connected to NoC. Vitis based on AI Engine Graph software will make additional auto-connections during v++ linking stage.
    4. For DFX platforms, specify correct PFM properties in the dynamic region BD so that the Vitis tools can attach accelerators correctly.
  2. Update the design HW Emulation packaging into XSA.
    1. Before packaging the design into XSA, it is important that your design step through the simulator correctly.
    2. For Versal adaptive SoCs only, prepare the platform design to enable SystemC models. Update the CIPS and NoC IP setting to change SELECTED_SIM_MODEL property to TLM. This ensures that for CIPS IP, the design uses QEMU model on which SW can be run. Similarly, for Zynq 7000 and Zynq UltraScale+ MPSoCs, set the SELECTED_SIM_MODEL on the processing system IP instance. Following Tcl command can be used in the design. Also, set the parameter to enable SystemC simulation in Vivado:
      foreach tlmCell [get_bd_cells * -hierarchical -filter {VLNV =~ "*:*:axi_noc:*" || VLNV =~ "*:*:versal_cips:*"}] {set_property SELECTED_SIM_MODEL tlm $tlmCell }
      set_param bd.generateHybridSystemC true
    3. Create a test bench in sim_1 fileset fileset and instantiate the <top> module of your design. For Versal adaptive SoCs, Vivado requires that the user test bench should not instantiate the <top> module directly. Instead, it should instantiate <top>_sim_wrapper module. A file called <top>_sim_wrapper.v is generated when you call the launch_simulation -scripts_only command. The interface of this module is the same as your <top> module, but it instantiates additional simulations models related to an aggregated NoC module created from various logical NoC modules instantiated in the design. Use the following Vivado Tcl commands to generate the necessary NoC simulation file and use them in your simulation sources.
      # Ensure that your top of synthesis module is also set as top for simulation
      
      set_property top <rtl_top> [get_filesets sim_1]
      
      # Generate simulation top for your entire design which would include
      # aggregated NOC in the form of xlnoc.bd
      
      launch_simulation -scripts_only
      update_compile_order -fileset sim_1
      
      # Set the auto-generated <rtl_top>_sim_wrapper as the sim top
      
      set_property top <rtl_top>_sim_wrapper [get_filesets sim_1]
      update_compile_order -fileset sim_1
      
      #Generate the final simulation script which will compile
      # the <syn_top>_sim_wrapper and xlnoc.bd modules also
      launch_simulation -scripts_only
      launch_simulation -step compile
      launch_simulation -step elaborate
    4. Compile the design, go through the above steps, and start simulation. Because the design is configured to use QEMU, the CIPS IP will not generate any transactions because there is no SW present when doing simulation in Vivado simulator. You will see the following ERROR message in the Vivado simulation, but it indicates that the basic design loads correctly in simulator.
      ##############################################################
      #
       #  Simulation does not work as Versal CIPS Emulation (SELECTED_SIM_MODLE=tlm) only works with Vitis tool(launch_emulator.py tool in Vitis)
      #
      ##############################################################
       
      ERROR: [Simtcl 6-50] Simulation engine failed to start: The Simulation shut down unexpectedly during initialization.
      Note: To confirm that the design will have correct transactions, you can optionally perform a simulation of the design using the CIPS VIP first before changing it to use TLM (QEMU). First, you must keep the SELECTED_SIM_MODEL property to be RTL for NoC and CIPS IP. Also, create a different test bench which drives the CIPS VIP and also meet the requirement of the NoC Verilog model. Refer to the CIPS VIP and NoC IP documentation for additional details on how to set up test bench for Verilog-based simulation.
  3. Package the HW Emulation only XSA.
    Important: The source files for all elements of the Vivado project must be local to the project prior to exporting it as an XSA, or an error can be returned when using the platform in the Vitis tool.
    1. Use Vivado File > Export > Export Platform to export a Hardware Emulation platform or use the following Tcl command:
      set_property platform.platform_state "pre_synth" [current_project]
      write_hw_platform -hw_emu -file  platform_hw_emu.xsa
    2. This XSA can be used with pre-built Linux images or with PetaLinux to create a custom Linux image to create a full platform. Then, the remainder of the Vitis tools can be used to add a kernel to design with the XRT.