Creating SDSoC Platforms

The SDx™ IDE is used to assemble the hardware and software components into an SDSoC™ 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 Typical SDSoC Platform

In general, only the platform provider can ensure that a platform is “correct” for use within the SDSoC environment. However, the folder <SDx_Install_Dir>/samples/platforms/Conformance contains 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: <SDx_Install_Dir> signifies the location where the SDx tools are installed, including the released version: <SDx_Install_Dir> = <installation_path>/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 a samples sub-folder containing source files and a description.json file for each application, users can use the SDx IDE New Project wizard to select and build any of the provided sample applications. For additional information on application template creation, see Sample Applications.

To create a platform using the SDx IDE, 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 SDSoC platform.

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 the SDx™ 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 <workspace_name>

    • Double-clicking the SDx icon to start the program.
    • Launching from the Start menu in the Windows operating system.
  2. The SDx IDE 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 SDx command, ensure that you first source the settings64 and setup scripts to set up the tool environment. On Windows, run the settings64.bat file from the command shell. See the SDSoC Development Environment Release Notes, Installation, and Licensing Guide for more information.

The SDx workspace 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 an SDSoC project.

  1. Click the Browse button to navigate to, and specify, the workspace, or type the appropriate path in the Workspace field.
  2. Select the Use this as the default and do not ask again check box to set the specified workspace as your default choice and eliminate this dialog box in subsequent uses of SDx.
  3. Click Launch.
    TIP: You can change the current workspace from within the SDx IDE by selecting File > Switch Workspace.

You have now created an SDx workspace and can populate the workspace with projects. Platform and application projects are created to describe the SDx tool flow for creating an SDSoC platform.

The SDx IDE 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 SDSoC platforms.

Creating an SDSoC Platform Project

In this chapter, two platform projects are created using files from the SDx install 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 SDx tools 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 SDx IDE for standalone and Linux applications.
TIP: There are sample platform files provided in the SDx tools software installation area at <SDx_Install_Dir>/platforms.

Defining a Standalone Domain with Prebuilt Hardware and Software

After launching the SDx IDE, you can define a new SDSoC platform by creating a Platform Project using either the Welcome screen or the SDx menubar by selecting File > New > SDx Platform Project. The New Platform Project dialog opens and prompts you for a project name. Name the project platform_1 for this ZCU102 based example.

Figure: New Platform Project

Click Next to 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

Click Next to specify the DSA as the Hardware Specification. Use the Browse button to locate the DSA for your project, or simply type the path to the DSA file in the field. The SDx tool includes platforms and DSA files that you can use as the foundation for creating your own SDSoC platforms, or you can create the DSA for a new platform using the Vivado Design Suite. Refer to Creating the Platform Hardware Component for more information on creating the DSA. For this example, use the ZCU102 DSA located at <SDx_Install_Dir>/platforms/zcu102/hw/zcu102.dsa.

Figure: Platform Hardware Specification

Leave the Operating system and Processor settings as standalone and psu_cortexa53_0.

Click Finish to create the Platform project.

The platform configuration settings opens in the Editor Area of the SDx IDE. For this example, use the prebuilt hardware components and software components for the ZCU102 platform provided with the SDx tools at <SDx_Install_Dir>/platforms/zcu102. Select Use existing pre-built data on the platform configuration settings view and browse to or set the Prebuilt Data path to <SDx_Install_Dir>/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 on sysconfig1 for the System Configuration settings view. Select Use pre-built software components and browse to or set the Boot Directory path to <SDx_Install_Dir>/platforms/zcu102/sw/a53_standalone/boot. Browse to or set the BIF File to <SDx_Install_Dir>/platforms/zcu102/sw/a53_standalone/boot/standalone.bif.

Figure: System Configuration Settings

Click on standalone on psu_cortexa53_0 for 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 on Quick Links - #3 Generate Platform to complete the platform generation process. After the platform is generated, build SDx applications targeting the platform.

Defining a Linux Domain with Prebuilt Hardware and Software

