sdx command and utility reference guide (ug1279) · sdx command and utility reference guide ug1279...

SDx Command and UtilityReference Guide

UG1279 (v2018.2) June 6, 2018

ATTENTION! SDAccel Development Environment 2018.2 XDF users: Click here to view the 2018.2.xdf version of this guide.

https://www.xilinx.com

https://www.xilinx.com/support/documentation/sw_manuals/xilinx2018_2_xdf/ug1279-sdx-command-utility-reference-guide.pdf

Revision HistoryThe following table shows the revision history for this document.

Section Revision Summary06/06/2018 Version 2018.2

General updates Initial Xilinx release.

Revision History

UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text]SDx Command and Utility Reference Manual 2Send Feedback


https://www.xilinx.com/about/feedback.html?docType=Reference_Guide&docId=UG1279&Title=SDx%20Command%20and%20Utility%20Reference%20Guide%20%28UG1279%29&releaseVersion=2018.2&docPage=2

Table of ContentsRevision History...............................................................................................................2

Chapter 1: Introduction.............................................................................................. 5

Chapter 2: Configuring Command Settings in the SDx GUI....................6Using the Assistant View............................................................................................................ 6Configuring SDSoC Commands in the SDx IDE....................................................................... 7Configuring SDAccel Commands in the SDx IDE...................................................................15

Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility..34XOCC Common Options........................................................................................................... 35XOCC Options for Compile Mode............................................................................................ 39XOCC Options for Link Mode................................................................................................... 40XP Parameters........................................................................................................................... 42Using the Message Rule File.................................................................................................... 45

Chapter 4: SDSCC/SDS++ Compiler Commands............................................48Command Synopsis.................................................................................................................. 48General Options........................................................................................................................ 50Hardware Function Options.....................................................................................................51SDSCC/SDS++ Performance Estimation Flow Options..........................................................54Compiler Macros....................................................................................................................... 55System Options..........................................................................................................................56Compiler Toolchain Support.................................................................................................... 61

Chapter 5: emconfigutil (Emulation Configuration) Utility................. 64

Chapter 6: xbinst (Xilinx Board Installation) Utility................................. 66

Chapter 7: xbsak (Xilinx Board Swiss Army Knife) Utility......................68xbsak Commands and Options............................................................................................... 68Requirements for Boot Function of xbsak............................................................................. 71




Chapter 8: sdx_pack Utility......................................................................................73

Appendix A: Clock ID Values by Platform....................................................... 76

Appendix B: Additional Resources and Legal Notices............................. 78Xilinx Resources.........................................................................................................................78Documentation Navigator and Design Hubs.........................................................................78References..................................................................................................................................79Training Resources....................................................................................................................79Please Read: Important Legal Notices................................................................................... 80




Chapter 1

IntroductionThe Xilinx® SDx tools, including the SDAccel™ and SDSoC™ environment, provide command-lineutilities and a graphical Integrated Development Environment (IDE). The tools and commandsprovided enable the development of designs similar to a software-based design flow, where thesource code is first compiled and then linked against each other. This flow applies to the hostapplication as well as the hardware kernels in the FPGA.

The commands and utilities described in this guide are:

• XOCC Compiler (xocc): The Xilinx OpenCL™ compiler (xocc) is a command line utility forcompiling kernel accelerator functions and linking them with the SDAccel environmentsupported platforms.

• SDSCC/SDS++ System Compilers: The SDSCC/SDS++ system compilers compile and link C/C++ source files into an application-specific hardware/software system-on-chip (SoC), targetingembedded Arm Cortex-A9, A53, and R5 CPUs with programmable logic hardwareaccelerators.

• Emulation Configuration Utility (emconfigutil): The emulation configuration utility(emconfigutil) is used to automate the creation of the emulation configuration file.

• Xilinx Board Installation Utility (xbinst): The Xilinx board installation utility (xbinst) is usedto install and generate all necessary files for the platform support package for the FPGA card.

• Xilinx Board Swiss Army Knife Utility (xbsak): The Xilinx Board Swiss Army Knife utility(xbsak) is a command line utility used to perform various board administration and debugtasks independent of the SDAccel runtime library, and for the SDAccel tools installation.

• SDSoC Utility (sdx_pack): The sdx_pack utility allows for publishing RTL IP as a C library(.a file). For use by software developers.

This document provides a reference for commands, syntax, and the various options that areavailable for each of the utilities. Some of the settings can be configured through the SDx GUI orusing command line options. The xbinst, xbsak and sdx_pack utilities are only availablethrough the command line.




Chapter 2

Configuring Command Settings inthe SDx GUI

The SDx™ GUI provides different views for you to manage projects and builds, debug the design,view the design, and analyze the design. The Assistant view can be used as your primaryinterface to the various build configurations of a project. It is open by default in the lower-leftcorner of the SDx™ IDE.

TIP: Because the SDx IDE is based on Eclipse, many of the dialog boxes and settings are standardoptions available through the Eclipse environment. You can find help on the C/C++ developmentenvironment in Eclipse at: https://help.eclipse.org/oxygen/index.jsp

Using the Assistant ViewThe Assistant provides quick and easy access to all aspects of building and managing the project.Right-click an item in this view to see the available actions.

The Assistant view is arranged by project. If multiple projects are present in the workspace, theyare present in the Assistant pane.

Chapter 2: Configuring Command Settings in the SDx GUI


https://help.eclipse.org/oxygen/index.jsp



Figure 1: Assistant View

• Show Reports: Enables the display of reports in the Assistant window

• Show Active Build Configurations Only: Checking this option will hide any build configurationthat isn't active, and could be useful if you have created a lot of different build configurations.

• Link with Console: When you select a build configuration in the Assistant window, theconsole for that configuration will be made active as well.

• Link with Guidance: The Guidance window will update to show information for the buildconfiguration selected in the Assistant view.

Configuring SDSoC Commands in the SDxIDEThe SDx™ GUI provides different views for you to manage SDSoC™ projects and builds, debugthe design, view the design, and analyze the design.

The Assistant view in the SDx GUI shows the project and all of the build configurations that arepart of the project. See Using the Assistant View.

The following sections describe the options and settings that are available through the GUI.





SDSoC Project SettingsTo edit the SDSoC™ project settings, select the project in the Assistant view, and click the

Settings icon ( ) to bring up the Project Settings window.

Figure 2: SDSoC Project Settings Dialog Box

Project Settings provides quick access to the project settings via the Project name: link. TheProject flow: link will take you to the www.xilinx.com page for the SDSoC flow. You can changethe platform, and the system configuration for the current project using the browse button.



http://www.xilinx.com

https://www.xilinx.com/products/design-tools/software-zone/sdsoc.html



SDSoC Build Configuration SettingsBuild Configuration Settings

To edit the settings for any of the build configurations under the project, select a specific build

configuration in the Assistant view and click the Settings icon ( ) to bring up the window withthe build configurations.

Figure 3: Build Configuration Settings





The Build Configuration Settings dialog provides a convenient way to make adjustments to yourbuild configuration. You can change the build target, choose analysis like performance estimation,and event tracing, and specify the root function in order to exclude certain code fromperformance estimation. See SDSoC Environment Getting Started Tutorial (UG1028) for moreinformation on using these options.

TIP: Hold the mouse over a setting to display an informative tooltip about what that setting does.

The Data motion network clock frequency drop down shows available values for the clockfrequency in between the platform and hardware accelerated functions. For more information onthis see SDSoC Environment User Guide (UG1027).

Use the Generate SD card image option to copy the files required to allow booting your boardfrom an SD Card.

Finally, the Edit Toolchain Settings link at the bottom of the dialog box will take you to thecompiler and linker settings that allow you to modify include directories, specify additionallibraries and change command line options, for the active configuration. Many other settings arealso available from the Toolchain Settings dialog.

SDSoC Toolchain SettingsToolchain Settings

The toolchain settings allow you to access and specify C/C++ build settings in the SDSoC GUI.Click the link Edit Toolchain Settings at the bottom of the build configuration window to bring upthe Settings window containing all of the C/C++ build settings.

Figure 4: Toolchain Settings

When you are working in an SDSoC project, the three main settings are:

• SDSCC Compiler



https://github.com/Xilinx/SDSoC-Tutorials/blob/master/getting-started-tutorial/README.md

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1027-sdsoc-user-guide.pdf



• SDS++ Compiler

• SDS++ Linker

SDSCC Compiler and SDS++ Compiler CommandOptionsSDSCC Compiler and SDS++ Compiler Command Options

The SDSCC Compiler and SDS++ Compiler sections show the sdscc and sds++ commands andany additional options that need to be passed when calling the compiler.

Figure 5: Compiler Command Options

Compiler Symbols Settings

Click Symbols under SDSCC Compiler or SDS++ Compiler to define any symbols that are passedwith the –D option when calling sdscc or sds++.

You can have multiple symbols, which are added by clicking the add ( ) icon.

Figure 6: Enter Value for Symbols

Compiler Warnings Settings

Command options related to compiler warnings are provided through the Warnings section.





Figure 7: Compiler Warnings Settings

Compiler Optimization Settings

Compiler optimization flags and other optimization settings can be specified in this section.

Figure 8: Compiler Optimization Settings

Compiler Debugging Settings

Debug Level and other debugging flags are specified through this section in the GUI.

Figure 9: Compiler Debugging Settings

Compiler Profiling Settings

Profiling can be enabled with the Profiling option.

Compiler Directories Settings

Include paths for the SDSCC and SDS++ compiler are added under the Directories option.

Compiler Miscellaneous Settings

Any other flags that need to be passed to the sdscc compiler or the sds++ compiler are addedto the Miscellaneous section.





Figure 10: Compiler Miscellaneous Settings

Inferred OptionsInferred Options

Software platform inferred flags and software platform include paths are added under theInferred Options section.

Figure 11: Inferred Options

SDS++ Linker SettingsSDS++ Linker General Settings

Some general setting for the SDS++ linker are specified in this section.

Figure 12: SDS++ Linker General Settings





The SDS++ Linker section shows the sds++ command and any additional options to be passedwhen calling sds++ for the linker stage.

Figure 13: SDS++ Linker Settings

SDS++ Linker Libraries Settings

Libraries for the SDS++ linker are added to the Libraries section.

Figure 14: SDS++ Linker Libraries Settings

SDS++ Linker Miscellaneous Settings

Any other flags that needs to be passed to the SDS++ Linker can be provided through theMiscellaneous section.

Figure 15: SDS++ Linker Miscellaneous Settings

SDS++ Linker Script Settings

The path and file name of the linker script is provided in the Linker Script field.





Figure 16: SDS++ Linker Script Settings

SDS++ Linker Inferred Options

Software platform inferred flags are added under the Inferred Options section.

Figure 17: SDS++ Linker Inferred Options

Configuring SDAccel Commands in the SDxIDEThe SDx™ GUI provides different views for you to manage SDAccel™ projects and builds, debugthe design, view the design, and analyze the design.

The Assistant view in the SDx GUI shows the project and all of the build configurations that arepart of the project.





Figure 18: SDAccel Assistant View Project Options

The Assistant provides quick and easy access to all aspects of building and managing the project.Right-click an item in this view to see the available actions.

• Settings: Edit/review the project settings.

• Add Build Configuration: Add a new Build Configuration to the project.

• RTL Kernel Wizard: Open the RTL Kernel Wizard to package RTL IP for use in this project.

• Build All: Build the active build configuration associated with this project.

• Open in Project Explorer: View the project in the Project Explorer pane.

• Export SDx Project: Export this project.

• Delete: Delete this project.

The Assistant view is arranged by project. If multiple projects are present in the workspace, theyare present in the Assistant pane.

Select the Build Container by right-clicking the mouse, which shows the actions on a container.





Note: This view of the Assistant shows System Estimate reports, which are available inside the binarycontainers after the build is complete.

Figure 19: SDAccel Assistant View Container Options

• Settings: Edit/Review the build settings.

• Duplicate: Duplicate this Build Configuration. You are prompted for a new name for the BuildConfiguration.

• Add Binary Container: Add a new Binary Container to this Build Configuration.

• Add Hardware Function: Specify a function to be implemented in hardware for this BuildConfiguration.

• Build: Build everything associated with this Build Configuration.

• Clean: Remove all existing builds from this container.

