Creating the Platform Software Component

Introduction

The software components of an SDSoC™ platform can be generated directly from the SDx™ IDE. Using the DSA as the input hardware specification an SDx Platform project can be configured to generate the software files necessary for standalone, FreeRTOS, or Linux targets. For Linux targets, the SDx IDE invokes the PetaLinux tools to build the Linux image and the necessary software object files for constructing an SDSoC platform. The DSA file used by the SDx IDE is created in the Vivado® Design Suite using the write_dsa command.

Developers can also continue to create software with the Xilinx® SDK for standalone and FreeRTOS applications and utilize the PetaLinux tools to create Linux images and applications to construct an SDSoC platform through the SDx Platform project flow. An HDF file is used by the software creation tools as an input that describes the hardware design. To generate an HDF file, in Vivado, use the File > Export > Export Hardware command.

IMPORTANT: Because of the different configuration requirements for the different tools, such as the Vivado Design Suite and PetaLinux, running the tools in separate terminal shells is the recommended practice.

The software platform data creation process consists of building software components, such as libraries and header files, boot files, and others, for each supported operating system (OS) running on the device, and generating a software platform metadata file (.spfm) that captures how the components are used and where they are located. The platform folder <path_to_platform>/sw contains the software components, while the software platform metadata file is found in <path_to_platform>/sw/<platform>.spfm.

Every software platform should also include one or more sample designs that provide example usage.

This chapter describes required and optional components of a software platform, and assumes the platform creator is able to create these components. For example, if your platform supports Linux, you will need:

  • Boot files - first stage bootloader or FSBL; U-boot; Linux FIT image image.ub or separate devicetree.dtb, kernel and ramdisk files; boot image file or BIF used to create BOOT.BIN boot files.
  • Optional prebuilt data used by SDSoC when building applications without hardware accelerators, such as a pre-generated hardware bitstream and SDSoC data files to reduce compile time.
  • Optional header and library files if the platform provides software libraries.
  • Optional emulation data files, if the platform supports emulation flows using the Vivado Simulator for programmable logic and QEMU for the processing subsystem.

If your platform supports the Xilinx Standalone OS (a bare-metal board support package or BSP), the software components are similar to those for Linux, but the boot files include the FSBL and BIF files.

TIP: Zynq® UltraScale+™ MPSoC boot files also require ELF files for the Platform Management Unit firmware (PMUFW) and Arm® Trusted firmware (ATF).

Once you build the software components for a target OS, use the SDSoC platform project to add these components to the platform as described in Creating an SDSoC Platform Project.

Begin with an SDx Platform Project

In this chapter, two platform projects are created to illustrate the generation of standalone and Linux software objects and files using the SDx IDE. 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.

After launching the SDx IDE, define a new workspace (sdx_workspace_gen) for this example. This workspace contains the two platform projects for which the SDx tools will generate the software components. Use the Welcome screen or the SDx menu bar by selecting File > New > SDx Platform Project to create the first platform for a standalone target. The New Platform Project dialog opens and prompts you for a project name. Name the project platform_1_gen 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: New Platform Source - DSA

Click Next to specify the DSA filename as the Hardware Specification. Use the DSA generated in the example from the Creating the Platform Hardware Component chapter. For this example a copy of the generated DSA is located at /tmp/vivado/design_1.dsa.

Click on Generate Platform on the Quick Links selections. The platform generation process takes about 10 minutes to produce all the software output products for the Standalone target.

Standalone

A standalone target provides software applications complete access to the hardware design within the platform. This is also referred to as “bare-metal” since there are no layers of protection between software applications and the underlying hardware.

Figure: Platform Hardware Specification

Figure: Platform Configuration Settings - Standalone

Figure: System Configuration Settings - Standalone

Figure: Domain Configuration Settings - Standalone

Linux

A Linux target offers multi-tasking, virtual memory, and a variety of drivers to support many different hardware interfaces. Multiple software applications can run simultaneously or appear to do so through the Linux scheduler.

