Sample Applications

Optionally, a platform can include sample applications to demonstrate the usage of the platform. Sample applications can be provided in thesamplesdirectory of a platform. Each sample application is located in a sub-directory of thesamplesdirectory, as illustrated inDirectory Structure for a Typical SDSoC Platform, and is described by adescription.jsonfile.

The following is an exampledescription.jsonfor thearray_copysample application in the Arty platform found in the/samples/platforms/arty/samples/arty_arraycopyfolder.

{ "example": "Arraycopy", "overview": "Implementation of an array copy core that simply reads from one array and writes to another. By default the function arraycopy() is marked for hardware and you can build the project." "board": [ "arty" ], "os": [ "Standalone" ], "runtime": [ "C/C++" ], "accelerators": [ { "name": "arraycopy", "location": "arraycopy.cpp" } ], "contributors" : [ { "group" : "Xilinx, Inc.", "url" : "http://www.xilinx.com" } ], "revision" : [ { "date" : "2018", "version" : "1.0", "description" : "Initial revision" } ] }
The description.jsonfile is in JSONformat and consists of comma-separated key-value pairs, and JSONvalues can be strings, arrays, or nested JSONobjects. The example above includes the following information:
  • Name and description: The example (name) is required, but the overview (description) is recommended.
  • Platform: The board is optional, but the OS and runtime are required.
  • Accelerators: Required to specify the hardware function name and the location of the source code file.
  • Contributors: Optionally identifies the name and description of the source code provider.
  • Revision: Optionally specifies version information.

The following table shows a complete list of the available attributes.

Table 1.Description.JSON Attributes
Attribute Description
"example" Name displayed in the GUI.
"overview" Description displayed in the GUI.
"type" Used to identify library projects vs application projects.
"board" List of supported platforms; if specified, project platform must match an entry in the list.
"os" List of supported operating systems.
"runtime" List of supported runtime environments.
"accelerators" List of hardware function names and source files.
"exclude" List of files and directories that should not be copied into the example project.
"compiler" Settings to specify compiler options and include directories.
"linker" Settings to specify linker options, library paths, and libraries.
"system" System-level settings.
"cmd_args" Command line arguments used when launching the GUI.
"revision" A list of revisions.
"contributors" A list of contributors/authors for the example.

Example

The "example"attribute defines the name of the sample application to show in the SDx™GUI. It should be descriptive, but not overly long. 
"example" : "Array Copy"

Overview

The "overview"attribute is a longer text description of the sample application. The value can be either a single string, or an array of strings.
  • Single string:
    "overview" : "Shows a __median filter__ function accelerated in hardware."
  • Array of strings:
    "overview" : [ "This is the first line of the description.", "The description supports limited Markdown syntax,", "including __bold__, _italics_, and ~~strikethrough~~.", "- list item 1", "- list item 2", ]
TIP:The description supports limited Markdown syntax, including bold, italic, and numbered or bulleted lists.

Type

The optional typeattribute identifies whether this example creates an application project or a library project. If the typevalue is set to library, this example creates a shared library project. Otherwise, it creates an application project. 
"type" : "library"

Board

The boardattribute lists all development board platforms this example is compatible with. If omitted, this example is available for any platform. The sample application will be available if the current platform matches any of the values in the list. If the example is included with a custom platform, the example is available for the custom platform only, and boardneed not be specified. 
"board" : [ "zc702", "zc706" ]

Operating System (OS)

Theosattribute defines an operating system match for the selectedSDSoC™platform. TheOSvalue is a list of supported operating systems including Linux, Standalone, and FreeRTOS. The sample application will be available if the current operating system matches any of the values in the list.

The following example defines an application that can be selected when any of Linux, Standalone, or FreeRTOS are selected as the operating system: 
"os" : [ "Linux", "Standalone", "FreeRTOS" ]

Runtime

Theruntimeattribute defines the runtime environments supported by this example is C/C++. The sample application will be available if the run time of the project matches any of the values in the list. For example, an example might work for the OpenCL runtime, and not work for the C/C++ runtime.

The following example defines an application that can be selected when the run time is C/C++: 
"runtime" : [ "C/C++" ]

Accelerators

The optional Acceleratorsattribute is a list of hardware functions that will be set up when creating a new project. The Acceleratorsattribute includes several required and optional sub-tags:
  • name: A required value that specifies the name of the function.
  • locationA required value that specifies the path to the source file containing the function. The path is relative to the sample application folder in the platform.
  • clkid: An optional values that specifies the accelerator clock to use instead of the default.
  • hlsfiles: A optional value that specifies a list of additional files to compile along with the source file, when the accelerator calls code found in other files. TheSDSoCenvironment invokesVivado®HLS to compile the source file containing the function. If the source file depends on functions contained in additional source files, usehlsfileto specify those source files.
