Creating the Platform Software Component

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

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.

<platform_root>/sw/<relative_lib_path>

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.

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.

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

$ 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

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.

/* linux */
 the_ROM_image:
 {
   [bootloader]<fsbl.elf>
   <bitstream> 
   <u-boot.elf>
 }

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.