The SDx IDE can also generate the software files needed for a Linux target. Using the same sdx_workspace_gen workspace a new SDx Platform project named platform_2_gen is illustrated below. The SDx IDE generates the required Linux software objects and files by invoking the PetaLinux tools. Prior to creating the Linux platform project it is necessary to set a path to the PetaLinux tools through the SDx IDE.

Setting the PetaLinux path is accomplished through the SDx menu bar using Window > Preferences > Xilinx SDx > Platform Project. Click on Apply and Close to save settings.

Figure: PetaLinux Path

Figure: Platform Configuration Settings - Linux

Figure: Linux Domain Settings

Figure: Generate Software - Linux

As part of the Linux software generation process, a root file system that includes the libsds_lib.so shared library is placed in the /usr/lib directory. This can be viewed by using the SDx Project Explorer and navigating to <platform_name>/export/<platform_name>/sw/<system_name>/<domain_name>/sysroot. For our Linux platform_2_gen example this translates to platform_2_gen/export/platform_2_gen/sw/sysconfig1/linux_domain/sysroot. Platform developers should be aware that this previously statically linked library is now a dynamically linked library that must be included in the Linux file system image that runs on a board.

Figure: Linux Domain

Figure: System Configuration

Click on Generate Platform on the Quick Links selections. The PetaLinux tools are invoked and the generated software output products build time is approximately an hour for this example.

You have now successfully generated two SDSoC platforms based on a custom ZCU102 DSA and the SDx tools created the necessary software components for the platforms. One set for a standalone target (platform_1_gen) and another set for a Linux target (platform_2_gen).

Build an SDx Application - Standalone

As a part of the SDx environment a set of application code templates are available to test platforms or explore hardware acceleration features. Using the same workspace where you generated the custom platforms for Standalone and Linux targets, two SDx Application projects are added. The Array Partitioning template is used for both targets and creates an SD card image for testing the platforms on a ZCU102 board.

Figure: Application Project

Figure: Platform Selection

Figure: System Configuration

Figure: Array Partitioning Template Application

Figure: Application Settings

Figure: Standalone Build - Assistant View

An Array Partitioning application project for Linux can also be created for platform_2_gen as was done for the Standalone application using platform_1_gen. Results of booting and running the contents of the SD Card Image generated by the SDx IDE for both a Standalone target and a Linux target are shown below.

Figure: Linux Build - Assistant View

Figure: Application Run Output - Standalone

Build an SDx Application - Linux

Figure: Application Run Output - Linux

Prebuilt Hardware

A platform can optionally include prebuilt configurations to be used when the platform user does not specify any hardware functions in an SDSoC application. This can save significant run-time as the user should not need to wait for the compilation and implementation of the platform to create a bitstream. The prebuilt bitstream and other required files will be used to configure the hardware when needed.
TIP: An SDSoC application project with no hardware functions will compile without the prebuilt hardware, but it will take longer. Providing the prebuilt hardware is simply a way to reduce run-time in this situation.
When defining the SDSoC platform project, as described in SDx IDE Glossary, you can specify the Prebuilt Data, which is a folder containing prebuilt hardware information to be included in the platform. The prebuilt hardware will be copied into a subdirectory of the platform software directory as part of generating the SDSoC platform project. Data in the subdirectory is pointed to by metadata in the software platform file (.spfm). As shown in Directory Structure for a Typical SDSoC Platform, the path to prebuilt hardware data in an SDSoC platform is:
<path_to_platform>/sw/prebuilt

The prebuilt folder for the ZCU102 platform contains bitstream.bit, zcu102.hdf, partitions.xml, apsys_0.xml, portinfo.c and portinfo.h files.

In the SDx IDE platform project, selecting Generate prebuilt data in the Platform configuration settings causes the prebuilt data to be generated automatically when selecting the Quick Link Generate Platform. The generation process requires additional time to run, since Vivado synthesis and implementation are run in order to produce a bitstream, which is one of the prebuilt data files. If you created prebuilt data manually, select Use exisiting prebuilt data in the Platform configuration settings view and specify a path to the directory containing the manually created data files.

