Intel® High Level Synthesis Compiler Pro Edition: Reference Manual

Download PDF
ID 683349
Date 12/04/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
1. Intel® HLS Compiler Pro Edition Reference Manual 2. Compiler 3. C Language and Library Support 4. Component Interfaces 5. Component Memories (Memory Attributes) 6. Loops in Components 7. Component Concurrency 8. Arbitrary Precision Math Support 9. Component Target Frequency 10. Systems of Tasks 11. Libraries 12. Advanced Hardware Synthesis Controls 13. Intel® High Level Synthesis Compiler Pro Edition Reference Summary A. Advanced Math Source Code Libraries B. Supported Math Functions C. Cyclone® V Restrictions D. Intel® HLS Compiler Pro Edition Reference Manual Archives E. Document Revision History of the Intel® HLS Compiler Pro Edition Reference Manual
1. Intel® HLS Compiler Pro Edition Reference Manual x
1.1. Pending Deprecation of the Intel® HLS Compiler
2. Compiler x
2.1. Intel® HLS Compiler Pro Edition Command Options 2.2. Using Libraries in Your Component 2.3. Compiler Interoperability 2.4. Intel® HLS Compiler Hardware Model
2.3. Compiler Interoperability x
2.3.1. Compiling Your Testbench and Component Separately
3. C Language and Library Support x
3.1. Supported C and C++ Subset for Component Synthesis 3.2. C and C++ Libraries 3.3. Templated and Overloaded Functions 3.4. Intel® HLS Compiler Pro Edition Compiler-Defined Preprocessor Macros
3.3. Templated and Overloaded Functions x
3.3.1. Templated Functions 3.3.2. Overloaded Functions 3.3.3. Function Name Mapping
4. Component Interfaces x
4.1. Component Invocation Interface 4.2. Avalon® Streaming Interfaces 4.3. Pipes 4.4. Avalon® Memory-Mapped Host Interfaces 4.5. Agent Interfaces 4.6. Stable Component Parameters 4.7. Global Variables 4.8. Structs in Component Interfaces 4.9. Reset Behavior
4.1. Component Invocation Interface x
4.1.1. Scalar Parameters 4.1.2. Pointer and Reference Parameters 4.1.3. Interface Definition Example: Component Invocation Interface Control Attributes 4.1.4. Interface Definition Example: Component with Both Scalar and Pointer Arguments
4.3. Pipes x
4.3.1. The pipe Class and Its Use
4.4. Avalon® Memory-Mapped Host Interfaces x
4.4.1. Memory-Mapped Host Testbench Constructor 4.4.2. Implicit and Explicit Examples of Describing a Memory Interface 4.4.3. Avalon® Memory-Mapped Host Interfaces and Load-Store Units
4.4.3. Avalon® Memory-Mapped Host Interfaces and Load-Store Units x
4.4.3.1. Load-Store Unit Types 4.4.3.2. Memory-Access Coalescing and Load-Store Units
4.5. Agent Interfaces x
4.5.1. Control and Status Register (CSR) Agent 4.5.2. Agent Memories
5. Component Memories (Memory Attributes) x
5.1. Static Variables
6. Loops in Components x
6.1. Loop Initiation Interval (ii Pragma) 6.2. Loop-Carried Dependencies (ivdep Pragma) 6.3. Loop Coalescing (loop_coalesce Pragma) 6.4. Loop Unrolling (unroll Pragma) 6.5. Loop Concurrency (max_concurrency Pragma) 6.6. Loop Iteration Speculation (speculated_iterations Pragma) 6.7. Loop Pipelining Control (disable_loop_pipelining Pragma) 6.8. Loop Interleaving Control (max_interleaving Pragma) 6.9. Loop Fusion
6.9. Loop Fusion x
6.9.1. Loop Fusion Control (loop_fuse Pragma) 6.9.2. Loop Fusion Exemption (nofusion pragma)
7. Component Concurrency x
7.1. Serial Equivalence within a Memory Space or I/O 7.2. Concurrency Control (hls_max_concurrency Attribute) 7.3. Component Pipelining Control (hls_disable_component_pipelining Attribute)
8. Arbitrary Precision Math Support x
8.1. Declaring ac_int Data Types 8.2. Declaring ac_fixed Data Types 8.3. Declaring ac_complex Data Types 8.4. AC Data Types and Native Compilers 8.5. Declaring hls_float Data Types
8.1. Declaring ac_int Data Types x
8.1.1. Important Usage Information on the ac_int Data Type 8.1.2. Integer Promotion and ac_int Data Types 8.1.3. Debugging Your Use of the ac_int Data Type
8.2. Declaring ac_fixed Data Types x
8.2.1. Arbitrary Precision Fixed-Point Literals in Operations
8.5. Declaring hls_float Data Types x
8.5.1. Operators and Return Types Supported by the hls_float Data Type 8.5.2. Additional Data Types Provided By hls_float.h
9. Component Target Frequency x
9.1. Effects of Specifying Target II and Target fMAX
10. Systems of Tasks x
10.1. Task Functions 10.2. Internal Streams 10.3. System of Tasks Simulation
11. Libraries x
11.1. Static-Object Libraries 11.2. Creating a Static-Object Library 11.3. Creating Objects From HLS Code 11.4. Creating Objects From RTL Code 11.5. Packaging Object Files Into a Library
11.3. Creating Objects From HLS Code x
11.3.1. Creating an Object File From HLS Code 11.3.2. Supported OpenCL* Language Constructs
11.4. Creating Objects From RTL Code x
11.4.1. RTL Modules and the HLS Pipeline 11.4.2. Creating a Static-Object File from an RTL Module
11.4.1. RTL Modules and the HLS Pipeline x
11.4.1.1. Integration of an RTL Module into the HLS Pipeline 11.4.1.2. RTL Module Interfaces 11.4.1.3. RTL Reset and Clock Signals 11.4.1.4. Object Manifest File Syntax 11.4.1.5. Mapping HLS Data Types to RTL Signals 11.4.1.6. HLS Emulation Models for RTL-Based Functions 11.4.1.7. Potential Incompatibility between RTL Modules and Partial Reconfiguration 11.4.1.8. Stall-Free RTL 11.4.1.9. RTL Module Restrictions and Limitations for HLS Libraries
11.4.1.2. RTL Module Interfaces x
11.4.1.2.1. RTL Module Interface Signals
11.4.1.3. RTL Reset and Clock Signals x
11.4.1.3.1. Intel Agilex® 7 and Intel® Stratix® 10 Design-Specific Reset Requirements for Stall-Free and Stallable RTL Modules
11.4.1.4. Object Manifest File Syntax x
11.4.1.4.1. XML Elements for ATTRIBUTES 11.4.1.4.2. XML Elements for INTERFACE 11.4.1.4.3. XML Elements for RESOURCES
11.4.1.4.1. XML Elements for ATTRIBUTES x
11.4.1.4.1.1. Interaction Between ALLOW_MERGINGand HAS_SIDE_EFFECTS Elements
12. Advanced Hardware Synthesis Controls x
12.1. Hardware Implementation Control for Math Functions 12.2. The hls_fpga_reg() Function
12.1. Hardware Implementation Control for Math Functions x
12.1.1. Math Function Hardware Implementation Summary 12.1.2. The --dsp-mode Command Option 12.1.3. The ihc::math_dsp_control Function
13. Intel® High Level Synthesis Compiler Pro Edition Reference Summary x
13.1. Intel® HLS Compiler Pro Edition i++ Command-Line Arguments 13.2. Intel® HLS Compiler Pro Edition Header Files 13.3. Intel® HLS Compiler Pro Edition Compiler-Defined Preprocessor Macros 13.4. Intel® HLS Compiler Pro Edition Keywords 13.5. Intel® HLS Compiler Pro Edition Simulation API (Testbench Only) 13.6. Intel® HLS Compiler Pro Edition Component Memory Attributes 13.7. Intel® HLS Compiler Pro Edition Loop Pragmas 13.8. Intel® HLS Compiler Pro Edition Scope Pragmas 13.9. Intel® HLS Compiler Pro Edition Component Attributes 13.10. Intel® HLS Compiler Pro Edition Component Default Interfaces 13.11. Intel® HLS Compiler Pro Edition Component Invocation Interface Control Attributes 13.12. Intel® HLS Compiler Pro Edition Component Macros 13.13. Intel® HLS Compiler Pro Edition Systems of Tasks API 13.14. Intel® HLS Compiler Pro Edition Pipes API 13.15. Intel® HLS Compiler Pro Edition Streaming Input Interfaces 13.16. Intel® HLS Compiler Pro Edition Streaming Output Interfaces 13.17. Intel® HLS Compiler Pro Edition Memory-Mapped Interfaces 13.18. Intel® HLS Compiler Pro Edition Load-Store Unit Control 13.19. Intel® HLS Compiler Pro Edition Arbitrary Precision Data Types
13.13. Intel® HLS Compiler Pro Edition Systems of Tasks API x
13.13.1. ihc::stream Class
A. Advanced Math Source Code Libraries x
A.1. Random Number Generator Library A.2. Matrix Multiplication Library A.3. Cholesky Decomposition Library
B. Supported Math Functions x
B.1. Math Functions Provided by the math.h Header File B.2. Math Functions Provided by the extendedmath.h Header File B.3. Math Functions Provided by the ac_fixed_math.h Header File B.4. Math Functions Provided by the hls_float.h Header File B.5. Math Functions Provided by the hls_float_math.h Header File B.6. Default Rounding Schemes and Subnormal Number Support
1. Intel® HLS Compiler Pro Edition Reference Manual
2. Compiler
3. C Language and Library Support
4. Component Interfaces
5. Component Memories (Memory Attributes)
6. Loops in Components
7. Component Concurrency
8. Arbitrary Precision Math Support
9. Component Target Frequency
10. Systems of Tasks
11. Libraries
12. Advanced Hardware Synthesis Controls
13. Intel® High Level Synthesis Compiler Pro Edition Reference Summary
A. Advanced Math Source Code Libraries
B. Supported Math Functions
C. Cyclone® V Restrictions
D. Intel® HLS Compiler Pro Edition Reference Manual Archives
E. Document Revision History of the Intel® HLS Compiler Pro Edition Reference Manual

