Migrating Releases

Before migrating to a new target platform, you should also determine if you will need to target the new platform to a different release of the Vitis technology. If you intend to target a new release, Xilinx highly recommends to first target the existing platform using the new software release to confirm there are no changes required, and then migrate to a new target platform.

There are two steps to follow when targeting a new release with an existing platform:

  • Host Code Migration
  • Release Migration
IMPORTANT: Before migrating to a new release, Xilinx recommends that you review the Vitis 2020.1 Software Platform Release Notes.

Host Code Migration

The XILINX_XRT environment variable is used to specify the location of the XRT library environment and must be set before you compile the host code. When the XRT library environment has been installed, the XILINX_XRT environment variable can be set by sourcing the /opt/xilinx/xrt/setup.csh, or /opt/xilinx/xrt/setup.sh file as appropriate. Secondly, ensure that your LD_LIBRARY_PATH variable also points to the XRT library installation area.

To compile and run the host code, source the <INSTALL_DIR>/settings64.csh or <INSTALL_DIR>/settings64.sh file from the Vitis installation.

If you are using the GUI, it will automatically incorporate the new XRT library location and generate the makefile when you build your project.

However, if you are using your own custom makefile, you must use the XILINX_XRT environment variable to set up the XRT library.

  • Include directories are now specified as: -I${XILINX_XRT}/include and -I${XILINX_XRT}/include/CL
  • Library path is now: -L${XILINX_XRT}/lib
  • OpenCL library will be: libxilinxopencl.so, use -lxilinxopencl in your makefile

Release Migration

After migrating the host code, build the code on the existing target platform using the new release of the Vitis technology. Verify that you can run the project in the Vitis unified software platform using the new release, ensure it completes successfully, and meets the timing requirements.

Issues which can occur when using a new release are:

  • Changes to C libraries or library files.
  • Changes to kernel path names.
  • Changes to the HLS pragmas or pragma options embedded in the kernel code.
  • Changes to C/C++/OpenCL compiler support.
  • Changes to the performance of kernels: this might require adjustments to the pragmas in the existing kernel code.

Address these issues using the same techniques you would use during the development of any kernel. At this stage, ensure the throughput performance of the target platform using the new release meets your requirements. If there are changes to the final timing (the maximum clock frequency), you can address these when you have moved to the new target platform. This is covered in Address Timing.