SDx Command and Utility Reference Guide

SDx Command and Utility Reference Guide

SDx Command and Utility Reference Guide

SDx Command and Utility Reference 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.

SDx Command and Utility Reference Guide

Revision History The following table shows the revision history for this document. Section Revision Summary 06/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 2 Send Feedback

SDx Command and Utility Reference Guide

Table of Contents Revision History .

. 2 Chapter 1: Introduction . 5 Chapter 2: Configuring Command Settings in the SDx GUI . . 6 Using the Assistant View . 6 Configuring SDSoC Commands in the SDx IDE . 7 Configuring SDAccel Commands in the SDx IDE . . 15 Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility..34 XOCC Common Options . 35 XOCC Options for Compile Mode . . 39 XOCC Options for Link Mode . 40 XP Parameters . 42 Using the Message Rule File . 45 Chapter 4: SDSCC/SDS++ Compiler Commands . . 48 Command Synopsis . 48 General Options . 50 Hardware Function Options . . 51 SDSCC/SDS++ Performance Estimation Flow Options .

. 54 Compiler Macros . 55 System Options . . 56 Compiler 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 . . 68 xbsak Commands and Options . 68 Requirements for Boot Function of xbsak . 71 UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 3 Send Feedback

SDx Command and Utility Reference Guide

Chapter 8: sdx_pack Utility . . 73 Appendix A: Clock ID Values by Platform . 76 Appendix B: Additional Resources and Legal Notices . 78 Xilinx Resources . . 78 Documentation Navigator and Design Hubs . . 78 References . . 79 Training Resources . . 79 Please Read: Important Legal Notices . 80 UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 4 Send Feedback

SDx Command and Utility Reference Guide

Chapter 1 Introduction The Xilinx® SDx tools, including the SDAccel™ and SDSoC™ environment, provide command-line utilities and a graphical Integrated Development Environment (IDE).

The tools and commands provided enable the development of designs similar to a software-based design flow, where the source code is first compiled and then linked against each other. This flow applies to the host application 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 for compiling kernel accelerator functions and linking them with the SDAccel environment supported 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), targeting embedded Arm Cortex-A9, A53, and R5 CPUs with programmable logic hardware accelerators. • 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 used to 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 debug tasks 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 are available for each of the utilities. Some of the settings can be configured through the SDx GUI or using command line options. The xbinst, xbsak and sdx_pack utilities are only available through the command line. UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 5 Send Feedback

SDx Command and Utility Reference Guide

Chapter 2 Configuring Command Settings in the 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 primary interface to the various build configurations of a project. It is open by default in the lower-left corner of the SDx™ IDE. TIP: Because the SDx IDE is based on Eclipse, many of the dialog boxes and settings are standard options available through the Eclipse environment. You can find help on the C/C++ development environment in Eclipse at: https:/ /help.eclipse.org/oxygen/index.jsp Using the Assistant View 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.

The Assistant view is arranged by project. If multiple projects are present in the workspace, they are present in the Assistant pane. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 6 Send Feedback

SDx Command and Utility Reference Guide

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 configuration that 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, the console for that configuration will be made active as well. • Link with Guidance: The Guidance window will update to show information for the build configuration selected in the Assistant view.

Configuring SDSoC Commands in the SDx IDE The SDx™ GUI provides different views for you to manage SDSoC™ projects and builds, debug the 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 are part of the project. See Using the Assistant View. The following sections describe the options and settings that are available through the GUI. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 7 Send Feedback

SDx Command and Utility Reference Guide

SDSoC Project Settings To 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. The Project flow: link will take you to the www.xilinx.com page for the SDSoC flow. You can change the platform, and the system configuration for the current project using the browse button. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 8 Send Feedback

SDx Command and Utility Reference Guide

SDSoC Build Configuration Settings Build 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 with the build configurations. Figure 3: Build Configuration Settings Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 9 Send Feedback

SDx Command and Utility Reference Guide

The Build Configuration Settings dialog provides a convenient way to make adjustments to your build 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 from performance estimation. See SDSoC Environment Getting Started Tutorial (UG1028) for more information 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 clock frequency in between the platform and hardware accelerated functions. For more information on this see SDSoC Environment User Guide (UG1027).

