Intel® High Level Synthesis Compiler Pro Edition: Reference Manual

Download PDF
ID 683349
Date 12/13/2021
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
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 Supported Math Functions Conversion Rules Operations With Explicit Precision Controls Comparison Operators Additional hls_float Functions 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™ 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

8.5.1. Operators and Return Types Supported by the hls_float Data Type

The hls_float data type supports all overloaded math operators and a limited set of the math functions provided by the Intel® HLS Compiler Pro Edition. For some math operators, you can control the precision of the output by using templated versions of the functions.

Important: Due to the differences in the internal math implementations and rounding errors, the results from hls_float operations might not always be bit-accurate to those produced by C++ native floating-point types with the same exponent and mantissa bit widths. However, these results are validated against the infinitely accurate results.

Supported Math Functions

In addition to supporting all overloaded math operators, the Intel® HLS Compiler supports the following additional math functions for the hls_float data type through the HLS/hls_float_math.h header file:
  • Exponential and logarithmic functions 5:
    • ln, log2 , log10 , ln(1+x)
    • e x , 2 x , 10 x , e x −1
  • Advanced functions5:
    • reciprocal
    • reciprocal_sqrt
    • sqrt 5
    • cbrt (cube root)
    • hypot (hypotenuse)
  • Power functions5:
    • pow, powr, pown
  • Trigonometric functions5:
    • sin, cos, sincos
    • sinpi, cospi
    • asin, asinpi, acos, acospit, atan, atanpi, atan2

Conversion Rules

You can convert between different sizes of hls_float data types through assignment or by using the convert_to() function. For example, 
hls_float<8, 32> myFloat = ...;
hls_float<3, 18> myFloat2 = myFloat; // use rounding rules defined by hls_float type
hls_float <3, 18>myFloat3 = myFloat.convert_to<3, 18, ihc::fp_config::FP_Round::RZERO>();
// use rounding rules defined in convert_to() function call

To convert between native types (for example, float, double) and hls_float data types, assign to or from the types. Type conversion in an assignment occurs according to the rules in the Default Conversion Rules for hls_float Variables table that follows.

For two hls_float variables in a binary operation, the hls_float variable with the larger exponent bit-width is considered to be the "larger" variable. If the two variables have the same exponent bit width, the variable with the larger mantissa bit-width is considered to be the larger variable. The operands are then unified to the "larger" type before the binary operation occurs.

Native floating point data types and hls_float data types are converted to hls_float data types according to the rules in the Default Conversion Rules for hls_float Variables table that follows.

The Intel® HLS Compiler also provides some operations that leave the precision of input types untouched and provide control over the output precision. For details, see Operations With Explicit Precision Controls.

Table 21.  Default Conversion Rules for hls_float Variables
Data Type From hls_float To Data Type From Data Type To hls_float
hls_float with higher representable range Keep exponent equivalent.

The mantissa is rounded according to the rounding mode of the target hls_float (with the higher representable range).

+-Inf if the source of the conversion is out of the representable range.

Otherwise, keep exponent equivalent.

The mantissa is rounded according to the rounding mode of the target hls_float (with the smaller representable range).

float Convert original hls_float to hls_float<8, 23> with earlier hls_float rule, then bit-cast to float Bit-cast float to hls_float<8, 23>, and then convert to target hls_float precision using the hls_float to hls_float rules described earlier.
double Convert original hls_float to hls_float<11, 52> with earlier hls_float rule, then bit-cast to double Bit-cast double to hls_float<11, 52>, and then convert to target hls_float precision using the hls_float to hls_float rules described earlier.
long double

(emulation only)

(Linux only)

 Convert original hls_float to hls_float<15, 63> with earlier hls_float rule, then insert a 1-bit 1 to the MSB of fraction bits to get an approximate equivalent of 80-bit representation of long double Drop the explicit 1 fraction bit to convert long double to 79-bit hls_float<15, 63>
long double

(emulation only)

(Windows only)

 Same as double Same as double
C++ native integer types Truncate towards zero

Converting from hls_float that is larger than range of integer type is undefined behavior.

Round to nearest, tie breaks to even.

If the integer value is too large, the hls_float value saturates to plus infinity.

Operations With Explicit Precision Controls

The Intel® HLS Compiler provides the following operations that leave the precision of input hls_float-type variables untouched and let you control the output precision:

