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

13.1. Intel® HLS Compiler Pro Edition i++ Command-Line Arguments

Use the i++ command-line arguments to affect how your component is compiled and linked.

General i++ Command Options

Option Description
--debug-log Generate the compiler diagnostics log.
-h, --help List compiler command options along with brief descriptions.
-o result Place compiler output into the <result> executable and the <result>.prj directory.
-v Display messages describing the progress of the compilation.
--version Display compiler version information.

Command Options Affecting Compiling

Option Default Value Description
-c Preprocess, parse, and generate object files.
--component component name Comma-separated list of function names to compile to RTL.
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 ] Define a <macro> with <val> as its value.
-g   Generate debug information (default option).
-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.

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

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.

-I dir Add directory <dir> to the end of the main include path.
-march=[x86-64 | FPGA_family | FPGA_part_number] x86-64 Generate code for an emulator flow (x86-64) or for the specified FPGA family or FPGA part number.
--quartus-compile Run the HDL generated through Intel® Quartus® Prime to generate accurate fMAX and area estimates. Your component is not expected to cleanly close timing.
--quartus-seed <seed>   Specifies the Fitter seed to use when your component is compiled to hardware by Intel® Quartus® Prime.
--simulator simulator_name modelsim 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.

-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.

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.

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

  Relax the order of floating point arithmetic operations, except for code blocks fenced by #pragma clang fp reassociate(off)

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 double-precision floating-point computations.
--rounding= [ieee | faithful]  

For double data types only, control rounding scheme for 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 uses 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.

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.

--clock clock target 240 MHz Optimize 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] 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 with DSP blocks or soft logic (ALMs) 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

Command Options Affecting Linking

Option Default Value Description
-ghdl[=<depth>] Enable full debug visibility and logging of HDL signals in simulation.

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.

-L dir

-L dir

(Linux only) Add directory <dir> to the list of directories to be searched for library files specified with the -l option.
-l library (Linux only) Use the library name <library> when linking.
--x86-only   Create only the testbench executable ( <result>.out/ <result>.exe).
--fpga-only   Create only the <result>.prj directory and its contents.
Level Two Title