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

10.1. Task Functions

The Intel® HLS Compiler Pro Edition implements task functions in way similar to HLS component functions, but with some additional constraints.

Task Function Interfaces

You can get data in and out of task functions in the following ways:
Task function interfaces are subject to the following restrictions:
  • You cannot use Avalon® MM Host interfaces (ihc::mm_host) defined at global or file scope in a component or its tasks.
  • Pointer or reference data types cannot be passed to task functions as arguments unless they are a pointer or reference to an explicit Avalon® MM Host interface.
For more details and example of task function interfaces, refer to the following tutorial:

<quartus_installdir>/hls/examples/tutorials/system_of_tasks/interfaces_sot

Task Invocation Interface

You can invoke a function as a task with the ihc::launch<>() and ihc::collect<>() API.

An ihc::launch<task_function>() call in your code produces a call interface for the specified task with the top-level component as the source and the task as the sink. The top-level component invokes the call interface of a task by asserting the start signal to start a new execution of the task.

An ihc::collect<task_function>() call in your code produces a return interface for the specified task with the task as the source and the top-level component as the sink. This return interface has a done signal that is asserted by the task when it has completed a single execution. When the top-level component invokes the return interface it consumes this donesignal and retrieves any returned values.

In the High Level Design Reports (report.html), the ihc::launch and ihc::collect calls appear as blocking streaming write and streaming read operations.

Scalar Parameters and Return Values

Like HLS components, the scalar parameters and return value for an HLS task are implemented as conduits and the hand-shaking is implemented as a simple stall/valid handshake. The ihc::launch and ihc::collect calls connect directly to the HLS task function do and return streams.

In the High Level Design Report (report.html), the ihc::launch and ihc::collect calls appear as blocking streaming write and streaming read operations.

Interaction with External Systems

Task functions can use a global instance of the ihc::stream_in class to take an input from the external system, or a global instance of the ihc::stream_out class to provide output to the external system.

The global ihc::stream_in and ihc::stream_out streams must be declared outside of any struct variables, and they cannot be declared in arrays.

Communication Between HLS Task Functions

For two task functions to communicate with each other, connect them with a global ihc::stream object (instead of the ihc::stream_in and ihc::stream_out objects).

The global ihc::stream object must be declared outside of any struct variables, and it cannot be declared in an array.

The ihc::stream object has an API very similar to the ihc::stream_in and ihc::stream_out classes. However, since these streams always require handshaking, the API does not support the parameters ihc::usesReady or ihc::usesValid. They do support tryRead and tryWrite API functions.

The ihc::stream objects can have both of their endpoints within the system of tasks. This includes within the same function as well. For an example of using an ihc::stream within a single function as a FIFO, see the following tutorial: 
<quartus_installdir>/hls/examples/tutorials/system_of_tasks/internal_stream
If an instance of the ihc::stream class has only one endpoint within the system of tasks, it is treated as if it were a ihc::stream_in or ihc::stream_out class based on its usage within the system, so it can be used interchangeably with ihc::stream_in or ihc::stream_out (provided that the limitations do not affect the design). An ihc::stream object can be used for multiple tasks to communicate with one another. See the following tutorial: 
<quartus_installdir>/hls/examples/tutorials/system_of_tasks/parallel_loops
The following diagram shows how you might use the ihc::stream object to communicate between task functions:
Figure 13. Example of a Systems of Tasks using Internal Streams


HLS Task Function Restrictions

HLS task functions are subject to the following restrictions:
  • Task functions cannot be shared between multiple components.
  • All read sites and write sites for a stream must be within the same function (component or task).
  • If you implement a class member function as a task function, the member function must be static. If you want to parameterize the function behavior, use function parameters or template parameters. You cannot use instance variables of an object.
  • A task function can be launched (with ihc::launch) only from one component function or task function. The launching function and the collecting function can be different functions but they must part of the same component system of tasks.
  • A task function can be collected (with ihc::collect) only from one component or task function. The collecting function and the launching function can be different functions but they must part of the same component system of tasks.
  • No guarantee of execution order is provided between independent I/O instructions, even at the task level.

    The ihc::launch and ihc::collect calls to a particular task function are executed in order.

    Any stream accesses to that task from the current function are executed in instruction order only with respect to ihc::launch and ihc::collect calls to the corresponding function.

Figure 14. Example 1 of a Valid ihc::launch/ihc::collect Sequence
Figure 15. Example 2 of a Valid ihc::launch/ihc::collect Sequence
Figure 16. Example 3 of a Valid ihc::launch/ihc::collect Sequence
Figure 17. Example of an Invalid ihc::launch/ihc::collect Sequence

Task Attributes

You can use the following function-level attributes on an HLS task function:
  • hls_max_concurrency
  • hls_component_ii
  • hls_scheduler_target_fmax_mhz
  • hls_disable_component_pipelining

In addition to these function attributes, you can use any HLS attributes and pragmas within your HLS task functions. For example, you can use attributes and pragmas like #pragma ii, #pragma ivdep, hls_memory, and hls_register.

You cannot use component macros or component invocation interface control attributes when you define HLS task functions. For example, you cannot use hls_avalon_agent_register_argument, hls_conduit_argument, hls_stall_free_return, or hls_avalon_streaming_component

Task Capacity

The compiler schedules launches and collects in the top-level component or caller datapath.

If you schedule multiple tasks with different latencies, you might need to add capacity to ihc::launch and ihc::collect calls.

Similarly, setting the capacity parameter in an ihc::launch call inserts a buffer that allows the caller to push work onto the task function which is then free to pull work off that queue when it can.

Setting the capacity parameter in an ihc::collect call inserts a buffer that can hold the return values as they are computed by the task function. The caller function is free to pull the return values from the buffer at a convenient later time without causing backpressure on the task function.

For more information on how and when to use the capacity parameter with your ihc::launch and ihc::collect calls, refer to "Explicitly Add Buffer Capacity to Your Design When Needed" in the Intel HLS Compiler Best Practices Guide

You can also review the following tutorial: 
<quartus_installdir>/hls/examples/tutorials/system_of_tasks/launch_and_collect_capacity
Related Information
Level Two Title