Creating SDSoC Platforms

TheSDx™IDE is used to assemble the hardware and software components into anSDSoC™platform. The design flow for generating a platform is shown below and is utilized in the platform creation example that follows.

Figure:Platform Generation Design Flow

In creating an SDx platform project, developers select settings for the platform, the system configurations, and the domains. Platforms can contain multiple system configurations and domains as iterated and defined through the SDx IDE. Platform settings for prebuilt data allow inclusion of a hardware bitstream or its automatic generation to save on hardware build time when creating software solutions that do not require or create hardware accelerators. System configuration settings are available to either generate the needed platform software components or reference prebuilt software components. The type of software component Exectuable and Linkable Format (ELF) files, Boot Image Format (BIF) files, and Flattened Image Tree (FIT) image files are listed below. Domain settings provide choices for processor selection, operating system, and the runtime environment.

  • Zynq® UltraScale+™ MPSoC
    • FSBL (ELF)
    • PMU (ELF)
    • BL31 (ELF)
    • U-BOOT (ELF) - for Linux target
    • LINUX image.ub (FIT) - for Linux target
    • BOOT file components (BIF)
  • Zynq®-7000 SoC
    • FSBL (ELF)
    • U-BOOT (ELF) - for Linux target
    • LINUX image.ub (FIT) - for Linux target
    • BOOT file components (BIF)

Once generated, the file system layout of an SDSoC platform is structured as shown in the following figure.

Figure:Directory Structure for a TypicalSDSoCPlatform

In general, only the platform provider can ensure that a platform is “correct” for use within theSDSoCenvironment. However, the folder/samples/platforms/Conformancecontains basic tests you should run, with instructions describing how to run them. These tests should build cleanly, and should be tested on the hardware platform.

Note: signifies the location where the SDx tools are installed, including the released version: = /SDx/< version>.

A platform should provide tests for every custom interface so that users have examples of how to access these interfaces from application C/C++ code.

A platform may optionally include sample applications. By creating asamplessub-folder containing source files and adescription.jsonfile for each application, users can use theSDxIDE New Project wizard to select and build any of the provided sample applications. For additional information on application template creation, seeSample Applications.

To create a platform using the SDxIDE, you can launch the application and select the Platform Project type.
IMPORTANT:Before creating the platform project, you must have the DSA hardware definition as described in Creating the Platform Hardware Component, and the software files as described in Creating the Platform Software Component, available for use in defining the SDSoCplatform.

Using an SDx Workspace

IMPORTANT:Linux host is strongly recommended for SDSoC™platform development, and required for creating a platform supporting a target Linux OS.
  1. Launch theSDx™IDE directly from the desktop icon or from the command line by one of the following methods:
    • Using either of the following commands from the command prompt:

      sdx

      or

      sdx -workspace

    • Double-clicking theSDxicon to start the program.
    • Launching from theStartmenu in the Windows operating system.
  2. TheSDxIDE opens and prompts you to select a workspace, as shown in the following figure.

    Figure:Specify the SDx Workspace

IMPORTANT:When opening a new shell to enter an SDxcommand, ensure that you first source the settings64and setupscripts to set up the tool environment. On Windows, run thesettings64.batfile from the command shell. See theSDSoC Development Environment Release Notes, Installation, and Licensing Guidefor more information.

TheSDxworkspace is the folder that stores your projects, source files, and results while working in the tool. You can define separate workspaces for each project or have workspaces for different types of projects. The following instructions show you how to define a workspace for anSDSoCproject.

  1. Click theBrowsebutton to navigate to, and specify, the workspace, or type the appropriate path in theWorkspacefield.
  2. Select theUse this as the default and do not ask againcheck box to set the specified workspace as your default choice and eliminate this dialog box in subsequent uses ofSDx.
  3. ClickLaunch.
    TIP:You can change the current workspace from within the SDxIDE by selecting File>Switch Workspace.

You have now created anSDxworkspace and can populate the workspace with projects. Platform and application projects are created to describe theSDxtool flow for creating anSDSoCplatform.

The SDxIDE can populate the workspace with three types of user selected project types:
  • Application Project
  • Platform Project
  • Library Project
The following sections describe how to use the Platform and Application project types while constructing the example SDSoCplatforms.

Creating an SDSoC Platform Project

In this chapter, two platform projects are created using files from the SDxinstall tree. The first platform shows what files are needed and used in creating a platform for standalone use. The second platform illustrates the same flow but for the case of a platform that runs Linux on the target hardware. In general, a Linux and standalone system configuration can coexist in a single platform and they are not required to be in separate platform projects. Files sourced from the ZCU102 platform provided with the SDxtools are used to generate a new platform using the Platform Project flow. Subsequent chapters show how to create the hardware component of a platform with the Vivado®Design Suite and how to create the software components using the SDxIDE for standalone and Linux applications.
TIP:There are sample platform files provided in the SDxtools software installation area at /platforms.

Defining a Standalone Domain with Prebuilt Hardware and Software

After launching the SDx IDE, you can define a newSDSoCplatform by creating a Platform Project using either the Welcome screen or the SDx menubar by selectingFile>New>SDx Platform Project. TheNew Platform Projectdialog opens and prompts you for a project name. Name the projectplatform_1for this ZCU102 based example.