2.1. Intel® HLS Compiler Pro Edition Command Options

Use the Intel® HLS Compiler Pro Edition command options to customize how the compiler performs general functions, customize file linking, or customize compilation.
Table 2.  General Command OptionsThese i++ command options perform general compiler functions.
Command Option Description
-h or --help Instructs the compiler to list all the command options and their descriptions on screen.
-o <result> Instructs the compiler to place its output into the <result> executable and the <result>.prj directory.

If you do not specify the -o <result>option, the compiler outputs an a.out file for Linux and an a.exe file for Windows. Use the -o <result> command option to specify the name of the compiler output.

Example command: i++ -o hlsoutput multiplier.c

Invoking this example command creates an hlsoutput executable for Linux and an hlsoutput.exe for Windows in your working directory.

--debug-log Instructs the compiler to generate a log file that contains diagnostic information.

The debug.log file is in the <result>.prj subdirectory within your current working directory.

If your compilation fails, the debug.log file is generated whether you set this option or not.

-v Verbose mode that instructs the compiler to display messages describing the progress of the compilation.

Example command: i++ -v multiplier.cpp, where multiplier.cpp is the input file.

--version Instructs the compiler to display its version information on screen.

Command: i++ --version

Table 3.  Command Options that Customize CompilationThese i++ command options perform compiler functions that impact the translation from source file to object file.
Option Description
-c Instructs the compiler to preprocess, parse, and generate object files (.o/.obj) in the current working directory. The linking stage is omitted.

