Software Platform XML Metadata Reference

An SDSoC software platform XML file (.spfm) defines one or more system configurations. When building an SDSoC application, the user specifies the system configuration that defines a software runtime environment for a target operating system (OS), and metadata used by the SDSoC system compilers to generate application-specific systems-on-chip built upon the hardware platform. The information includes:

• Optional prebuilt platform data, for example bitstream and files normally generated by SDSoC, which minimizes SDSoC build times when a design contains no accelerators.
• SD card image data files, for example bootloaders, boot files for Linux (kernel, ramdisk, devicetree) and the Boot Image File (BIF) template used with by SDSoC with the bootgen utility to create the images.
• Compile and link software files and settings for a targeted processor:
  • Optional include files and libraries required by platform software applications.
  • Linker scripts.
  • Optional BSP configuration files and repositories.
  • Target device information.

The informal software platform XML schema is shown below, although not all elements or attributes are required:

<?xml version="1.0" encoding="UTF-8"?><sdx:platform sdx:vendor="xilinx.com"
              sdx:library="sdx"
              sdx:name="platform_name"
              sdx:version="1.0"
              sdx:schemaVersion="1.0"
              xmlns:sdx="http://www.xilinx.com/sdx">   
          <sdx:description>software_platform_description   
          </sdx:description>   
        <sdx:systemConfigurations sdx:defaultConfiguration="default_name">       
        <sdx:configuration sdx:name="name"
                           sdx:displayName="GUI_name"                          
          sdx:defaultProcessorGroup="default_name">           
          <sdx:description>configuration_description
               </sdx:description>
            <sdx:prebuilt sdx:data="prebuilt_platform_path"/>
             <sdx:bootImages sdx:default="default_name">
                <sdx:image sdx:name="name"
                           sdx:bif="path_to_bif_file"
                           sdx:imageData="path_to_image_data"
                           sdx:extraData=”path_to_more_image_data”
                           sdx:mountPath="sd_card_mount_path"
                           sdx:readme="path_to_readme_file"
                           sdx:qemuDevicetree="path_qemu_devicetree"
                           sdx:qemuBoot="path_qemu_uboot"
                           sdx:qemuArguments="path_arguments_file" />
            </sdx:bootImages>
            <sdx:processorGroup sdx:name="name"                               
          sdx:displayName="GUI_name"
                                sdx:cpuType="cpu_type"
                                sdx:cpuInstance=”instance_name”>
                <sdx:os sdx:name="os_name"
                        sdx:displayName="GUI_name"
                        sdx:includePaths=”path_to_include_folder”
                        sdx:libraryPaths=”path_to_library_folder”
                        sdx:libraryNames=”list_of_library_names”
                        sdx:ldscript=”path_to_linker_script”
                        sdx:bspConfig=”path_to_mss_file”
                        sdx:bspRepo=”path_to_bsp_repository”
                        sdx:compilerOptions=”compiler_options”
                        sdx:linkerOptions=”linker_options”
            </sdx:processorGroup>       
          </sdx:configuration>
              :
              .      
           <sdx:configuration sdx:name="name"
                           sdx:displayName="GUI_name"                          
          sdx:defaultProcessorGroup="default_name">
              :
              .        
        </sdx:configuration>   
          </sdx:systemConfigurations></sdx:platform> 

The first line of the file defines the format of the file to be XML and is mandatory:

<?xml version="1.0" encoding="UTF-8"?>

<sdx:platform>

The <sdx:platform> XML element is required as a container for all software platform information. It has the following attributes:

<sdx:platform sdx:vendor="xilinx.com"
 sdx:library="sdx"
 sdx:name="platform_name"
 sdx:version="1.0"
 sdx:schemaVersion="1.0"
 xmlns:sdx="http://www.xilinx.com/sdx">

<sdx:description>

The <sdx:description> element describes the software platform and may be used when SDSoC displays summary information.

 <sdx:description>software_platform_description
 </sdx:description>

<sdx:systemConfigurations>

The <sdx:systemConfigurations> XML element is required as a container for all system configurations.

The <sdx:systemConfigurations> element specifies the name of the default sdx:configuration to use as the selection in the SDx environment IDE New Project Wizard drop-down list of system configurations, or when the SDSoC compiler tool sdscc/sds++ command line does not include the –sds-sys-config <system_configuration_name> option.

<sdx:systemConfigurations sdx:defaultConfiguration="default_name">

The <sdx:configuration> element defines a System Configuration and includes the following attributes:

 <sdx:configuration sdx:name="name"
 sdx:displayName="GUI_name"
 sdx:defaultProcessorGroup="default_name">

The <sdx:configuration> element can also contain multiple XML sub-elements:

<sdx:description> Element