As an example of creating an SDSoC platform for Linux applications, use the source files from the ZCU102 platform again and create a second platform, platform_2 in the same workspace as platform_1. Begin by creating a new platform project using the menu bar File > New > SDx Platform Project and use the same ZCU102 DSA as before at <SDx_Install_Dir>/platforms/zcu102/hw/zcu102.dsa. Select linux for the Operating system and psu_cortexa53 for the Processor.

Figure: Platform Hardware Specification

Select Use existing pre-built data on the platform configuration settings view and browse or set the Prebuilt Data path to <SDx_Install_Dir>/platforms/zcu102/sw/prebuilt.

Figure: Platform Configuration Settings

Select linux on psu_cortexa53 to view the Linux domain settings and click on the Click here link within the dialog's The linux domain is not configured. Click here to update prompt.

Figure: Linux Domain Settings

In the domain configuration dialog, select Use pre-built software components and browse to or set the Boot Directory path to <SDx_Install_Dir>/platforms/zcu102/sw/a53_linux/boot. Browse to or set the BIF File to <SDx_Install_Dir>/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.ub file from the ZCU102 platform is referenced through the specified image directory. Optionally, a sysroot is associated with a platform by providing a reference within this Domain settings dialog.

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

In the linux_domain view, browse to the Linux image at <SDx_Install_Dir>/platforms/zcu102/sw/a53_linux/a53_linux/image.

Figure: Configured Linux Domain Settings

The sysconfig1 system 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 on Quick Links - #3 Generate Platform to complete the platform generation process. After the platform is generated, build the SDx applications targeting the platform.

The SDx Project Explorer and Assistant views after platform generation completes is shown below.

Figure: Generated Platforms

Defining an SDSoC Application Project for Platform Testing

The SDx IDE provides compilation tools and example code templates for creating applications that run on SDSoC platforms. Create example applications for the standalone (platform_1) and Linux (platform_2) platforms using the Array zero_copy code template provided with the SDx tools.

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 the SDx workspace (sdx_workspace) containing the standalone and Linux platforms created in the section above.

Create a new SDx Application project using the menu bar and selecting File > New > SDx Application Project. The New SDx Application Project dialog opens and prompts you for a project name. Name the project app_standalone for this ZCU102-based example.

Figure: New SDx Application Project

Click Next to advance to the Platform selection dialog. Select platform_1 [custom] as this platform was configured for the standalone domain when it was created.

Figure: Application Platform Selection

Click Next to advance to the System Configuration dialog. Leave the settings at their default values for System configuration: sysconfig1, Runtime: C/C++, and Domain: standalone on psu_cortexa53_0. Recall that when platform_1 was 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 this System Configuration dialog.

Figure: Application System Configuration

Click Next to advance to the Templates dialog and select the Array zero_copy example as the code base for the application.

Figure: Application Template

Click Finish to add the template code to the SDx application. The Editor Area now shows the application project settings including the functions that have been selected for hardware acceleration. The Project Explorer and Assistant views are updated with the new app_standalone application.

Figure: Application Project Settings

Figure: Project Explorer View

Build the app_standalone application by expanding the app_standalone [SDSoC] listing in the Assistant view, right-click on Debug [Hardware] and select Build.

Figure: Application Build Assistant View

After the application builds the Data Motion Network Report and Compilation Log are available through the Assistant view. 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 on SD Card Image and selecting Open > Open in Project Explorer, Open > Open in File Browser, or Open > 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_copy template example for testing the Linux platform (platform_2) generated earlier is similar to the standalone flow. The workspace is reused again to add another SDx Application project, named app_linux, and use the Linux system configuration offered in platform_2. The Project Explorer and Assistant views after a successful build of the application are shown below. The contents of the sd_card directory 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 SDx environment provides tools to read and check the platform files you create. From within the SDx terminal window you can verify that the SDx IDE can correctly read the platform files created by the SDSoC platform project by executing the following command, from within the workspace/project_name/export where the generated platform is written: 
> sds++ –sds-pf-list

This command lists the available SDx platforms by reading the platform folders in the current working directory, and reading the platforms in the SDx installation 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 <platform_name>
TIP: For platforms that are not in the installation area, the platform_name is 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 <platform_name>
The follow platform properties are reported after running the sds++ -sds-pf-info zcu102 command:
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 (<SDx_Install_Dir>/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 the SDx Command and Utility Reference Guide for more information.