Library Header Files

If the platform requires application code to #include platform-specific header files, these should be defined in the platform software description file in a subdirectory relative to the platform directory for the corresponding OS. When defining the SDSoC platform project, you can specify the path to one or more folders containing header files.

For a given <relative_include_path> in a platform software description file, the location is:
platform/sw/os/os/relative_include_path
RECOMMENDED: If header files are not put in the standard area, users need to point to them using the –I switch in the SDSoC environment compile command.

Static Libraries

If the platform requires users to link against static libraries provided in the platform, these should reside in a subdirectory of the platform directory for the corresponding OS in the platform software description file. When defining the SDSoC platform project, you can specify static libraries to be included as platform software data.

For a given <relative_lib_path> in a platform software description file, the location is:
<platform_root>/sw/<relative_lib_path>
RECOMMENDED: If static libraries are not put in the standard area, every application needs to point to them using the –L option to the sdscc link command.

Linux Boot Files

PetaLinux can generate the Linux boot files for an SDSoC platform using the process documented in PetaLinux Tools Documentation: Workflow Tutorial (UG1156). The overall workflow for SDSoC platforms is the same, and the basic steps are outlined below. If you are familiar with the PetaLinux tools, you should be able to complete these steps for Zynq UltraScale+ MPSoC or Zynq-7000 SoC designs.

Platform developers should be aware that the previously statically linked library is now a dynamically linked library (libsds_lib.so) that must be included in the Linux file system image that runs on a board. As part of the Linux software generation process, a root file system that includes the libsds_lib.so shared library is placed in the /usr/lib directory. When running the PetaLinux tools manually this library must be included as part of the root file system. The libraries can be found in <SDX_Install_Dir>/target/<architecture>-linux/lib. Refer to PetaLinux Tools Documentation: Reference Guide (UG1144) for more information on how to include libraries with PetaLinux.

IMPORTANT:

Custom platforms that support Linux must include the SDSoC control API shared libraries. If the shared libraries are not included with the platform, applications targeting the custom platform must explicitly use static linking. Legacy support for static linking is provided by the sds++ -static-sds option, but you lose the capabilities made possible by shared library support, including startup of multiple hardware subsystems without conflicts.

Before starting, you should complete the following:

  1. Set up your shell environment with PetaLinux tools in your PATH environment variable.
    IMPORTANT: Because of the different configuration requirements for the different tools, such as the Vivado Design Suite and PetaLinux, running the tools in separate terminal shells is the recommended practice.
  2. Create and cd into a working directory.
  3. Create a new PetaLinux project targeting a BSP that corresponds to the type of board you are targeting:
    petalinux-create –t project -n <project_name> \
    -s <path_to_base_BSP>
  4. Obtain a copy of the hardware handoff file (.hdf) from the Vivado project for your hardware platform.
IMPORTANT: This guide assumes the existence of a valid hardware description file (HDF) for the platform, which is generated from the Vivado Design Suite project. Refer to Creating the Platform Hardware Component for more information.

The steps below include basic setup, loading the hardware handoff file, kernel configuration, root file system configuration, and building the Linux image, fsbl, pmufw, and atf. The steps include the actions to perform, or the PetaLinux command to run, with arguments. Once the build completes, your working directory contains a FIT image file (image.ub) that includes the devicetree, kernel and ramdisk. The basic setup is the procedure used to configure the Linux images packaged in all base platforms shipped with SDSoC platforms.

When using the petalinux-config command, a text-based user interface appears with a hierarchical menu system. The steps present a hierarchy of commands and the settings to use. Selections with the same indentation are at the same level of hierarchy. For example, the petalinx-config –c kernel step asks you to select Device Drivers from the top-level menu, select Generic Driver Options, go down one level to apply settings, go back up to Staging drivers, and apply settings to its sub-menu items.

Building the PetaLinux Image

