Creating an SDSoC Platform

Introduction

Tip: There are sample platform files including Vivado projects and boot files provided in the SDSoC software installation area at <install>/samples/sdspfm. Refer to Tutorial: Using the SDSoC Platform Utility for a demonstration of creating an SDSoC platform.

The SDSoC Platform Utility simplifies the creation of SDSoC platforms. The platform utility exists in two parts: a simple form-like GUI for entering platform data and locating platform files, and a command-line utility that produces the platform as defined by the options.

SDSoC Platform Utility

The SDSoC Platform Utility simplifies the creation of SDSoC platforms, and can be invoked via the GUI as follows:
sdspfm -gui
Important: The SDSoC Platform Utility should be launched from the C:/ directory on the Windows OS, or an equivalent root directory, to avoid path name length limitations that can cause problems when generating the platform files on Windows.
This GUI lets you save the platform configuration as an XML file that can be reloaded so that the platform configuration can be modified and reused. The GUI Platform Utility has three areas for platform data entry, as seen in the figure below:
  • Base Info: The base information related to the platform name and the Vivado hardware project.
  • Processor Information: Specifies the type of processor found in the platform as defined in the Vivado hardware design.
  • Boot Info: As it relates to the Operating System data and the Compiler Settings for include paths and libraries to link against.

Figure: SDSoC Platform Utility



The Base Info includes:
  • Platform Name: Must match the name of the Vivado project and the IP Integrator block diagram. (REQUIRED)
  • Output Directory: Specifies a top-level platform repository, where the newly created platform directory will be written. (REQUIRED)
  • Vivado Project: Specifies the Vivado project file (.xpr) containing the hardware platform as defined in Hardware Platform Creation. (REQUIRED)
  • Platform Tcl: Script file that contains the platform clocks and ports exposed to SDSoC as defined in SDSoC Tcl Commands in Vivado (REQUIRED)
  • Samples Directory: A directory containing any sample applications associated with the platform and the user-created template.xml file as defined in Platform Sample Applications. (OPTIONAL)

The Processor Information defines the available types of processors for the platform. The types of processors available is configured based on the device chosen in the Vivado project. For example, if a Zynq-7000 device such as the XC7Z020 part is chosen in the Vivado project then the GUI will only show an ARM Cortex-A9 processor type. However, if a Zynq MPSoC device such as the XCZU9 part is chosen then the GUI will show both ARM Cortex-A53 and ARM Cortex-R5 processor types. This allows the user to create a platform targeting just the A53 or R5 cores, or both as desired.

Tip: You must select a Vivado project *.xpr file before the processors can be added to the configuration. Otherwise, the processor types will be empty.

SDSoC only allows projects to be built targeting core #0 of any processor (Cortex-A9, Cortex-A53, or Cortex-R5). This means that you can have a standalone project on a9_0, but not a standalone project on a9_1. In another case, you can have Linux on both cores a9_0 and a9_1 but SDSoC doesn’t need to know that Linux also uses a9_1. This limitation is mainly due to the fact that the FSBL must run on core #0 to initialize all cores in the processor, regardless of which core your application/OS runs on.