Use the Generate SD card image option to copy the files required to allow booting your board from an SD Card. Finally, the Edit Toolchain Settings link at the bottom of the dialog box will take you to the compiler and linker settings that allow you to modify include directories, specify additional libraries and change command line options, for the active configuration. Many other settings are also available from the Toolchain Settings dialog. SDSoC Toolchain Settings Toolchain 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 up the 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 Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 10 Send Feedback

• SDS++ Compiler • SDS++ Linker SDSCC Compiler and SDS++ Compiler Command Options SDSCC Compiler and SDS++ Compiler Command Options The SDSCC Compiler and SDS++ Compiler sections show the sdscc and sds++ commands and any 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 passed with 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. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 11 Send Feedback

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 added to the Miscellaneous section.

Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 12 Send Feedback

Figure 10: Compiler Miscellaneous Settings Inferred Options Inferred Options Software platform inferred flags and software platform include paths are added under the Inferred Options section. Figure 11: Inferred Options SDS++ Linker Settings SDS++ Linker General Settings Some general setting for the SDS++ linker are specified in this section. Figure 12: SDS++ Linker General Settings Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 13 Send Feedback

The SDS++ Linker section shows the sds++ command and any additional options to be passed when 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 the Miscellaneous 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.

Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 14 Send Feedback

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 SDx IDE The SDx™ GUI provides different views for you to manage SDAccel™ projects and builds, debug the 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 are part of the project. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 15 Send Feedback

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, they are present in the Assistant pane. Select the Build Container by right-clicking the mouse, which shows the actions on a container. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 16 Send Feedback

Note: This view of the Assistant shows System Estimate reports, which are available inside the binary containers 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 Build Configuration. • 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 Build Configuration.

• 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. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 17 Send Feedback

• 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 Settings SDAccel 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 summary of the design environment at https:/ /www.xilinx.com. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 18 Send Feedback

• Platform: Target platform for this project. Click the link to open the platform summary. Click the 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 Settings To edit the settings for any of the build configurations under the project, select the build configuration in the Assistant view and click the Settings icon to bring up the window with the build configurations.

Figure 21: Build Configuration Settings • Target: The Build Configuration target • Host Debug: Select to enable debug of the host code. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 19 Send Feedback

• Kernel Debug: Select to enable debug of the kernel code. • Report Type: This option specifies whether to generate a report of system estimates during Emulation-SW build or not. The default is to not generate any reports. This option calls the HLS Compiler and might result in a longer build execution time.

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

The Build Configuration window also contains links to the Compiler and Linker Toolchain settings. These provide complete information on all the settings in a standard Eclipse environment view. SDAccel™ specific settings, such as the XOCC compiler and linker flags, which are not part of the standard C/C++ toolchain, are provided in the Miscellaneous tab. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 20 Send Feedback

SDAccel Binary Container Settings Binary Container Settings To edit the settings for any of the binary containers under the project, select the binary container in the Assistant view and click the Settings icon to bring up the window with the build configurations.

Figure 22: Binary Container Settings • Name: Binary container name. • XOCC Linker Options: XOCC link options for this binary container are specified and listed here. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 21 Send Feedback

SDAccel Hardware Function Settings To edit the settings for any of the Hardware Functions under the project, select the hardware function in the Assistant view and click the Settings icon to bring up the window with the Hardware 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 global memory buffer declared in the kernel function signature. If not selected, a single physical memory 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 and listed here. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 22 Send Feedback

• Debug and Profiling Settings: This option allows debug and profile monitors to be inserted at the hardware function boundary to review signal traces.

This option is only available in the Build 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 between compute 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 unit executions.

○ Stall Profiling: Add an Accelerator monitor with functionality to capture three kinds of stalls in the flow of data: - Inside a kernel. - Between two kernels. - Between kernel and external memory. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 23 Send Feedback