Example command: i++ -march="Arria 10" -c multiplier.c

Invoking this example command creates a multiplier.o file and sets the name of the <result>.prj directory to multiplier.prj.

When you later link the .o file, the -o option affects only the name of the executable file. The name of the <result>.prj directory remains unchanged from when the directory name was set by i++ -c command invocation.

--component <components> Allows you to specify a comma-separated list of function names that you want to the compiler to synthesize to RTL.

Example command: i++ counter.cpp --component count

To use this option, your component must be configured with C-linkage using the extern "C" specification. For example: 
extern "C" int myComponent(int a, int b)

Using the component function attribute is preferred over using the --component command option to indicate functions that you want the compile to RTL.

-D <macro> [= <val> ] Allows you to pass a macro definition (<macro>) and its value (<val>) to the compiler.

If you do not a specify a value for <val>, its default value will be 1.

-g Generate debug information (default).
-g0 Do not generate debug information.
--gcc-toolchain=<GCC_dir>

Specifies the path to a GCC installation that you want to use for compilation. This path should be the absolute path to the directory that contains the GCC lib, bin, and include folders.

You should not need to use this if you configured your system as described in the Getting Started Guide.

--hyper-optimized-handshaking=[auto|off]

This option applies to Intel Agilex® 7 and Intel® Stratix® 10 devices only.