The sdx:description element contains a description of the System Configuration. This is used in the SDx Environment IDE New Project Wizard when a more detailed description is required, for example mouse over the name in a list of system configurations, or when sdscc/sds++ -sds-pf-list or –sds-pf-info options are used to print information about a platform

 <sdx:description>configuration_description 
</sdx:description>

<sdx:prebuilt> Element

The <sdx:prebuilt> element specifies pre-generated data for the platform used with the system configuration when building user applications that contain no accelerators. This optional element can be used to reduce build times, since you do not need to wait for a hardware compile of the platform itself to create a bitstream and other required files.

The <sdx:prebuilt> element contains a single attribute sdx:data which specifies the path to a folder containing pre-generated files.

 <sdx:prebuilt sdx:data="prebuilt_platform_path"/>

The path is relative to the software platform folder. For example, the element:

 <sdx:prebuilt sdx:data="prebuilt_data"/>

Indicates the prebuilt hardware bitstream and generated files are found in <path_to_platform>/sw/prebuilt_data (the folder name can be defined by the platform provider).

Pre-built hardware files are automatically used by the SDSoC compiler when an application has no hardware functions specified in the SDx Environment IDE in the SDx Project Settings view or in the sdscc/sds++ command line using the platform, system configuration and processor flags:

-sds-pf zc702 –sds-sys-config linux –sds-proc a9_0

To force a full Vivado tools bitstream and SD card image compile, use the following sdscc option:

-rebuild-hardware

Files used to populate the <path_to_platform>/sw/prebuilt_data are found in the _sds project folder after creating the application ELF and bitstream:

• bitstream.bit : found in _sds/p0/ipi/<platform>.runs/impl_1/bitstream.bit
• <platform>.hdf : found in _sds/p0/ipi/<platform>.sdk
• apsys_0.xml and partitions.xml : found in _sds/.llvm
• portinfo.c and portinfo.h : found in _sds/swstubs

If the <sdx:prebuilt> element is not defined, SDSoC will generate the bitstream for applications without hardware accelerators. Examples can be found in factory platforms in <install>/platforms/<platform>/sw/prebuilt_data.

<sdx:bootImages> Element

The <sdx:bootImages> element is a container for one or more <sdx:image> elements, each of which includes attributes used to create an SD card image. The attribute sdx:default specifies the name of the default <sdx:image> to use.

 <sdx:bootImages sdx:default="default_name">
 <sdx:image sdx:name="name"
 sdx:bif="path_to_bif_file"
 sdx:imageData="path_to_image_data"
 sdx:extraData=”path_to_more_image_data”
 sdx:mountPath="sd_card_mount_path"
 sdx:readme="path_to_readme_file"
 sdx:qemuDevicetree="path_qemu_devicetree"
 sdx:qemuBoot="path_qemu_uboot"
 sdx:qemuArguments="path_arguments_file"
 />
</sdx:bootImages>

The <sdx:image> element contains attributes used when SDSoC creates SD card boot images.

sdx:name Attribute

The sdx:name attribute is required and specifies the name of the <sdx:image> element.

sdx:bif Attribute

The sdx:bif attribute is required and specifies the path to a Boot Image File (BIF) relative to the software platform folder where the BIF file must exist. For example, the attribute:

sdx:bif="boot/linux.bif"

resolves to the path <path_to_platform>/sw/boot/linux.bif, where <path_to_platform>/sw is the folder containing the <platform>.spf file and both of these values are attributes specified in the file <path_to_platform>/<platform>.xpfm file.

An example platform BIF file template for a Linux target has the following contents:

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

During system generation, the SDSoC system compiler reads this template and inserts application-specific file names to generate the BIF file. This file is passed to the bootgen utility to create the boot image.

/* linux */
the_ROM_image:
{
[bootloader]<path_to_platform>/boot/fsbl.elf
<path_to_generated_bitstream>/<project_name>.elf.bit
<path_to_platform>/boot/u-boot.elf
}

An example standalone.bif file has the following contents:

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

During system generation, the SDSoC system compiler reads this template and inserts application-specific file names to generate the BIF file. This file is passed to the bootgen utility to create the boot image.

/* standalone */
the_ROM_image:
{
[bootloader]<path_to_platform>/boot/fsbl.elf
<path_to_generated_bitstream_directory>/<project_name>.elf.bin
<path_to_generated_application_elf_directory>/<project_name>.elf
}

sdx:imageData Attribute

The sdx:imageData attribute is required for Linux images and specifies a folder containing boot files to copy to the SD card image whose path is relative to the software platform folder. For example, the attribute:

sdx:imageData="image"

resolves to the path <path_to_platform>/sw/image, where <path_to_platform>/sw is the folder containing the <platform>.spfm file.

The folder typically contains Linux boot files, and SDSoC copies all folders and files found in the folder to the root of the SD card. If you are using a unified boot image file (.ub) containing a kernel image, device tree and root file system, the folder typically contains an image.ub file. If you use separate image.ub, devicetree.dtb and ramdisk.image.gz files, the folder contains those files.