The following example specifies two functions to move to hardware func1and func2when creating the new project: 
"accelerators" : [ { "name" : "func1", "location" : "func1.cpp" }, { "name" : "func2", "location" : "func2.cpp", "clkid” : "2", "hlsfiles" : [ "func2_helper_a.cpp", "func2_helper_b.cpp" ] } ]

Compiler

The compilerattribute is optional, and is used to specify the following compiler options:
  • includepaths: Defines a set of paths relative to the sample application folder that are passed to thesds++compiler using the-Iflags.
  • options: Defines application project settings for the compiler when creating a new project. The value defines compiler options required to build the application and appears in theSDxenvironment C/C++ Build Settings dialog box as compilerInferred Optionsunder the software platform.
  • symbols: Defines a list of pre-processor symbols. This is an alternative tooptionswhen you want the symbols to show in the symbols list in the Eclipse project build settings.
The following example results in the SDSoCenvironment adding the flags -I"../src/myinclude" -I"../src/dir/include", and the compiler option -D MYAPPMACRO, to the compilercommand: 
"compiler" : { "includepaths” : [ "myinclude", "dir/include" ] "options" : "-D MYAPPMACRO" }

Linker

The linkerattribute is optional, and is used to add directories to the link path, and add libraries to be linked. When using multiple linker settings, they should be added to the same linkernode.
  • librarypaths: Specifies a list of paths relative to the application build directory (which is the location of the compiled application). The specified paths are passed to the linker using-Lflags.
  • libraries: Secifies additional libraries that are to be passed to the linker-lflags.
  • options: Defines application project settings for the linker when creating a new project. The value defines linker options required to build the application and shows in theSDxenvironment C/C++ Build Settings dialog box as linkerMiscellaneousoptions.

    ForSDSoCprojects, use thesdcardattribute c to specify thesds++ -sdcardoption. The SD card path is relative to the build directory:

The following settings add the flags -lmylib1 -lmylib2, and -L"mylibrary", and add the linker option -poll-mode 1to the linker command line, and specifies the -sdcardpath: 
"linker": { "options" : "-poll-mode 1", "libraries" : [ "mylib1" "mylib2" ], "librarypaths" : [ "mylibrary" ] "sdcard" : "../sdcard" }

Exclude

Theexcludeattribute defines a set of directories and files to be excluded from being copied whenSDxcreates the new project. This lets you have files or directories in the sample application folder that are not used to build the application.

The following example will result in SDSoCnot making a copy of directories MyDirand MyOtherDirwhen creating the new project. It will also not make a copy of files MyFile.txtand MyOtherFile.txt: 
"exclude" : [ "MyDir", "MyOtherDir", "MyFile.txt", "MyOtherFile.txt" ]

System

The optionalsystemattribute defines application project settings for the system when creating a new project. Thedmclkidattribute defines the data motion clock ID. If thesystemattribute is not specified, the data motion clock uses the default clock ID.

The following example will result in SDxsetting the data motion clock ID to 2 instead of the default clock ID when creating the new project: 
"system" : { "dmclkid" : “2” }

cmd_args

The optional cmd_argsattribute defines a custom command line when launching the SDSoCapplication. There are two special variables that can be used in the cmd_args:
  • PROJECTis replaced with the path to the project directory.
  • BUILDis replaced with the path to the build directory.

These variables can be used to specify project-rooted data files, or build-output files.

Revision

The optional revisionattribute provides the revision of the sample application, and with some limited revision history. The attribute includes several optional sub-tags:
  • date: A user-meaningful string representing a date for the sample application.
  • version: A string representing the version of the application as a period-delimited string of numbers, typicallymajor.minor[.update]. For example: 1.0, or 2.5.1. If a sample application lists multiple versions, the highest number is considered the most recent version.
  • description: Astring providing a brief description of the revision.
The following provides a brief revision history of the sample application: 
"revision" : [ { "date" : "2017", "version" : "1.2", "description" : "Updated the example for the 17.1 release" }, { "date" : "2018", "version" : "1.0", "description" : "original release" } ]

Contributors

The contributorsattribute is a list of contributors to the example, including the following sub-tags:
  • group: A string specifying the name of the sample application developer.
  • url: Specifies a URL for the contributor.
The following is an example: 
"contributors" : [ { "group" : "Xilinx, Inc.", "url" : "http://www.xilinx.com/" } ]