Creating an SDAccel Project

Within the SDx™ tool you can create an SDAccel™ project using the IDE GUI. The following topic shows you how to set up a SDx workspace, create an SDAccel project, and use key features of the IDE.

In addition to the SDx IDE, the SDAccel environment provides a command line interface to support a scripted flow, described in Command Line Flow. For a full list of commands, see the SDx Command and Utility Reference Guide.

Using an SDx Workspace

  1. Launch the SDx IDE directly from the command line:
    $ sdx
  2. The SDx IDE opens and prompts you to select a workspace, as shown in the following figure.

    Figure: Specify the SDx Workspace

IMPORTANT: When opening a new shell to enter an SDx command, ensure that you first source the settings64 and setup scripts to set up the tool environment. See the SDAccel Environment Release Notes, Installation, and Licensing Guide (UG1238) for more information.
IMPORTANT: If you use a single computer to perform both development and deployment, be sure to open separate terminals for running the SDx tools and thexbutil board installation utility. Running both tools from the same terminal adversely affects the environment variables and causes tool issues.

The SDx workspace is the folder that stores your projects, source files, and results while working in the tool. You can define separate workspaces for each project or have workspaces for different types of projects. The following instructions show you how to define a workspace for an SDAccel project.

  1. Click the Browse button to navigate to, and specify, the workspace, or type the appropriate path in the Workspace field.
  2. Select the Use this as the default and do not ask again check box to set the specified workspace as your default choice and eliminate this dialog box in subsequent uses of SDx.
  3. Click Launch.
    TIP: You can change the current workspace from within the SDx IDE by selecting File > Switch Workspace.

You have now created an SDx workspace and can populate the workspace with projects. Platform and application projects are created to describe the SDx tool flow for creating an SDAccel platform.

Creating an Application Project

TIP: Example designs are provided with the SDAccel tool installation, and also on the Xilinx GitHub repository. See Getting Started with Examples for more information.
  1. After launching the SDx IDE you can create a new Project. Select File > New > SDx Application Project, or if this is the first time the SDx IDE has been launched, you can select Create Application Project on the Welcome screen.
  2. The New SDx Project wizard opens.
  3. In the Create a New SDx Application Project page, you can specify the project name as shown. Specify the name of the project in the Project name field.

    Figure: Create a New SDx Application Project

  4. The Use default location is selected by default to locate your project in a folder in the SDx workspace. You can uncheck this check box to specify that the project is created in a Location of your choice.
  5. If you specify the location, you can use Choose file system to select the default file system, or enable the Eclipse Remote File System Explorer (RSE).
    IMPORTANT: The project location cannot be a parent folder of an SDx workspace.
  6. Click Next.

The Platform dialog box, similar to the one shown in the following figure, displays the available installed platforms. For installing additional platforms, see the "Installing Platform-Specific Packages" section in SDAccel Environment Release Notes, Installation, and Licensing Guide (UG1238).

IMPORTANT: Be sure to select the right platform for your project, as subsequent processes are driven by this choice.

Figure: Specify SDAccel Platform

A platform is composed of a shell, which describes the base hardware design and the meta-data used in attaching accelerators to declared interfaces. SDAccel offers platforms for specific boards based on the following:

  • Alveo™
    • xilinx_u200
    • xilinx_u250
  • Virtex® UltraScale+™
    • vcu1525

You can add custom defined or third-party platforms into a repository. See Managing Platforms and Repositories for more information.

  1. To select the target platform for your project, select the desired platform and click Next.
  2. The System configuration page opens, as shown in the following figure. Select System configuration and Runtime from a list of those defined for the selected platform. The System Configuration defines the software environment that runs on the hardware platform. It specifies the operating system and the available runtime settings for the processors in the hardware platform.

    Figure: Specify System Configuration

  3. After selecting the System Configuration and clicking Next, the Templates page displays, as shown in the following figure. Specify an application template for your new project. The samples directory within the SDx tools installation contains multiple source code example templates.
  4. Initially, the Template dialog box has an Empty Application and a Vector Addition application. To access additional SDAccel examples, click the SDx Examples button.

    Figure: Application Templates

  5. When the SDx Examples dialog box opens, click the Download button for the SDAccel Examples. Then click OK. The downloaded examples are now listed in the Templates page.
    Note: The SDx tool might try to download the examples from a GitHub repo depending on your network configuration. Specific proxy settings might be necessary.
  6. You can use the template projects as examples to learn about the SDx tool and acceleration kernels or as a foundation for your new project. Note that you must select a template. You can select Empty Application to create a blank project into which you can import files and build your project from scratch.
  7. Click Finish to close the New SDx Project wizard and open the project.

