Overview

In this article, we will explore a method to migrate embedded applications managed with Xilinx SDK into Vitis. This methodology will utilize the xsct command set for each tool. Between the tools a number of commands have changed so it will be necessary to use a different set of command scripts for each environment. It is assumed that the applications being migrated are managed with a source control system such as git. The migration will be handled via scripts at the command prompt level, avoiding the need to utilize either GUI. Many other methodologies are possible for this effort, this article explores one such method. A mixture of example applications is included to show some variations in the commands needed. The end product of this flow is the set of application ELF files. The bootgen command set has not changed such that new scripts are necessary to combine ELF files into a boot image. As such that process is beyond the scope of this article.


Introduction

The diagram below illustrates the two flows with the upper portion covering Xilinx SDK (i.e. pre 2019.2) flow and the lower portion covering Vitis (i.e. 2019.2 and later). Each flow operates on the same application source repository (but a unique hardware design file). Each uses a set of scripts tailored for the respective toolset and produces a workspace corresponding to the toolset. From the workspace, the ELF files can be obtained (unlikely to be identical between the two flows). 

xilinx-sdk-and-vitis-tool-flows-to-produce-elf-files-from-the-application-source-archive

The application source repository is common to both flows. It is expected that prior to running either flow all the source files are set to the desired version and made available to be read by the scripts or tools. The organization of the repository is detailed below, the basic structure is a folder for each application with each containing that application’s source files, linker script, and MSS file. The MSS file contains the information necessary to generate the BSP.

repo

               <app name> - {FSBL, PMUFW, A53_DDR_Test, R50_app, R51_app}

                              <src> - all the source files for the application

                              lscript.ld – the linker script for the application system.mss – the MSS for the application’s BSP

               hdf – contains the hardware definition file from Vivado for Xilinx SDK

               xsa – contains the hardware definition file from Vivado for Vitis

The set of applications chosen to illustrate this methodology is –

FSBL – A ZynqMP FSBL application, common to most Zynq UltraScale+ MPSoC (ZU+) projects. Illustrates an available template application for the Cortex-A53 which includes reliance on libraries.

PMUFW – The PMU Firmware application for ZU+. Illustrates targeting the PMU.

A53_DDR_Test – An application for exercising the DDR controller in ZU+ from the Cortex-A53. Illustrates a basic application which can be generated from a template.

R50_app – A basic Hello World app using the standalone BSP and running on the Cortex-R5 core 0 in ZU+. Illustrates targeting the RPU.

R51_app – A threaded Hello World app using the FreeRTOS BSP on running on the Cortex-R5 core 1 in ZU+. It illustrates the use of FreeRTOS as the BSP as well as targeting yet another CPU.


Xilinx SDK Methodology

This method is being detailed as the guidance in this article is to organize your SDK related builds in this fashion prior to migrating to into the Vitis tool. The steps for this method are –

1.      Populate the repository (repo) with the current source items (noted earlier)

  • Steps are specific to your chosen archive tools

2.      Generate the XSDK workspace using the xsdk scripts.

  • xsct create_hw_platform.xsdk.tcl
  • xsct create_allappsandbsps_template.xsdk.tcl

3.      For each application replace the generated source files, linker script, and MSS with the files managed in the repo

  • The managed MSS file should overwrite the one in xsdk_workspace/<app>_bsp
  • The managed linker script should overwrite the one in xsdk_workspace/<app>/src
  • The managed application source should overwrite the corresponding source in xsdk_workspace/<app>/src

4.      Build all the applications. xsct build_allappsandbsps.xsdk.tcl

The following scripts are utilized to implement the example in this article for the XSDK method. It is assumed that prior to running xsct the needed tool paths have been setup.

Content of create_hw_platform.xsdk.tcl:

    # set the workspace
setws ../xsdk_workspace
#
# CREATE THE HW PLATFORM FROM THE HDF
#
createhw -name ZCU102_hw -hwspec ../repo/hdf/design_1_wrapper.hdf

Content of create_allappsandbsps_template.xsdk.tcl:

    # set the workspace
setws ../xsdk_workspace
#
# CREATE FSBL FROM TEMPLATE
#
createapp -name FSBL -app {Zynq MP FSBL} -proc psu_cortexa53_0 \
-hwproject ZCU102_hw -os standalone
configapp -app FSBL build-config release
#
# CREATE PMUFW FROM TEMPLATE
#
createapp -name PMUFW -app {ZynqMP PMU Firmware} \
-proc psu_pmu_0 -hwproject ZCU102_hw -os standalone
configapp -app PMUFW build-config release
#
# CREATE A53 DDR TEST APP FROM TEMPLATE
#
createapp -name A53_DDR_Test -app {Zynq MP DRAM tests} \
-proc psu_cortexa53_0 -hwproject ZCU102_hw -os standalone
configapp -app A53_DDR_Test build-config release
#
# CREATE R5-0 BARE METAL HELLO WORLD APP FROM TEMPLATE
#
createapp -name R50_app -app {Hello World} -proc psu_cortexr5_0 \
-hwproject ZCU102_hw -os standalone
configapp -app R50_app build-config release
#
# CREATE R5-1 FREERTOS HELLO WORLD APP FROM TEMPLATE
#
createapp -name R51_app -app {FreeRTOS Hello World} \
-proc psu_cortexr5_1 -hwproject ZCU102_hw -os freertos10_xilinx
configapp -app R51_app build-config release

Content of build_allappsandbsps.xsdk.tcl:

    # set the workspace
setws ../xsdk_workspace
#
# BUILD ALL OF THE APPLICATIONS IN THE WORKSPACE
#
projects -build

Vitis Methodology

Using (nearly) the same repository that was setup for the Xilinx SDK methodology the ELF can be built using Vitis technology. A needed difference in the repository is that it includes an XSA to define the hardware in place of the HDF that Xilinx SDK uses. The steps for this method are –

