Intel® High Level Synthesis Compiler Pro Edition: Reference Manual

Download PDF
ID 683349
Date 10/04/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 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

13.15. Intel® HLS Compiler Pro Edition Streaming Input Interfaces

Use the stream_in object and template arguments to explicitly declare Avalon® Streaming (ST) input interfaces. You can also use the stream_in Function APIs.

Table 53.   Intel® HLS Compiler Pro Edition Streaming Input Interface Template Summary
Template Object or Parameter Description
ihc::stream_in Streaming input interface to the component.
ihc::buffer Specifies the capacity (in words) of the FIFO buffer on the input data that associates with the stream.
ihc::readyLatency Specifies the number of cycles between when the ready signal is deasserted and when the input stream can no longer accept new inputs.
ihc::bitsPerSymbol Describes how the data is broken into symbols on the data bus.
ihc::firstSymbolInHighOrderBits Specifies whether the data symbols in the stream are in big endian order.
ihc::usesPackets Exposes the startofpacket and endofpacket sideband signals on the stream interface.
ihc::usesEmpty

Exposes the empty out-of-band signal on the stream interface.

ihc::usesValid Controls whether a valid signal is present on the stream interface.

ihc::stream_in Template Object

Syntax
ihc::stream_in<datatype, template parameters >
Valid Values
Any valid C++ datatype
Default Value
N/A
Description
Streaming input interface to the component.

The width of the stream data bus is equal to a width of sizeof(datatype).

The testbench must populate this buffer (stream) fully before the component can start to read from the buffer.

To learn more, review the following tutorials:
  • <quartus_installdir>/hls/examples/tutorials/interfaces/explicit_streams_buffer
  • <quartus_installdir>/hls/examples/tutorials/interfaces/explicit_streams_packets_empty
  • <quartus_installdir>/hls/examples/tutorials/interfaces/explicit_streams_packet_ready_valid
  • <quartus_installdir>/hls/examples/tutorials/interfaces/explicit_streams_ready_latency
  • <quartus_installdir>/hls/examples/tutorials/interfaces/multiple_stream_call_sites

ihc::buffer Template Parameter

Syntax
ihc::buffer<value>
Valid Values
Non-negative integer value.
Default Value
0
Description
The capacity, in words, of the FIFO buffer on the input data that associates with the stream. The buffer has latency. It immediately consumes data, but this data is not immediately available to the logic in the component.

If you use the tryRead() function to access this stream and the stream read is scheduled within the first cycles of operation, the first (or more) calls to the tryRead() function might return false in simulation (and therefore in hardware).

Review the function viewer in the System Viewer of the High-Level Design Reports to see when operations are scheduled in your component. If you see this behavior, use the blocking read() function to ensure consistency between emulation and simulation.

This parameter is available only on input streams.

ihc::readyLatency Template Parameter

Syntax
ihc::readyLatency<value>
Valid Values
Non-negative integer value between 0-8.
Default Value
0
Description
The number of cycles between when the ready signal is deasserted and when the input stream can no longer accept new inputs.

ihc::bitsPerSymbol Template Parameter

Syntax
ihc::bitsPerSymbol<value>
Valid Values
A positive integer value that evenly divides by the data type size.
Default Value
Datatype size
Description
Describes how the data is broken into symbols on the data bus.

Data is broken down according to how you set the ihc::firstSymbolInHighOrderBits declaration. By default, data is broken down in little endian order.

ihc::firstSymbolInHighOrderBits Template Parameter

Syntax
ihc::firstSymbolInHighOrderBits<value>
Valid Values
true or false
Default Value
false
Description
Specifies whether the data symbols in the stream are in big endian order.

ihc::usesPackets Template Parameter

Syntax
ihc::usesPackets<value>
Valid Values
true or false
Default Value
false
Description
Exposes the startofpacket and endofpacket sideband signals on the stream interface, which can be accessed by the packet based reads/writes.

ihc::usesEmpty Template Parameter

Syntax
ihc::usesEmpty<value>
Valid Values
true or false
Default Value
false
Description

Exposes the empty out-of-band signal on the stream interface.

Use this declaration only with streams that read more than one data symbol per clock cycle.

The empty signal indicates the number of symbols on the data bus that do not represent valid data during the final stream read of a packet.

You can control whether the empty symbols are in the low-order bits or high-order bits with the ihc::firstSymbolInHighOrderBits declaration.

ihc::usesValid Template Parameter

Syntax
ihc::usesValid<value>
Valid Values
true or false
Default Value
true
Description
Controls whether a valid signal is present on the stream interface. If false, the upstream source must provide valid data on every cycle that ready is asserted.

This is equivalent to changing the stream read calls to tryRead and assuming that success is always true.

If set to false, buffer and readyLatency must be 0.

Intel® HLS Compiler Pro Edition Streaming Input Interface stream_in Function APIs

Table 54.   Intel® HLS Compiler Pro Edition Streaming Input Interface stream_in Function APIs
Function API Description
T read() Blocking read call to be used from within the component
T read(bool& sop, bool& eop)

Available only if usesPackets<true> is set.

Blocking read with out-of-band startofpacket and endofpacket signals.
T read(bool& sop, bool& eop, int& empty) Available only if usesPackets<true> and usesEmpty<true> are set.

Blocking read with out-of-band startofpacket, endofpacket, and empty signals.

T tryRead(bool &success) Non-blocking read call to be used from within the component. The success bool is set to true if the read was valid. That is, the Avalon® -ST valid signal was high when the component tried to read from the stream.

The emulation model of tryRead() is not cycle-accurate, so the behavior of tryRead() might differ between emulation and simulation.

T tryRead(bool& success, bool& sop, bool& eop)

Available only if usesPackets<true> is set.

Non-blocking read with out-of-band startofpacket and endofpacket signals.
T tryRead(bool& success, bool& sop, bool& eop, int& empty) Available only if usesPackets<true> and usesEmpty<true> are set.

Non-blocking read with out-of-band startofpacket, endofpacket, and emptysignals.

void write(T data) Blocking write call to be used from the testbench to populate the FIFO to be sent to the component.
void write(T data, bool sop, bool eop)

Available only if usesPackets<true> is set.

Blocking write call with out-of-band startofpacket and endofpacket signals.
void write(T data, bool sop, bool eop, int empty) Available only if usesPackets<true> and usesEmpty<true> are set.

Blocking write call with out-of-band startofpacket, endofpacket, and empty signals.

Intel® HLS Compiler Streaming Input Interfaces Code Example

The following code example illustrates both stream_in declarations and stream_in function APIs. 
 // Blocking read
void foo (ihc::stream_in<int> &a) {
 int x = a.read(); 

}
 // Non-blocking read
void foo_nb (ihc::stream_in<int> &a) {
 bool success = false;
 int x = a.tryRead(success);

 if (success) {
 // x is valid
 }
}

int main() {
 ihc::stream_in<int> a;
 ihc::stream_in<int> b;
 for (int i = 0; i < 10; i++) {
  a.write(i);
  b.write(i);
 }
 foo(a);
 foo_nb(b);
}
Level Two Title