SDAccel Toolchain Settings Toolchain Settings The toolchain settings provide a standard Eclipse-based view of the project, providing all options for the C/C++ build in SDAccel™. From the Build Configuration Settings window, click the link Edit Toolchain Compiler Settings or Edit Toolchain Linker Settings at the bottom of the Build Configuration window to bring up the compiler 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 tab are: • SDx XOCC Kernel Compiler • SDx XOCC Kernel Linker • emconfigutil • SDx GCC Host Compiler • SDx GCC Host Linker Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 24 Send Feedback

SDx XOCC Kernel Compiler Options SDx XOCC Kernel Compiler Options The SDx™ XOCC Kernel Compiler section shows the xocc command and any additional options that 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.

Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 25 Send Feedback

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 as flags 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 Settings SDx XOCC Kernel Linker Settings The SDx XOCC Kernel Linker section shows the xocc command and any additional options to be passed when calling xocc for the linker stage.

Figure 29: XOCC Kernel Linker Settings Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 26 Send Feedback

XOCC Kernel Linker Miscellaneous Options Any additional options that need to be passed to the xocc compiler can be added as flags in the Miscellaneous 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, or to 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 Settings emconfigutil Settings The emconfigutil command and options can be provided in the Command field under emconfigutil 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 Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 27 Send Feedback

SDx GCC Host Compiler Settings The compiler arguments for the SDAccel™ GCC host compiler are provided through the various options available under the SDx GCC Host Compiler section of the Assistant. XCPP is an SDAccel wrapper around the underlying GCC system compiler/linkers to create a uniform front-end for the 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 using the Preprocessor settings.

The default symbols already defined include the platform which is passed to the compiler so that the host code can check for the specific platform. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 28 Send Feedback

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. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 29 Send Feedback

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 the Miscellaneous section. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 30 Send Feedback

Figure 39: GCC Host Compiler Miscellaneous Settings SDx GCC Host Linker Settings SDx GCC Host Linker Settings The linker arguments for the SDAccel GCC Host Linker are provided through the options available 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 Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 31 Send Feedback

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 the Miscellaneous 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. Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 32 Send Feedback

Figure 44: GCC Host Linker Shared Libraries Settings Chapter 2: Configuring Command Settings in the SDx GUI UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 33 Send Feedback

