Sample Applications

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"

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",
  ]

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

"type" : "library"

The board attribute 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 board need not be specified.

"board" : [
    "zc702",
    "zc706"
]

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"
]

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

"runtime" : [
    "C/C++"
]

The optional Accelerators attribute is a list of hardware functions that will be set up when creating a new project. The Accelerators attribute includes several required and optional sub-tags:

• name: A required value that specifies the name of the function.
• location A 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. The SDSoC environment invokes Vivado® HLS to compile the source file containing the function. If the source file depends on functions contained in additional source files, use hlsfile to specify those source files.

The following example specifies two functions to move to hardware func1 and func2 when 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"
        ]
    }
]

The compiler attribute 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 the sds++ compiler using the -I flags.
• 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 the SDx environment C/C++ Build Settings dialog box as compiler Inferred Options under the software platform.
• symbols: Defines a list of pre-processor symbols. This is an alternative to options when you want the symbols to show in the symbols list in the Eclipse project build settings.

The following example results in the SDSoC environment adding the flags -I"../src/myinclude" -I"../src/dir/include", and the compiler option -D MYAPPMACRO, to the compiler command:

"compiler" : {
    "includepaths” : [
        "myinclude",
        "dir/include"
    ]
    "options" : "-D MYAPPMACRO"
}

The linker attribute 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 linker node.

• 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 -L flags.
• libraries: Secifies additional libraries that are to be passed to the linker -l flags.
• 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 the SDx environment C/C++ Build Settings dialog box as linker Miscellaneous options.

  For SDSoC projects, use the sdcard attribute c to specify the sds++ -sdcard <path> option. 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 1 to the linker command line, and specifies the -sdcard path:

"linker": {
    "options" : "-poll-mode 1",
    "libraries" : [
        "mylib1"
        "mylib2"
    ],
    "librarypaths" : [
        "mylibrary"
    ]
    "sdcard" : "../sdcard"
}

The following example will result in SDSoC 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:

"exclude" : [
    "MyDir",
    "MyOtherDir",
    "MyFile.txt",
    "MyOtherFile.txt"
]

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”
}

The optional cmd_args attribute defines a custom command line when launching the SDSoC application. There are two special variables that can be used in the cmd_args:

• PROJECT is replaced with the path to the project directory.
• BUILD is replaced with the path to the build directory.

The optional revision attribute 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, typically major.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"
    }
]

The contributors attribute 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/"
    }
]