sdx:extraData Attribute

The sdx:extraData attribute is optional. It specifies a folder containing additional files to copy to the SD card folder whose path is relative to the software platform folder. For example, the attribute:

sdx:extraData="sdfiles"

resolves to the path <path_to_platform>/sw/sdfiles, where <path_to_platform>/sw is the folder containing the <platform>.spfm file.

The sdx:extraData attribute is optional and allows you isolate non-boot SD card files from the boot files specified by sdx:imageData.

sdx:mountPath Attribute

The sdx:mountPath attribute is optional. It specifies the SD card mount path, which defaults to /mnt if not specified.

sdx:readme Attribute

The sdx:readme attribute is optional. It specifies a readme file copied to the root of the SD card and whose path is relative to the software platform folder. For example, the attribute:

sdx:readme="linux/readme.txt"

resolves to the path <path_to_platform>/sw/linux/readme.txt, where <path_to_platform>/sw is the folder containing the <platform>.spfm file.

-= SD card boot image =-

Platform: <platform>
Application: <elf>

1. Copy the contents of this directory to an SD card
2. Set boot mode to SD
   Revision C and earlier boards:
     Jumper J22 1-2
     Jumper J25 1-2
   Revision D and newer boards:
     DIP switch SW16 positions 3 and 4 set to 1
3. Insert SD card and turn board on

If the sdx:readme attribute is used, SDSoC prepends build information to the start of the file before writing it to the SD card. If build information is not required to be inserted into the README file, the README file can be added to a folder defined by the sdx:imageData or sdx:extraData attributes and the sdx:readme attribute can be omitted.

sdx:qemuDevicetree, sdx:qemuBoot, and sdx:qemuArguments Attributes

The sdx:qemuDevicetree, sdx:qemuBoot and sdx:qemuArguments attributes define the path to the device tree, U-boot executable and QEMU arguments files used in SDSoC emulation flows, where the user application executes on QEMU and interacts with programmable logic running in the Vivado simulator. The paths to these files are relative to the software platform folder, where <path_to_platform>/sw is the folder containing the <platform>.spfm file.

The sdx:qemuDevicetree attribute is required whether the operating system (OS) running on the target is Linux or baremetal. The device tree is used by QEMU to enable device support.

The sdx:qemuBoot attribute is required when Linux is running on the target, but not for baremetal software. It points to the U-boot executable used to create Linux SD card boot images.

The sdx:qemuArguments attribute is required for all target OS which support emulation flows.

For an example of QEMU software platform files and support, see the folder <install>/platforms/zc702/sw/qemu.

<sdx:processorGroup> Element

The <sdx:processorGroup> element defines compile and link software files and settings for a targeted processor such as:

• Target device information.
• Optional include files and libraries required by platform software applications.
• Linker scripts.
• Optional BSP configuration files and repositories.

The <sdx:processorGroup> element includes the following attributes:

<sdx:processorGroup sdx:name="name"
sdx:displayName="GUI_name"
 sdx:cpuType="cpu_type"
 sdx:cpuInstance=”instance_name”>

The <sdx:processorGroup> element contains a single sub-element <sdx:os>, which optionally contains paths to file and folders, settings and other data used to build the user application for the target operating system.

The <sdx:os> element contains the following attributes:

 <sdx:os sdx:name="os_name"
sdx:displayName="GUI_name"
sdx:includePaths=”path_to_include_folder”
sdx:libraryPaths=”path_to_library_folder”
sdx:libraryNames=”list_of_library_names”
sdx:ldscript=”path_to_linker_script”
sdx:bspConfig=”path_to_mss_file”
sdx:bspRepo=”path_to_bsp_repository”
sdx:compilerOptions=”compiler_options”
sdx:linkerOptions=”linker_options”
/>
</sdx:processorGroup>

sdx:name Attribute

The sdx:name attribute specifies the operating system running on the processor. Valid values are linux, standalone or freertos, if supported by the platform.

sdx:displayName Attribute

The sdx:displayName attribute is a descriptive name for the operating system, used in the SDx environment IDE as a label in the New Project Wizard in the Choose Software Platform and Target CPU page.

sdx:includePaths Attribute

The sdx:includePaths attribute is optional. It specifies the path to any platform software include folders that must be added when compiling user source files. Separate multiple include paths with a colon character ‘:’. The include folder is located in the software platform folder. When specified, the SDSoC Compiler tool sdscc/sds++ automatically adds the –I option during compilation. For example, the attribute:

sdx:includePaths="aarch32-none/include"

resolves to the path <path_to_platform>/sw/aarch32-none/include, where <path_to_platform>/sw is the folder containing the <platform>.spfm file. When compiling source files, sdscc/sds++ adds the option "–I <path_to_platform>/sw/aarch32-none/include”.