• Terminate: Halt any build operation currently in progress with this container.

• Run: Run this project.





• Debug: Debug this project. This option switches the view to the Debug perspective.

• Show Console: This option activates the Console pane and brings it to the front.

• Show Guidance: This option activates the Guidance pane and brings it to the front.

• Open in Project Explorer: View this object in the Project Explorer pane.

• Delete: Delete this project.

SDAccel Project SettingsSDAccel Project Settings

To edit the SDAccel project settings, click the project in the Assistant view and click the Settings

icon ( ) to bring up the project Settings window.

Figure 20: SDAccel Project Settings

• Project Name: Name of the project. Click the link to open a summary of the project.

• Project Flow: Specify if this is an SDAccel or SDSoC project. Click the link to open a summaryof the design environment at https://www.xilinx.com.



https://www.xilinx.com/



• Platform: Target platform for this project. Click the link to open the platform summary. Clickthe browse icon to change the platform.

• Runtime: Runtime management used in this project.

• System Configuration: OS targeted by this project.

• Number of Devices: Specify the number of devices used for emulation.

• XOCC Compiler Options: XOCC Compile options are specified and listed here.

• XOCC Linker Options: XOCC Link options are specified and listed here.

SDAccel Build Configuration SettingsTo edit the settings for any of the build configurations under the project, select the buildconfiguration in the Assistant view and click the Settings icon to bring up the window with thebuild configurations.

Figure 21: Build Configuration Settings

• Target: The Build Configuration target

• Host Debug: Select to enable debug of the host code.





• Kernel Debug: Select to enable debug of the kernel code.

• Report Type: This option specifies whether to generate a report of system estimates duringEmulation-SW build or not. The default is to not generate any reports. This option calls theHLS Compiler and might result in a longer build execution time. This option is only available inthe Build Configuration Emulation-SW.

• Hardware Optimization: This option specifies how much effort to use on optimizing thehardware. Hardware optimization is a compute intensive task. Higher levels of optimizationmight result in more optimal hardware but with increased build time. This option is onlyavailable in the Build Configuration System.

The Build Configuration window also contains links to the Compiler and Linker Toolchainsettings. These provide complete information on all the settings in a standard Eclipseenvironment view. SDAccel™ specific settings, such as the XOCC compiler and linker flags, whichare not part of the standard C/C++ toolchain, are provided in the Miscellaneous tab.





SDAccel Binary Container SettingsBinary Container Settings

To edit the settings for any of the binary containers under the project, select the binary containerin the Assistant view and click the Settings icon to bring up the window with the buildconfigurations.

Figure 22: Binary Container Settings

• Name: Binary container name.

• XOCC Linker Options: XOCC link options for this binary container are specified and listedhere.





SDAccel Hardware Function SettingsTo edit the settings for any of the Hardware Functions under the project, select the hardwarefunction in the Assistant view and click the Settings icon to bring up the window with theHardware Function settings.

Figure 23: Hardware Function Settings

• Name: Name of the function to be implemented in hardware.

• Compute Units: Number of compute units used.

• Max Memory Ports: If selected, generate one physical memory interface for every globalmemory buffer declared in the kernel function signature. If not selected, a single physicalmemory interface is created.

• Port Data Width: Specify the width of the data port.

• Extra Source Files: Specify any additional source files required by this hardware function.

• XOCC Compiler Options: XOCC Compile options for this binary container are specified andlisted here.





• Debug and Profiling Settings: This option allows debug and profile monitors to be inserted atthe hardware function boundary to review signal traces. This option is only available in theBuild Configuration System. These monitors enable the following:

○ ChipScope Debug: Add monitors to capture hardware trace debug information.

○ Protocol Checker: Add AXI Protocol Checker.

○ Data Transfer: Add performance monitors to capture the data transferred betweencompute unit and global memory. Captured data includes counters, trace, or both.

○ Execute Profiling: Add an Accelerator monitor to capture the start and end of compute unitexecutions.

○ Stall Profiling: Add an Accelerator monitor with functionality to capture three kinds ofstalls in the flow of data:

- Inside a kernel.

- Between two kernels.

- Between kernel and external memory.





SDAccel Toolchain SettingsToolchain Settings

The toolchain settings provide a standard Eclipse-based view of the project, providing all optionsfor the C/C++ build in SDAccel™.

From the Build Configuration Settings window, click the link Edit Toolchain Compiler Settings orEdit Toolchain Linker Settings at the bottom of the Build Configuration window to bring up thecompiler and Linker Settings window containing all of the C/C++ build settings.

Figure 24: Toolchain Settings

When you are working in an SDAccel project, the four main settings under the Tool Settings tabare:

• SDx XOCC Kernel Compiler

• SDx XOCC Kernel Linker

• emconfigutil

• SDx GCC Host Compiler

• SDx GCC Host Linker





SDx XOCC Kernel Compiler OptionsSDx XOCC Kernel Compiler Options

The SDx™ XOCC Kernel Compiler section shows the xocc command and any additional optionsthat need to be passed when calling xocc for the compile stage.

Figure 25: XOCC Compiler Command Options

The xocc options can be symbols, include paths, --xp parameters, or other valid options.

XOCC Kernel Compiler Symbols Settings

Click Symbols under SDx XOCC Kernel Compiler to define any symbols that are passed with the–D option when calling xocc.

You can have multiple symbols, which are added by clicking the add ( ) icon.

Figure 26: XOCC Compiler Symbols Settings

XOCC Kernel Compiler Includes Settings

To add include paths to the xocc compiler, select Includes and click the add ( ) icon.





Figure 27: XOCC Compiler Includes Directory Settings

XOCC Miscellaneous Options

Any additional compile options that need to be passed to the xocc compiler can be added asflags in the Miscellaneous section. Refer to Chapter 3: XOCC (Xilinx OpenCL Compiler)Command Line Utility for more information on available compiler options.

Figure 28: XOCC Miscellaneous Options

SDx XOCC Kernel Linker SettingsSDx XOCC Kernel Linker Settings

The SDx XOCC Kernel Linker section shows the xocc command and any additional options to bepassed when calling xocc for the linker stage.

Figure 29: XOCC Kernel Linker Settings





XOCC Kernel Linker Miscellaneous Options

Any additional options that need to be passed to the xocc compiler can be added as flags in theMiscellaneous section. This is where you will add various linking options such as --nk, --sp, or--xp to specify the number of kernel instances, or to assign kernel interfaces to DDR banks, orto control specific implementation options for generating the kernel binary. Refer to Chapter 3:XOCC (Xilinx OpenCL Compiler) Command Line Utility for more information on these options.

Figure 30: XOCC Linker Miscellaneous Options

emconfigutil Settingsemconfigutil Settings

The emconfigutil command and options can be provided in the Command field underemconfigutil to create an emulation configuration file.

For more information on emconfigutil and its options, refer to Chapter 5: emconfigutil(Emulation Configuration) Utility.

Figure 31: emconfigutil Settings





SDx GCC Host Compiler SettingsThe compiler arguments for the SDAccel™ GCC host compiler are provided through the variousoptions available under the SDx GCC Host Compiler section of the Assistant. XCPP is an SDAccelwrapper around the underlying GCC system compiler/linkers to create a uniform front-end forthe host computer compilation.

Figure 32: GCC Host Compiler Settings

GCC Host Compiler Dialect Settings

The Dialect settings specify the command options that select the C++ language standard to use.

Figure 33: GCC Host Compiler Dialect Settings

GCC Host Compiler Preprocessor Settings

Preprocessor arguments to the host compiler such as symbol definitions can be specified usingthe Preprocessor settings.

The default symbols already defined include the platform which is passed to the compiler so thatthe host code can check for the specific platform.





Figure 34: GCC Host Compiler Preprocessor Settings

GCC Host Compiler Includes Settings

Include paths and include files are specified under the Includes section.

Figure 35: GCC Host Compiler Includes Settings

GCC Host Compiler Optimization Settings

Compiler optimization flags and other Optimization settings can be specified in this section.

Figure 36: GCC Host Compiler Optimization Settings

GCC Host Compiler Debugging Settings

Debug level and other debugging flags are specified in this section in the Assistant.





Figure 37: GCC Host Compiler Debugging Settings

GCC Host Compiler Warnings Settings

Options related to compiler warnings are provided through the Warnings section.

Figure 38: GCC Host Compiler Warnings Settings

GCC Host Compiler Miscellaneous Settings

Any other flags that are passed to the GCC Host Compiler can be provided through theMiscellaneous section.





Figure 39: GCC Host Compiler Miscellaneous Settings

SDx GCC Host Linker SettingsSDx GCC Host Linker Settings

The linker arguments for the SDAccel GCC Host Linker are provided through the optionsavailable under the SDx GCC Host Linker section of the Assistant.

Figure 40: GCC Host Linker Settings

GCC Host Linker General Settings

The general settings for the linker are specified in this section.

Figure 41: GCC Host Linker General Settings





GCC Host Linker Libraries Settings

Libraries and library search paths for the GCC Host Linker can be specified in this section.

Figure 42: GCC Host Linker Libraries Settings

GCC Host Linker Miscellaneous Settings

Any other flags that need to be passed to the GCC Host Linker can be provided through theMiscellaneous section.

Figure 43: GCC Host Compiler Miscellaneous Settings

GCC Host Linker Shared Libraries Settings

Libraries and library search paths for the GCC Host Linker can be specified in this section.





Figure 44: GCC Host Linker Shared Libraries Settings





Chapter 3

XOCC (Xilinx OpenCL Compiler)Command Line Utility

The Xilinx® OpenCL™ Compiler (xocc) is a standalone command line utility for compiling kernelaccelerator functions and linking them with the SDAccel™ environment supported platforms.This section describes the xocc link and compile commands. All commands are provided in thefollowing sections:

• XOCC Common Options

• XOCC Options for Compile Mode

• XOCC Options for Link Mode

The first activity in building any system is to select an acceleration platform supported by Xilinxor third-party providers and to compile a kernel accelerator function using the -c/--compileoption.

TIP: The default output name for the .xo file is a.xo; rename the file so that it relates to the kernel.

The -c/--compile command syntax is as follows:

xocc -c --platform <platform_name> <kernel_source_file> -o <xo_kernel_name>.xo

TIP: OpenCL uses the kernel keyword within the OpenCL file to identify a kernel. For C/C++ kernels,you need to provide the kernel name by --kernel <kernel_name>.

The second activity is to link one or more kernels into the platform to create the binary containerxclbin file using the -l/--link option.

TIP: The default output name for the xclbin file is a.xclbin; rename it as needed.

The -l/--link command syntax is as follows:

xocc -l --platform <platform_name> <xo_kernel1_name>.xo \ [<xo_kernel2_name>.xo ..] -o <xclbin_name>.xclbin

Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility




For a list of supported platforms, see the SDx Environments Release Notes, Installation, andLicensing Guide (UG1238).

IMPORTANT!: All examples in the SDAccel installation use the Makefile to compile OpenCLapplications with xcpp and xocc commands that can be used as references for compiling userapplications.

XOCC Common OptionsThe --platform option accepts either a platform name or alternatively an xpfm file name(using full or relative path) that represents the top level of a platform. This is needed when youuse a platform that is not included by default in the SDAccel™ tool installation, for example touse a Device Support Archive (DSA) and matching board.

The compile target is specified with the --target <sw_emu....> option. The default compiletarget is hw_emu.

IMPORTANT!: Do not mix the compiling for sw_emu with linking for hw_emu.

Valid values for the -t / --target switch are:

• hw (for hardware compile)

• hw_emu (for hardware emulation)

• sw_emu (for software emulation)

Table 1: XOCC Common Options (For Compile and Link Modes)

Option Valid Values Description--platform <arg> Name of supported acceleration

platform by Xilinx or full pathto .xpfm file that represents aplatform.

Required. Set the target Xilinx device. For example:

--platform xilinx_vcu1525_dynamic_5_1

For a list of all supported platforms and devices, see the SDAccel Product Page.When using a platform that is not included by default in theSDAccel tool installation, the .xpfm file that represents aplatform should be provided using the full path.

--platforminfo N/A List the supported devices.



https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1238-sdx-rnil.pdf

https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html#boardskits



