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:

 software_platform_description    configuration_description         : .  : .  

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

TheXML element is required as a container for all software platform information. It has the following attributes:

platform_name" sdx:version="1.0" sdx:schemaVersion="1.0" xmlns:sdx="http://www.xilinx.com/sdx">

Theelement describes the software platform and may be used when SDSoC displays summary information.

software_platform_description 

TheXML element is required as a container for all system configurations.

Theelement specifies the name of the defaultsdx:configurationto 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 option.

default_name">

Theelement defines a System Configuration and includes the following attributes:

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

Theelement can also contain multiple XML sub-elements:

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

configuration_description 

Element

Theelement 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.

Theelement contains a single attributesdx:datawhich specifies the path to a folder containing pre-generated files.

prebuilt_platform_path"/>

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

Indicates the prebuilt hardware bitstream and generated files are found in/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/sw/prebuilt_dataare found in the _sds project folder after creating the application ELF and bitstream:

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

If theelement is not defined, SDSoC will generate the bitstream for applications without hardware accelerators. Examples can be found in factory platforms in/platforms//sw/prebuilt_data.

Element

Theelement is a container for one or moreelements, each of which includes attributes used to create an SD card image. The attributesdx:defaultspecifies the name of the defaultto use.

default_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" /> 

Theelement contains attributes used when SDSoC creates SD card boot images.

sdx:name Attribute

Thesdx:nameattribute is required and specifies the name of theelement.

sdx:bif Attribute

Thesdx:bifattribute 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/sw/boot/linux.bif, where/swis the folder containing the.spffile and both of these values are attributes specified in the file/.xpfmfile.

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

/* linux */ the_ROM_image: { [bootloader]   }

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]/boot/fsbl.elf /.elf.bit /boot/u-boot.elf }

An examplestandalone.biffile has the following contents:

/* standalone */ the_ROM_image: { [bootloader]   }

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]/boot/fsbl.elf /.elf.bin /.elf }

sdx:imageData Attribute

Thesdx:imageDataattribute 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/sw/image, where /sw is the folder containing the.spfmfile.

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 animage.ubfile. If you use separateimage.ub,devicetree.dtbandramdisk.image.gzfiles, the folder contains those files.

sdx:extraData Attribute

Thesdx:extraDataattribute 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/sw/sdfiles, where /sw is the folder containing the.spfmfile.

Thesdx:extraDataattribute is optional and allows you isolate non-boot SD card files from the boot files specified bysdx:imageData.

sdx:mountPath Attribute

Thesdx:mountPathattribute is optional. It specifies the SD card mount path, which defaults to /mnt if not specified.

sdx:readme Attribute

Thesdx:readmeattribute 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/sw/linux/readme.txt, where /sw is the folder containing the.spfmfile.

-= SD card boot image =- Platform:  Application:  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 thesdx:readmeattribute 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 thesdx:imageDataorsdx:extraDataattributes and thesdx:readmeattribute can be omitted.

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

Thesdx:qemuDevicetree,sdx:qemuBootandsdx:qemuArgumentsattributes 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 /sw is the folder containing the.spfmfile.

Thesdx:qemuDevicetreeattribute 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.

Thesdx:qemuBootattribute 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.

Thesdx:qemuArgumentsattribute is required for all target OS which support emulation flows.

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

Element

Theelement 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.

Theelement includes the following attributes:

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

Theelement contains a single sub-element, which optionally contains paths to file and folders, settings and other data used to build the user application for the target operating system.

Theelement contains the following attributes:

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: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

Thesdx:includePathsattribute 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/sw/aarch32-none/include, where /sw is the folder containing the.spfmfile. When compiling source files, sdscc/sds++ adds the option "–I /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

Thesdx:libraryPathsattribute 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/sw/aarch32-none/lib, where /sw is the folder containing the.spfmfile. When linking the application ELF, sdscc/sds++ adds the option "–L /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

Thesdx:libraryNamesattribute 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 librarylibnumeric.ais linked in. The platform library path must be specified using thesdx:libraryPathsattribute.

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

Thesdx:ldscriptattribute 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/sw/standalone/lscript.ld, where /sw is the folder containing the.spfmfile.

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

sdx:bspConfig Attribute

Thesdx:bspConfigattribute 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/sw/bsp/system.mss, where /sw is the folder containing the.spfmfile.

When thesdx:bspConfigattribute is used for generating a platform-specific standalone BSP, thesdx:includePathsattribute 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). SeeGenerating Basic Software Platforms(UG1138) for information about BSP configuration files (.mss).

sdx:bspRepo Attribute

Thesdx:bspRepoattribute 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/sw/bsp/repo, where /sw is the folder containing the.spfmfile.

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 toGenerating Basic Software Platforms(UG1138) for information about BSP repositories.

sdx:compilerOptions Attribute

Thesdx:compilerOptionsattribute 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. Thetemplate.xmlused by the SDSoC GUI when creating template applications supports a similar attribute and adds compiler options to the generated Make file, while thesdx:compilerOptionsattribute 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

Thesdx:linkerOptionsattribute 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. Thetemplate.xmlused by the SDSoC GUI when creating template applications supports a similar attribute and adds linker options to the generated Make file, while thesdx:linkerOptionsattribute 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.