When the SDSoC Compiler tool sdscc/sds++ compiles source files, the include path search order is:

• user include paths
• platform include paths
• SDSoC installation include paths
• Vivado HLS include paths (if required)

sdx:libraryPaths Attribute

The sdx:libraryPaths attribute is optional. It specifies the path to any platform software library folders that must be added when linking the user application ELF. Separate multiple library paths with a colon character ‘:’. The library folder is located in the software platform folder and contains libraries used to link applications. When specified, the SDSoC Compiler tool sdscc/sds++ automatically adds the –L option during compilation. For example, the attribute:

sdx:libraryPaths="aarch32-none/lib"

resolves to the path <path_to_platform>/sw/aarch32-none/lib, where <path_to_platform>/sw is the folder containing the <platform>.spfm file. When linking the application ELF, sdscc/sds++ adds the option "–L <path_to_platform>/sw/aarch32-none/lib”.

When the SDSoC Compiler tool sdscc/sds++ links the application ELF, the library path order is:

• user library paths
• path to SDSoC generated board support package (BSP) libraries (standalone or FreeRTOS)
• platform library paths
• SDSoC installation library paths
• SDSoC generated libraries

sdx:libraryNames Attribute

The sdx:libraryNames attribute is optional. It specifies the names of any platform software libraries that must be passed to the linker when linking the ELF file. Separate multiple library names with a colon character ‘:’. When specified, the SDSoC Compiler tool sdscc/sds++ automatically adds the –l option when linking the ELF. For example, the attribute:

sdx:libraryNames="numeric"

causes the –lnumeric option to be used when linking and the library libnumeric.a is linked in. The platform library path must be specified using the sdx:libraryPaths attribute.

The attribute is optional, since the user can specify the –l option in the SDSoC GUI C/C++ Build Settings dialog and in user Make files.

sdx:ldscript Attribute

The sdx:ldscript attribute specifies the path to a linker script file located in the software platform folder. For example, the attribute:

sdx:ldscript="standalone/lscript.ld"

resolves to the path <path_to_platform>/sw/standalone/lscript.ld, where <path_to_platform>/sw is the folder containing the <platform>.spfm file.

The linker script is used by the SDSoC Compiler tool sdscc/sds++ when linking your application ELF.

sdx:bspConfig Attribute

The sdx:bspConfig attribute is optional and specifies the path to a board support package (BSP) configuration file (.mss) located in the software platform folder. For example, the attribute:

sdx:bspConfig="bsp/system.mss"

resolves to the path <path_to_platform>/sw/bsp/system.mss, where <path_to_platform>/sw is the folder containing the <platform>.spfm file.

When the sdx:bspConfig attribute is used for generating a platform-specific standalone BSP, the sdx:includePaths attribute must be specified and refer to folder containing BSP header files. The SDSoC Compiler tool sdscc/sds++ command uses this .mss file instead of generating a default BSP configuration based on both the platform and hardware in the programmable logic (PL). Consequently the .mss file must specify drivers required in SDSoC user designs, including the Xilinx AXI DMA driver (scatter-gather mode). See Generating Basic Software Platforms (UG1138) for information about BSP configuration files (.mss).

sdx:bspRepo Attribute

The sdx:bspRepo attribute is optional and specifies the path to a board support package (BSP) repository folder located in the software platform folder. For example, the attribute:

sdx:bspRepo="bsp/repo"

resolves to the path <path_to_platform>/sw/bsp/repo, where <path_to_platform>/sw is the folder containing the <platform>.spfm file.

The use case supports platforms which define drivers or libraries that must be included in the BSP. The SDSoC Compiler tool sdscc/sds++ command adds the folder to the repository search path when generating a standalone BSP llibrary (libxil.a). Refer to Generating Basic Software Platforms (UG1138) for information about BSP repositories.

sdx:compilerOptions Attribute

The sdx:compilerOptions attribute specifies compiler options required to compile an application that uses the platform, exclusive of include path attributes.

This attribute is optional and typically not required. The template.xml used by the SDSoC GUI when creating template applications supports a similar attribute and adds compiler options to the generated Make file, while the sdx:compilerOptions attribute causes the specified options to be inserted when the SDSoC Compiler tool sdscc/sds++ invokes the underlying cross-compiler to compile all source files for every application.

sdx:linkerOptions Attribute

The sdx:linkerOptions attribute specifies linker options required to link an application that uses the platform, exclusive of library path and library name attributes.

This attribute is optional and not typically used. The template.xml used by the SDSoC GUI when creating template applications supports a similar attribute and adds linker options to the generated Make file, while the sdx:linkerOptions attribute causes the specified options to be inserted when the SDSoC Compiler tool sdscc/sds++ invokes the underlying cross-compiler to link the ELF file for every application.