Understanding the SDx GUI

When you open a project in the SDx IDE, the workspace is arranged in a series of different views and editors, also known as a perspective in the IDE. The tool opens with the SDx (default) perspective shown in the following figure.

Figure: SDAccel – Default Perspective

Some key views/editors in the default perspective are:

Project Explorer
Displays a file-oriented tree view of the project folders and their associated source files, plus the build files, and reports generated by the tool.
Provides a central location to view/edit settings, build and run your SDAccel application, launch profiling and debug sessions, and open reports.
Editor Area
Displays project settings, build configurations, and provides access to many commands for working with the project.
Console Area
Presents multiple views including the command console, design guidance, project properties, logs and terminal views.
Displays an outline of the current source file opened in the Editor Area.
Target Connections
Provides status for different targets connected to the SDx tool, such as the Vivado hardware server, Target Communication Framework (TCF), and quick emulator (QEMU) networking.

To close a view, click the Close button (x) on the tab of the view. To open a view, select Window > Show View and select a view. You can arrange views to suit your needs by dragging and dropping them into new locations in the IDE.

To save the arrangement of views as a perspective, select Window > Perspective > Save Perspective As. This defines different perspectives for initial project editing, report analysis, and debug for example. Any changes made without saving as a perspective are stored with the workspace. To restore the default arrangement of views, select Window > Perspective > Reset Perspective.

To open different perspectives, select Window > Perspective > Open Perspective.

To restore the SDx (default) perspective, click the SDx button on the right side of the main toolbar.

SDx Assistant

The Assistant view provides an SDx-centric project tree to manage settings, builds, run times, profile, debug, and reports. It is a companion view to the Project Explorer and is opened by default directly below the Project Explorer view.

An example view of the Assistant and its tree structure is shown below. For the expanded Emulation-HW flow, it shows the binary container contents and the debug reports including the Profile Summary, Application Timeline, and Waveform.

Figure: Assistant Tree Structure Example

Each item in the tree has a type-specific right-click menu with actions for that item. The actions can open dialogs, reports or views, start processes, or launch external tasks.

For example, right-clicking the project (mixed_c_rtl in the following example) displays the following menu:

Figure: Assistant Right-Click

TIP: If the actions are disabled/grayed out, this means the project does not have the applicable information.

Select Settings to open the Project Settings dialog box.

Figure: Project Settings

You can select the settings for the various items listed in the tree. For example, if you select the setting for the Emulation-HW build configuration, it displays the following. The Assistant makes it easy to navigate through the design objects and view/update their settings.

Figure: Emulation-HW

The View menu includes options that affect the Assistant view behavior, but do not affect project data. Select this option by left-clicking the downward pointing arrow shown in the following graphic.

Figure: Assistant View Menu

It displays the following options:

Show Reports
If checked, reports will be visible in the tree. If not checked, reports will not be shown in the tree. Reports open in the tree only when they exist in the project, usually after a project has been built or run, with specific settings.
Show Active Build Configurations Only
If checked, the tree will only show the "active" build configurations for each project. The active build configuration, in the assistant, will be the most-recently-built configuration. The active build configuration can also be changed to view the standard CDT methods (Project > Build Configurations > Set Active, or Project > Build Configurations > Manage).

When using the assistant to iterate on a specific build, it can be helpful to see only the current build configuration.

Link with Console
If checked, the build console in the Console view switches automatically to match the current selection in the Assistant tree, if the selection is for a build configuration, or a descendant in the tree from a build configuration. If not checked, the console does not automatically switch when the Assistant selection changes.
Link with Guidance
If checked, the Guidance in the Console area automatically switches to match the current selection in the Assistant tree.

Figure: Assistant Link with Console View Menu

You can see that with a couple of clicks you can access many of the functions and features of the tool using the Assistant.

XOCC Linking and Compilation Options

Using the Assistant window, you can update both the xocc compile and link options. First, right-click a binary_container folder in the Assistant window and select Settings as shown below.

Figure: XOCC Settings from Assistant

The Binary Container Settings window is displayed as shown below. To add linker xocc options, enter the options directly into the XOCC linker options field. Your added options are updated in the makefile (located under the Project Explorer) and applied during building. In addition, the updated options are also displayed in the XOCC Linker Command Line box for convenience.