Chapter 3 XOCC (Xilinx OpenCL Compiler) Command Line Utility The Xilinx® OpenCL™ Compiler (xocc) is a standalone command line utility for compiling kernel accelerator functions and linking them with the SDAccel™ environment supported platforms. This section describes the xocc link and compile commands. All commands are provided in the following 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 Xilinx or third-party providers and to compile a kernel accelerator function using the -c/--compile option.

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 -o .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 . The second activity is to link one or more kernels into the platform to create the binary container xclbin 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 .xo \ [.xo - o .xclbin Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 34 Send Feedback

For a list of supported platforms, see the SDx Environments Release Notes, Installation, and Licensing Guide (UG1238). IMPORTANT!: All examples in the SDAccel installation use the Makefile to compile OpenCL applications with xcpp and xocc commands that can be used as references for compiling user applications. XOCC Common Options The --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 you use a platform that is not included by default in the SDAccel™ tool installation, for example to use a Device Support Archive (DSA) and matching board.

The compile target is specified with the --target option. The default compile target 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 Name of supported acceleration platform by Xilinx or full path to .xpfm file that represents a platform.

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 the SDAccel tool installation, the .xpfm file that represents a platform should be provided using the full path. --platforminfo N/A List the supported devices. Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 35 Send Feedback

Table 1: XOCC Common Options (For Compile and Link Modes) (cont'd) Option Valid Values Description --target [sw_emu | hw_emu | hw] Specify a compile target. • sw_emu: Software emulation • hw_emu: Hardware emulation • hw: Hardware Default: hw -o/-output File name with .xo or .xclbin extension depending on xocc mode. 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 not supported.

The stall option must be specified during xocc compile (- c) to direct HLS to enable stall signals before using this option during xocc link (-l). --xp Refer to XP Parameters. Specify detailed parameter and property settings in the Vivado Design Suite used to implement the FPGA hardware. For example: --xp :stream Familiarity with the Vivado Design Suite is recommended to make the most use of these parameters. For a complete description of the --xp option, see XP Parameters. --debug N/A Generate code for debugging. --message-rules Message rule file name Optional. Specify a message rule file with message controlling rules.

Fore more details, see Using the Message Rule File.

--report [estimate | system] Generate a report type specified by : • estimate: Generate estimate report in report_estimate.xtxt • system: Generate the estimate report and detailed hardware reports in the report directory. --save-temps N/A Save intermediate files/directories created during the compilation and build process. Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 36 Send Feedback

Table 1: XOCC Common Options (For Compile and Link Modes) (cont'd) Option Valid Values Description --report_dir Directory Specify a report directory.

If the --report option is specified, the default is to generate all reports in the current working directory (cwd). If no report directory is specified, the tool saves the files to /_x/reports. --log_dir Directory Specify a log directory. If the --log option is specified, the default is to generate the log file in the current working directory (cwd). If no log directory is specified, the tool saves the files to /_x/logs.

--temp_dir Directory Specify a temp directory. If the --save-temps option is specified, the default is to create the temporary compilation and build files in the current working directory (cwd). If no temp directory is specified, the tool saves the files to /_x/reports. --export_script N/A This option allows detailed control of the Vivado Design Suite used to implement the FPGA hardware. Familiarity with the Vivado Design Suite is recommended to make the most use of the Tcl file generated by this option. Generates the Tcl script, .tcl, used to execute Vivado HLS but halts before Vivado HLS starts.

The expectation is for the script to be modified and used with the --custom_script option.

Not supported for –t sw_emu with OpenCL kernels. --custom_script : Intended for use with the .tcl file generated with --export_script. This option allows you to customize the Tcl file used to create the kernel and execute using the customize version of the script. OpenCL or C/C++ kernel source file, or Xilinx object file (.xo). Compile kernels into a.xo or a.xclbin file depending on the xocc mode (compile or link). Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 37 Send Feedback

Table 1: XOCC Common Options (For Compile and Link Modes) (cont'd) Option Valid Values Description -- user_ip_repo_path s Specify the directory location of the existing user IP repository. This value is prefixed to ip_repo_paths. Using this switch, you can specify one or more IP repository paths which will be given highest priority by placing these paths at the beginning of the overall IP_REPO_PATHS property for the underlying Vivado project. Any IP definitions from any of these paths specified that you specify will be used ahead of IP repositories from the DSA or from the Xilinx catalog.

Multiple --user_ip_repo_paths can be specified.

The following lists show the priority order in which IP definitions will be found during SDx compilation flows (High to Low). Note that all of these entries can possibly include multiple 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. /SDx/2018.2/data/ cache/) 5. IP cache stored inside DSA 6. SDx Specific Xilinx IPs from install area (e.g./SDx/2018.2/ data/ip/) 7. General Xilinx IP catalog from install area (for example,/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./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. /SDx/2018.2/data/ ip/) 9. General Xilinx IP catalog from install area (e.g./Vivado/ 2018.2/data/ip/) Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 38 Send Feedback

Table 1: XOCC Common Options (For Compile and Link Modes) (cont'd) Option Valid Values Description --remote_ip_cache 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 define custom report levels. • (Default) The -R 0 specification turns off all intermediate DCP generation during Vivado implementation. Turns on post route timing report generation. • The -R 1 specification turns on everything -R0 does, plus report_failfast pre-opt_design, report_failfast post- opt_design, and all intermediate DCP generation.

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

• The -R estimate forces Vivado_HLS to generate a design.xml datafile if it does not exist, in order to generate an estimate report. This option is useful for software emulation target, when design.xml is not generated by default. --reuse_impl Import an implemented DCP, and run only the XCLBIN packaging. --ini_file Read in XP switches from file in xocc.ini format. May be used multiple times for multiple files. These will take priority over xocc.ini files found in default locations, but explicit --xp command line switches will still take priority over those found in the specified file.

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

XOCC Options for Compile Mode Table 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 Kernel to be compiled from the input .cl or .c/.cpp kernel source code. Required for C/C++ kernels. Optional for OpenCL kernels. Compile/build only the specified kernel from the input file. Only one -k option is allowed per command.

When an OpenCL kernel is compiled without the -k option, all the kernels in the input file are compiled. Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 39 Send Feedback

Table 2: XOCC Options for Compile Mode (cont'd) Option Valid Values Description --define Valid macro name and definition pair. = Predefine name as a macro with definition. This option is passed to the xocc preprocessor. --include Directory name that includes required header files.

Add the directory to the list of directories to be searched for header files. This option is passed to the SDAccel compiler preprocessor. XOCC Options for Link Mode Table 3: XOCC Options for Link Mode Option Valid Values Description --optimize Valid optimization levels: 0, 1, 2, 3, s, quick.

example: --optimize2 This option ONLY applies to Vivado. The compile step runs the C code through HLS and has no bearing. These options control the default optimizations performed by the Vivado hardware synthesis engine. Familiarity with the Vivado tool suite is recommended to make better use of these settings. • 0: Default optimization. Reduce compilation time and make debugging produce the expected results. • 1: Optimize to reduce power consumption. This takes more time to compile the design. • 2: Optimize to increase kernel speed. This option increases both compilation time and the performance of the generated code.

• 3: This is the highest level of optimization. This option provides the highest level performance in the generated code, but compilation time might increase considerably. • s: Optimize for size. This reduces the logic resources for the kernel • quick: Quick compilation for fast run time. This might result in reduced hardware performance, and a greater use of resources in the hardware implementation. Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 40 Send Feedback

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 input files, generate .xclbin file. --nk : For example: foo:2 : : .… For example: foo:3:fooA.fooB.fooC This option instantiates the specified number of compute units for the given kernel in the .xclbin file. The instance name is optional. If the instance name is not specified, the first instance is named _1, the second instance is named _2, and so forth.

Default: One compute unit per kernel. Optional in link mode. Not applicable in compile mode. --jobs Number of parallel jobs. Optional. This option allows detailed control of the Vivado Design Suite used to implement the FPGA hardware. Familiarity with the Vivado Design Suite is recommended to make the most use of this option. Specify the number of parallel jobs to be passed to the Vivado Design Suite for implementation. Increasing the number of jobs allows the hardware implementation step to spawn more parallel processes and complete faster. --lsf bsub command line to pass to LSF cluster.

This argument is required for use with --lsf.

Optional. Use IBM Platform Load Sharing Facility (LSF) for Vivado implementation and synthesis. For example: --lsf '{bsub -R "select[type=X86_64]" -N -q medium}' --sp .: Valid DDR4 bank names are bank0, bank1, bank2, and bank3 for platforms with four DDR banks. Connect a kernel to a specific DDR bank. Multiple --sp options can be specified to map each of the interfaces to a particular bank. For DSA 5.x and later, the --xp misc:map_connect option is deprecated and replaced with the system port --sp option with a much simpler syntax requiring only the kernel instance name, an interface name of that kernel, and the target DDR bank for the required connection.

Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 41 Send Feedback

XP Parameters When compiling or linking, fine grain control over the hardware generated by SDAccel™ and the hardware 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 up emulation and compile options. IMPORTANT!: Familiarity with the Vivado Design Suite is required to make the most use of these parameters. See Vivado Design Suite User Guide: High-Level Synthesis (UG902) and Vivado Design Suite User Guide: Implementation (UG904) for more information.

Parameters are specified as parm:=. 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 specify the value(s) in an xocc.ini file with each option specified on a separate line (without --xp switch). param:prop:solution.device_repo_paths=../dsa param: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 line value is used.

The following table lists the -–xp parameters and their values. Table 4: XP Parameter Options Parameter Name Valid Values Description param:compiler.acceleratorBinaryConte nt Type: String Default Value: Content to insert in xclbin. Valid options are bitstream and dcp. param:compiler. enableDSAIntegrityCheck Type: Boolean Default Value: FALSE Enable the DSA Integrity Check. If this value is set to TRUE and SDAccel detects a DSA which has been modified outside of the Vivado Design Suite, SDAccel halts operation.

param:compiler.errorOnHoldViolation Type: Boolean Default Value: TRUE Error out if there is hold violation.

Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 42 Send Feedback

Table 4: XP Parameter Options (cont'd) Parameter Name Valid Values Description param:compiler.maxComputeUnits Type: Int Default Value: -1 Maximum compute units allowed in the system. Any positive value will overwrite the numComputeUnits setting in the DSA. param:hw_em.enableProcSyncReset Type: Boolean Default Value: FALSE Enable proc_sync_reset in hw_em. param.hw_em.platformPath Type: String Default Value: Specify the path to the custom platform directory. The directory should meet the following requirements to be used in platform creation: • The directory should contain a subdirectory called ip_repo.

• The directory should contain a subdirectory called scripts and this scripts directory should contain a hw_em_util.tcl file. The hw_em_util.tcl file should have following two procedures defined in it: ○ hw_em_util::add_base_platform ○ hw_em_util::generate_simulation_scripts _and_compile param:hw_em.compiledLibs Type: String Default Value: Uses mentioned clibs for the specified simulator. param:hw_em.enableProtocolChecker Type: Boolean Default Value: FALSE Enable the AXI protocol checker during HW emulation. This is used to confirm the accuracy of any AXI interfaces in the design. param:compiler.interfaceLatency Type: Int Default Value: -1 Specify the expected latency on the kernel AXI bus, the number of clock cycles from when bus access is requested until it is granted.

param:compiler.fsanitizestring Type: String Default Value: Enable the software emulation runtime checks. Possible values are: • address: Out of Bound Access • memory: Uninitialized Memory Access The software emulation run produces a debug log: /Emulation- SW/-Default>/ emulation_debug.log with emulation diagnostic messages. param:compiler.xclDataflowFifoDepth Type: Int Default Value: -1 Specify the depth of FIFOs used in kernel data flow region.

param:compiler.interfaceWrOutstanding Type: Int Range Default Value: 0 Specify how many outstanding writes to buffer are on the kernel AXI interface. Values are 1 through 256. param:compiler.interfaceRdOutstanding Type: Int Range Default Value: 0 Specify how many outstanding reads to buffer are on the kernel AXI interface. Values are 1 through 256. Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 43 Send Feedback

Table 4: XP Parameter Options (cont'd) Parameter Name Valid Values Description param:compiler.interfaceWrBurstLen Type: Int Range Default Value: 0 Specify the expected length of AXI write bursts on the kernel AXI interface.

This is used with option compiler.interfaceWrOutstanding to determine the hardware buffer sizes. Values are 1 through 256. param:compiler.interfaceRdBurstLen Type: Int Range Default Value: 0 Specify the expected length of AXI read bursts on the kernel AXI interface. This is used with option compiler.interfaceRdOutstanding to determine the hardware buffer sizes. Values are 1 through 256.

misc:map_connect=. kernel.. .core. OCL_REGION_0. Type: String Default Value: Used to map AXI interfaces from a kernel to DDR memory banks. • is add or remove. • is the name of the kernel. • is a DDR memory bank M00_AXI, M01_AXI, M02_AXI, or M03_AXI. This option is available only for DSA 4.x and earlier and deprecated for DSA 5.x and later. Use system ports using the --sp documented in the xocc Linker Options. prop:kernel.. kernel_flags Type: String Default Value: Set specific compile flags on the kernel .

prop:solution.device_repo_path Type: String Default Value: Specify the path to the DSA repository.

The -- platform option with full path to the .xpfm platform file should be used instead. prop:solution.hls_pre_tcl Type: String Default Value: Specify the path to a Vivado HLS Tcl file, which is executed before the C code is synthesized. This allows Vivado HLS configuration settings to be applied prior to synthesis. prop:solution.hls_post_tcl Type: String Default Value: Specify the path to a Vivado HLS Tcl file, which is executed after the C code is synthesized. prop:solution.kernel_compiler_margin Type: Float Default Value: 12.5% of the kernel clock period.

The clock margin in ns for the kernel. This value is subtracted from the kernel clock period prior to synthesis to provide some margin for P&R delays. Chapter 3: XOCC (Xilinx OpenCL Compiler) Command Line Utility UG1279 (v2018.2) June 6, 2018 www.xilinx.com [placeholder text] SDx Command and Utility Reference Manual 44 Send Feedback