To build the PetaLinux image, use the following steps:

  1. Configure PetaLinux with the HDF derived earlier for the associated platform (the production of which is described in the introduction):
    petalinux-config -p <petalinux_project> \
    --get-hw-description=<HDF path>
    Optionally, change boot args to include "quiet" at the end of whatever is the default:
    • Kernel Bootargs→generate boot args automatically (OFF)
    • for Zynq MPSoC: Kernel Bootargs→ user set kernel bootargs (earlycon clk_ignore_unused quiet)
    • for Zynq-7000: Kernel Bootargs→ user set kernel bootargs (console=ttyPS0,115200 earlyprintk quiet)
  2. Configure PetaLinux kernel:
    petalinux-config -p <petalinux_project> \
    -c kernel
    Set CMA size to be larger, for SDS-alloc buffers:
    • for Zynq UltraScale+ MPSoC: Device Drivers→ Generic Driver Options → Size in Mega Bytes(1024)
    • for Zynq-7000 SoC: Device Drivers→ Generic Driver Options → Size in Mega Bytes(256)
    Enable staging drivers:
    • Device Drivers → Staging drivers (ON)
    Enable APF management driver:
    • Device Drivers → Staging drivers → Xilinx APF Accelerator driver (ON)
    Enable APF DMA driver:
    • Device Drivers → Staging drivers → Xilinx APF Accelerator driver → Xilinx APF DMA engines support (ON)
    Note:

    For Zynq UltraScale+ MPSoC, you must turn off CPU idle and frequency scaling. To do so, mark the following options:

    • CPU Power Management > CPU idle > CPU idle PM support (OFF)
    • CPU Power Management > CPU Frequency scaling > CPU Frequency scaling (OFF)
  3. Configure petalinux rootfs:
    petalinux-config -p <petalinux_project> \
    -c rootfs
    Add stdc++ libs:
    • Filesystem Packages → misc → gcc-runtime → libstdc++ (ON)
  4. Add device tree fragment for APF driver. At the bottom of <>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi, add the following entry:
    /{
     xlnk {
     compatible = "xlnx,xlnk-1.0";
     };
    };
  5. Build the PetaLinux image:
    • petalinux-build

Preparing the Image for the SDSoC Platform Utility

In the directory <petalinux_project>/images/linux/ there are a number of important files that are partitioned into two categories:
  1. Files that end up compiled into BOOT.BIN, referred to collectively as ‘boot files’, that should be copied into a boot folder. Boot files include the following: u-boot.elf, zynq-fsbl.elf or zynqmp-fsbl.elf, along with bl31.elf and pmufw.elf for Zynq UltraScale+ devices.
  2. Files that must reside on the SD card but are not compiled into BOOT.BIN, referred to as ‘image files’, that should be copied into an image folder. The only image file from a PetaLinux build is image.ub, but you can add other files to the image folder that you want to make available to users of the platform.
From within the <petalinux_project>/images/linux/ folder run the following commands:
$ mkdir ./boot
$ mkdir ./image
$ cp u-boot.elf ./boot/u-boot.elf
$ cp *fsbl.elf ./boot/fsbl.elf
$ cp bl31.elf ./boot/bl31.elf
$ cp linux/pmufw.elf ./boot/pmufw.elf
$ cp image.ub ./image/image.ub
TIP: The bl31.elf and pmufw.elf files are only required for for Zynq UltraScale+ devices.

Finally, create a boot image format, or BIF file, that is used to compile the contents of the boot folder into a BOOT.BIN file. For more information on creating the BIF file for a target processor, refer to Zynq-7000 SoC Software Developers Guide (UG821) or Zynq UltraScale+ MPSoC Software Developer Guide (UG1137).

An SDSoC boot image format file looks similar to a standard BIF file, with tokens specified in angle brackets (< >) rather than direct paths to boot files. The BIF file tokens are replaced at SDSoC compile time with actual files and generated content. This is because the bitstream file for the programmable logic (PL) region will be procedurally generated, and some of the elements do not have known file names at the time the BIF file is created.

The following is an example boot.bif file for the Zynq-7000 SoC:
/* linux */
 the_ROM_image:
 {
   [bootloader]<fsbl.elf>
   <bitstream> 
   <u-boot.elf>
 }