Table 1: XOCC Common Options (For Compile and Link Modes) (cont'd)

Option Valid Values Description--target <arg> [sw_emu | hw_emu | hw] Specify a compile target.

• sw_emu: Software emulation

• hw_emu: Hardware emulation

• hw: Hardware

Default: hw

-o/-output <arg> File name with .xo or .xclbinextension depending on xoccmode.

Optional. Set output file name. Default:

• a.xo for compile mode

• a.xclbin for link and build mode

--version N/A Print the version and build information of XOCC.--help N/A Print help.--kernel_frequency

Frequency (MHz) of the kernel. Set a user-defined clock frequency in MHz for the kernel,overriding a default value from the DSA.

--profile_kernel data:[ kernel_name | all ]:[ compute_unit_name | all ]:[ interface_name | all ](:[ counters | all ])

[ stall | exec ]:[ kernel_name | all ]:[ compute_unit_name | all ](:[ counters | all ])

Profiling DDR memory traffic for kernel and host.The last field for trace value (counters or all) is optional.If not specified, the default value is all.For [ stall | exec ], the interface_name field is notsupported.The stall option must be specified during xocc compile (-c) to direct HLS to enable stall signals before using thisoption during xocc link (-l).

--xp Refer to XP Parameters. Specify detailed parameter and property settings in theVivado Design Suite used to implement the FPGA hardware.For example:

--xp <kernel_name>:stream

Familiarity with the Vivado Design Suite is recommended tomake the most use of these parameters.For a complete description of the --xp option, see XPParameters.

--debug N/A Generate code for debugging.--message-rules<arg>

Message rule file name Optional. Specify a message rule file with messagecontrolling rules. Fore more details, see Using the MessageRule File.

--report <arg> [estimate | system] Generate a report type specified by <arg>:

• estimate: Generate estimate report inreport_estimate.xtxt

• system: Generate the estimate report and detailedhardware reports in the report directory.

--save-temps N/A Save intermediate files/directories created during thecompilation and build process.






Option Valid Values Description--report_dir<arg>

Directory Specify a report directory. If the --report option isspecified, the default is to generate all reports in the currentworking directory (cwd).If no report directory is specified, the tool saves the files to<cwd>/_x/reports.

--log_dir <arg> Directory Specify a log directory. If the --log option is specified, thedefault is to generate the log file in the current workingdirectory (cwd).If no log directory is specified, the tool saves the files to<cwd>/_x/logs.

--temp_dir <arg> Directory Specify a temp directory. If the --save-temps option isspecified, the default is to create the temporary compilationand build files in the current working directory (cwd).If no temp directory is specified, the tool saves the files to<cwd>/_x/reports.

--export_script N/A This option allows detailed control of the Vivado DesignSuite used to implement the FPGA hardware.Familiarity with the Vivado Design Suite is recommended tomake the most use of the Tcl file generated by this option.Generates the Tcl script, <kernel_name>.tcl,used to execute Vivado HLS but halts before Vivado HLSstarts. The expectation is for the script to be modified andused with the --custom_script option.Not supported for –t sw_emu with OpenCL kernels.

--custom_script <kernel_name>:<pathto kernel Tcl file>

Intended for use with the <kernel_name>.tcl filegenerated with --export_script.This option allows you to customize the Tcl file used tocreate the kernel and execute using the customize versionof the script.

<input file> OpenCL or C/C++ kernel source file,or Xilinx object file (.xo).

Compile kernels into a.xo or a.xclbin filedepending on the xocc mode (compile or link).






Option Valid Values Description--user_ip_repo_paths <arg>

<directory> Specify the directory location of the existing user IPrepository. This value is prefixed to ip_repo_paths.Using this switch, you can specify one or more IP repositorypaths which will be given highest priority by placing thesepaths at the beginning of the overall IP_REPO_PATHSproperty for the underlying Vivado project. Any IPdefinitions from any of these paths specified that youspecify will be used ahead of IP repositories from the DSA orfrom the Xilinx catalog.Multiple --user_ip_repo_paths can be specified.The following lists show the priority order in which IPdefinitions will be found during SDx compilation flows (Highto Low). Note that all of these entries can possibly includemultiple directories in them.

• For HW flow:

1. IP definitions from --user_ip_repo_paths switch

2. Kernel IP definitions (vpl --iprepo switch value)

3. IP definitions from DSA IP repo

4. IP cache dir from Install area (e.g.<SDxInstall>/SDx/2018.2/data/cache/)

5. IP cache stored inside DSA

6. SDx Specific Xilinx IPs from install area(e.g.<SDxInstall>/SDx/2018.2/data/ip/)

7. General Xilinx IP catalog from install area (forexample,<SDxInstall>/Vivado/2018.2/data/ip/)

• For HW EMU flow:

1. IP definitions from --user_ip_repo_paths switch

2. User emulation ip repository (for example,$::env(SDX_EM_REPO))

3. Kernel IP definitions (vpl --iprepo switch value)

4. IP cache dir from Install area(e.g.<SDxInstall>/SDx/2018.2/data/cache/)

5. IP cache stored inside DSA

6. $::env(XILINX_SDX)/data/emulation/hw_em/ip_repo

7. $::env(XILINX_VIVADO)/data/emulation/hw_em/ip_repo

8. SDx Specific Xilinx IPs from install area (e.g.<SDxInstall>/SDx/2018.2/data/ip/)

9. General Xilinx IP catalog from install area(e.g.<SDxInstall>/Vivado/2018.2/data/ip/)






Option Valid Values Description--remote_ip_cache<arg>

<directory> Specify remote IP cache directory for Vivado synthesis.

--no_ip_cache N/A Turn off IP cache for Vivado synthesis.--report_level|-R 0, 1,2, estimate These Report levels have mappings kept in the optMap.xml

file. You can override the installed optMap.xml to definecustom report levels.

• (Default) The -R 0 specification turns off all intermediateDCP generation during Vivado implementation. Turnson post route timing report generation.

• The -R 1 specification turns on everything -R0 does, plusreport_failfast pre-opt_design, report_failfast post-opt_design, and all intermediate DCP generation.

• The -R 2 specification turns on everything -R1 does, plusit adds report_failfast post-route_design.

• The -R estimate forces Vivado_HLS to generate adesign.xml datafile if it does not exist, in order togenerate an estimate report. This option is useful forsoftware emulation target, when design.xml is notgenerated by default.

--reuse_impl <Implemented DCP> Import an implemented DCP, and run only the XCLBINpackaging.

--ini_file <path_to_file> Read in XP switches from file in xocc.ini format. May be usedmultiple times for multiple files. These will take priority overxocc.ini files found in default locations, but explicit --xpcommand line switches will still take priority over thosefound in the specified file.

--interactive [ synth | impl ] xocc will configure necessary environment and launchVivado® with either synthesis or implementation project.

XOCC Options for Compile ModeTable 2: XOCC Options for Compile Mode

Option Valid Values Description-c/--compile N/A Required, but mutually exclusive with --link.

Run xocc in compile mode, generate .xo file.

-k/--kernel <arg> Kernel to be compiled fromthe input .clor .c/.cpp kernel sourcecode.

Required for C/C++ kernels. Optional for OpenCLkernels.Compile/build only the specified kernel from theinput file. Only one -k option is allowed percommand.When an OpenCL kernel is compiled without the-k option, all the kernels in the input file arecompiled.





Table 2: XOCC Options for Compile Mode (cont'd)

Option Valid Values Description--define <arg> Valid macro name and

definition pair.<name>=<definition>

Predefine name as a macro with definition. Thisoption is passed to the xocc preprocessor.

--include <arg> Directory name that includesrequired header files.

Add the directory to the list of directories to besearched for header files. This option is passed tothe SDAccel compiler preprocessor.

XOCC Options for Link ModeTable 3: XOCC Options for Link Mode

Option Valid Values Description--optimize <arg> Valid optimization levels: 0, 1, 2, 3, s,

quick.example: --optimize2

This option ONLY applies to Vivado. Thecompile step runs the C code throughHLS and has no bearing.

These options control the defaultoptimizations performed by the Vivadohardware synthesis engine.Familiarity with the Vivado tool suite isrecommended to make better use ofthese settings.

• 0: Default optimization. Reducecompilation time and makedebugging produce the expectedresults.

• 1: Optimize to reduce powerconsumption. This takes more timeto compile the design.

• 2: Optimize to increase kernelspeed. This option increases bothcompilation time and theperformance of the generatedcode.

• 3: This is the highest level ofoptimization. This option providesthe highest level performance inthe generated code, butcompilation time might increaseconsiderably.

• s: Optimize for size. This reducesthe logic resources for the kernel

• quick: Quick compilation for fastrun time. This might result inreduced hardware performance,and a greater use of resources inthe hardware implementation.





Table 3: XOCC Options for Link Mode (cont'd)

Option Valid Values Description--link N/A Required, but mutually exclusive with

--compile.Run xocc in link mode. Link .xo inputfiles, generate .xclbin file.

--nk <arg> <kernel_name>: <compute_units>

For example:

foo:2

<kernel_name>:<compute_units>:<kernel_name1>.<kernel_name2>…<kernel_nameN>

For example:

foo:3:fooA.fooB.fooC

This option instantiates the specifiednumber of compute units for the givenkernel in the .xclbin file.The instance name is optional. If theinstance name is not specified, the firstinstance is named <kernel_name>_1,the second instance is named<kernel_name>_2, and so forth.Default: One compute unit per kernel.Optional in link mode. Not applicable incompile mode.

--jobs <arg> Number of parallel jobs. Optional. This option allows detailedcontrol of the Vivado Design Suite usedto implement the FPGA hardware.Familiarity with the Vivado Design Suiteis recommended to make the most useof this option.Specify the number of parallel jobs tobe passed to the Vivado Design Suitefor implementation. Increasing thenumber of jobs allows the hardwareimplementation step to spawn moreparallel processes and complete faster.

--lsf <arg> bsub command line to pass to LSFcluster.This argument is required for use with--lsf.

Optional. Use IBM Platform LoadSharing Facility (LSF) for Vivadoimplementation and synthesis. Forexample: --lsf '{bsub -R"select[type=X86_64]" -N -qmedium}'

--sp <arg> <kernel_inst_name>.<interface_name>:<bank>

Valid DDR4 bank names are bank0,bank1, bank2, and bank3 for platformswith four DDR banks.

Connect a kernel to a specific DDRbank. Multiple --sp options can bespecified to map each of the interfacesto a particular bank.For DSA 5.x and later, the --xpmisc:map_connect option isdeprecated and replaced with thesystem port --sp option with a muchsimpler syntax requiring only thekernel instance name, an interfacename of that kernel, and the targetDDR bank for the required connection.





XP ParametersWhen compiling or linking, fine grain control over the hardware generated by SDAccel™ and thehardware emulation process can be specified by using the --xp switch.

The –-xp switch is paired with parameters to configure the Vivado® tools. For instance, the --xp switch can configure optimization, placement and timing, or the switch can be used to set upemulation and compile options.

IMPORTANT!: Familiarity with the Vivado Design Suite is required to make the most use of theseparameters. See Vivado Design Suite User Guide: High-Level Synthesis (UG902) and Vivado DesignSuite User Guide: Implementation (UG904) for more information.

Parameters are specified as parm:<param_name>=<value>. For example:

xocc -–xp param:compiler.enableDSAIntegrityCheck=true –xp param:prop:kernel.foo.kernel_flags="-std=c++0x"

You can specify the -–xp command option multiple times in a single xocc invocation or specifythe value(s) in an xocc.ini file with each option specified on a separate line (without --xpswitch).

param:prop:solution.device_repo_paths=../dsaparam:compiler.preserveHlsOutput=1

Upon invocation, xocc first looks for an xocc.ini file in the $HOME/.Xilinx/sdx directory.If the file does not exist, then xocc looks for it in the current working directory. If the same --xp parameter value is specified in both the command line and xocc.ini file, the command linevalue is used.

The following table lists the -–xp parameters and their values.

Table 4: XP Parameter Options

Parameter Name Valid Values Descriptionparam:compiler.acceleratorBinaryContent

Type: StringDefault Value:<empty>

Content to insert in xclbin. Valid options arebitstream and dcp.

param:compiler.enableDSAIntegrityCheck

Type: BooleanDefault Value: FALSE

Enable the DSA Integrity Check. If this value isset to TRUE and SDAccel detects a DSA whichhas been modified outside of the Vivado DesignSuite, SDAccel halts operation.

param:compiler.errorOnHoldViolation Type: BooleanDefault Value: TRUE

Error out if there is hold violation.



https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug902-vivado-high-level-synthesis.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug904-vivado-implementation.pdf



Table 4: XP Parameter Options (cont'd)

Parameter Name Valid Values Descriptionparam:compiler.maxComputeUnits Type: Int

Default Value: -1Maximum compute units allowed in the system.Any positive value will overwrite thenumComputeUnits setting in the DSA.

param:hw_em.enableProcSyncReset Type: BooleanDefault Value: FALSE

Enable proc_sync_reset in hw_em.

param.hw_em.platformPath<absolute_path_of_custom_platform_directory>


Specify the path to the custom platformdirectory. The <platformPath> directoryshould meet the following requirements to beused in platform creation:

• The directory should contain a subdirectorycalled ip_repo.

• The directory should contain a subdirectorycalled scripts and this scriptsdirectory should contain ahw_em_util.tcl file. Thehw_em_util.tcl file should havefollowing two procedures defined in it:

○ hw_em_util::add_base_platform

○ hw_em_util::generate_simulation_scripts_and_compile

param:hw_em.compiledLibs Type: StringDefault Value:<empty>

Uses mentioned clibs for the specifiedsimulator.

param:hw_em.enableProtocolChecker Type: BooleanDefault Value: FALSE

Enable the AXI protocol checker during HWemulation. This is used to confirm the accuracyof any AXI interfaces in the design.

param:compiler.interfaceLatency Type: IntDefault Value: -1

Specify the expected latency on the kernel AXIbus, the number of clock cycles from when busaccess is requested until it is granted.

param:compiler.fsanitizestring Type: StringDefault Value:<empty>

Enable the software emulation runtime checks.Possible values are:

• address: Out of Bound Access

• memory: Uninitialized Memory Access

The software emulation run produces a debuglog: <project_dir>/Emulation-SW/<proj_name>-Default>/emulation_debug.log withemulation diagnostic messages.

param:compiler.xclDataflowFifoDepth Type: IntDefault Value: -1

Specify the depth of FIFOs used in kernel dataflow region.

param:compiler.interfaceWrOutstanding Type: Int RangeDefault Value: 0

Specify how many outstanding writes to bufferare on the kernel AXI interface. Values are 1through 256.

param:compiler.interfaceRdOutstanding Type: Int RangeDefault Value: 0

Specify how many outstanding reads to bufferare on the kernel AXI interface. Values are 1through 256.






Parameter Name Valid Values Descriptionparam:compiler.interfaceWrBurstLen Type: Int Range

Default Value: 0Specify the expected length of AXI write burstson the kernel AXI interface. This is used withoption compiler.interfaceWrOutstandingto determine the hardware buffer sizes. Valuesare 1 through 256.

param:compiler.interfaceRdBurstLen Type: Int RangeDefault Value: 0

Specify the expected length of AXI read burstson the kernel AXI interface. This is used withoption compiler.interfaceRdOutstandingto determine the hardware buffer sizes. Valuesare 1 through 256.

misc:map_connect=<type>.kernel.<kernel_name>.<kernel_AXI_interface>.core.OCL_REGION_0.<dest_port>


Used to map AXI interfaces from a kernel toDDR memory banks.

• <type> is add or remove.

• <kernel_name> is the name of the kernel.

• <dest_port> is a DDR memory bankM00_AXI, M01_AXI, M02_AXI, or M03_AXI.

This option is available only for DSA 4.x andearlier and deprecated for DSA 5.x and later.Use system ports using the --sp documentedin the xocc Linker Options.

prop:kernel.<kernel_name>.kernel_flags


Set specific compile flags on the kernel<kernel_name>.

prop:solution.device_repo_path Type: StringDefault Value:<empty>

Specify the path to the DSA repository. The --platform option with full path to the .xpfmplatform file should be used instead.

prop:solution.hls_pre_tcl Type: StringDefault Value:<empty>

Specify the path to a Vivado HLS Tcl file, whichis executed before the C code is synthesized.This allows Vivado HLS configuration settings tobe applied prior to synthesis.

prop:solution.hls_post_tcl Type: StringDefault Value:<empty>

Specify the path to a Vivado HLS Tcl file, whichis executed after the C code is synthesized.

prop:solution.kernel_compiler_margin Type: FloatDefault Value: 12.5% ofthe kernel clockperiod.

The clock margin in ns for the kernel. This valueis subtracted from the kernel clock period priorto synthesis to provide some margin for P&Rdelays.






Parameter Name Valid Values Descriptionvivado_prop:<object_type>.<object_name>.<prop_name>

Type: VariousDefault Value: Various

This allows you to specify any property used inthe Vivado hardware compilation flow.<object_type> is run|fileset|file|project.The <object_name> and <prop_name> valuesare described in Vivado Design Suite PropertiesReference Guide (UG912).Examples:

vivado_prop:run.impl_1.{STEPS.PLACE_DESIGN.ARGS.MORE OPTIONS}={-fanout_opt}

vivado_prop:fileset.current.top=foo

If <object_type> is set to file, current isnot supported.If <object type> is set to run, the specialvalue of __KERNEL__ can be used to specifyrun optimization settings for ALL kernels,instead of the need to specify them one by one.

Using the Message Rule FileXOCC executes various Xilinx® tools during kernel compilation. These tools generate manymessages that provide compilation status to you. These messages might or might not be relevantto you depending on your focus and design phases. A Message Rule file can be used to bettermanage these messages. It provides commands to promote important messages to the terminalor suppress unimportant ones. This helps you better understand the kernel compilation resultand explore methods to optimize the kernel.

The Message Rule file (.mrf) is a text file consisting of comments and supported commands.Only one command is allowed on each line.

Comment

Any line with “#” as the first non-white space character is a comment.



https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug912-vivado-properties.pdf



Supported Commands

By default, xocc recursively scans the entire working directory and promotes all error messagesto the xocc output. The promote and suppress commands below provide more control onthe xocc output.

• promote: This command indicates that matching messages should be promoted to the xoccoutput.

• suppress: This command indicates that matching messages should be suppressed or filteredfrom the xocc output. Note that errors cannot be suppressed.

Command Options

The Message Rule file can have multiple promote and suppress commands. Each commandcan have one and only one of the options below. The options are case-sensitive.

• -id [<message_id>]: All messages matching the specified message ID are promoted orsuppressed. The message ID is in format of nnn-mmm. As an example, the following is awarning message from HLS. The message ID in this case is 204-68.

WARNING: [XOCC 204-68] Unable to enforce a carried dependence constraint (II = 1, distance = 1, offset = 1) between bus request on port 'gmem' (/matrix_multiply_cl_kernel/mmult1.cl:57) and bus request on port 'gmem'-severity [severity_level]

• -severity [<severity_level>]: The following are valid values for the severity level. Allmessages matching the specified severity level will be promoted or suppressed.

○ info

○ warning

○ critical_warning

Precedence of Message Rules

The suppress rules take precedence over promote rules. If the same message ID or severitylevel is passed to both promote and suppress commands in the Message Rule file, thematching messages are suppressed and not displayed.





Example of Message Rule File

The following is an example of a valid Message Rule file:

# promote all warning, critical warningpromote -severity warningpromote -severity critical_warning# suppress the critical warning message with id 19-2342suppress -id 19-2342





Chapter 4

SDSCC/SDS++ Compiler CommandsThis section describes the SDSoC™ sdscc/sds++ compiler commands and options.

Note: SDS++ and SDSCC are compilers based on GCC, and therefore support many standard GCC optionswhich are not documented here. For information refer to the GCC Option Index.

Compiler Commands

sdscc – SDSoC C compiler

sds++ - SDSoC C++ compiler

Command Synopsissdscc | sds++ [hardware_function_options] [system_options] [performance_estimation_options] [options_passed_through_to_cross_compiler] [-sds-pf platform_name] [-sds-pf-info platform_name] [-sds-pf-list] [-sds-sys-config configuration_name] [-sds-proc processor_name] [-target-os os_name] [-sds-pf-path path] [-sds-image image_name] [-verbose] [-version] [--help] [files]

Hardware Function Options

[-sds-hw function_name source_file [-clkid clock_id_number] [-files hls_file_list] [-hls-tcl hls_tcl_directives_file] [-shared-aximm] -sds-end]*

For detail on these commands, see Hardware Function Options.

Performance Estimation Options

[[-perf-funcs function_name_list -perf-root function_name] | [-perf-est data_file][-perf-est-hw-only]]

For detail on these commands, see SDSCC/SDS++ Performance Estimation Flow Options.

Chapter 4: SDSCC/SDS++ Compiler Commands


https://gcc.gnu.org/onlinedocs/gcc/Option-Index.html



System Options

[[-ac function_name:clock_id_number]*[-apm] [-bsp-config-file mss_file] [-bsp-config-merge-file mss_file][-disable-ip-cache] [-dm-sharing <0-3>] [-dmclkid clock_id_number] [-emulation mode] [-impl-strategy <strategy>] [-instrument-stub] [-maxthreads number] [-mno-bitstream][-mno-boot-files] [-rebuild-hardware] [-remote-ip-cache cache_directory][-synth-strategy <strategy>] [-trace] [-trace-buffer depth] [-trace-no-sw] [-maxjobs <number>] [-sdcard <data_directory>][-vpl-ini ini_file] [-xp parameter_value]]

For details on these commands, see System Options.

The sdscc/sds++ compilers compile and link C/C++ source files into an application-specifichardware/software system on chip implemented on a Zynq®-7000 SoC or Zynq® UltraScale+™MPSoC device.

The command usage and options are identical for sdscc and sds++. Options not recognized bysdscc are passed to the Arm® cross-compiler. Compiler options within an -sds-hw ... -sds-end clause are ignored for the -c foo.c option when foo.c is not the file containing thespecified hardware function.

When linking the application ELF, sdscc creates and implements the hardware system. It alsogenerates an SD card image containing the ELF and boot files required to initialize the hardwaresystem, configures the programmable logic, and runs the target operating system.

When linking application ELF files for non-Linux targets, for example Standalone or FreeRTOS,default linker scripts found in the folder <install_path>/platforms/<platform_name>are used. If a user-defined linker script is required, it can be specified using the –Wl,-T –Wl,<path_to_linker_script> linker option.

When building a system containing no functions marked for hardware implementation, sdsccuses pre-built hardware when available for the target platform.

Report and log files are found in the _sds/reports folder.

When running Linux applications that use shared libraries, the libraries must be contained in theroot file system or SD card and the path to the libraries added to the LD_LIBRARY_PATHenvironment variable.

Optional PL Configuration After Linux BootWhen sdscc/sds++ creates a bitstream .bin file in the sd_card folder, it can be used toconfigure the PL after booting Linux and before running the application ELF. The embeddedLinux command used is cat bin_file > /dev/xdevcfg.





General OptionsThe following command line options are applicable to any sdscc invocation or your displayinformation.

Table 5: General Options

Option Valid Values Description-sds-pf<platform_name>

<platform_name> Specify the target platform that defines the basesystem hardware and software, includingoperation system and boot files. The<platform_name> can be the name of aplatform in the SDSoC environment installationor a file path to a folder containing platform fileswith the last component of the path matchingthe platform name.The platform defines the base hardware andsoftware, including operation system and bootfiles. Use this option when compiling acceleratorsource files and when linking the ELF file. Use the–sds-pf-list option to list available platforms.

-sds-pf-info<platform_name>

<platform_name> Display general information about a platform.Use the –sds-pf-list option to list availableplatforms. The information displayed includesavailable system configurations that can bespecified with the -sds-sys-configsystem_configuration option.<platform_name> can be the name of aplatform in the SDSoC environment installationor a file path to a folder containing platform files.

-sds-pf-list N/A Display a list of available platforms and exit (if noother options are specified). The informationdisplayed includes available systemconfigurations that can be specified with the -sds-sys-config system_configuration option.

-sds-sys-config<configuration_name>

<configuration_name> Specify the system configuration that defines thesoftware platform used, which includes thetarget operating system and other settings. The-sds-pf-list and -sds-pf-info options canbe used to list the available systemconfigurations for a platform.When the -sds-sys-config option is used, donot specify the -target-os option. If the -sds-sys-config option is not specified, the defaultsystem configuration is used.<configuration_name> can be any of theavailable system configurations for a platform.

-sds-proc<processor_name>

<processor_name> Specify the processor name to use with thesystem configuration defined by the -sds-sys-config option. A system configuration normallyspecifies a target CPU and this option is notrequired.<processor_name> specifies the target CPU touse.





Table 5: General Options (cont'd)

Option Valid Values Description-target-os <os_name> <linux | standalone | freertos> Specify the target operating system. The selected

OS determines the compiler toolchain used andincludes file and library paths added by sdscc.For a list of valid os_name options, use thecommand sdscc -sds-pf-info<plat_name>.If the -sds-sys-config system_configurationoption is specified, do not specify the -target-os option, because a system configuration itselfdefines a target operating system.If you do not specify the -sds-sys-config butdo specify the -target-os option, SDSoCsearches for a system configuration with an OSthat matches the one specified by -target-os.

-sds-pf-path <path> <path> Specify a search path for platforms. The specifiedpath can contain one or more sub-folders, eachof which is a platform folder.<path> is a search path for platforms.

-sds-image<image_name>

<image_name> Used with the -sds-sys-config option, thisspecifies the SD card image to use. If this optionis not specified, the default image is used.<image_name> specifies the SD card image touse.

-verbose N/A Print verbose output to STDOUT.-version N/A Print the sdscc version information to STDOUT.

--help N/A Print command line help information. Note thattwo consecutive hyphen or dash characters - areused.

The following command line options are applicable only to sdscc invocations used to compile asource file.

Hardware Function OptionsHardware function options provide a means to consolidate sdscc/sds++ options within aMakefile to simplify command line calls and make minimal modifications to a pre-existingMakefile.

The -sds-hw and -sds-end options are used in pairs:

• The -sds-hw option begins the description of a single function being moved into hardware.

• -sds-end option terminates the list of configuration details for that function.

For the next function moved into hardware, there is another pair with -sds-hw as the start ofthe configuration and -sds-end as the terminator.





The Makefile fragment below illustrates the use of –sds-hw blocks to collect all options in theSDSFLAGS Makefile variable and to replace an original definition of CC with sdscc ${SDSFLAGS} or sds++ ${SDSFLAGS}. Thus the original Makefile for an application can beconverted to an sdscc/sds++ compiler Makefile with minimal changes.

APPSOURCES = add.cpp main.cppEXECUTABLE = add.elf CROSS_COMPILE = arm-xilinx-linux-gnueabi-AR = ${CROSS_COMPILE}arLD = ${CROSS_COMPILE}ld#CC = ${CROSS_COMPILE}g++PLATFORM = zc702SDSFLAGS = -sds-pf ${PLATFORM} \ -sds-hw add add.cpp -clkid 1 -sds-end \ -dmclkid 2CC = sds++ ${SDSFLAGS}

INCDIRS = -I..LDDIRS =LDLIBS =CFLAGS = -Wall -g -c ${INCDIRS}LDFLAGS = -g ${LDDIRS} ${LDLIBS} SOURCES := $(patsubst %,../%,$(APPSOURCES))OBJECTS := $(APPSOURCES:.cpp=.o) .PHONY: all all: ${EXECUTABLE} ${EXECUTABLE}: ${OBJECTS} ${CC} ${OBJECTS} -o $@ ${LDFLAGS} %.o: ../%.cpp ${CC} ${CFLAGS} $<

Table 6: Hardware Function Options

Option Valid Values Description-sds-hw function_namefile [[-clkid <n>] [-files file_list] [-hls-tclhls_tcl_directives_file]] –sds-end

N/A An sdscc command line can include zero ormore –sds-hw blocks. Each block is associatedwith a top-level hardware function specified asthe first argument and its containing source filespecified as the second argument. If the filename associated with an -sds-hw block matchesthe source file to be compiled, the options areapplied. Options outside of –sds-hw blocks areapplied where applicable.When using the xfOpenCV library, thefunction_name is the template functioninstantiation enclosed in double quotes, forexample"auCanny<1080,1920,0,0,3,2,1,1,1>", andthe file is the source file containing the templatefunction instantiation, for exampleau_canny_tb.cpp.





Table 6: Hardware Function Options (cont'd)

Option Valid Values Description-clkid <n> N/A Set the accelerator clock ID to <n>, where <n>

has one of the values listed in the Appendix A:Clock ID Values by Platform table. (You can usethe command sdscc –sds-pf-infoplatform_name to display the informationabout a platform.) If the clkid option is notspecified, the default value for the platform isused. Use the command sdscc –sds-pf-listto list available platforms and settings.

-files file_list N/A Specify a comma-separated list (without whitespace) of one or more files required to compilethe current top-level function into hardwareusing Vivado® HLS. If any of these files containsource code that is not used by HLS but isrequired to produce the application executable,they must be compiled separately to createobject files (.o), and linked with other objectfiles during the link phase.When using the xfOpenCV library, the -filesoption specifies the path to the source filecontaining the function template definition, forexample au_canny.hpp.

-hls-tclhls_tcl_directives_file

N/A When using the Vivado HLS tool to synthesize thehardware accelerator, source the specified Tcl filecontaining HLS directives. During HLS synthesis,sdscc creates a run.tcl file used to drivethe Vivado HLS tool. In this Tcl file, the followingcommands are inserted:

# synthesis directivescreate_clock -period <clock_period>set_clock_uncertainty 27.0%config_rtl -reset_level lowsource <sdsoc_generated_tcl_directives_file># end synthesis directives

If the –hls-tcl option is used, the user-definedTcl file is sourced after the synthesis directivesgenerated by the SDSoC environment.

-shared-aximm N/A Share AXIMM ports instead of enabling multipleports.

-sds-end N/A Specify the end of the -sds-hw options for thespecified function_name.

Clock ID Values by Platform

For a list of clock ID values by platform, see Appendix A: Clock ID Values by Platform.





SDSCC/SDS++ Performance EstimationFlow OptionsA full bitstream compile can take much more time than a software compile, so the sdscc/sds++(referred to as sds++) applications provide performance estimation options to compute theestimated run-time improvement for a set of hardware function calls.

In the Application Project Settings pane, invoke the estimator by clicking the EstimatePerformance check box, to enable performance estimation for the current build configurationand builds the project.

Figure 45: Setting Estimate Performance in Application Project Settings

Estimating the speed-up is a two phase process:

• First, the SDSoC™ environment compiles the hardware functions and generates the system.Instead of synthesizing the system to bitstream, the sds++ computes an estimate of theperformance based on estimated latencies for the hardware functions and data transfer timeestimates for the callers of hardware functions.

• Then, in the generated Performance report, select Click Here to run an instrumented versionof the software on the target to determine a performance baseline and the performanceestimate.

See the SDSoC Environment Getting Started Tutorial (UG1028) for a tutorial on how to use thePerformance Report.

You can also generate a performance estimate from the command line. As a first pass to gatherdata about software runtime, use the -perf-funcs option to specify functions to profile and -perf-root to specify the root function encompassing calls to the profiled functions.

The sds++ system compiler then automatically instruments these functions to collect run-timedata when the application is run on a board. When you run an instrumented application on thetarget, the program creates a file on the SD card called swdata.xml, which contains the run-time performance data for the run.






Copy the swdata.xml to the host and run a build that estimates the performance gain on a perhardware function caller basis and for the top-level function specified by the –perf-rootfunction in the first pass run. Use the –perf-est option to specify swdata.xml as input datafor this build.

The following table specifies the sds++ system compiler options normally used to build anapplication.

Option Description-perf-funcs function_name_list Specify a comma separated list of all functions to be profiled in the

instrumented software application.-perf-root function_name Specify the root function encompassing all calls to the profiled

functions. The default is the function main.-perf-est data_file Specify the file containing run time data generated by the

instrumented software application when run on the target. Estimateperformance gains for hardware accelerated functions. The defaultname for this file is swdata.xml.

-perf-est-hw-only Run the estimation flow without running the first pass to collectsoftware run data. Using this option provides hardware latency andresource estimates without providing a comparison against baseline.

CAUTION!: After running thesd_card image on the board for collecting profile data, type cd /;sync; umount /mnt;. This ensures that the swdata.xml file is written out to the SD card.

Compiler MacrosPredefined macros allow you to guard code with #ifdef and #ifndef preprocessorstatements. The macro names begin and end with two underscore characters ‘_’. The __SDSCC__macro is defined whenever sdscc or sds++ (referred to collectively as sds++) is used tocompile source files. It can be used to guard code depending on whether it is compiled by sds++or another compiler, for example GCC.

When sds++ compiles source files targeted for hardware acceleration using Vivado® HLS, the__SDSVHLS__ macro is defined to be used to guard code depending on whether high-levelsynthesis is run or not.





The code fragment below illustrates the use of the __SDSCC__ macro to use the sds_alloc()and sds_free() functions when compiling source code with sds++, malloc(), and free()when using other compilers.

#ifdef __SDSCC__#include <stdlib.h>#include "sds_lib.h"#define malloc(x) (sds_alloc(x))#define free(x) (sds_free(x))#endif

In the example below, the __SDSVHLS__ macro is used to guard code in a function definitionthat differs depending on whether it is used by Vivado HLS to generate hardware or used in asoftware implementation.

#ifdef __SDSVHLS__void mmult(ap_axiu<32,1,1,1> A[A_NROWS*A_NCOLS], ap_axiu<32,1,1,1> B[A_NCOLS*B_NCOLS], ap_axiu<32,1,1,1> C[A_NROWS*B_NCOLS])#elsevoid mmult(float A[A_NROWS*A_NCOLS], float B[A_NCOLS*B_NCOLS], float C[A_NROWS*B_NCOLS])#endif

In addition, the macro, HLS_NO_XIL_FPO_LIB, is defined prior to the include option for VivadoHLS headers and is visible to Vivado HLS, SDSoC™ analysis tools, and target cross-compilers.This macro disables the use of bit-accurate, floating-point simulation models, instead using thefaster (although not bit-accurate) implementation from your local system. Bit-accurate simulationmodels are not provided for Zynq-7000 SoC and Zynq® UltraScale+™ MPSoC Arm® targets.

System OptionsTable 7: System Options

Option Description-ac <function_name>:<clock_id_number> Use the specified clock ID number for an RTL accelerator function in a

C-callable IP library instead of the default clock ID.-apm Insert an AXI Performance Monitor (APM) IP block to monitor all

generated hardware/software interfaces. Within the SDSoC™ IDE, inthe Debug perspective, you can activate the APM prior to running yourapplication by clicking the Start button within the PerformanceCounters View. See the SDSoC Environment Getting Started Tutorial(UG1028) for more information.

-bsp-config-file <mss_file> Specify the path to a board support package (BSP) configuration file(.mss) to use instead of an automatically-generated file for a bare-metal based target OS, for example Standalone or FreeRTOS. Whenusing this option, also add an include option specifying the path toyour BSP header files: -I</path/to/includes>






Table 7: System Options (cont'd)

Option Description-bsp-config-merge-file <mss_file> Specify the path to a board support package (BSP) configuration file

(.mss) to use for the base platform and merge using hardwareinformation from the final design to create a BSP configuration filecontain user settings for the base platform plus settings for hardwareadded to the base platform; for example, DMA drivers. This mergedBSP configuration file is used instead of an automatically generated filefor a bare-metal based target OS, for example, Standalone orFreeRTOS. When using this option, add an include option specifying thepath to your BSP header files: -I</path/to/includes>.

-disable-ip-cache Do not use a cache of pre-synthesized IP cores. The use of IP cachingreduces the overall build time by eliminating the synthesis step forstatic IP cores. If the resources required to implement the hardwaresystem exceeds available resources by a small amount, the -disable-ip-cache option forces SDSoC to synthesize all IP cores in the contextof the design and might reduce resource usage enough to enableimplementation.

-dmclkid <n> Set the data motion network clock ID to <n>, where <n> has one of thevalues listed in Appendix A: Clock ID Values by Platform. You can usethe command sdscc –sds-pf-info platform_name to display theinformation about the platform. If the dmclkid option is not specified,the default value for the platform is used. Use the command sdscc –sds-pf-list to list available platforms and settings.

-dk chipscope:instance:port Specify an instance name and port to monitor using a System ILAmodule. Multiple -dk options can be specified, instantiating a SystemILA as needed. For special cases, use the option --xpparam:compiler.userPostSysLinkTcl=<file> to specify a Tcl filecontaining VivadoIP integrator Tcl commands to post-process theSystem ILA in the block diagram after system linking and beforesynthesis.Note: --dk is also accepted.

-dk list_ports List available instance and port names for System ILA insertion. Thisoption can only be specified when linking the design and you canspecify -mno-bitstream to exit, review <pwd>/_sds/p0/dk_list_ports.txt, and update the command line to create thebitstream.Note: --dk is also accepted.

-dm-sharing <n> The –dm-sharing <n> option enables exploration of data moversharing capabilities if the initial schedule can be relaxed. The level ofsharing defaults to 0 (low) if not specified. Other values are 1(medium), 2 (high), and 3 (maximum – schedule can be relaxedinfinitely). For example, to enable maximum data mover sharing, addthe sdscc -dm-sharing 3 option.

-emulation <mode> Generate files required to run emulation of the system using QEMU forthe processing subsystem and the Vivado Logic Simulator for theprogrammable logic. This only works on boards that enable this flow(currently Xilinx base platforms only). The <mode> specifies the type ofsimulation models created for the PL, debug, or optimized. In thesame directory that you ran sds++, type the sdsoc_emulatorcommand to run the emulation in the current shell.






Option Description-impl-strategy <strategy_name> Specify the Vivado implementation strategy name to use instead of the

default strategy, for example Performance_Explore. The strategy namecan be found in the Vivado Implementation Settings dialog box in theStrategy menu, and the strategies are described in this link in theVivado Design Suite User Guide: Implementation (UG904).Note: When creating the Tcl file for synthesis and implementation, thiscommand is added: set_property strategy <strategy_name>[get_runs impl_1].

-instrument-stub The –instrument-stub option instruments the generated hardwarefunction stubs with calls to the counter functionsds_clock_counter(). When a hardware function stub isinstrumented, the time required to call send and receive functions, aswell as the time spent for waits, is displayed for each call to thefunction.

-maxjobs <n> The -maxjobs <n> option specifies the maximum number of jobsused for Vivado synthesis. The default is the number of cores dividedby 2.

-maxthreads <n> The –maxthreads <n> option specifies the number of threads used inmultithreading to speed up certain tasks, including Vivado placementand routing. The number of threads can be an integer from 1 to 8. Thedefault value is 4, but the tools do not use more threads than thenumber of cores on the machine. Also, a general limit based on the OSapplies to all tasks.

-mno-bitstream Do not generate the bitstream for the design used to configure theprogrammable logic (PL). Normally a bitstream is generated byrunning the Vivado implementation feature, which can be time-consuming with runtimes ranging from minutes to hours dependingon the size and complexity of the design. This option can be used todisable this step when iterating over flows that do not impact thehardware generation. The application ELF is compiled before bitstreamgeneration.

-mno-boot-files Do not generate the SD card image in the folder sd_card. Thisfolder includes your application ELF and files required to boot thedevice and bring up the specified OS. This option disables the creationof the sd_card folder in case you would like to preserve an earlierversion of this folder.

-rebuild-hardware When building a software-only design with no functions mapped tohardware, sdscc uses a pre-built bitstream if available within theplatform, but use this option to force a full system build.

-remote-ip-cache <cache_directory> Specify the path to a directory used for IP caching for Vivado synthesis.The use of an IP cache can reduce the amount of time required forlogic synthesis for subsequent runs. The option --remote_ip_cacheis also accepted.

-sdcard <data_directory> Specify an optional directory containing additional files to include inthe SD card image.

-synth-strategy <strategy_name> Specify the Vivado synthesis strategy name to use instead of thedefault strategy, for example Flow_RuntimeOptimized. The strategyname can be found in the Vivado Synthesis Settings dialog box in theStrategy menu and the strategies are described in this link in theVivado Design Suite User Guide: Synthesis (UG901). When creating the Tclfile for synthesis and implementation, this command is added:set_property strategy <strategy_name> [get_runssynth_1].



https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug904-vivado-implementation.pdf;a=xImplementationCategoriesStrategyDescriptionsAndDirectiveMapping

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug904-vivado-implementation.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug901-vivado-synthesis.pdf;a=xVivadoPreconfiguredStrategies

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug901-vivado-synthesis.pdf




Option Description-trace The –trace option inserts hardware and software infrastructure into

the design to enable tracing functionality.-trace-buffer The -trace-buffer option specifies the trace buffer depth, which

must be at least 16 and a power of 2. If this option is not specified, thedefault value of 1024 is used.

-trace-no-sw The –trace-no-sw option inserts hardware trace monitors into thedesign without instrumenting the software when enabling tracingfunctionality.

-vpl-ini <ini_file> Specify an initialization file containing one -xp <parameter_value>per line, but do not include the -xp option itself. This is equivalent tospecify multiple -xp options on the command line. Advanced users canuse this option to customize the Vivado synthesis and implementationflows.






Option Description-xp <parameter_value> Specify a Vivado synthesis or implementation property or parameter,

optionally enclosed in double quotes. The <parameter_value> usesone of the following forms to set a Vivado property or parameter,respectively.

"vivado_prop:run.run_name.<prop_name>=<value>" "vivado_param:<param_name>=<value>"

Familiarity with the Vivado tool suite is recommended to make themost use of these parameters.The first two examples set a Vivado property to specify a post-synthesisand post-optimization Tcl script, respectively:

vivado_prop:run.synth_1.STEPS.SYNTH_DESIGN.TCL.POST=/path/to/postsynth.tcl""vivado_prop:run.impl_1.STEPS.OPT_DESIGN.TCL.POST=/path/to/postopt.tcl"

The following example sets the implementation strategy and isequivalent to using the sds++/sdscc (referred to as sds++) -impl-strategy option. It illustrates a method for setting a Vivado propertyfor the implementation run named impl_1.

"vivado_prop:run.impl_1.strategy=Performance_Explore"

The following example sets the maximum number of threads used byVivado and is equivalent to using thesds++ -maxthreads option. Itillustrates a method for setting a Vivado parameter:

"vivado_param:general.maxThreads=1"

Advanced users can use the -xp option to customize the Vivadosynthesis and implementation flows. The --xp option is also accepted.Normally, Vivado implementation does not produce a bitstream if thereare timing violations. To force sds++ to skip the timing violation checkand continue, allowing you to proceed and correct timing issues later,you can use this parameter:

param:compiler.skipTimingCheckAndFrequencyScaling=1

Clock ID Values by Platform

For a list of clock ID values by platform, see Appendix A: Clock ID Values by Platform





Compiler Toolchain SupportThe SDSoC™ environment uses the same GNU Arm® cross-compiler toolchains included with theXilinx® Software Development Kit (SDK).

The Linaro-based GCC compiler toolchains support the Zynq®-7000 SoC and Zynq® UltraScale+™ MPSoC family devices. This section includes additional information on toolchain usage.

When compiling and linking applications, use only object files and libraries built using the samecompiler toolchain and options as those used by the SDSoC environment. All SDSoC providedsoftware libraries and software components (Linux kernel, root filesystem, BSP libraries, andother pre-built libraries) are built with the included toolchains. If you use sdscc or sds++(referred to collectively as sds++) to compile object files, the tools automatically insert a smallnumber of options. If you invoke the underlying toolchains, you must use the same options.

For example, if you use a different Zynq-7000 floating-point application binary interface (ABI),your binary objects are incompatible and cannot be linked with SDSoC Zynq-7000 binary objectsand libraries.

The following table summarizes the sds++ usage of Zynq-7000 toolchains and options. Whereoptions are listed, you need to specify them only if you use the toolchain gcc and g++commands directly instead of invoking sds++.

Table 8: sds++ Usage with Zynq-7000

Usage DescriptionZynq-7000 Arm bare-metalcompiler and linker options

-mcpu=cortex-a9 -mfpu=vfpv3 -mfloat-abi=hard

Zynq-7000 Arm bare-metal linkeroptions

-Wl,--build-id=none -specs=<specfile>

Where the <specfile> contains*startfile:

crti%O%s crtbegin%O%s

Zynq-7000 Arm bare-metalcompiler

${SDSOC_install}/SDK/gnu/aarch32/<host>/gcc-arm-none-eabi/bin

Toolchain prefix: arm-none-eabigcc executable: arm-none-eabi-gccg++ executable: arm-none-eabi-g++

Zynq-7000 SDSoC bare-metalsoftware (lib, include)

${SDSOC_install}/aarch32-none

Zynq-7000 Arm Linux compiler ${SDSOC_install}/SDK/gnu/aarch32/<host>/gcc-arm-linux-gnueabi/bin

Toolchain prefix: arm-linux-gnueabihf-gcc executable: arm-linux-gnueabihf-gccg++ executable: arm-linux-gnueabihf-g++

Zynq-7000 SDSoC Linux software(lib, include)

${SDSOC_install}/aarch32-linux





The following table summarizes sds++ usage of Zynq UltraScale+ MPSoC Cortex™-A53toolchains and options. Where options are listed, you only need to specify them if you use thetoolchain gcc and g++ commands directly instead of invoking sds++.

Table 9: sds++ Usage with Zynq UltraScale+ MPSoC Cortex-A53

Usage DescriptionZynq UltraScale+ MPSoC Arm bare-metal compiler and linker options

-mcpu=cortex-a53 -DARMR5 -mfloat-abi=hard -mfpu=vfpv3-d16

Zynq UltraScale+ MPSoC Arm bare-metal linker options

-Wl,--build-id=none

Zynq UltraScale+ MPSoC Arm bare-metal compiler

${SDSOC_install}/SDK/gnu/aarch64/<host>/aarch64-none/bin

Toolchain prefix: aarch64-none-elfgcc executable: aarch64-none-elf-gccg++ executable: aarch64-none-elf-g++

Zynq UltraScale+ MPSoC SDSoC bare-metal software (lib, include)

${SDSOC_install}/aarch64-none

Zynq UltraScale+ MPSoC Arm Linuxcompiler

${SDSOC_install}/SDK/gnu/aarch64/<host>/aarch64-linux/bin

Toolchain prefix: aarch64-linux-gnu-gcc executable: aarch64-linux-gnu-gccg++ executable: aarch64-linux-gnu-g++

Zynq UltraScale+ MPSoC SDSoC Linuxsoftware (lib, include)

${SDSOC_install}/aarch64-linux

The following table summarizes the sds++ usage of Zynq® UltraScale+™ MPSoC Cortex-R5toolchains and options. Where options are listed, you need to specify them only if you use thetoolchain gcc and g++ commands directly instead of invoking sds++.

Table 10: sds++ Usage with Zynq UltraScale+ MPSoC Cortex-R5

Usage DescriptionZynq UltraScale+ MPSoC Arm bare-metal compiler and linker options

-mcpu=cortex-r5 -DARMR5 -mfloat-abi=hard -mfpu=vfpv3-d16

Zynq UltraScale+ MPSoC Arm bare-metal linker options

-Wl,--build-id=none

Zynq UltraScale+ MPSoC Arm bare-metal compiler

${SDSOC_install)/SDK/gnu/armr5/<host>/gcc-arm-none-eabi/bin

Toolchain prefix: armr5-none-eabigcc executable: armr5-none-eabi-gccg++ executable: armr5-none-eabi-g++

Zynq UltraScale+ MPSoC SDSoC bare-metal software (lib, include)

${SDSoC_install}/armr5-none

IMPORTANT!: When using sds++ to compile Zynq-7000 source files, be aware that SDSoC toolsthat are processing and analyzing source files issue errors if they contain NEON instrinsics. If hardwareaccelerator (or caller) source files contain NEON intrinsics, guard them using the __SDSCC__ and__SDSVHLS__ macros.





For source files that do not contain hardware accelerators or callers but do use NEON intrinsics,you can either compile them directly using the GNU toolchain and link the objects with sds++,or you can add the sds++ command line option -mno-ir for these source files. This optionprevents clang-based tools from being invoked to create an intermediate representation (IR) usedin analysis. You are programmatically aware that they are not required (such as no accelerators orcallers).

For the latter solution, if you are using the SDSoC environment, you can apply the option on aper-file basis by right-clicking the source file, select Properties and go to the Settings dialog boxunder C/C++ Build Settings → Settings.

Figure 46: Build Settings





Chapter 5

emconfigutil (EmulationConfiguration) Utility

In the XOCC/Makefile flow, manage the compilation and execution of host code and kernelsoutside the Xilinx® SDAccel™ development environment. Follow the steps below to run softwareand hardware emulation:

1. Create the emulation configuration file.

For software or hardware emulation, the runtime library needs to know what devices andhow many to emulate. This information is provided to the runtime library by an emulationconfiguration file. SDAccel provides a utility, emconfigutil to automate creation of theemulation configuration file.

Note: When running on real HW, the runtime and drivers query the installed HW to determine the type ofdevice, how many of that devices are installed and the characteristics of that device.

The following are details of the emconfigutil command line format and options:

Table 11: emconfigutil Options

Option Valid Values Description--platform

Target device Required. Set target device. See the SDx Environments Release Notes,

Installation, and Licensing Guide (UG1238) for all supported devices.

--nd Any positive integer Optional. Number of devices. Default is 1.

--od Valid directory Optional. Output directory, emconfig.json file must be in thesame directory as the host executable.

--save-temps

N/A Optional. Specifies that intermediate files will not be deleted, and willremain after command is executed.

--xp Valid Xilinx parameters andproperties

Optional. Specify additional parameters and properties. Forexample:--xpprop:solution.platform_repo_paths=my_dsa_path

Sets the search path for the device specified in --platform option.

-h N/A Print help messages.

The emconfigutil command creates the configuration file emconfig.json in the outputdirectory.

Chapter 5: emconfigutil (Emulation Configuration) Utility


https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1238-sdx-rnil.pdf



The emconfig.json file must be in the same directory as the host executable. Thefollowing example creates a configuration file targeting twoxilinx_vcu1525_dynamic_5_0 devices.

$emconfigutil --platform xilinx_vcu1525_dynamic_5_0 --nd 2

2. Set the XILINX_SDX environment variable.

The XILINX_SDX environment needs to be set and pointed to the SDAccel installation pathfor the emulation to work. Below are examples assuming SDAccel is installed in /opt/Xilinx/SDx/2018.2.

C Shell:

setenv XILINX_SDX /opt/Xilinx/SDx/2018.2

Bash:

export XILINX_SDX=/opt/Xilinx/SDx/2018.2

3. Set the emulation mode.

Setting XCL_EMULATION_MODE environment variable to sw_emu (software emulation) orhw_emu (hardware emulation) changes the application execution to emulation mode. Inemulation mode, runtime looks for the file emconfig.json in the same directory as thehost executable and reads in the target configuration for the emulation runs.

C Shell:

setenv XCL_EMULATION_MODE sw_emu

Bash:

export XCL_EMULATION_MODE=sw_emu

Not setting the XCL_EMULATION_MODE environment variable turns off the emulation mode.

4. Run the emulation.

With the configuration file emconfig.json and XCL_EMULATION_MODE, use the followingcommand line to perform emulation:

$./host.exe kernel.xclbin

Chapter 5: emconfigutil (Emulation Configuration) Utility




Chapter 6

xbinst (Xilinx Board Installation)Utility

The FPGA acceleration card plugged into the host machine must have the associated Linuxkernel driver, firmware, and runtime libraries installed before it can run the user applications.SDAccel™ provides a Xilinx® board installation utility, xbinst to generate all necessary files forthe platform support package for the FPGA card. It creates an installation script to compile andinstall the driver, firmware, and runtime libraries. It also provides a small ready to use example totest the installed platform.

The xbinst utility requires Superuser privileges on the host machine to run. The supportedoptions are listed here.

Table 12: xbinst Options

Option Valid Values Description-h/--help N/A Print Usage Message.-f/--platform <arg> Supported platform from SDAccel

installation or the full path toplatform definition file for customplatforms

Required. All installed platforms are listed at SDAccel Developer Zone: Platforms.

-d/--destination <arg> Valid path on the file system. Required destination directory for driver andfirmware for the specified platform.

-z/--archive N/A Archive board installation files fordeployment.

-p/--deploy N/A Deploy board installation files.--classic N/A Release classic drivers and binaries.--platform_repo_paths <arg> Valid path on the file system Specify a user platform directory.

Follow the instructions below to install the driver and firmware for the FPGA card on the hostmachine. The xilinx_kcu1500_dynamic_5_0 DSA is used as an example. Replace it withthe DSA for the actual card plugged into the system.

All commands need to be run with Superuser privileges.

1. Create a board installation directory.

sudo mkdir -p /opt/dsa/xilinx_kcu1500_dynamic_5_0

Chapter 6: xbinst (Xilinx Board Installation) Utility


https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html#boardskits



2. Run xbinst to generate all necessary files.

$ sudo xbinst --platform xilinx_kcu1500_dynamic_5_0-d /opt/dsa/<file_path>/xilinx_kcu1500_dynamic_5_0****** xbinst v2018.2_sdx **** Copyright 1986-2018 Xilinx, Inc. All Rights Reserved.

INFO: [XBINST 60-267] Packaging for ..INFO: [XBINST 60-268] Packaging for ..CompleteINFO: [XBINST 60-667] xbinst has successfully created a board installation directory at <file_path>/*_dsa

If you installed a custom platform, the full path to the platform package file needs to beprovided to the xbinst command as shown in the following example:

$ sudo xbinst -f /platform/repo/vendor_board_name_version.xpfm -d custom_platform

3. Install the driver, firmware, and runtime libraries.

$cd <verson>_dsa/xbinst/$ sudo ./install.sh

This performs the following:

• Compile and install Linux kernel device drivers.

• Install the firmware files to the Linux firmware area.

• Generate a setup.sh (Bash) or setup.csh (for csh/tcsh) to set up the runtimeenvironment. You must source the setup script before running any application on thetarget FPGA card.

TIP: You can use sudo ./install.sh -k no to generate the setup.csh and setup.shwithout installing the drivers.

• Test the install by running a ready-to-use example:

$source setup.csh$cd test$./verify.exe verify.xclbin

Chapter 6: xbinst (Xilinx Board Installation) Utility




Chapter 7

xbsak (Xilinx Board Swiss ArmyKnife) Utility

The Xilinx® Board Swiss Army Knife (xbsak) utility is a standalone command line utility that canperform the following board administration and debug tasks independent of the SDAccel™runtime library (.so) and for the SDAccel tools installation:

• Board administration tasks:

○ Flash device configuration memory of the board.

○ Reboot boards without rebooting the host.

○ Reset hung boards.

○ Query board status, sensors, and PCIe® AER registers.

• Debug operations:

○ Download the SDAccel binary (.xclbin) to FPGA.

○ Test DMA for PCIe bandwidth.

○ Show status of compute units.

The xbsak utility automatically adds itself to your path when you run the setup.{csh|sh}file. The xbinst created the setup.{csh|sh} file when it generated the deployment files forthe deployment machine.

xbsak Commands and OptionsThe Xilinx® Board Swiss Army Knife Utility (xbsak) is a powerful standalone command line utilitythat can be used to debug lower level hardware/software interaction issues and program theplatforms.

Chapter 7: xbsak (Xilinx Board Swiss Army Knife) Utility




The following documents the xbsak command line format and the available commands andoptions.

xbsak <command> [options]

xbsak Commands and Options

Table 13: xbsak Commands and Options

Option Valid Values Descriptionhelp N/A Print help messages.list N/A List all supported devices installed on the server in the

format of [device_id] : device_name.The following is an example output where the device ID is 0and the device nameisxilinx_vcu1525_dynamic_5_0.

$xbsak listINFO: Found 1 device(s)[0] xilinx:vcu1525:dynamic:5.0

query [-d device_id] [-r region_id] Query the specified device and programmable region on thedevice to get detailed status information.

• -d device_id: Specify the target device. Optional.Default = 0 if not specified.

• -r region_id: Specify the target region. Optional.Default = 0 if not specified.

boot [-d <device_id>] Attempts to boot the device <device_id> from itsconfiguration memory, retain the PCIe link withoutrebooting the host, and trigger a re-enumeration of thePCIe bus and bus re-scanning. If this option command doesnot complete as expected, xbsak notifies you and requestsfor a hard reboot (sometimes called cold reboot: shutdownand restart of the machine).

clock [-d <device_id] [-r <region_id>] [-f<clock1_freq>] [-g <clock2_freq>]

Set frequencies of clocks driving the computing units.

• -d <device_id>: Specify the target device. Optional.Default = 0 if not specified.

• -r <region_id>: Specify the target region. Optional.Default = 0 if not specified.

• -f <clock1_freq>: Specify clock frequency in MHz forthe first clock. Required. All platforms have this clock.

• -g <clock2_freq>: Specify clock frequency in MHz forthe second clock. Optional. Some platforms have thisclock to support IP based kernels.





Table 13: xbsak Commands and Options (cont'd)

Option Valid Values Descriptiondmatest [-d device_id] [-b blocksize] Test throughput of data transfer between the host machine

and global memory on the device.


• -b blocksize: Specify the test block size in KB.Optional: Default = 65536 or 64 MB if not specified. Theblock size can be specified in both decimal orhexadecimal formats. For example, both -b 1024 and -b 0x400 set the block size to 1024 KB or 1 MB.

flash [-d device_id] -m primary_mcs [-nsecondary_mcs]

Note: The MSC files for this command option aregenerated by the xbinst utility.

This option helps program the configuration memory (flashmemory device) on the FPGA board with specifiedconfiguration files for the FPGA device to boot from. If youknow the platform installed currently on the board, thenyou can use this method.If you do not know what DSA is installed or want to programfrom a starting point, you need to externally flash using theUSB JTAG or USB cable as detailed in the board installationsection for your FPGA board.

• -d <device_id>: Specify the target device. Optional.Default = 0 if not specified.

• -m <primary_mcs>: Specify the primary configurationfile. Required. All platforms have at least oneconfiguration memory.

• -n <secondary_mcs>: Specify the secondaryconfiguration file. Optional. Some platforms have twoconfiguration memories and the secondaryconfiguration file is required for the secondconfiguration memory.

Note: For the flash programming function of xbsak to accessand program the flash configuration memory on the board,certain hardware features must be present in the currentplatform programmed onto the FPGA. This means the flashprogramming function works with boards already programmedwith a given firmware only.

Refer to Requirements for Boot Function of xbsak.

program [-d device_id] [-r region_id] -pxclbin

Download the OpenCL binary to the programmable regionon the device.



• -p xclbin: Specify the OpenCL binary file. Required.





Table 13: xbsak Commands and Options (cont'd)

Option Valid Values Descriptionreset [-d device_id][-r region_id] Reset the programmable region on the device. All running

compute units in the region are stopped and reset.



status [--apm | --lapc] Displays the status of any AXI Performance Monitor (APM)or Lightweight AXI Protocol Checkers (LAPC) that areavailable in the base platform.

• --spm: Returns the value of the AXI PerformanceMonitor (APM) counters in SDx. This option is onlyapplicable if one or more AXI Performance Monitors areavailable in the base platform.

• --lapc: Returns the values of the violations codesdetected by the Lightweight AXI Protocol Checkers(LAPC). This option is only applicable if one or moreLightweight AXI Protocol Checkers are available in thebase platform.

scan N/A Scans the system and displays any Xilinx® PCIe devices,associated drivers, and pertinent system information.

xbsakmem --read -a0x1000 -i 256 -oread.out

Default values are:

• Address: 0x0

• Size: DDR size

• File: memread.out

Read 256 bytes.

xbsakmem --write -a0x1000 -i 256 -e0xaa

Default values are:

• Address: 0x0

• Size: DDR size

• Pattern: 0x0

Write 256 bytes to DDR starting at 0x1000 with byte 0xaa.

Requirements for Boot Function of xbsakFor the flash programming function of xbsak to access and program the flash configurationmemory on the board, certain hardware features must be present in the current platformprogrammed onto the FPGA. This means the flash programming function works with boardsalready programmed with a given firmware only, which are listed in the following table.

The following are required steps:





1. Have two xbinst-generated deployment areas.

a. The first area corresponds to the current platform deployed on the board. This providesthe necessary xbsak that matches the current drivers installed on the deploymentmachine; most often you already have this area present on the deployment machine. Youmust source the setup.{sh,csh} from this area to use the xbsak matching theinstalled drivers.

b. The second area corresponds to the new platform to be deployed on the board whichprovides the following:

i. Configuration file(s) needed for the primary mcs (-m) and optional secondary mcs (-n) options

ii. New drivers needed to be deployed on the machine

2. Find the new configuration files in the new platform with the command:$ find -name‘*.mcs’ OR $ find /path/to/new/platform -name ‘*.mcs’.

3. Run xbsak to program the configuration file(s) onto the configuration memory of the boardwith the-m and -n options.

4. Install the drivers of the new platform in the OS (to replace the old drivers) with $ sudo ./install.sh -k yes -f yes; the -f and -k options force the install of the OS kerneldrivers.

The table lists the boards and their minimum required platform firmware versions for the flashprogramming to function. The entries show the platform names to use for the xbinstcommand.

Board Platform Firmwarexbinst Versions in Which the

Firmware is Used2017.4 2018.2

KCU1500 xilinx_kcu1500_dynamic_5_0 X X

VCU1525 xilinx_vcu1525_dynamic_5_1 X X





Chapter 8

sdx_pack UtilityThe SDSoC™ tools include the sdx_pack command line utility for creating C-callable IP librariesfor linking RTL IP into SDSoC applications using the sds++ system compiler.

Usage

sdx_pack -header <header.h/pp> -ip <component.xml> [-param <name>="value"] [configuration options]

Configuration Options

Table 14: Configuration Options

Option Valid Values Description-add-ip-repo Valid path to the repository on the file

system.Add IP repository to library

-header <header.h/.hpp> Header file with function declarations,Only one top header file allowed

Required. Header file with functionprototype

-ip<component.xml> N/A Required. IP packed by the Vivado® IPintegrator

-param <name>="value" N/A IP parameter values-func <function_name> N/A Required. Function name-control<protocol>[=<port>[:offset]]

N/A Required. IP control protocol options:

• AP_CTRL

• AXI

• none

-map<sw_name>=<hw_name>:direction[:<offset>[<aximm_name>:<direction>]]

N/A Required. SW function argument to IPportmapping:<SW_Name>=<HW_Name>:direction[:offset[<aximm_name>:direction]

-target-cpu <cpu_type> N/A Specify target CPU:

• cortex-a9

• cortex-a53

• cortex-r5

• microblaze




Table 14: Configuration Options (cont'd)

Option Valid Values Description-target-family <board_family> N/A Specify target board family; for

example, zynq or zynquplus.

-target-os<name> N/A Specify target Operating System:

• linux (default)

• standalone (bare-metal)

-stub<file.c/.cpp> N/A Stub file with entry points; can bemultiple functions mapping to a singleIP.

-verbose N/A Print verbose output to STDOUT.

-version N/A Print the sdx_pack versioninformation to STDOUT.

-help N/A Display information about thiscommand. sdx_pack -headercount.hpp -ip ../ip/component.xml -func count \ -control AXI=S_AXI:0 -target-cpu cortex-a9 -mapstart_value=S_AXI:in:0x8 -mapreturn=S_AXI:out:4 -target-osstandalone

Example:

sdx_pack -header count.hpp -ip ../ip/component.xml -func count \-control AXI=S_AXI:0 -target-cpu cortex-a9 -map start_value=S_AXI:in:0x8 -map return=S_AXI:out:4 -target-os standalone

Where:

• The count.hpp specifies the header file defining the function prototype for the countfunction.

• The component.xml sdx_pack -header count.hpp -ip ../ip/comp of the IPgenerates the packaged Vivado IP for SDx.

• The -control specifies the IP control protocol.

• The –map specifies the mapping of an argument from the software function to a port on theVivado IP. Notice the option is used twice in the example above to map start_value andreturn arguments to IP ports.

• The –target-cpu option specifies the target operating system.

The sdx_pack utility automatically generates:

• <function_name>.o: Compiled object code for the specified function

Chapter 8: sdx_pack Utility




• <function_name>.fcnmap.xml: Mapping IP ports to function arguments

• <function_name>.params.xml: IP parameters

• <function_name>.cpp: C++ file with entry point.

Note: You need to create an archive file (.a) of the sdx_pack compiled object code (.o) using anappropriate GNU tool chain utility, like arm-none-eabi-ar. Therefore, this function can be linked to theappropriate IP during runtime. For multiple functions mapping to a single IP, currently sdx_pack haslimited support, use sdslib instead.

Chapter 8: sdx_pack Utility




Appendix A

Clock ID Values by PlatformPlatform Value of <n>

zc702 0 – 166 MHz

1 – 142 MHz

2 – 100 MHz

3 – 200 MHz

zc706 0 – 166 MHz

1 – 142 MHz

2 – 100 MHz

3 – 200 MHz

zed 0 – 166 MHz

1 – 142 MHz

2 – 100 MHz

3 – 200 MHz

zcu102 0 – 75 MHz

1 – 100 MHz

2 – 150MHz

3 – 200 MHz

4 – 300 MHz

5 – 400 MHz

6 – 600 MHz

zcu104 0 – 75 MHz

1 – 100 MHz

2 – 150MHz

3 – 200 MHz

4 – 300 MHz

5 – 400 MHz

6 – 600 MHz

Appendix A: Clock ID Values by Platform




Platform Value of <n>zcu106 0 – 75 MHz

1 – 100 MHz

2 – 150MHz

3 – 200 MHz

4 – 300 MHz

5 – 400 MHz

6 – 600 MHz

Appendix A: Clock ID Values by Platform




Appendix B

Additional Resources and LegalNotices

Xilinx ResourcesFor support resources such as Answers, Documentation, Downloads, and Forums, see XilinxSupport.

Documentation Navigator and DesignHubsXilinx® Documentation Navigator provides access to Xilinx documents, videos, and supportresources, which you can filter and search to find information. To open the Xilinx DocumentationNavigator (DocNav):

• From the SDAccel™ or SDSoC™ IDE, select Help → Documentation and Tutorials.

• On Windows, select Start → All Programs → Xilinx Design Tools → DocNav.

• At the Linux command prompt, enter docnav.

Xilinx Design Hubs provide links to documentation organized by design tasks and other topics,which you can use to learn key concepts and address frequently asked questions. To access theDesign Hubs:

• In the Xilinx Documentation Navigator, click the Design Hubs View tab.

• On the Xilinx website, see the Design Hubs page.

Note: For more information on Documentation Navigator, see the Documentation Navigator page on theXilinx website.

Appendix B: Additional Resources and Legal Notices


https://www.xilinx.com/support

https://www.xilinx.com/support

https://www.xilinx.com/cgi-bin/docs/ndoc?t=design+hubs

https://www.xilinx.com/cgi-bin/docs/rdoc?t=docnav



ReferencesThese documents provide supplemental material useful with this guide:

SDAccel Documents

1. SDAccel Environment User Guide (UG1023)

2. SDAccel Environment Profiling and Optimization Guide (UG1207)

3. SDAccel Environment Getting Started Tutorial (UG1021)

SDSoC Documents

1. SDSoC Environment User Guide (UG1027)

2. SDSoC Environment Profiling and Optimization Guide (UG1235)

3. SDSoC Environment Tutorial: Introduction (UG1028)

4. SDSoC Environment Platform Development Guide (UG1146)

Additional Documents

1. SDx Pragma Reference Guide (UG1253)

2. Xilinx OpenCV User Guide (UG1233)

3. Platform Cable USB II Data Sheet (DS593)

More Resources

1. Xilinx® licensing website: https://www.xilinx.com/getproduct

2. SDSoC Developer Zone: https://www.xilinx.com/products/design-tools/software-zone/sdsoc.html.

3. SDAccel Developer Zone: https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html

4. Xilinx End-User License Agreement (UG763)

5. Third Party End-User License Agreement (UG1254 )

Training Resources1. SDSoC Development Environment and Methodology



https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1023-sdaccel-user-guide.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1207-sdaccel-optimization-guide.pdf

https://github.com/Xilinx/SDAccel-Tutorials/blob/master/getting-started-tutorial/README.md

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1027-sdsoc-user-guide.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1235-sdsoc-optimization-guide.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1028-sdsoc-intro-tutorial.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1146-sdsoc-platform-development.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1253-sdx-pragma-reference.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1233-xilinx-opencv-user-guide.pdf

https://www.xilinx.com/cgi-bin/docs/ndoc?t=data_sheets;d=ds593.pdf

https://www.xilinx.com/getproduct



https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html

https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=end-user-license-agreement.pdf

https://www.xilinx.com/cgi-bin/docs/rdoc?v=2018.2;d=ug1254-sdx-tplg.pdf

https://www.xilinx.com/training/courses/sdsoc-development-environment-method.html



2. Advanced SDSoC Development Environment and Methodology

Please Read: Important Legal NoticesThe information disclosed to you hereunder (the "Materials") is provided solely for the selectionand use of Xilinx products. To the maximum extent permitted by applicable law: (1) Materials aremade available "AS IS" and with all faults, Xilinx hereby DISCLAIMS ALL WARRANTIES ANDCONDITIONS, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TOWARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANYPARTICULAR PURPOSE; and (2) Xilinx shall not be liable (whether in contract or tort, includingnegligence, or under any other theory of liability) for any loss or damage of any kind or naturerelated to, arising under, or in connection with, the Materials (including your use of theMaterials), including for any direct, indirect, special, incidental, or consequential loss or damage(including loss of data, profits, goodwill, or any type of loss or damage suffered as a result of anyaction brought by a third party) even if such damage or loss was reasonably foreseeable or Xilinxhad been advised of the possibility of the same. Xilinx assumes no obligation to correct anyerrors contained in the Materials or to notify you of updates to the Materials or to productspecifications. You may not reproduce, modify, distribute, or publicly display the Materialswithout prior written consent. Certain products are subject to the terms and conditions ofXilinx's limited warranty, please refer to Xilinx's Terms of Sale which can be viewed at https://www.xilinx.com/legal.htm#tos; IP cores may be subject to warranty and support terms containedin a license issued to you by Xilinx. Xilinx products are not designed or intended to be fail-safe orfor use in any application requiring fail-safe performance; you assume sole risk and liability foruse of Xilinx products in such critical applications, please refer to Xilinx's Terms of Sale which canbe viewed at https://www.xilinx.com/legal.htm#tos.

AUTOMOTIVE APPLICATIONS DISCLAIMER

AUTOMOTIVE PRODUCTS (IDENTIFIED AS "XA" IN THE PART NUMBER) ARE NOTWARRANTED FOR USE IN THE DEPLOYMENT OF AIRBAGS OR FOR USE IN APPLICATIONSTHAT AFFECT CONTROL OF A VEHICLE ("SAFETY APPLICATION") UNLESS THERE IS ASAFETY CONCEPT OR REDUNDANCY FEATURE CONSISTENT WITH THE ISO 26262AUTOMOTIVE SAFETY STANDARD ("SAFETY DESIGN"). CUSTOMER SHALL, PRIOR TO USINGOR DISTRIBUTING ANY SYSTEMS THAT INCORPORATE PRODUCTS, THOROUGHLY TESTSUCH SYSTEMS FOR SAFETY PURPOSES. USE OF PRODUCTS IN A SAFETY APPLICATIONWITHOUT A SAFETY DESIGN IS FULLY AT THE RISK OF CUSTOMER, SUBJECT ONLY TOAPPLICABLE LAWS AND REGULATIONS GOVERNING LIMITATIONS ON PRODUCTLIABILITY.



https://www.xilinx.com/training/courses/advanced-sdsoc-development-environment-methodology.html

https://www.xilinx.com/legal.htm#tos





Copyright

© Copyright 2018 Xilinx, Inc. Xilinx, the Xilinx logo, Artix, ISE, Kintex, Spartan, Virtex, Vivado,Zynq, and other designated brands included herein are trademarks of Xilinx in the United Statesand other countries. OpenCL and the OpenCL logo are trademarks of Apple Inc. used bypermission by Khronos. All other trademarks are the property of their respective owners.