Figure:New Platform Project

ClickNextto advance to the next dialog and select the source of the hardware specification for the platform. You can choose to use a DSA or an existing platform as the source for the hardware component of the platform. Select DSA for this example.

Figure:Specify New Platform Source - DSA or Existing Platform

ClickNextto specify the DSA as theHardware Specification. Use the Browse button to locate the DSA for your project, or simply type the path to the DSA file in the field. TheSDxtool includes platforms and DSA files that you can use as the foundation for creating your ownSDSoCplatforms, or you can create the DSA for a new platform using the Vivado Design Suite. Refer toCreating the Platform Hardware Componentfor more information on creating the DSA. For this example, use the ZCU102 DSA located at/platforms/zcu102/hw/zcu102.dsa.

Figure:Platform Hardware Specification

Leave the Operating system and Processor settings asstandaloneandpsu_cortexa53_0.

ClickFinishto create the Platform project.

The platform configuration settings opens in the Editor Area of theSDxIDE. For this example, use the prebuilt hardware components and software components for the ZCU102 platform provided with theSDxtools at/platforms/zcu102. SelectUse existing pre-built dataon the platform configuration settings view and browse to or set thePrebuilt Datapath to/platforms/zcu102/sw/prebuilt.

Figure:Platform Configuration Settings

Providing a platform with prebuilt data containing software files with port interface specifications and a bitstream allows developers to quickly compile and run software applications that do not invoke hardware accelerated functions.

Click onsysconfig1for the System Configuration settings view. SelectUse pre-built software componentsand browse to or set theBoot Directorypath to/platforms/zcu102/sw/a53_standalone/boot. Browse to or set theBIF Fileto/platforms/zcu102/sw/a53_standalone/boot/standalone.bif.

Figure:System Configuration Settings

Click onstandalone on psu_cortexa53_0for the Domain settings view. Do not make any changes to the domain settings for this example, but note that this view is used to change settings for the board support package, the application linker script, and included libraries.

Figure:Domain Configuration Settings

At this point, set up references to all the files necessary to create a standalone platform for the ZCU102. Click onQuick Links - #3 Generate Platformto complete the platform generation process. After the platform is generated, buildSDxapplications targeting the platform.

Defining a Linux Domain with Prebuilt Hardware and Software

As an example of creating anSDSoCplatform for Linux applications, use the source files from the ZCU102 platform again and create a second platform,platform_2in the same workspace asplatform_1. Begin by creating a new platform project using the menu barFile>New>SDx Platform Projectand use the same ZCU102 DSA as before at/platforms/zcu102/hw/zcu102.dsa. Selectlinuxfor theOperating systemandpsu_cortexa53for theProcessor.

Figure:Platform Hardware Specification

SelectUse existing pre-built dataon the platform configuration settings view and browse or set thePrebuilt Datapath to/platforms/zcu102/sw/prebuilt.

Figure:Platform Configuration Settings

Selectlinux on psu_cortexa53to view the Linux domain settings and click on theClick herelink within the dialog'sThe linux domain is not configured. Click here to updateprompt.

Figure:Linux Domain Settings

In the domain configuration dialog, selectUse pre-built software componentsand browse to or set theBoot Directorypath to/platforms/zcu102/sw/a53_linux/boot. Browse to or set theBIF Fileto/platforms/zcu102/sw/a53_linux/boot/linux.bif.

Figure:Linux Boot and BIF Files

The linux_domain configuration settings view now shows additional fields that can be populated to reference the following items:
  • Linux Image Directory
  • Sysroot
The exisiting Linux image.ubfile from the ZCU102 platform is referenced through the specified imagedirectory. Optionally, a sysroot is associated with a platform by providing a reference within this Domain settings dialog.

Platforms with a sysroot enables theSDxIDE to create Linux application projects with make files containing default sysroot options for specifying include paths, library paths, and other options.

In thelinux_domainview, browse to the Linux image at/platforms/zcu102/sw/a53_linux/a53_linux/image.

Figure:Configured Linux Domain Settings

Thesysconfig1system configuration settings are automatically populated by the Linux domain settings entered for the Boot files directory and the BIF file are in place.

Figure:Linux System Configuration Settings

At this point, set up references to all the files necessary to create a Linux platform for the ZCU102. Click onQuick Links - #3 Generate Platformto complete the platform generation process. After the platform is generated, build theSDxapplications targeting the platform.

TheSDxProject ExplorerandAssistantviews after platform generation completes is shown below.

Figure:Generated Platforms

Defining an SDSoC Application Project for Platform Testing

TheSDxIDE provides compilation tools and example code templates for creating applications that run onSDSoCplatforms. Create example applications for the standalone (platform_1) and Linux (platform_2) platforms using theArray zero_copycode template provided with theSDxtools.

The Compilation log contains the commands issued to build the application and is useful for observing the sequence of actions taken during the build process. The Data Motion Network report lists the accelerated functions and how their arguments were mapped and connected to platform interfaces. The type of data mover used for each argument is also listed.

