Platform Sample Applications

Overview

A platform can optionally include sample applications to demonstrate the usage of the platform. The sample applications must be defined in a file named template.xml found in the samples directory of a platform. Here is an example for the zc702_axis_io sample platform found in the <SDx_install>/SDx/2017.1/samples/sdspfm/zc702_axis_io/src/samples folder.

<?xml version="1.0" encoding="UTF-8"?>
<manifest:Manifest xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" 
                   xmlns:manifest="http://www.xilinx.com/manifest">
    <template location="aximm" name="Unpacketized AXI4-Stream to DDR" 
              description="Shows how to copy unpacketized AXI-Stream data directly to DDR.">
        <supports>
            <and>
                <or>
                    <os name="Linux"/>
                    <os name="Standalone"/>
                </or>
            </and>
        </supports>
        <accelerator name="s2mm_data_copy" location="main.cpp"/>
    </template>
	<template location="stream" name="Packetize an AXI4-Stream" 
                  description="Shows how to packetize an unpacketized AXI4-Stream.">
        <supports>
            <and>
                <or>
                    <os name="Linux"/>
		    <os name="Standalone"/>
                </or>
            </and>
        </supports>
        <accelerator name="packetize" location="packetize.cpp"/>
        <accelerator name="minmax" location="minmax.cpp"/>
    </template>
    <template location="pull_packet" name="Lossless data capture from AXI4-Stream to DDR" 
              description="Illustrates a technique to enable lossless data capture from a free-running input source.">
        <supports>
            <and>
                <or>
                    <os name="Linux"/>
                </or>
            </and>
        </supports>
        <accelerator name="PullPacket" location="main.cpp"/>
    </template>
</manifest:Manifest>
The first line defines the template file format as XML, and is mandatory:
<?xml version="1.0" encoding="UTF-8"?> 
The <manifest:Manifest> XML element is required as a container for all application templates defined in the template file:
<manifest:Manifest xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" 
                   xmlns:manifest="http://www.xilinx.com/manifest">
   <!-- ONE OR MORE TEMPLATE XML ELEMENTS GO HERE -->
</manifest:Manifest>

<template> element

Each application template is defined inside a <template> element, and there can be multiple <template> tags defined within the <manifest> element. The <template> element can have multiple attributes as shown in the following table:

Table 1. Attributes of the Template Element
Attribute Description
location Relative path to the template application
name Application name displayed in the SDSoC environment
description Application description displayed in the SDSoC environment
Example:
<template location="aximm" name="Unpacketized AXI4-Stream to DDR" 
              description="Shows how to copy unpacketized AXI-Stream data directly to DDR.">
The <template> element can also contain multiple nested elements that define different aspects of the application.
Table 2. Template Sub-Elements
Element Description
<supports> Boolean function that defines the matching template.
<includepaths> Paths relative to the application to be added to the compiler as -I flags.
<librarypaths> Paths relative to the application to be added to the linker as -L flags.
<libraries> Platform libraries to be linked against using linker -l flags.
<exclude> Directories or files to exclude from copying into the SDSoC project.
<system> Application project settings for the system, for example the data motion clock.
<accelerator> Application project settings for specifying a function target for hardware.
<compiler> Application project settings defining compiler options.
<linker> Application project settings defining linker options.

<supports> element

The <supports> element defines an Operating System match for the selected SDx platform. The <os> elements must be enclosed in <and> and <or> elements to define a boolean function.

The following example defines an application that can be selected when either of Linux, Standalone or FreeRTOS are selected as an Operating System:

<supports>
  <and>
    <or>
      <os name="Linux"/>
      <os name="Standalone"/>
      <os name="FreeRTOS"/>
    </or>
  </and>
</supports>

<includepaths> element

The <includepaths> element defines the set of paths relative to the application that are to be passed to the compiler using -I flags. Each <path> element has a location attribute.

The following example results in SDx adding the flags -I"../src/myinclude" -I"../src/dir/include" to the compiler:
<includepaths>
  <path location="myinclude"/>
  <path location="dir/include"/>
</includepaths>

<librarypaths> element

The <librarypaths> element defines the set of paths relative to the application that are to be passed to the linker using -L flags. Each <path> element has a location attribute.

The following example results in SDSoC adding the flags -L"../src/mylibrary" -L"../src/dir/lib" to the linker:
<librarypaths>
  <path location="mylibrary"/>
  <path location="dir/lib"/>
</librarypaths>

<libraries> element

The <libraries> element defines the set of libraries that are to be passed to the linker -l flags. Each <lib> element has a name attribute.

The following example results in SDx adding the flags -lmylib2 -lmylib2 to the linker:
<libraries>
  <lib name="mylib1"/>
  <lib name="mylib2"/>
</libraries>

<exclude> element

The <exclude> element defines a set of directories and files to be excluded from being copied when SDx creates the new project.

The following example will result in SDx not making a copy of directories MyDir and MyOtherDir when creating the new project. It will also not make a copy of files MyFile.txt and MyOtherFile.txt. This allows you to have files or directories in the application directory that are not needed to build the application.

<exclude>
  <directory name="MyDir"/>
  <directory name="MyOtherDir"/>
  <file name="MyFile.txt"/>
  <file name="MyOtherFile.txt:/>
</exclude>  

<system> element

The optional <system> element defines application project settings for the system when creating a new project. The dmclkid attribute defines the data motion clock ID. If the <system> element is not specified, the data motion clock uses the default clock ID.

The following example will result in SDx setting the data motion clock ID to 2 instead of the default clock ID when creating the new project.

<system dmclkid="2"/>

<accelerator> element

The optional <accelerator> element defines application project settings for a function targeted for hardware when creating a new project. The name attribute defines the name of the function and the location attribute defines the path to the source file containing the function (the path is relative to the folder in the platform containing the application source files). The name and location are required attributes of the <accelerator> element. The optional attribute clkid specifies the accelerator clock to use instead of the default. The optional sub-element <hlsfiles> specifies the name of a source file (path relative to the folder in the platform containing application source files) containing code called by the accelerator and the accelerator is found in a different file. The SDx environment normally infers <hlsfiles> information for an application and this sub-element does not need to be specified unless the default behavior needs to be overridden.

The following example will result in SDx specifying two functions to move to hardware func1 and func2 when creating the new project.

<accelerator name="func1" location="func1.cpp"/>
<accelerator name="func2" location="func2.cpp" clkid="2">
  <hlsfiles name="func2_helper_a.cpp/>
  <hlsfiles name="func2_helper_b.cpp/>
</accelerator>

<compiler> element

The optional <compiler> element defines application project settings for the compiler when creating a new project. The inferredOptions attribute defines compiler options required to build the application and appears in the SDx Environment C/C++ Build Settings dialog as compiler Inferred Options under Software Platform.

The following example will result in SDSoC adding the compiler option -D MYAPPMACRO when creating the new project.

<compiler inferredOptions="-D MYAPPMACRO"/>

<linker> element

The optional <linker> element defines application project settings for the linker when creating a new project. The inferredOptions attribute defines linker options required to build the application and appears in the SDx Environment C/C++ Build Settings dialog as linker Miscellaneous options.

The following example will result in SDx adding the linker option -poll-mode 1 when creating the new project.

<linker inferredOptions="-poll-mode 1"/>