The following is an example BIF for a Zynq UltraScale+ MPSoC device:
the_ROM_image:
{
  [fsbl_config] a53_x64
  [bootloader]<fsbl.elf>
  [pmufw_image]<pmufw.elf>
  [destination_device=pl] <bitstream>
  [destination_cpu=a53-0, exception_level=el-3, trustzone] <bl31.elf>
  [destination_cpu=a53-0, exception_level=el-2] <u-boot.elf>
}

Taken together, the boot directory, the image directory, and the BIF file, constitute the software elements that the SDSoC platform project needs as input for the Linux OS. See SDx IDE Glossary for more information.

Standalone Boot Files

If no OS is required, you can create a standalone boot image (boot.bin) that runs the specified executable, along with any necessary boot loaders.

TIP: If you have already configured the boot files for Linux OS then you can use those same files when creating the standalone boot image format file.

First Stage Boot Loader (FSBL)

The first stage boot loader (FSBL) is responsible for loading the bitstream and configuring the Zynq and Zynq UltraScale + architecture Processing System (PS) at boot time.

When the platform hardware design is open in the Vivado Design Suite, click the File > Export > Export Hardware menu option.

Using the SDx IDE, or the Xilinx Software Development Kit (SDK), create a new Application project File > New > Application Project with the name fsbl.

Using the exported Hardware Platform, select the Zynq FSBL application from the list. This creates an FSBL executable. For more detailed information, see the SDK Help.

Once you generate the FSBL, you can copy it into a standard location for the SDx environment flow, or you can consume it as part of the process of building a platform project.

Example:
samples/platforms/zcu102_axis_io/sw/a53_standalone/boot/fsbl.elf

Board Image Format (BIF) File

For the SDx environment to use an executable (ELF) in the boot image, a BIF file must point to it. The following is an example standalone boot.bif file for the Zynq-7000 SoC:
/* standalone */
the_ROM_image:
 {
   [bootloader]<fsbl.elf>
   <bitstream>
   <elf>
 }

The SDx environment replaces the <bitstream> and <elf> tokens in the BIF file with actual bitstream and ELF file references generated during the SDSoC compilation process.

TIP: The BIF file for the Zynq UltraScale+ MPSoC device is different from the BIF file for a Zynq-7000 SoC, and requires the addition of pmufw.elf. This file can be generated through SDK or the SDx IDE as a sample targeting the "psu_pmu_0" processor.

FreeRTOS Configuration/Version Change

SDx support for FreeRTOS is based on the implementation found in the Xilinx Software Development Kit (SDK) tool. By default FreeRTOS v10 is supported and in SDK this corresponds to the most recent freertos10_xilinx BSP library.

IMPORTANT: In the generated SDx platform file (.spfm), the processor group contains metadata that specifies the OS name (sdx:os/sdx:osname). If osname is specified as "freertos", that is mapped to the latest version of freertos10_xilinx. If the OS name is specified explicitly as "freertos10_xilinx", the specified version will be used.
To change FreeRTOS configuration settings, you can use SDx, just as you would use Xilinx SDK, with the platform DSA to create and customize a supported FreeRTOS BSP.
  1. Add the include files from the SDK BSP to your platform as library include files (you will define a library include path) when using the SDx IDE to create the platform project.
  2. Add the .mss file from the SDK BSP to your platform as a BSP configuration file. A linker script can be generated when SDK creates a sample application using the BSP.
  3. When you add the linker script to your SDx platform, you must increase the stack and heap sizes because the SDK default values are too small for a typical SDx application.
  4. You may also need to increase the task heap size passed to xTaskCreate from configMINIMAL_STACK_SIZE when creating FreeRTOS applications.
    TIP: This is application dependent, but try 1000 and adjust up or down as appropriate.

If you want to use a different FreeRTOS version or customize it in a manner that is different from the Xilinx BSP implementations, your can define a System Configuration for the standalone BSP, and add your FreeRTOS implementation as a library. You need to provide a FreeRTOS library, include files and a linker script.