Getting Started with Examples

All Xilinx® SDx™ environments are provided with example designs. These examples can:

  • Be a useful learning tool for both the SDx IDE and compilation flows such as makefile flows.
  • Help you quickly get started in creating a new application project.
  • Demonstrate useful coding styles.
  • Highlight important optimization techniques.

Every platform provided within the SDx environment contains sample designs to get you started, and are accessible through the project creation flow as described in Creating an Application Project. Furthermore, each of these designs, which are found in <SDx_Install_Dir>/samples provides a makefile so you can build, emulate, and run the code working entirely on the command line if you prefer.

Many example designs and tutorials can be downloaded from the Xilinx GitHub repository. The example design repository contains the latest examples to get you started with application optimization targeting Xilinx PCIe® FPGA acceleration boards. All examples are ready to be compiled and executed on SDAccel™ supported boards and accelerated cloud service partners.

In addition, the tutorial repository provides step-by-step instructions on a range of topics including building an application, emulation, along with advanced topics such as mixing C++ and RTL kernels, and optimizing host code.

Installing Examples

Select a template for new projects when working through the New SDx Project wizard. You can also load template projects from within an existing project, by selecting Xilinx > SDx Examples.

Figure: SDSoC Examples – Empty



The left side of the dialog box shows SDSoC™ Examples, and has a download command for each category. The right side of the dialog box shows the directory to where the examples downloaded and the URL from where the examples are downloaded. Customizing the location of the download directory is accomplished using the directions in the Using Local Copies section.

Click Download next to SDSoC Examples to download the examples and populate the dialog box. The examples are downloaded as shown in the following figure.

Figure: SDSoC Examples – Populated



The command menu at the bottom left of the SDx Examples dialog box provides two commands to manage the repository of examples:
Refresh
Refreshes the list of downloaded examples to download any updates from the GitHub repository.
Reset
Deletes the downloaded examples from the .Xilinx folder.
Note: Corporate firewalls can restrict outbound connections. Specific proxy settings might be necessary.

Using Local Copies

While you must download the examples to add Templates when you create new projects, the SDx IDE always downloads the examples into your local .Xilinx/SDx/<version> folder:

  • On Windows: C:\Users\<user_name>\.Xilinx\SDx\<version>
  • On Linux: ~/.Xilinx/SDx/<version>

The download directory cannot be changed from the SDx Examples dialog box. You might want to download the example files to a different location from the .Xilinx folder. To perform this, use the git command from a command shell to specify a new destination folder for the downloaded examples:

git clone https://github.com/Xilinx/SDSoC_Examples 
<workspace>/examples

When you clone the examples using the git command as shown above, you can use the example files as a resource for application and kernel code to use in your own projects. However, many of the files use include statements to include other example files that are managed in the makefiles of the various examples. These include files are automatically populated into the src folder of a project when the Template is added through the New SDx Project wizard. To make the files local, locate the files and manually make them local to your project.

You can find the needed files by searching for the file from the location of the cloned repository. For example, you can run the following command from the examples folder to find the xcl2.hpp file needed for the vadd example:

find -name xcl2.hpp

C++ Design Libraries

A number of design libraries are provided with the SDSoC environment installation. The C libraries allow common hardware design constructs and functions to be modeled in C and synthesized to RTL. The following C libraries are provided:

  • GitHub xfOpenCV
  • Arbitrary Precision Data Types
  • HLS Stream
  • HLS Math
  • HLS Video
  • HLS IP
  • HLS Linear Algebra
  • HLS DSP

You can use each of the C/C++ libraries in your design by including the library header file. These header files are located in the include directory in the SDSoC environment installation area (<Vivado_Install_Dir>/include).

IMPORTANT: The header files for the Vivado® HLS C/C++ libraries do not have to be in the include path if the C++ code is used in the SDSoC environment.

Wrapping HLS Functions

Many of the functions in the Vivado HLS source code libraries included in the SDSoC environment do not comply with the SDSoC environment coding guidelines. To use these libraries in the SDSoC environment, you typically have to wrap the functions to insulate the system compilers from non-portable data types or unsupported language constructs.

The Synthesizeable FIR Filter example demonstrates a standard idiom to use such a library function that computes a finite-impulse response digital filter. This example uses a filter class constructor and operator to create and perform sample-based filtering. To use this class within the SDSoC environment, the example wraps within a function wrapper as follows:
void cpp_FIR(data_t x, data_t *ret)
{
    static CF<coef_t, data_t, acc_t> fir1;
    *ret = fir1(x);
}

This wrapper function becomes the top-level hardware function that can be invoked from application code.

See also: Coding Guidelines.