Rounding Mode Control For hls_float to hls_float Conversions
Syntax
convert_to<output_exponent_width, output_mantissa_width, rounding_mode>
Description

Use this method to override the rounding mode set for an hls_float variable when you are converting the variable to different precision.

By default, hls_float to hls_float conversions use the rounding mode that you specified when you declared the variable.

Multiplication
Syntax
ihc::hls_float< output_exponent_width, output_mantissa_width > ::mul <accuracy_setting], [subnormal_setting]> (hls_float_a, hls_float_b)
Where the optional parameters are defined as follows:
subnormal_setting
Optional parameter to specify whether input and output number are flushed to zero when carrying out basic binary operations explicitly.
Set this parameter with one of the following values:
  • ihc::fp_config::FP_Subnormal::ON

    Input and output numbers in the subnormal range are preserved.

    The target FPGA device must have subnormal support,

    Subnormal support might require more FPGA area.

  • ihc::fp_config::FP_Subnormal::OFF

    Input or output numbers in the subnormal range are flushed to zero.

  • ihc::fp_config::FP_Subnormal::AUTO

    With this setting, the Intel® HLS Compiler enables subnormal support only when it is directly supported by the target FPGA device and it does incur any extra FPGA area overhead.

If you do not set this parameter, the Intel® HLS Compiler uses the ihc::FP_Subnormal::AUTO subnormal setting.
accuracy_setting
Optional parameter that influences trade-offs between the accuracy of the result due to different rounding decisions in the intermediary calculations and the FPGA area utilized by the generated hardware. Floating-point operations with less accurate results typically use fewer logic elements.

For example, a divider with a high accuracy might use 20% more FPGA area than divider with low accuracy. The low accuracy divider has a higher error bound [1 unit of least precision (ULP)] than a high accuracy divider (0.5 ULP).

Set this parameter with one of the following values:
  • ihc::fp_config::FP_Accuracy::LOW
  • ihc::fp_config::FP_Accuracy::HIGH
If you do not set this parameter, the Intel® HLS Compiler uses the ihc::fp_config::FP_Accuracy::HIGH accuracy setting.
Description

This math function supplements the basic multiplication operation performed by the multiplication (*) operator.

Multiplies hls_float_a and flaot_b without changing the input types, and outputs an hls_float at the specified precision.

Addition/Subtraction/Division
Syntax
ihc::hls_float< output_exponent_width, output_mantissa_width > ::add <[optional parameters]> (hls_float_a, hls_float_b)

ihc::hls_float< output_exponent_width, output_mantissa_width > ::sub <[optional parameters]> (hls_float_a, hls_float_b)

ihc::hls_float< output_exponent_width, output_mantissa_width > ::div <[optional parameters]> (hls_float_a, hls_float_b)

Description

These math functions supplement the basic math operations performed by the addition/subtraction/division (+/ −//) operators.

Adds/Subtracts/Divides hls_float_a and hls_float_b by first casting hls_float_a and hls_float_b to the specified hls_floatprecision. The operation and output are at the specified precision.

You can also specify the optional parameters that are the accuracy_setting and subnormal_setting parameters described earlier.

Comparison Operators

Comparison operators (>, <, ==, !=, >=, <=) are subject to the conversion rules described earlier.

The == and != operators impose a bit-wise comparison of the casted values.

Comparisons with NaN always return false.

Additional hls_float Functions

The hls_float data type also has the following additional functions:
Table 22.  
Function Description
Getters and Setters
hls_float::get_exponent

hls_float::set_exponent

Gets/sets the exponent value of the hls_float variable.
hls_float::get_mantissa

hls_float::set_mantissa

Gets/sets the mantissa value of the hls_float variable.
hls_float::get_sign

hls_float::set_sign

Gets/sets the sign bit of the hls_float variable.
Special Constants
hls_float<e,m>::nan() Constant used to assign the hls_float variable a value of NaN.
hls_float<e,m>::pos_inf() Constant used to assign the hls_float variable a value of +∞.
hls_float<e,m>::neg_inf() Constant used to assign the hls_float variable a value of −∞.
Value Queries
hls_float::is_nan() Returns true if the value of the hls_float variable is NaN.
hls_float::is_inf() Returns true if the value of the hls_float variable is ±∞.
hls_float::is_zero() Returns true if the value of the hls_float variable is zero.
Special Functions
hls_float::next_after(next_val) Returns the next representable value towards next_val.
* Not supported for hls_float<15,63> precision variables.
Level Two Title