Use this option to modify the handshaking protocol used in certain areas of your design.

By default, the --hyper-optimized-handshaking option is set to auto.

When you enable this optimization, the compiler adds pipeline registers to the handshaking paths of the stallable nodes. This optimization results in a higher fMAX at the cost of increased area and latency due to the added registers.

Disabling this optimization typically decreases area and latency at the cost of lower fMAX.

Restriction: This option applies only to designs targeting Intel Agilex® 7 and Intel® Stratix® 10 devices. If you use this option when you target devices other than Intel Agilex® 7 and Intel® Stratix® 10 devices, the compiler exits with an error.
-I <dir> Adds a directory (<dir>) to the end of the include path list.
-march= [x86-64 | <FPGA_family> | <FPGA_part_number>] Instructs the compiler to compile the component to the specified architecture or FPGA family.
The -march compiler option can take one of the following values:
x86-64
Instructs the compiler to compile the code for an emulator flow.
"<FPGA_family>"
Instructs the compiler to compile the code for a target FPGA device family.
The <FPGA_family> value can be any of the following device families:
  • Agilex
  • Arria10 or "Arria 10"
  • CycloneV 1
  • Cyclone10GX or "Cyclone 10 GX"
  • Stratix10 or "Stratix 10"
Quotation marks are required only if you specify a FPGA family name specifier that contains spaces
<FPGA_part_number>
Instructs the compiler to compile the code for a target device. The compiler determines the FPGA device family from the FPGA part number that you specify here.

If you do not specify this option, -march=x86-64 is assumed.

If the parameter value that you specify contains spaces, surround the parameter value in quotation marks.

--quartus-compile Compiles your design with the Intel® Quartus® Prime compiler.

Example command: i++ --quartus-compile <input_files> ‑march="Arria 10"

When you specify this option, the Intel® Quartus® Prime compiler is run after the RTL is generated. The compiled Intel® Quartus® Prime project is put in the <result>.prj/quartus directory and a summary of the FPGA resource consumption and maximum clock frequency is added to the high level design reports in the <result>.prj/reports directory.

This compilation is intended to estimate the best achievable fMAX for your component. Your component is not expected to cleanly close timing in the reports.

--quartus-seed <seed> Specifies the seed numeric value that is used by Intel® Quartus® Prime project located in the <result>.prj/quartus directory.

This seed value is used by the Intel® Quartus® Prime Fitter for initial placement configuration when optimizing design placement to meet timing requirements (fMAX).

For more information about the Fitter seed, refer to Fitter Initial Placement Seed in the "Fitter Settings Reference" section of Intel® Quartus® Prime Pro Edition User Guide: Design Compilation .

--simulator <simulator_name> Specifies the simulator you are using to perform verification.
This command option can take the following values for <simulator_name>:
  • modelsim

    Use Siemens* EDA ModelSim* or Questa* for component verification.

  • none

    Disable verification. That is, generate RTL for components without the test bench.

If you do not specify this option, --simulator modelsim is assumed.

Important: The --simulator command option only works in conjunction with the -march command option.

The --simulator none option instructs the HLS compiler to skip the verification flow and generate RTL for the components without generating the corresponding test bench. If you use this option, the high-level design report (report.html) is generated more quickly but you cannot simulate your design. Without data from simulation, the report must omit verification statistics such as component latency.

Example command: i++ -march="<FPGA_family_or_part_number>" ‑‑simulator none multiplier.c

-ffp-contract=[ fast | on ]

For double-precision data types, controls whether the compiler can contract floating-point multiply and add or subtract operations into a single fused multiply-add (FMA), and controls whether the compiler skips intermediate rounding and conversions, except for code blocks fenced by #pragma clang fp contract(off).

This option has no effect on operations that involve single-precision data types.