The Boot Info consists of the Operating System and the Compiler Settings. SDSoC currently supports 3 Operating Systems: Linux, FreeRTOS, and Standalone (ie. bare-metal). For each OS there are various files that must be included in order to compile, link, or generate the boot files for a given application. Refer to Software Platform Data Creation for information on creating these files:
  • Config ID: The ID of the OS/Boot configuration. The SDSoC Platform Utility allows platform developers to produce platforms with multiple build configurations. Each build configuration specifies: an OS, a processor type, and a set of boot files/settings. The Config ID identifies the build configuration, and must be unique for each build configuration in the platform. The Config ID must be made up of an alphanumeric string with underscores or dashes only (no spaces or special characters). When creating an SDSoC Makefile project, this ID is passed into the option -sds-sys-config<config_ID>. (All OSes)
  • Config Name: The name of the OS/Boot configuration. The user-defined Config Name must be unique for each build configuration in the platform. The Config Name must be made up of an alphanumeric string with spaces, parentheses, underscores or dashes only. When creating an SDSoC project in the SDSoC Development Environment IDE this name is displayed in the project creation wizard.
  • BIF File: the Boot Information File (BIF) contains information such as which ELF file to load on which processor (ie. FSBL runs on core 0), how the bitstream should be loaded, and any other sub-programs which must run to configure the processor (such as the ARM Trust Zone bl31.elf, or u-boot.elf, etc.). It is assumed that any files referenced in the BIF file will be in the directory specified by the Boot Directory field.
  • Readme File: This file is required by SDSoC to inform users of the platform how to boot an application for this boot configuration on the platform. It is a plain text file that contains instructions to the user, for setting the boot mode switches on the board for example.
  • Image Directory: A directory containing any OS image files that must be copied to the SD card. This directory should include the image.ub file for Linux, or a set of Linux files: image.gz, ramdisk, devicetree.dtb. This is required for Linux only.
  • Linker Script: A file that allows the programmer to control how the sections are merged in the ELF, and at what locations they are placed in memory. It also allows the user to specify how much of DDR memory is allocated for the stack and heap. This is required for FreeRTOS and Standalone Only.
  • Boot Directory: A directory containing any files referenced in the BIF file such as the FSBL, U-Boot, ARM Trusted Firmware, etc.

Compiler Settings: For each OS Configuration, compiler settings for the platform can be specified with include paths, and libraries to link against. These directories and libraries will be copied locally into the output platform at the time of platform generation. Users can add multiple include paths and libraries .

Platform Generation

After configuring the settings for your SDSoC platform, click the Generate button at the bottom of the SDSoC Platform Utility. This will start the process of copying and creating files, and generating metadata for your platform. If the output directory already exists, it will automatically be overwritten by the new platform files. You can regenerate the platform files as needed.

Important: If you encounter errors when the SDSoC Platform Utility is generating the platform, the cause may be related to the Vivado Design Suite project, and the IP Integrator block design. IP Locked errors can occur when the SDSoC Platform Utility invokes the Vivado tools to generate the hardware platform. This can be a result of improperly copying the Vivado project as described in Vivado Design Suite Project, or failing to upgrade the IP and output products as described in SDSoC Platform Migration.

Utility Menus

The SDSoC Platform Utility GUI has two menus:
  • File: provides options for saving the current configuration, opening a previously saved configuration, , and exiting the utility.
  • Export: provides an option to export the platform configuration as a Makefile. This takes all the data entered into the GUI and outputs a file containing a bare-minimum Makefile with the options to call the command-line utility to generate a platform. This option may be helpful for advanced users. The exported Makefile cannot be read back into the SDSoC Platform Utility, so you are advised to also save the configuration using the File > Save command in addition to exporting it to a Makefile.

Utility Command Line

The sdspfm -help command displays the following information:

Usage: sdspfm -xpr <vivado_project.xpr> -pfmtcl <platform.tcl> [other options]

Configuration Options:
  [-sds-cfg <required options> -sds-end]
    Required options:
       -arch <process arch> : [cortex-a9, cortex-a53, cortex-r5, microblaze]
       -os <OS type> : [standalone, freertos, linux]
       -name <configuration name>
       -id <configuration ID>
       -bif <bif file path>
       -readme <readme file path>
       -boot <boot files directory path>
       -lscript <linker script path> : Only for Standalone/FreeRTOS OSes
       -image <image directory path> : Only for Linux OSes
       -inc <include path> : adds path to list of include paths (can use multiple times)
       -lib <library file path> : adds path to list of library files (can use multiple times)
       -libfreertos <FreeRTOS library file path> : use custom FreeRTOS library,only for 
FreeRTOS OSes
       -incfreertos <FreeRTOS include path> : use custom FreeRTOS includes, only for 
FreeRTOS OSes
       -qemu-args <QEMU arguments file>

Optional Options:
  -o <output directory>
  -samples <samples directory path containing template.xml>
  -prebuilt <prebuilt directory path containing: portinfo.c/h,apsys_0.xml,bitstream.bit,
<platform>.hdf,partitions.xml>
  -force : overwrites output directory if it already exists
  -cfg : load configuration saved from the GUI
  -gui : launch the GUI
  -verbose
  -version
  -help