1.      Populate the repository (repo) with the current source items (noted earlier)

  • Steps are specific to your chosen archive tools

2.      Generate the Vitis workspace using the vitis scripts.

  • xsct create_allappsandbsps_template.vitis.tcl

3.      For each application replace the generated source files, linker script, and MSS with the files managed in the repo

  • The managed MSS file will be brought into the workspace as part of the build script (build_allappsandbsps.vitis.tcl)
  • The managed linker script should overwrite the one in vitis_workspace/<app>/src
  • The managed application source should overwrite the corresponding source in vitis_workspace/<app>/src

4.      Build all the applications.

  • xsct build_allappsandbsps.vitis.tcl

The following scripts are utilized to implement the example in this article for the XSDK method. It is assumed that prior to running xsct the needed tool paths have been setup.

Content of create_allappsandbsps_template.vitis.tcl

    # set the workspace
setws ../vitis_workspace
#
# CREATE FSBL FROM TEMPLATE
#
app create -name FSBL -template {Zynq MP FSBL} -proc psu_cortexa53_0 -hw ../repo/xsa/design_1_wrapper.xsa \
 -os standalone
app config -name FSBL build-config release
platform generate design_1_wrapper
#
# CREATE PMUFW FROM TEMPLATE
#
app create -name PMUFW -template {ZynqMP PMU Firmware} \
-proc psu_pmu_0 -hw ../repo/xsa/design_1_wrapper.xsa \
-os standalone
app config -name PMUFW build-config release
platform generate design_1_wrapper_1
#
# CREATE A53 DDR TEST APP FROM TEMPLATE
#
app create -name A53_DDR_Test -template {Zynq MP DRAM tests} \
-proc psu_cortexa53_0 \
-hw ../repo/xsa/design_1_wrapper.xsa -os standalone
app config -name A53_DDR_Test build-config release
platform generate design_1_wrapper_2
#
# CREATE R5-0 BARE METAL HELLO WORLD APP FROM TEMPLATE
#
app create -name R50_app -template {Hello World} \
-proc psu_cortexr5_0 \
-hw ../repo/xsa/design_1_wrapper.xsa -os standalone
app config -name R50_app build-config release
platform generate design_1_wrapper_3
#
# CREATE R5-1 FREERTOS HELLO WORLD APP FROM TEMPLATE
#
app create -name R51_app -template {FreeRTOS Hello World} \
-proc psu_cortexr5_1 \
-hw ../repo/xsa/design_1_wrapper.xsa -os freertos10_xilinx
app config -name R51_app build-config release
platform generate design_1_wrapper_4

Content of build_allappsandbsps_template.vitis.tcl

    # set the workspace
setws ../vitis_workspace
#
# CREATE FSBL FROM TEMPLATE
#
platform active design_1_wrapper
domain active standalone_domain
domain config -mss ../repo/FSBL/system.mss
platform generate design_1_wrapper
app build -name FSBL
#
# CREATE PMUFW FROM TEMPLATE
#
platform active design_1_wrapper_1
domain active standalone_domain
domain config -mss ../repo/PMUFW/system.mss
platform generate design_1_wrapper_1
app build -name PMUFW
#
# CREATE A53 DDR TEST APP FROM TEMPLATE
#
platform active design_1_wrapper_2
domain active standalone_domain
domain config -mss ../repo/A53_DDR_Test/system.mss
platform generate design_1_wrapper_2
app build -name A53_DDR_Test
#
# CREATE R5-0 BARE METAL HELLO WORLD APP FROM TEMPLATE
#
platform active design_1_wrapper_3
domain active standalone_domain
domain config -mss ../repo/R50_app/system.mss
platform generate design_1_wrapper_3
app build -name R50_app
#
# CREATE R5-1 FREERTOS HELLO WORLD APP FROM TEMPLATE
#
platform active design_1_wrapper_4
domain active freertos10_xilinx_domain
domain config -mss ../repo/R51_app/system.mss
platform generate design_1_wrapper_4
app build -name R51_app

An example archive is included with this article to illustrate both build methodologies. The included items are as followed 

repo – content to be managed for each of the 5 example applications as well as an HDF and XSA for the ZCU102. Each application subfolder contains its MSS and linker script as well as a src folder for the various source files

xsdk_scripts – the scripts cited previously to setup and build the xsdk workspace

xsdk_workspace – an empty folder to use as the xsdk workspace

vitis_scripts – the scripts cited previously to setup and build the vitis workspace

vitis_workspace - an empty folder to use as the vitis workspace


Summary

Though there are many methods to migrate your Xilinx SDK projects into Vitis, utilizing the xsct command set as demonstrated provides a path that is repeatable and supports automated build flows. The command line mechanisms offered by xsct in both Xilinx SDK and Vitis are a solid basis for moving your code from one environment to the next.


About Bruce Karsten

About Bruce Karsten

Bruce Karsten is a Processor Specialist Field Applications Engineer based in the Chicago (IL) area and has advocated for and supported AMD Embedded applications for 15 years. Bruce has aided customers to utilize Microblaze, PowerPC, and ARM CPUs as implemented in device families from Spartan-3 / Virtex2 through Zynq UltraScale+ MPSoC and now moving into Versal.  Bruce is involved in embedded engagements from the early phases of educating on new technology and assisting with architectural decisions through development, board bring up, and integration.  Bruce has enjoyed enabling the adoption of AMD Embedded technology in the gamut of markets AMD plays in which include  Aerospace and Defense, Automotive, Medical, and Wireless.  Outside of work, Bruce turns his attention to photography, waverunning, kayaking, hiking, and attending sporting and concert events with his youngest son (#1 Cubs fan).