The -ffp-contract option can take one of the following values:
fast
Math operations can be fused across multiple adjacent lines of code unless they are fenced by #pragma clang fp contract(off).

Math operations in code fenced by #pragma clang fp contract(on) can be fused only across a single line of code.

on
Math operations can be fused only across a single line of code unless they are fenced by #pragma clang fp contract(off).

Math operations in code fenced by #pragma clang fp contract(fast) can still be fused across multiple adjacent lines of code.

To learn more, review the following tutorials:
  • <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_contract
  • <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_ops
-ffp-reassociate

Controls whether the compiler can rearrange the order of floating-point arithmetic operations of any precision if the rearrangement improves throughput, latency, or both.

Code blocks fenced by #pragma clang fp reassociate(off) are not rearranged.

To learn more, review the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_ops

--daz For double data types only, disable subnormal support in native IEEE-754 double-precision floating-point computations.

To learn more, review the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/submnormal_and_rounding

--rounding= [ieee | faithful]

For double data types only, control rounding scheme for native IEEE-754 double-precision adders, multipliers, and dividers.

If you do not specify this option, adders and multipliers use IEEE-754 round to nearest, ties to even (RNE) rounding (0.5 ULP) and dividers use faithful rounding (1 ULP).

The --rounding option can take one of the following values:
ieee
All adders, multipliers, and dividers use IEEE-754 RNE rounding.

IEEE-754 RNE rounding rounds results to the nearest value. If the number falls midway, it is rounded to the nearest value with an even least-significant digit. This is the default rounding mode defined by IEEE 754-2008 standard.

IEEE-754 RNE rounding has a accuracy of 0.5 ULP.

faithful
All adders, multipliers, and dividers use faithful rounding.

Faithful rounding rounds results to either the upper or lower nearest single-precision numbers. Therefore, faithful rounding produces one of two possible values. The choice between the two is not defined.

Faithful rounding has a maximum error of one ULP. Errors are not guaranteed to be evenly distributed.

Faithful rounding mode is not defined by the IEEE-754 standard.

To learn more, review the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/submnormal_and_rounding

--clock <clock target> Optimizes the RTL for the specified clock frequency or period.

The <clock target> value must include a unit.

For example: 
i++ -march="Arria 10" test.cpp --clock 100MHz
i++ -march="Arria 10" test.cpp --clock 10ns
--dsp_mode= [prefer-dsp | prefer-softlogic | default] For supported data types and math operations, controls the hardware implementation of math functions on a global scope.
prefer-dsp
The compiler tries to implement supported math operations with DSPs.
prefer-softlogic
The compiler tries to implement supported math operations with soft logic using ALMs.
default
The compiler implements supported math operations based on data type and operation.

This value is the default.

For details about the implementation of math functions in hardware, refer to Math Function Hardware Implementation Summary.

To learn more, refer to the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/control_of_dsp_usage

Table 4.  Command Options that Customize File LinkingThese HLS command options specify compiler actions that impact the translation of the object file to the binary or RTL component.
Option Description
-ghdl[=<depth>]

Logs signals when running the verification executable to help you debug the generated RTL. After running the executable, the simulator logs waveforms to the a.prj/verification/vsim.wlf file.

Use the optional <depth> attribute to specify how many levels of hierarchy are logged. If you do not specify a value for the <depth> attribute, all signals are logged.

Use -ghdl=1 to log only the top-level signals.

For details about the ModelSim* waveform, see Debugging during Verification in Intel® High Level Synthesis Compiler Pro Edition User Guide.

-L <dir>

-L <dir>

(Linux only) Adds a directory (<dir>) to the end of the search path for the library files.
-l <library> (Linux only) Specifies the library file (.a) name when linking the object file to the binary.

On Windows, you can list library files (.lib) on the command line without specifying any command options or flags.

--x86-only Creates only the testbench executable.

The compiler outputs a <result> file for Linux or a <result>.exe file for Windows. The <result>.prj directory and its contents are not created.

--fpga-only Creates only the <result>.prj directory and its contents.

The testbench executable file ( <result> / <result>.exe) is not created.

Before you can simulate your hardware from a compilation output that uses this option, you must compile your testbench with the --x86-only option (or as part of a full compilation).

1 Cyclone® V device support is subject to restrictions. For details, refer to Cyclone V Restrictions.
Level Two Title