Reuse theSDxworkspace (sdx_workspace) containing the standalone and Linux platforms created in the section above.

Create a newSDxApplication project using the menu bar and selectingFile>New>SDx Application Project. TheNew SDx Application Projectdialog opens and prompts you for a project name. Name the projectapp_standalonefor this ZCU102-based example.

Figure:New SDx Application Project

ClickNextto advance to thePlatformselection dialog. Selectplatform_1 [custom]as this platform was configured for the standalone domain when it was created.

Figure:Application Platform Selection

ClickNextto advance to theSystem Configurationdialog. Leave the settings at their default values forSystem configuration:sysconfig1,Runtime:C/C++, andDomain:standalone on psu_cortexa53_0. Recall that whenplatform_1was created it was configured with a single system configuration containing a single standalone domain. If additional system configurations or domains are present in a platform an application can be customized to use them through thisSystem Configurationdialog.

Figure:Application System Configuration

ClickNextto advance to theTemplatesdialog and select theArray zero_copyexample as the code base for the application.

Figure:Application Template

ClickFinishto add the template code to theSDxapplication. TheEditor Areanow shows the application project settings including the functions that have been selected for hardware acceleration. TheProject ExplorerandAssistantviews are updated with the newapp_standaloneapplication.

Figure:Application Project Settings

Figure:Project Explorer View

Build theapp_standaloneapplication by expanding theapp_standalone [SDSoC]listing in theAssistantview, right-click onDebug [Hardware]and selectBuild.

Figure:Application Build Assistant View

After the application builds the Data Motion Network Report and Compilation Log are available through theAssistantview. The Compilation log contains the commands issued to build the application and is useful for observing the sequence of actions taken during the build process. The Data Motion Network report lists the accelerated functions and how their arguments were mapped and connected to platform interfaces. The type of data mover used for each argument is also listed.

A set of files for booting and running the application on target hardware is generated and accessible by right-clicking onSD Card Imageand selectingOpen > Open in Project Explorer,Open > Open in File Browser, orOpen > Open in Terminal. The files should be copied to a FAT32 formatted SD card and used to boot the target hardware, ZCU102 for this example, to test the generated platform by running application code.

The procedure for using the Array zero_copytemplate example for testing the Linux platform ( platform_2) generated earlier is similar to the standalone flow. The workspace is reused again to add another SDxApplication project, named app_linux, and use the Linux system configuration offered in platform_2. The Project Explorerand Assistantviews after a successful build of the application are shown below. The contents of the sd_carddirectory are used to boot and run the Linux application on target hardware.

Figure:Linux Application Project Explorer View

Figure:Linux Application Build Assistant View

Querying the Platform

The SDxenvironment provides tools to read and check the platform files you create. From within the SDxterminal window you can verify that the SDxIDE can correctly read the platform files created by the SDSoCplatform project by executing the following command, from within the workspace/project_name/exportwhere the generated platform is written: 
> sds++ –sds-pf-list

This command lists the availableSDxplatforms by reading the platform folders in the current working directory, and reading the platforms in theSDxinstallation hierarchy. If you specify this command from a folder containing a custom platform it will read the platform found there.

Any platform listed by the previous command can be displayed in greater detail using the following command: 
> sds++ –sds-pf-info
TIP:For platforms that are not in the installation area, the platform_nameis the path to the folder containing the platform.

This command displays the details of the specified platform.

You can also specify the platform to use for a project using the following command: 
> sds++ –sds-pf
The follow platform properties are reported after running the sds++ -sds-pf-info zcu102command: 
Platform Information ==================== Name: zcu102 Device ------ Architecture: zynquplus Device: xczu9eg Package: ffvb1156 Speed grade: -2 System Clocks ------------- Clock ID Frequency ----------|------------ 1199.880127 0 74.992500 1 99.990000 2 149.985000 3 199.980000 4 299.970000 5 399.960000 6 599.940000 Platform: zcu102 (/platforms/zcu102) Description: A basic platform targeting the ZCU102 evaluation board, which includes 4GB of DDR4 for the Processing System, 512MB of DDR4 for the Programmable Logic, 2x64MB Quad-SPI Flash and an SDIO card interface. More information at https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html Available system configurations: a53_linux (a53_linux) a53_standalone (a53_standalone) r5_standalone (r5_standalone) System Ports Use the system port name in a sysport pragma, for example #pragma SDS data sysport(parameter_name:system_port_name) System Port Name (Vivado BD instance name, Vivado BD port name) ps_e_S_AXI_HPC0_FPD (ps_e, S_AXI_HPC0_FPD) ps_e_S_AXI_HPC1_FPD (ps_e, S_AXI_HPC1_FPD) ps_e_S_AXI_HP0_FPD (ps_e, S_AXI_HP0_FPD) ps_e_S_AXI_HP1_FPD (ps_e, S_AXI_HP1_FPD) ps_e_S_AXI_HP2_FPD (ps_e, S_AXI_HP2_FPD) ps_e_S_AXI_HP3_FPD (ps_e, S_AXI_HP3_FPD)

Refer to theSDx Command and Utility Reference Guidefor more information.