Figure: XOCC Linker Options

The xocc linker options differ slightly between the Emulation-HW, Emulation-SW, and System configurations. Specifically, the target (-t option) matches the respective configuration and debugging is not enabled in the System configuration.

To add xocc compile options to a particular kernel, click the desired kernel under the binary_container folder. For instance, in the image below, kernel krnl_vadd has been selected under the System configuration. Compile options can be entered directly into the XOCC compile options field. Your added options are only applied to that kernel and not shared across kernels. The XOCC Compiler Command Line displays the updated options.

Figure: XOCC Compiler Options

There are options to set the number of instances (Compute Units) of the kernel and for setting the port data width. When modifying these options, the associated xocc compile option is automatically generated and added to the xocc compiler command line for you.

Similar to the xocc linker options, the compiler options differ slightly between the Emulation-HW, Emulation-SW, and System configurations. Specifically, the target (-t option) matches the respective configuration and debugging is not enabled in the System configuration.

For Emulation-HW and System configurations, a Compute Unit Settings area is also displayed (outlined in yellow in the above image) which allows additional linker and compile options to be set. Since none of the additional options apply to Emulation-SW, the Compute Unit Settings area is not displayed for this configuration.

For Emulation-HW configuration, only Memory and SLR (see Super Logic Region for explanation of SLR) allocation options are displayed. However, for System configuration, additional protocol checker and profiling logic options are displayed. Depending on the options selected, this results in updates to both the xocc linker and compile options.

SDx Project Export and Import

SDx provides a simplified method for exporting/importing one or more SDx projects within your workspace. You can optionally include associated project build folders.

Exporting an SDx Project

When exporting a project, it archives the project in a zip file with all the relevant files necessary to import into another workspace.
  1. To export a project, select File > Export from the main menu.
  2. When the Export wizard opens, select the Project to import under the folder, as shown in the following figure, and click Next.

    Figure: Select Export Wizard

  3. When the Export SDx Projects window opens, the projects in the workspace will be displayed as shown in the following figure. Select the desired projects to be included in the archive by checking the respective check boxes. Enter the name of the archive file and the directory location to where you wish to save the file. In addition, you can optionally include the associated project build folders in the archive by checking the Include build folders check box. The build folders include all the build related files including reports and bit files for example.
  4. Click Finish to save the archive zip file.

    Figure: Export Filename Build Folder

    The SDx projects have been successfully archived and can be imported into a different workspace.

Importing an SDx Project

  1. To import an SDx project, select File > Import from the top menu.
  2. From the Import window, select the SDx Project import wizard under the Xilinx folder as shown in the following figure and click Next.

    Figure: Import Select an Import Wizard

  3. This opens the Import Projects window to select the import file type. Select the SDx project exported zip file shown in the following figure and click Next.

    Figure: Import Projects – Import Type

  4. This opens the Import SDx Projects window.
  5. Browse and select the desired archive file. It will display the archived projects.
  6. Select the projects to import using the check boxes and click Next. In the following figure both projects are selected for import.
  7. Click Finish to import the projects into your workspace.

    Figure: Import Archive Filename

Adding Sources

A project consists of many different sources including those for host application code, kernel functions and even pre-compiled .xo files. With the project open in the SDx IDE, you can add these source files to the project by left-clicking the import sources icon in the Project Explorer. This displays the Import Sources dialog box shown in the following image.

Figure: Import Sources Dialog Box

  1. In the dialog box, click Browse to select the directory from which you want to import sources. Select the desired sources and click Finish.
  2. The source files in that directory will be displayed. Select the desired sources to import by selecting the appropriate check boxes and click Finish. In the following image C/C++, OpenCL™ and header files will be imported into the project.
    IMPORTANT: When you import source files into a workspace, it copies the file into the workspace. Any changes to the files are lost if you delete the workspace.
  3. Similarly you can import compiled kernels (.xo files) into the project through the Import Sources selection. In the following image, the krnl_vadd.xo file will be imported into the project.

    Figure: Import .xo Sources

  4. In addition to importing sources, you can also create and edit new source files in the GUI. With the project open in the SDx IDE, right-click the src folder and select New > File as shown in the following image.

    Figure: New File Select

  5. Select the folder in which to create the new file and enter a file name as shown in the image below. Click Finish to add the file to the project.

    Figure: New File Name

  6. After adding source files to your project, you are ready to begin configuring, compiling, and running the application. You can open a source file by expanding the src folder in the Project Explorer and double-clicking on the file.