Packaging for DFX Platforms - 2023.2 English

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

Document ID
UG1393
Release Date
2023-12-13
Version
2023.2 English
Vitis Dynamic Function eXchange (DFX) platforms contain a static region and DFX regions.
Static Region
Hardened block that is loaded in system booting and is not reconfigurable at runtime.
DFX region
A reconfigurable partition (RP) that is implemented by the Vivado IP integrator block design container (BDC). This partition can be reprogrammed repeatedly during runtime to dynamically trade out one function, or reconfigurable module (RM), for another.

provides base DFX platforms, such as xilinx_zcu102_base_dfx_202320_1 and xilinx_vck190_base_dfx_202310_1. These are single RP platforms, meaning that it contains a static region and only one DFX region in which RMs can be dynamically exchanged at runtime. In the case of xilinx_vck190_base_dfx_202310_1, the RM contains an AI Engine array and PL kernels. When loading the RM the entire AI Engine array and all PL kernels are loaded at the same time. The following picture shows the block design (BD) of the platform.

Figure 1. Block Design of the Base DFX Platform

The static partition contains the following:

  • CIPS and PS NoC
  • Clock, Reset, Interrupt, and AXI interconnections
  • NoC Interface and DDR memory controller

The reconfigurable module (RM) to load into the DX region of the xilinx_vck190_base_dfx_202310_1 platform contains an AI Engine array and PL kernels that are linked together by the Vitis linker (v++ -l). Refer to Versal Adaptive SoC Hardware, IP, and Platform Development Methodology Guide (UG1387)). The following picture shows an example of the RM.

Figure 2. Block Design of the RM

The RM, with interfaces to the static region, includes:

  • Clock and Reset
  • Inter-NoC Interface (INI) outputs to general memory
  • INI input from PS to control AI Engine
  • AXI Interface from PS to control PL kernels

The contents of the RM can include:

  • AI Engine
  • PL kernels
  • AXI-NoC IP
  • Clock and reset modules
  • AXI Interconnect module
  • ILA
  • FIFO, Data Width Converter (DWC) and CDC modules

The v++ --compile and v++ --link commands are the same for both a DFX platform and a non-DFX platform. However, the v++ --package command is different for the DFX platform than the non-DFX platform, and is different between the hardware and hardware emulation targets as described below.

Hardware Packaging and Deployment

For a hw target the v++ --package command for the DFX platform requires two steps:

  1. The first step generates an xclbin file that contains the RM PDI that will be loaded at runtime.
    v++ -p -t hw -f xilinx_vck190_base_dfx_202310_1 
      --package.defer_aie_run \
      -o rm.xclbin \
      ${XSA} \
      libadf.a
    
  2. The second step packages the RM xclbin file (rm.xclbin) into the SD card that can be read by the host program.
    v++ -p -t hw -f xilinx_vck190_base_dfx_202310_1 
      --package.rootfs ${ROOTFS} 
      --package.kernel_image ${IMAGE} \
      --package.boot_mode=sd \
      --package.image_format=ext4 \
      --package.sd_dir data \
      --package.sd_file ${HOST_EXE} \
      --package.sd_file rm.xclbin
    
When running the hardware, after Linux has started type the following command to load the RM:
cd /run/media/mmcblk0p1
./host.exe rm.xclbin
Note: If the XRT detects that the same XCLBIN has been downloaded already, it will not download the XCLBIN again by default. Instead, it loads metadata from the xclbin file only.

To make sure XCLBIN is downloaded and the device is clean every time, set xrt.ini to enforce XCLBIN download to the device as follows:

  1. Add following configuration to the xrt.ini file:
    [Runtime]
    force_program_xclbin=true
  2. Add the xrt.ini file to the SD card during the package process: --package.sd_file xrt.ini

This ensures the XRT downloads the XCLBIN to device every time.

Hardware Emulation Packaging and Deployment

For hw_emu target the v++ --package command can be:
v++ -p -t hw_emu -f xilinx_vck190_base_dfx_202310_1 \
  --package.defer_aie_run \
  --package.rootfs ${ROOTFS} \
  --package.kernel_image ${IMAGE} \
  --package.boot_mode=sd \
  --package.image_format=ext4 \
  --package.sd_dir data \
  --package.sd_file ${HOST_EXE} \
  --package.sd_file emconfig.json \
  -o rm.xclbin \
  ${XSA} \
  libadf.a

Launch the emulation with the following command:

./launch_hw_emu.sh
Important: In hardware emulation you can load the XCLBIN only once. The RM cannot be reloaded.

In QEMU, following commands can be run:

cd /run/media/mmcblk0p1
export XCL_EMULATION_MODE=hw_emu
./host.exe rm.xclbin

To run multiple RMs on a DFX platform during hardware emulation you must start and stop the emulator, and load each RM .xclbin for a separate test run.