Intel High Level Synthesis Compiler: Reference Manual
Intel HLS Compiler Reference Manual
- Indicates that a feature or content applies only to Intel® HLS Compiler Pro Edition.
- Indicates that a feature or content applies only to Intel® HLS Compiler Standard Edition.
In this publication, <quartus_installdir> refers to the location where you installed Intel® Quartus® Prime Design Suite.
-
- Windows
- C:\intelFPGA_pro\19.2
- Linux
- /home/<username>/intelFPGA_pro/19.2
-
- Windows
- C:\intelFPGA_standard\19.2
- Linux
- /home/<username>/intelFPGA_standard/19.2
Compiler
Intel HLS Compiler Command Options
| Command Option | Description |
|---|---|
| --debug-log | Instructs the compiler to
generate a log file that contains diagnostic
information. By default, the debug.log file is in the a.prj subdirectory within your current working directory. If you also include the -o <result> command option, the debug.log file will be in the <result>.prj subdirectory. If your compilation fails, the debug.log file is generated whether you set this option or not. |
| -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. |
| -v | Verbose mode that instructs
the compiler to display messages describing the
progress of the compilation. Example command: i++ -v hls/multiplier/multiplier.c, where multiplier.c is the input file. |
| --version | Instructs the compiler to
display its version information on screen. Command: i++ --version |
| 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 compile 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 compiler to synthesize. |
| -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® 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 Stratix 10. If you use this option when
you target devices other than 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:
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. |
| --promote-integers | Instructs the compiler to use additional FPGA
resources to mimic g++ integer promotion. Integer promotion occurs
when all integer operations are carried out in 32 bits even if the
largest operand is smaller than 32 bits. The default behavior is to carry out integer operations in the size of the largest operand. Refer to the <path to i++ installation>/examples/tutorials/best_practices/integer_promotion design example for usage information on the --promote-integers command option. In Pro Edition, the compiler always promotes integers for standard types. Use the ac_int datatypes if you want smaller (or larger) datatypes. |
| --quartus-compile | Compiles your HDL file 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 HDL 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. |
| --simulator <simulator_name> | Specifies the simulator you are using to perform verification. This command option can take the following
values for <simulator_name>:
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 co-simulate your design. Without data from co-simulation, the report must omit verification statistics such as component latency. Example command: i++ -march="<FPGA_family_or_part_number>" ‑‑simulator none multiplier.c |
| Option | Description |
|---|---|
| --clock <clock_spec> | Optimizes the RTL for the specified clock frequency or period. |
| --fpc | Removes intermediate rounding and conversion whenever possible. To see an example of when and how to use this option, review the tutorial in <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_ops. |
| --fp-relaxed | Relaxes the order of arithmetic operations. To see an example of how to use this option, review the tutorial in <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_ops. |
| -ghdl | Logs all signals when running the verification executable. After
running the executable, the simulator logs waveforms to the a.prj/verification/vsim.wlf file. For details about the ModelSim* waveform, see Debugging during Verification in Intel® High Level Synthesis Compiler User Guide. |
| -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 an <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 co-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). |
- set_global_assignment -name INTERNAL_FLASH_UPDATE_MODE "SINGLE IMAGE WITH ERAM"
- set_global_assignment -name INTERNAL_FLASH_UPDATE_MODE "SINGLE COMP IMAGE WITH ERAM"
Compiler Interoperability
To see what versions of GCC and Microsoft Visual Studio the Intel® HLS Compiler supports, see " Intel® High Level Synthesis Compiler Prerequisites" in Intel® High Level Synthesis Compiler Getting Started Guide.
The interoperability between GCC or Microsoft Visual Studio, and the Intel® HLS Compiler lets you decouple your testbench development from your component development. Decoupling your testbench development can be useful for situations where you want to iterate your testbench quickly with platform-native compilers (GCC/Microsoft Visual Studio), without having to recompile the RTL generated for your component.
With Microsoft Visual Studio, you can compile only code that does not explicitly use the Avalon® -Streaming interface.
To create only your testbench executable with the i++ command, specify the --x86-only option.
You can choose to only generate RTL and cosimulation support for your component by linking the object file or files for your component with the Intel® High Level Synthesis Compiler.
To generate only your RTL and cosimulation support for your component, specify the --fpga-only option.
To use a native compiler (GCC or Microsoft Visual Studio) to compile your Intel® HLS Compiler code, you must point the native compiler to Intel® HLS Compiler resources and libraries. The Intel® HLS Compiler example designs contain build scripts (Makefile for Linux and build.bat for Windows) that you can use as examples of the required configuration. These scripts locate the Intel® HLS Compiler installation, so you do not need to hard-code the locations in your build scripts.
GCC
The following instructions were tested with GCC compiler and C++ Libraries version 5.4.0.
- Add the
Intel® HLS Compiler header files
to the g++ command include path.
The header files are in the quartus_installdir/hls/include directory.
- Add the HLS emulation library to the linker search path.
The emulation library is in the quartus_installdir/hls/host/linux64/lib directory.
- Add the hls_emul library to the linker command.
- Ensure that you specify the -std=c++14 option of the g++ command.
- If you are using HLS tasks in a system of tasks (ihc::launch and ihc:collect), add the pthread library to the linker command.
- If you are using arbitrary precision datatypes, include the reference
version instead of the FPGA-optimized version provided with the
Intel® HLS Compiler. You can use the __INTELFPGA_COMPILER__ macro to control which version is
included:
#ifdef __INTELFPGA_COMPILER__ #include "HLS/ac_int.h" #else #include "ref/ac_int.h" #endif
g++ myFile.cpp -I"$(HLS_INSTALL_DIR)/include" -L"$(HLS_INSTALL_DIR)/host/linux64/lib" -lhls_emul -pthread -std=c++14
Microsoft Visual C++
The following instructions were tested with Microsoft Visual Studio 2015 Professional.
To compile your Intel® HLS Compiler code with Microsoft Visual C++:
- Add the
Intel® HLS Compiler header files
to the compiler command include path.
The header files are in the quartus_installdir\hls\include directory.
- Add the HLS emulation library to the linker search path.
The emulation library is in the quartus_installdir\hls\host\windows64\lib directory.
- Add the hls_emul library to the linker command.
- If you are using arbitrary precision datatypes, include the reference
version instead of the FPGA-optimized version provided with the
Intel® HLS Compiler. You can use the __INTELFPGA_COMPILER__ macro to control which version is
included:
#ifdef __INTELFPGA_COMPILER__ #include "HLS/ac_int.h" #else #include "ref/ac_int.h" #endif
cl myFile.cpp /I "%HLS_INSTALL_DIR%\include" /nologo /EHsc /wd4068 /MD /link "/libpath:%HLS_INSTALL_DIR%\host\windows64\lib" hls_emul.lib
Intel HLS Compiler Pipeline Approach
The Intel® HLS Compiler attempts to pipeline functions as much as possible. Different stages of the pipeline might have multiple operations performed in parallel.
The following figure shows an example of the pipeline architecture generated by the Intel® HLS Compiler. The numbered operations on the right side represent the pipeline implementation of the C++ code on the left side of the figure. Each box in the right side of the figure is an operation in the pipeline.
With a pipelined approach, multiple invocations of the component can be simultaneously active. For example, the earlier figure shows that the first invocation of the component can be returning a result at the same time the fourth invocation of the component is called.
One invocation of a component advances to the its next stage in the pipeline only after all of the operations of its current stage are complete.
Some operations can stall the pipeline. A common example of operations that can stall a pipeline is a variable latency operation like a memory load or store operation. To support pipeline stalls, the Intel® HLS Compiler propagates ready and valid signals through the pipeline to all operations that have a variable latency.
For operations that have a fixed latency, the Intel® HLS Compiler can statically schedule the interaction between the operations and ready signals are not needed between the stages with fixed latency operations. In these cases, the compiler optimizes the pipeline to statically schedule the operations, which significantly reduces the logic required to implement the pipeline.
C Language and Library Support
Supported C and C++ Subset for Component Synthesis
The compiler cannot synthesize code for dynamic memory allocation, virtual functions, function pointers, and C++ or C library functions except the supported math functions explicitly mentioned in the appendix of this document. In general, the compiler can synthesize functions that include classes, structs, functions, templates, and pointers.
While some C++ constructs are synthesizable, aim to create a component function in C99 whenever possible.
C and C++ Libraries
| HLS Header File | Description |
|---|---|
| HLS/hls.h | Required for component identification and component parameter interfaces. |
| HLS/math.h | Includes FPGA-specific definitions for the math functions from the math.h for your operating system. |
| HLS/extendedmath.h | Includes additional FPGA-specific definitions of math functions not in math.h. |
| HLS/ac_int.h | Provides FPGA-optimized arbitrary width integer support. |
| HLS/ac_fixed.h |
Provides FPGA-optimized arbitrary precision fixed point support. |
| HLS/ac_fixed_math.h |
Provides FPGA-optimized arbitrary precision fixed point math functions. |
| HLS/stdio.h | Provides printf support for components so that printf statements work in x86 emulations, but are disabled in component when compiling to an FPGA architecture. |
| <iostream> | To use cout and cerr in your component, guard the statements with the HLS_SYNTHESIS macro. |
math.h
To access functions in math.h from a component to be synthesized, include the "HLS/math.h" file in your source code. The header ensures that the components call the hardware versions of the math functions.
For more information about supported math.h functions, see Supported Math Functions.
stdio.h
Synthesized component functions generally do not support C and C++ standard library functions such as FILE pointers.
A component can call printf by including the header file HLS/stdio.h. This header changes the behavior of printf depending on the compilation target:
- For compilation that targets the x86-64 architecture (that is, -march=x86-64 ), the printf call behaves as normal.
- For compilation that targets the FPGA architecture (that is, ‑march="<FPGA_family_or_part_number>"), the compiler removes the printf call.
If you use printf in a component function without first including the #include "HLS/stdio.h" line in your code, you get an error message similar to the following error when you compile hardware to the FPGA architecture:
$ i++ -march="<FPGA_family_or_part_number>" --component dut test.cpp Error: HLS gen_qsys FAILED. See ./a.prj/dut.log for details.
You can use C and C++ standard library functions such as fopen and printf as normal in all testbench functions.
iostream
#include “HLS/hls.h”
#include <iostream>
component int debug_component (int a){
#ifndef HLS_SYNTHESIS
std::cout << “input value: ” << a << std::endl;
#endif
return a;
}
If you attempt to use cout or cerr in a component function without guarding the line in your code with the HLS_SYNTHESIS macro , you get an error message similar to the following error when you compile hardware to the FPGA architecture:
$ i++ -march="<FPGA_family_or_part_number>" run.cpp run.cpp:5: Compiler Error: Cannot synthesize std::cout used inside of a component. HLS Main Optimizer FAILED.
Templated and Overloaded Functions
Templated Functions
Templated Functions as an HLS Component
When you create a template function, you must declare the variant of the function to synthesize into hardware.
template <typename T, int MULT>
T multadd (T a, T b) {
return MULT * (a + b);
}
template component int multadd<int, 5>(int a, int b);
This declaration combined with the earlier template definition marks the int variant with MULT=5 of the multiadd function to be generated into a component. This component can now be invoked from the testbench.
Templated Functions as an HLS Task
If you want to use the function as a task in a system of tasks, use the ihc::launch and ihc::collect calls, and wrap the function that is called in parentheses.
component void foo () {
int a, b;
ihc::launch((multadd<int, 5>), a, b);
int res = ihc::collect((multadd<int, 5>));
}
test.cpp:10:7: error: expected '>'
ihc::launch(multadd<int, 5>, a, b);
^
note: expanded from macro 'launch'
#define launch(x, ...) _launch<decltype(x),x>(__VA_ARGS__)
^
test.cpp:10:27: error: expected unqualified-id
ihc::launch(multadd<int, 5>, a, b);
Overloaded Functions
To overload a component function, define multiple variants of the function.
component int mult (int a, int b) {
return a * b;
}
component float mult (float a, float b) {
return a * b;
}
Function Name Mapping
A mapping of the full function declaration to the synthesized function name is provided in the summary page of the high-level design reports (repoort.html). The synthesized function name is used for all the other reports such as the loops report and area analysis.
The following example shows an example of this table in the report:
Arbitrary Precision Math Support
| AC Datatype | Intel Header File | Description |
|---|---|---|
| ac_int | HLS/ac_int.h | Arbitrary width integer support To learn
more, review the following tutorials:
|
| ac_fixed | HLS/ac_fixed.h | Arbitrary precision fixed-point support To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_fixed_constructor |
| HLS/ac_fixed_math.h | Support for some nonstandard math functions for arbitrary
precision fixed-point datatypes To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_fixed_math_library |
|
| ac_complex | HLS/ac_complex.h | Arbitrary precision complex number support |
The Intel® HLS Compiler also supports some nonstandard math functions for the ac_fixed datatype when you include the HLS/ac_fixed_math.h header file.
Advantages of AC Datatypes
The AC datatypes have the following advantages over using standard C/C++ datatypes in your components:
- You can achieve smaller datapaths and processing elements for various operations in the circuit.
- The datatypes ensure that all operations are carried out in a size guaranteed not to lose any data. However, you can still lose data if you store data into a location where the datatype is too small.
Limitations of AC Datatypes
The AC datatypes have the following limitations:
- Multipliers are limited to generating 512-bit results.
- Dividers are limited to a maximum of 64 bits.
- The Intel header files are not compatible with GCC or MSVC. When you
use the Intel header files, you cannot use GCC or MSVC to compile your testbench. Both
your component and testbench must be compiled with the
Intel® HLS Compiler.
To compile AC datatypes with GCC or MSVC, use the reference AC datatypes headers also provided with he Intel® HLS Compiler. For details, see AC Datatypes and Native Compilers.
Declaring ac_int Datatypes in Your Component
For a list of supported operators and their return types, see "Chapter 2: Arbitrary-Length Bit-Accurate Integer and Fixed-Point Datatypes" in Mentor Graphics Algorithmic C (AC) Datatypes, which is available in the following file: <quartus_installdir>/hls/include/ref/ac_datatypes_ref.pdf.
Important Usage Information on the ac_int Datatype
The ac_int datatype automatically increases the size of the result of the operation to guarantee that the intermediate operations never overflow. However, the HLS compiler automatically truncates or extends the result to the size of the specified destination container, so ensure that the storage variable for your computation is large enough.
The HLS compiler installation package includes a number of examples in the tutorials. Refer to the tutorials in <quartus_installdir>/hls/example/tutorials/ac_datatypes for some of the recommended practices.
Integer Promotion and ac_int Datatypes
The rules of integer promotion when you use ac_int datatypes are different from standard C/C++ rules. Your component design should account for these differing rules.
- Both operands are standard integer types (int, short, long, unsigned char, or signed char):
If both operands are of standard integer type (for example char or short) operations, integers are promoted following the C/C++ standard. That is, the operation is carried out in the datatype and size of the largest operand, but at least 32 bits. The expression returns the result in the larger datatype.
- Both operands are ac_int datatypes:
If both operands are ac_int datatypes, operations are carried out in the smallest ac_int datatype needed to contain all values. For example, the multiplication of two 8-bit ac_int values is carried out as an 16-bit operation. The expression returns the result in that type.
-
One operand is a standard integer type and one operand is an ac_int type:
If the expression has one standard datatype and one ac_int type, the rules for ac_int datatype promotion apply. The resulting expression type is always an ac_int datatype. For example, if you add a short datatype and an ap_int<16> datatype, the resulting datatype is ac_int<17>.
ac_int<5, true> ap;
...
if (ap < 4) {
...
If the operands are signed differently and the unsigned type is at least as large as the signed type, the operation is carried out as an unsigned operations. Otherwise, the unsigned operand is converted to a signed operand.
uint3 x = 7;
if (x != -1) {
// FAIL
}
Debugging Your Use of the ac_int Datatype
When you use the DEBUG_AC_INT_WARNING and DEBUG_AC_INT_ERROR macros, you cannot declare constexpr ac_int variables or constexpr ac_int arrays.
| Tool | Description |
|---|---|
| DEBUG_AC_INT_WARNING | Emits a warning for each detected overflow. |
| DEBUG_AC_INT_ERROR |
Emits a message for the first overflow that is detected and then exits the component with an error. |
Review the ac_int_overflow tutorial in <quartus_installdir>/hls/example/tutorials/ac_datatypes to learn more.
Declaring ac_fixed Datatypes in Your Component
For a list of supported operators and their return types, see "Chapter 2: Arbitrary-Length Bit-Accurate Integer and Fixed-Point Datatypes" in Mentor Graphics Algorithmic C (AC) Datatypes, which is available in the following file: <quartus_installdir>/hls/include/ref/ac_datatypes_ref.pdf.
Declaring ac_complex Datatypes in Your Component
For a list of supported operators and their return types, see "4. Complex Datatype" in Mentor Graphics Algorithmic C (AC) Datatypes, which is available in the following file: <quartus_installdir>/hls/include/ref/ac_datatypes_ref.pdf.
AC Datatypes and Native Compilers
The reference version of the Mentor Graphics* Algorithmic C (AC) datatypes is also provided with the Intel® HLS Compiler. Do not use these reference header files in your component if you want to compile your component with an FPGA target.
Use the reference header files for AC datatypes to confirm functional correctness in your component when you are compiling your component with native compilers (g++ or MSVC).
If you use the reference header files and compile your component to an FPGA target, your component can compile successfully but your component QoR will be poor.
All of your code must use the same header files (either the reference header files or the FPGA-optimized header files). For example, your code cannot use the reference header files in your testbench and, at the same time, use the FPGA-optimized header file in your component code.
| AC Datatype | Reference Header File | Description |
|---|---|---|
| ac_int | ref/ac_int.h | Arbitrary width integer support |
| ac_fixed | ref/ac_fixed.h | Arbitrary precision fixed-point support |
| ac_complex | ref/ac_complex.h | Arbitrary precision complex datatype support |
Component Interfaces
The component invocation interface is common to all HLS components and contains the return data (for nonvoid functions) and handshake signals for passing control to the component, and for receiving control back when the component finishes executing.
The parameter interface is the protocol you use to transfer data in and out of your component function. The parameter interface for your component is based on the parameters that you define in your component function signature.
Component Invocation Interface
- A call interface that consists of start and busy signals. The call interface is sometimes referred to as the do stream.
- A return interface that consists of done and stall signals. The return interface is sometimes referred to as the return stream.
- Return data if the component function has a return type that is not void
In addition, you can indicate the control signals that correspond to the actions of calling your component by using the component invocation interface arguments. For details, see Component Invocation Interface Arguments.
Scalar Parameters
The inputs are read into the component when the external system pulls the start signal high and the component keeps the busy signal low.
For an example of how to specify a scalar parameters and how it is read in by a component, see the a argument in Figure 2 and Figure 3.
Pointer and Reference Parameters
You can customize these pointer interfaces using the mm_master<> class.
For details about Avalon® (MM) Master interfaces, see Avalon Memory-Mapped Master Interfaces.
Interface Definition Example: Component with Both Scalar and Pointer Arguments
component int dut(int a, int* b, int i) {
return a*b[i];
}
If the dut component raises the busy signal, the caller needs to keep the start signal high and continue asserting the input arguments. Similarly, if the component downstream of dut raises the stall signal, then dut holds the done signal high until the stallsignal is de-asserted.
Avalon Streaming Interfaces
A component can have input and output streams that conform to the Avalon-ST interface specifications. These input and output streams are represented in the C source by passing references to ihc::stream_in<> and ihc::stream_out<> objects as function arguments to the component.
When you use an Avalon-ST interface, you can serialize the data over several clock cycles. That is, one component invocation can read from a stream multiple times.
You cannot derive new classes from the stream classes or encapsulate them in other formats such as structs or arrays. However, you may use references to instances of these classes as references inside other classes, meaning that you can create a class that has a reference to a stream object as a data member.
A component can have multiple read sites for a stream. Similarly, a component can have multiple write sites for a stream. However, try to restrict each stream in your design to a single read site, a single write site, or one of each.
For more information about streaming interfaces, refer to "Avalon Streaming Interfaces" in Avalon Interface Specifications. The Intel® HLS Compiler does not support the Avalon-ST channel or error signals.
Streaming Input Interfaces
| Template Object or Argument | 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. |
| 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 co-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. |
Streaming Output Interfaces
| Template Object or Argument | Description |
|---|---|
| ihc::stream_out | Streaming output interface from the component. |
| 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::usesReady | Controls whether a ready signal is present. |
| Function API | Description |
|---|---|
| void write(T data) | Blocking write call from the component |
| void write(T data, bool sop, bool eop) |
Available only if usesPackets<true> is set. Blocking write 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 with out-of-band startofpacket, endofpacket, and empty signals. |
| bool tryWrite(T data) | Non-blocking write call from the component. The return value represents whether the write was successful. |
| bool tryWrite(T data, bool sop, bool eop) |
Available only if usesPackets<true> is set. Non-blocking write with out-of-band startofpacket and endofpacket signals.The return value represents whether the write was successful. That is, the downstream interface was pulling the ready signal high while the HLS component tried to write to the stream. |
| bool tryWrite(T data, bool sop, bool eop, int empty) | Available only if usesPackets<true> and usesEmpty<true> are set. Non-blocking write with out-of-band startofpacket, endofpacket, and empty signals. The return value represents whether the write was successful. |
| T read() | Blocking read call to be used from the testbench to read back the data from the component |
| T read(bool &sop, bool &eop) |
Available only if usesPackets<true> is set. Blocking read call to be used from the testbench to read back the data from the component 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 call to be used from the testbench to read back the data from the component with out-of-band startofpacket, endofpacket, and empty signals. |
Avalon Memory-Mapped Master Interfaces
Each mm_master argument of a component results in an input conduit for the address. That input conduit is associated with the component start and busy signals. In addition to this input conduit, a unique Avalon® MM Master interface is created for each address space. Master interfaces that share the same address space are arbitrated on the same interface.
For more information about Avalon® MM Master interfaces, refer to "Avalon Memory-Mapped Interfaces" in Avalon Interface Specifications.
| Template Object or Argument | Description |
|---|---|
| ihc::mm_master | The underlying pointer type. |
| ihc::dwidth | The width of the memory-mapped data bus in bits |
| ihc::awidth | The width of the memory-mapped address bus in bits. |
| ihc::aspace | The address space of the interface that associates with the master. |
| ihc::latency | The guaranteed latency from when a read command exits the component when the external memory returns valid read data. |
| ihc::maxburst | The maximum number of data transfers that can associate with a read or write transaction. |
| ihc::align | The alignment of the base pointer address in bytes. |
| ihc::readwrite_mode | The port direction of the interface. |
| ihc::waitrequest |
Adds the waitrequest signal that is asserted by the slave when it is unable to respond to a read or write request. |
| getInterfaceAtIndex | This testbench function is used to index into an mm_master object. |
Memory-Mapped Master Testbench Constructor
To create an mm_master<> object, add the following constructor in your code:
ihc::mm_master<int, … > mm(void* ptr, int size, bool use_socket=false);
where the constructor arguments are as follows:
- ptr is the underlying pointer to the memory in the testbench
- size is the total size of the buffer in bytes
-
use_socket is the option you use to
override the copying of the memory buffer and have all the memory accesses pass back to the
testbench memory
By default, the Intel® HLS Compiler copies the memory buffer over to the simulator and then copies it back after the component has run. In some cases, such as pointer-chasing in linked lists, copying the memory buffer back and forth is undesirable. You can override this behavior by setting use_socket to true.
Note: When you set use_socket to true, only Avalon® MM Master interfaces with 64-bit wide addresses are supported. In addition, setting this option increases the run time of the simulation.
Implicit and Explicit Examples of Describing a Memory Interface
Implicit Example
The following code example arbitrates the load and store instructions from both pointer dereferences to a single interface on the component's top-level module. This interface will have a data bus width of 64 bits, an address width of 64 bits, and a fixed latency of 1.
#include "HLS/hls.h"
component void dut(int *ptr1, int *ptr2) {
*ptr1 += *ptr2;
*ptr2 += ptr1[1];
}
int main(void) {
int x[2] = {0, 1};
int y = 2;
dut(x, &y);
return 0;
}
Explicit Example
This example demonstrates how to optimize the previous code snippet for a specific memory interface using the explicit mm_master class. The mm_master class has a defined template, and it has the following characteristics:
- Each interface is given a unique ID that infers two independent interfaces and reduces the amount of arbitration within the component.
- The data bus width is larger than the default width of 64 bits.
- The address bus width is smaller than the default width of 64 bits.
- The interfaces have a fixed latency of 2.
By defining these characteristics, you state that your system returns valid read data after exactly two clock cycles and that the interface never stalls for both reads and writes, but the system must be able to provide two different memories. A unique physical Avalon® -MM master port ( as specified by the aspace parameter) is expected to correspond to a unique physical memory. If you connect multiple Avalon® -MM Master interfaces with different physical Avalon® -MM master ports to the same physical memory, the Intel® HLS Compiler cannot ensure functional correctness for any memory dependencies.
#include "HLS/hls.h"
typedef ihc::mm_master<int, ihc::dwidth<256>,
ihc::awidth<32>,
ihc::aspace<1>,
ihc::latency<2> > Master1;
typedef ihc::mm_master<int, ihc::dwidth<256>,
ihc::awidth<32>,
ihc::aspace<4>,
ihc::latency<2> > Master2;
component void dut(Master1 &mm1,Master2 &mm2) {
*mm1 += *mm2;
*mm2 += mm1[1];
}
int main(void) {
int x[2] = {0, 1};
int y = 2;
Master1 mm_x(x,2*sizeof(int),false);
Master2 mm_y(&y,sizeof(int),false);
dut(mm_x, mm_y);
return 0;
}
Slave Interfaces
Slave interfaces are implemented as Avalon® Memory Mapped ( Avalon® -MM) Slave interfaces. For details about the Avalon® -MM Slave interfaces, see "Avalon Memory-Mapped Interfaces in Avalon Interface Specifications.
| Slave Type | Associated Slave Interface | Read/Write Behavior | Synchronization | Read Latency | Controlling Interface Data Width |
|---|---|---|---|---|---|
| Register | The component control and status register (CSR) slave. | The component cannot update these registers from the datapath, so you can read back only data that you wrote in. | Synchronized with the component start signal. | Fixed value of 1. | Always 64 bits |
| Memory (M20K/ MLAB) | Dedicated slave interface on the component. |
The component reads from this memory and updates it as it runs. Updates from the component datapath are visible in memory. |
Reads and writes to slave memories from outside of the component should occur only when your component is not executing. You might experience undefined component behavior if outside slave memory accesses occur when your component is executing. The undefined behavior can occur even if a slave memory access is to a memory address that the component does not access. |
Fixed value that is dependent on the component memory access pattern
and any attributes or pragmas that you set. See the Function Viewer report in the High-Level Design Report (report.html) for the read latency of a specific slave memory argument. |
The data width is a multiple of the slave data type, where the multiple is determined by coalescing the internal accesses. |
Control and Status Register (CSR) Slave
Any arguments that are labeled as hls_avalon_slave_register_argument are located in this memory space. The resulting memory map is described in the automatically generated header file <results>.prj/components/<component_name>_csr.h. This file also provides the C macros for a master to interact with the slave.
The control and status registers (that is, function call and return) of an hls_avalon_slave_component attribute are implemented in this interface.
You do not need to use the hls_avalon_slave_component attribute to use the hls_avalon_slave_register_argument attribute.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/interfaces/mm_slaves
Example code of a component with a CSR slave:
#include "HLS/hls.h"
struct MyStruct {
int f;
double j;
short k;
};
hls_avalon_slave_component
component MyStruct mycomp_xyz (hls_avalon_slave_register_argument int y,
hls_avalon_slave_register_argument MyStruct struct_argument,
hls_avalon_slave_register_argument unsigned long long mylong,
hls_avalon_slave_register_argument char char_arg
) {
return struct_argument;
}
Generated C header file for the component mycomp_xyz:
/* This header file describes the CSR Slave for the mycomp_xyz component */
#ifndef __MYCOMP_XYZ_CSR_REGS_H__
#define __MYCOMP_XYZ_CSR_REGS_H__
/******************************************************************************/
/* Memory Map Summary */
/******************************************************************************/
/*
Register | Access | Register Contents | Description
Address | | (64-bits) |
------------|---------|--------------------------|-----------------------------
0x0 | R | {reserved[62:0], | Read the busy status of
| | busy[0:0]} | the component
| | | 0 - the component is ready
| | | to accept a new start
| | | 1 - the component cannot
| | | accept a new start
------------|---------|--------------------------|-----------------------------
0x8 | W | {reserved[62:0], | Write 1 to signal start to
| | start[0:0]} | the component
------------|---------|--------------------------|-----------------------------
0x10 | R/W | {reserved[62:0], | 0 - Disable interrupt,
| | interrupt_enable[0:0]} | 1 - Enable interrupt
------------|---------|--------------------------|-----------------------------
0x18 | R/Wclr | {reserved[61:0], | Signals component completion
| | done[0:0], | done is read-only and
| | interrupt_status[0:0]} | interrupt_status is write 1
| | | to clear
------------|---------|--------------------------|-----------------------------
0x20 | R | {returndata[63:0]} | Return data (0 of 3)
------------|---------|--------------------------|-----------------------------
0x28 | R | {returndata[127:64]} | Return data (1 of 3)
------------|---------|--------------------------|-----------------------------
0x30 | R | {returndata[191:128]} | Return data (2 of 3)
------------|---------|--------------------------|-----------------------------
0x38 | R/W | {reserved[31:0], | Argument y
| | y[31:0]} |
------------|---------|--------------------------|-----------------------------
0x40 | R/W | {struct_argument[63:0]} | Argument struct_argument (0 of 3)
------------|---------|--------------------------|-----------------------------
0x48 | R/W | {struct_argument[127:64]} | Argument struct_argument (1 of 3)
------------|---------|--------------------------|-----------------------------
0x50 | R/W | {struct_argument[191:128]} | Argument struct_argument (2 of 3)
------------|---------|--------------------------|-----------------------------
0x58 | R/W | {mylong[63:0]} | Argument mylong
------------|---------|--------------------------|-----------------------------
0x60 | R/W | {reserved[55:0], | Argument char_arg
| | char_arg[7:0]} |
NOTE: Writes to reserved bits will be ignored and reads from reserved
bits will return undefined values.
*/
/******************************************************************************/
/* Register Address Macros */
/******************************************************************************/
/* Byte Addresses */
#define MYCOMP_XYZ_CSR_BUSY_REG (0x0)
#define MYCOMP_XYZ_CSR_START_REG (0x8)
#define MYCOMP_XYZ_CSR_INTERRUPT_ENABLE_REG (0x10)
#define MYCOMP_XYZ_CSR_INTERRUPT_STATUS_REG (0x18)
#define MYCOMP_XYZ_CSR_RETURNDATA_0_REG (0x20)
#define MYCOMP_XYZ_CSR_RETURNDATA_1_REG (0x28)
#define MYCOMP_XYZ_CSR_RETURNDATA_2_REG (0x30)
#define MYCOMP_XYZ_CSR_ARG_Y_REG (0x38)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_0_REG (0x40)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_1_REG (0x48)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_2_REG (0x50)
#define MYCOMP_XYZ_CSR_ARG_MYLONG_REG (0x58)
#define MYCOMP_XYZ_CSR_ARG_CHAR_ARG_REG (0x60)
/* Argument Sizes (bytes) */
#define MYCOMP_XYZ_CSR_RETURNDATA_0_SIZE (8)
#define MYCOMP_XYZ_CSR_RETURNDATA_1_SIZE (8)
#define MYCOMP_XYZ_CSR_RETURNDATA_2_SIZE (8)
#define MYCOMP_XYZ_CSR_ARG_Y_SIZE (4)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_0_SIZE (8)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_1_SIZE (8)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_2_SIZE (8)
#define MYCOMP_XYZ_CSR_ARG_MYLONG_SIZE (8)
#define MYCOMP_XYZ_CSR_ARG_CHAR_ARG_SIZE (1)
/* Argument Masks */
#define MYCOMP_XYZ_CSR_RETURNDATA_0_MASK (0xffffffffffffffffULL)
#define MYCOMP_XYZ_CSR_RETURNDATA_1_MASK (0xffffffffffffffffULL)
#define MYCOMP_XYZ_CSR_RETURNDATA_2_MASK (0xffffffffffffffffULL)
#define MYCOMP_XYZ_CSR_ARG_Y_MASK (0xffffffff)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_0_MASK (0xffffffffffffffffULL)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_1_MASK (0xffffffffffffffffULL)
#define MYCOMP_XYZ_CSR_ARG_STRUCT_ARGUMENT_2_MASK (0xffffffffffffffffULL)
#define MYCOMP_XYZ_CSR_ARG_MYLONG_MASK (0xffffffffffffffffULL)
#define MYCOMP_XYZ_CSR_ARG_CHAR_ARG_MASK (0xff)
/* Status/Control Masks */
#define MYCOMP_XYZ_CSR_BUSY_MASK (1<<0)
#define MYCOMP_XYZ_CSR_BUSY_OFFSET (0)
#define MYCOMP_XYZ_CSR_START_MASK (1<<0)
#define MYCOMP_XYZ_CSR_START_OFFSET (0)
#define MYCOMP_XYZ_CSR_INTERRUPT_ENABLE_MASK (1<<0)
#define MYCOMP_XYZ_CSR_INTERRUPT_ENABLE_OFFSET (0)
#define MYCOMP_XYZ_CSR_INTERRUPT_STATUS_MASK (1<<0)
#define MYCOMP_XYZ_CSR_INTERRUPT_STATUS_OFFSET (0)
#define MYCOMP_XYZ_CSR_DONE_MASK (1<<1)
#define MYCOMP_XYZ_CSR_DONE_OFFSET (1)
#endif /* __MYCOMP_XYZ_CSR_REGS_H__ */
Slave Memories
- The master interface has a single port. If the component has multiple load-store sites, arbitration on that port might create stallable logic.
- Depending on the system in which the component is instantiated, other masters might use the memory bus while the component is running and create undesirable stalls on the bus.
Because a slave memory is internal to the component, the HLS compiler can create a memory architecture that is optimized for the access pattern of the component such as creating banked memories or coalescing memories.
Slave memories differ from component memories because they can be accessed from an Avalon® MM Master outside of the component. Component memories are by definition restricted to the component and cannot be accessed outside the component.
You can explicitly control the structure of your slave memories by applying memory arguments to slave memory variable declarations.
Unlike component memory, you cannot explicitly configure slave memory arguments (for example, banking or coalescing). You must rely on the automatic configurations generated by the compiler. You can control the structure of your slave memories only by restructuring your load and store operations.
A component can have many slave memory interfaces. Unlike slave register arguments that are grouped together in the CSR slave interface, each slave memory has a separate interface with separate data buses. The slave memory interface data bus width is determined by the width of the slave type. If the internal accesses to the memory have been coalesced, the slave memory interface data bus width might be a multiple of the width of the slave type.
| Argument Label | Description |
|---|---|
| hls_avalon_slave_memory_argument | Implement the argument, in on-chip memory blocks, which can be read from or written to over a dedicated slave interface. |
Component Invocation Interface Arguments
| Invocation Argument | Description |
|---|---|
| hls_avalon_streaming_component |
This is the default component invocation interface. The component uses start, busy, stall, and done signals for handshaking. |
| hls_avalon_slave_component | The start, done, and returndata (if applicable) signals are registered in the component slave memory map. |
| hls_always_run_component | The start signal is tied to 1 internally in the component. There is no done signal output. |
| hls_stall_free_return | If the downstream component never stalls, the stall signal is removed by internally setting it to 0. |
Unstable and Stable Component Arguments
You can declare an interface argument to be stable with the hls_stable_argument attribute. A stable interface argument is an argument that does not change while your component executes, but the argument might change between component executions.
- Scalar (conduit) arguments
- Pointer interface arguments
The address conduit input is stable. The associated Avalon MM Master interface is not affected.
- Pass-by-reference arguments
The address conduit input is stable. The associated Avalon MM Master interface is not affected.
-
Avalon®
Memory-Mapped (MM) Master interface
arguments
The address conduit input is stable. The associated Avalon MM Master interface is not affected.
- Avalon® Memory-Mapped (MM) Slave register interface arguments
- Avalon® Memory-Mapped (MM) Slave memory interface arguments
- Avalon® Streaming interface arguments
You might save some FPGA area in your component design when you declare an interface argument as stable because there is no need to carry the data with the pipeline.
You cannot have two component invocations in flight with different stable arguments between the two component invocations.
| Argument Label | Description |
|---|---|
| hls_stable_argument | A stable argument is an argument that does not change while there is live data in the component (that is, between pipelined function invocations). |
Global Variables
Components can use and update C++ global variables. If you access a global variable in your component function, it is implemented as an Avalon® Memory-Mapped (MM) Master interfaces, like a pointer parameter.
If you access more than one global variable, each global variable uses the same Avalon® - MM Master interface, which might result in stallable arbitration. If you use pointers and non-constant global memory accesses, then the pointers and global memory accesses all share the same Avalon® - MM Master interface.
In addition to the Avalon® - MM Master interface, each global variable that the component uses has an input conduit that must be supplied with the address of the global variable in system memory. The input conduit arguments that are generated in the RTL are named @<global variable name> . Input conduits generated for pointer arguments omit the @ are named for the corresponding pointer argument.
If your global variable is declared as const, then no Avalon® - MM Master interface and no additional input conduit is generated. Therefore, global variables declared as const use significantly less FPGA area than modifiable global variable.
Structs in Component Interfaces
Review the interface_structs.sv file in your <a.prj>/components/<component_name> folder to see information about the padding and packed-ness of the implementation interfaces for the structs in your component.
The interface_structs.sv file contains the Verilog-style definitions of the structs found on your component interface.
Reset Behavior
For your HLS component, the reset assertion can be asynchronous but the reset deassertion must be synchronous.
reg [2:0] sync_resetn;
always @(posedge clock or negedge resetn) begin
if (!resetn) begin
sync_resetn <= 3'b0;
end else begin
sync_resetn <= {sync_resetn[1:0], 1'b1};
end
end
This
synchronizer code is used in the example
Intel®
Quartus® Prime project that is generated for your
components included in an i++ compile.When the reset is asserted, the component holds its busy signal high and its done signal low. After the reset is deasserted, the component holds its busy signal high until the component is ready to accept the next invocation. All component interfaces (slaves, masters, and streams) are valid only after the component busy signal is low.
Simulation Component Reset
You can check the reset behavior of your component during simulation by using the ihc_hls_sim_reset API. This API returns 1 if the reset was exercised (that is, if the reset is called during hardware simulation of the component). Otherwise, the API returns 0.
int ihc_hls_sim_reset(void);
During x86 emulation of your component, the ihc_hls_sim_reset API always returns 0. You cannot reset a component during x86 emulation.
Local Variables in Components (Memory Attributes)
The Intel® High Level Synthesis (HLS) Compiler tries to provide the maximum throughput whenever possible. In certain cases, particularly when the Intel® HLS Compiler optimizes component memory configurations for throughput, it might be beneficial to trade some throughput for a smaller area.
Apply the component memory attributes to local variables and static variables in your component to customize the on-chip memory architecture of the component memory system and lower the FPGA area utilization of your component. You cannot apply memory attributes to constants, slave memories, or struct data members.
These component memory attributes are defined in the "HLS/hls.h" header file, which you can include in your code.
| Memory Attribute | Description |
|---|---|
| hls_register | Forces
a variable or array to be carried through the pipeline in
registers. A register variable can be implemented either exclusively in flip-flops (FFs) or in a mix of FFs and RAM-based FIFOs. |
| hls_memory | Forces a variable or array to be implemented as embedded memory. |
| hls_memory_impl | Forces a variable or array to be implemented as embedded memory of a specified type. |
| hls_singlepump | Specifies that the memory implementing the local variable must be single pumped. |
| hls_doublepump | Specifies that the memory implementing the local variable must be double pumped. |
| hls_numbanks | Specifies that the memory implementing the local variable must have a defined number of memory banks. |
| hls_bankwidth | Specifies that the memory implementing the local variable must have memory banks of a defined width. |
| hls_bankbits | Forces the memory system to split into a defined number of memory banks and defines the bits used to select a memory bank. |
| hls_numports_readonly_writeonly | Specifies that the memory implementing the local variable must have a defined number of read and write ports. |
| hls_simple_dual_port_memory | Specifies a memory configuration that is equivalent to specifying the hls_singlepump and hls_numports_readonly_writeonly(1,1) component memory attributes. |
| hls_merge (depthwise) | Allows merging two or more local variables to be implemented in component memory as a single merged memory system in a depth-wise manner. |
| hls_merge (widthwise) | Allows merging two or more local variables to be implemented in component memory as a single merged memory system in a width-wise manner. |
| hls_init_on_reset | Forces the static variables inside the component to be reset when the component reset signal is asserted. |
| hls_init_on_powerup | Sets the component memory implementing the static variable to set on power-up when the FPGA is programmed. |
| hls_max_concurrency | Specifies the memory has a defined maximum number of copies to allow simultaneous iterations of a loop at any given time. |
Struct Datatypes and Memory Attributes
You can apply memory attributes to the members variables in a struct variable in the struct declaration. If you also apply memory attributes to the object instantiation of a struct variable, the attributes on the instantiation override the attributes from the declaration.
struct State {
int array[100] hls_memory;
int reg[4] hls_register;
};
component int test(..) {
struct State S1;
struct State S2 hls_memory;
// some uses
}
For this example code, the compiler splits S1 into two variables, S1.array[100] (implemented in memory) and S1.reg[4] (implemented in registers). However, the compiler ignores the attributes applied at the struct declaration for object S2 and not split it as the S2 object has the hls_memory attribute applied.
Constraints on Attributes for Memory Banks
The properties of memory banks constrain how you can divide component memory into banks with the memory bank attributes.
- The number of bytes in your array that you want to access at one time (S). If you are accessing a local variable, this value represents the size (in bytes) of the local variable..
- The number of memory banks specified by hls_numbanks attribute ().
- The width (in bytes) of the memory banks specified by hls_bankwidth attribute ().
- The number of memory bank-select bits specified by hls_bankbits attribute. That is, n+1 when you specify b 0 , b 1 , ..., b n as the bank-select bits ().
-
The number of bytes accessed concurrently (or size of a local variable) is equal to the number of memory banks it uses times the width of the memory banks.
- must be a power of 2 value.
-
bank-selection bits that are required to address number of memory banks.
Values that you specify for the hls_numbanks, hls_bankwidth, and hls_bankbits attributes must meet these constraints. For attributes that you do not specify, the Intel® HLS Compiler infers values for the attributes following these constraints.
Static Variables
The HLS compiler supports function-scope static variables with the same semantics as in C and C++.
Function-scope static variables are initialized to the specified values on reset. In addition, changes to these variables are visible across component invocations, making function-scope static variables ideal for storing state in a component.
To initialize static variables, the component requires extra logic, and the component might take some time to exit the reset state while this logic is active.
Static Variable Initialization
Unlike a typical program, you can control when the static variables in your component are initialized, if they are implemented as memories. A static variable can be initialized either when your component is powered up or when your component is reset.
Initializing a static variable when a component is powered up resembles a traditional programming model where you cannot reinitialize the static variable value after the program starts to run.
Initializing a static variable when a component is reset initializes the static variable each time each time your component receives a reset signal, including on power up. However, this type of static variable initialization requires extra logic. This extra logic can affect the start-up latency and the FPGA area needed for your component.
- hls_init_on_reset (default behavior)
- The static variable value is initialized after the
component is reset.Add this attribute to your static variable declaration as shown in the following example:
static char arr[128] hls_init_on_reset;
This is the default behavior for initializing static variables. You do not need to specify the hls_init_on_reset keyword with your static variable declaration to get this behavior.
For example, the static variable in the following example is also initialized when the component is reset:static int arr[64];
- hls_init_on_powerup
- The static variable is initialized only on power up. This initialization uses a memory initialization file (.mif) to initialize the memory, which reduces the resource utilization and start-up latency of the component.
-
Add this keyword to your static variable declaration as shown in the following example:
static char arr[128] hls_init_on_powerup;
Some static variables might not be able to take advantage of this initialization because of the complexity of the static variables (for example, an array of structs). In these cases, the compiler returns an error.
For a demonstration of initializing static variables, review the tutorial in <quartus_installdir>/hls/examples/tutorials/component_memories/static_var_init.
For information about resetting your component, see Reset Behavior.
Loops in Components
Loop Pipelining
There are some cases where pipelining is not possible at all. In other cases, a new iteration of the loop cannot start until N cycles after the previous iteration.
The number of cycles for which a loop iteration must wait before it can start is called the initiation interval (II) of the loop. This loop pipelining status is captured in the high level design report (report.html). In general, an II of 1 is desirable.
A common case where II > 1 is when a part of the loop depends in some way on the results of the previous iteration of the same loop. The circuit must wait for these loop-carried dependencies to be resolved before starting a new iteration of the loop. These loop-carried dependencies are indicated in the optimization report.
In the case of nested loops, II > 1 for an outer loop is not considered a significant performance limiter if a critical inner loop carries out the majority of the work. One common performance limiter is if the HLS compiler cannot statically compute the trip count of an inner loop (for example, a variable inner loop trip count). Without a known trip count, the compiler cannot pipeline the outer loop.
For more information about loop pipelining, see Pipeline Loops in Intel® High Level Synthesis Compiler Best Practices Guide.
Compiler Pragmas Controlling Loop Pipelining
The Intel® HLS Compiler has several pragmas that you can specify in your code to control how the compiler pipelines your loops.
| Incorrect (produces a compile-time error) | Correct |
|---|---|
#pragma ivdep
TEST_LOOP: for(int idx = 0; idx < counter; idx++) {...}
|
TEST_LOOP:
#pragma ivdep
for(int idx = 0; idx < counter; idx++) {...}
|
| Pragma | Description |
|---|---|
| disable_loop_pipelining | Prevents compiler from pipelining a loop, |
| ii | Forces a loop to have a loop initiation interval (II) of a specified value. |
| ivdep | Ignores memory dependencies between iterations of this loop. |
| loop_coalesce | Tries to fuse all loops nested within this loop into a single loop. |
| max_concurrency | Limits the number of iterations of a loop that can simultaneously execute at any time. |
| speculated_iterations | Specifies the number of clock cycles that a loop exit condition can take to compute. |
| unroll | Unrolls the loop completely or by a number of times. |
Loop Initiation Interval (ii Pragma)
- The loop is not critical to the throughput of your component.
- The running time of the loop is small compared to other loops it might contain.
You can also apply the ii pragma to force a loop to an II of 1 and accept a possible fMAX penalty.
#pragma ii <desired_initiation_interval>The <desired_initiation_interval> parameter is required and is an integer that specifies the number of clock cycles to wait between the beginning of execution of successive loop iterations.
Example
Consider a case where your component has two distinct sequential pipelineable loops: an initialization loop with a low trip count and a processing loop with a high trip count and no loop-carried memory dependencies. In this case, the compiler does not know that the initialization loop has a much smaller impact on the overall throughput of your design. If possible, the compiler attempts to pipeline both loops with an II of 1.
Because the initialization loop has a loop-carried dependence, it will have a feedback path in the generated hardware. To achieve an II with such a feedback path, some clock frequency might be sacrificed. Depending on the feedback path in the main loop, the rest of your design could have run at a higher operating frequency.
If you specify #pragma ii 2 on the initialization loop, you tell the compiler that it can be less aggressive in optimizing II for this loop. Less aggressive optimization allows the compiler to pipeline the path limiting the fmax and could allow your overall component design to achieve a higher fmax.
The initialization loop takes longer to run with its new II. However, the decrease in the running time of the long-running loop due to higher fmax compensates for the increased length in running time of the initialization loop.
Loop-Carried Dependencies (ivdep Pragma)
The ivdep pragma tells the compiler that a memory dependency between loop iterations can be ignored. Ignoring the dependency saves area and lowers the loop initiation interval (II) of the affected loop because the hardware required for avoiding data hazards is no longer required.
You can provide more information about loop dependencies by adding the safelen(N) clause to the ivdep pragma. The safelen(N) clause specifies the maximum number of consecutive loop iterations without loop-carried memory dependencies. For example, #pragma ivdep safelen(32) indicates to the compiler that there are a maximum of 32 iterations of the loop before loop-carried dependencies might be introduced. That is, while #pragma ivdep promises that there are no implicit memory dependency between any iteration of this loop, #pragma safelen(32) promises that the iteration that is 32 iterations away is the closest iteration that could be dependent on this iteration.
- a component memory array
- a pointer argument
- a pointer variable that points to a component memory
- a reference to an mm_master object
Use Case 1:
If all accesses to memory arrays inside a loop do not cause loop-carried dependencies, add #pragma ivdep before the loop.
1 // no loop-carried dependencies for A and B array accesses
2 #pragma ivdep
3 for(int i = 0; i < N; i++) {
4 A[i] = A[i + N];
5 B[i] = B[i + N];
6 }
Use Case 2:
You may specify #pragma ivdep array (array_name) on particular memory arrays instead of all array accesses. This pragma is applicable to arrays, pointers, or pointer members of structs. If the specified array is a pointer, the ivdep pragma applies to all arrays that may alias with the specified pointer.
1 // No loop-carried dependencies for A array accesses
2 // Compiler inserts hardware that reinforces dependency constraints for B
3 #pragma ivdep array(A)
4 for(int i = 0; i < N; i++) {
5 A[i] = A[i - X[i]];
6 B[i] = B[i - Y[i]];
7 }
8
9 // No loop-carried dependencies for array A inside struct
10 #pragma ivdep array(S.A)
11 for(int i = 0; i < N; i++) {
12 S.A[i] = S.A[i - X[i]];
13 }
14
15 // No loop-carried dependencies for array A inside the struct pointed by S
16 #pragma ivdep array(S->X[2][3].A)
17 for(int i = 0; i < N; i++) {
18 S->X[2][3].A[i] = S.A[i - X[i]];
19 }
20
21 // No loop-carried dependencies for A and B because ptr aliases
22 // with both arrays
23 int *ptr = select ? A : B;
24 #pragma ivdep array(ptr)
25 for(int i = 0; i < N; i++) {
26 A[i] = A[i - X[i]];
27 B[i] = B[i - Y[i]];
28 }
29
30 // No loop-carried dependencies for A because ptr only aliases with A
31 int *ptr = &A[10];
32 #pragma ivdep array(ptr)
33 for(int i = 0; i < N; i++) {
34 A[i] = A[i - X[i]];
35 B[i] = B[i - Y[i]];
36 }
Loop Coalescing (loop_coalesce Pragma)
Coalescing nested loops also reduces the latency of the component, which could further reduce your component area usage. However, in some cases, coalescing loops might lengthen the critical loop initiation interval path, so coalescing loops might not be suitable for all components.
#pragma loop_coalesce <loop_nesting_level>
The <loop_nesting_level> parameter is optional and is an integer that specifies how many nested loop levels that you want the compiler to attempt to coalesce. If you do not specify the <loop_nesting_level> parameter, the compiler attempts to coalesce all of the nested loops.
for (A)
for (B)
for (C)
for (D)
for (E)
- Loop (A) has a loop nesting level of 1.
- Loop (B) has a loop nesting level of 2.
- Loop (C) has a loop nesting level of 3.
- Loop (D) has a loop nesting level of 4.
- Loop (E) has a loop nesting level of 3.
- If you specify #pragma loop_coalesce 1 on loop (A), the compiler does not attempt to coalesce any of the nested loops.
- If you specify #pragma loop_coalesce 2 on loop (A), the compiler attempts to coalesce loops (A) and (B).
- If you specify #pragma loop_coalesce 3 on loop (A), the compiler attempts to coalesce loops (A), (B), (C), and (E).
- If you specify #pragma loop_coalesce 4 on loop (A), the compiler attempts to coalesce all of the loops [loop (A) - loop (E)].
Example
The following simple example shows how the compiler coalesces two loops into a single loop.
#pragma loop_coalesce
for (int i = 0; i < N; i++)
for (int j = 0; j < M; j++)
sum[i][j] += i+j;
int i = 0;
int j = 0;
while(i < N){
sum[i][j] += i+j;
j++;
if (j == M){
j = 0;
i++;
}
}
Loop Unrolling (unroll Pragma)
Example code:
1 #pragma unroll <N>
2 for (int i = 0; i < M; ++i) {
3 // Some useful work
4 }
In this example, N specifies the unroll factor, that is, the number of copies of the loop that the HLS compiler generates. If you do not specify an unroll factor, the HLS compiler unrolls the loop fully. You can find the unroll status of each loop in the high level design report (report.html).
Loop Concurrency (max_concurrency Pragma)
To achieve maximum concurrency in loops, sometimes private copies of component memory have to be created to break dependencies on the underlying hardware that prevent the loop from being fully pipelined.
- In the Details pane of the Loop analysis report as a message that says that the maximum number of simultaneous executions has been limited to N.
- In the Bank view of your component memory in the Function Memory Viewer, where it graphically shows the number of private copies.
#pragma max_concurrency 1
for (int i = 0; i < N; i++) {
int arr[M];
// Doing work on arr
}
You can control the number of private copies created for a component memory accessed withing a loop by using the hls_max_concurrency memory attribute. For details, see hls_max_concurrency Memory Attribute.
You can also control the concurrency of your component by using the hls_max_concurrency component attribute. For more information about the hls_max_concurrency(N) component attribute, see Concurrency Control (hls_max_concurrency Attribute).
Loop Iteration Speculation (speculated_iterations Pragma)
Typically, the exit condition for a loop iteration must be evaluated before it is known whether to start the next loop iteration or continue into the rest of the function. This requirement means that the loop initiation interval (II) cannot be lower than the number of cycles required to compute the exit condition. Speculated iterations can help lower the loop II because operations within the loop can occur in the function pipeline at the same time as the exit condition is evaluated.
For any speculated iteration, instructions with side effects outside of the loop (like writing to memory or a stream) are not completed until the loop exit condition for the iteration has been evaluated. For loop iterations that are in flight but incomplete when the loop exit condition is met, side effect data is discarded.
The Intel® HLS Compiler determines the number of speculated iterations on a per-loop basis. You can see the number of speculated iterations for a loop in the Loop Analysis Report in the High Level Design Report (report.html).
While speculated iterations can improve loop II, they occupy the pipeline until they are completed. A new loop invocation cannot start until all of the speculated iterations have completed. For example, the next iteration of an outer loop cannot start until all the speculated iterations of an inner loop have completed.
For loops where the exit condition calculation is a bottleneck (as shown in the Loop Analysis Report), consider increasing the number of speculated iterations with the speculated_iterations pragma. Increasing the number of speculated iterations might not improve the loop II if other bottlenecks in the loop are found.
For frequently invoked loops with a low latency loop body (for example, an inner loop with a short trip count), you might want to use the speculated_iterations pragma to reduce the number of speculated iterations to reduce the overhead of your design. However, setting the number of speculated iterations too low might increase the loop II because there is not enough time to evaluate the exit condition.
The following example shows how you can change the characteristics of a pipelined loop with the speculated_iterations pragma.
include <HLS/hls.h>
component void unopt_int_cube_root (int *dst, int N) {
int m = 0;
// The exit condition which has 2 multiplies and a compare is most critical
// in loop feedback path. The compiler choice of 4 speculated iterations
// results in II=2 because the exit condition takes 7 cycles: each
// multiplication takes 3 cycles and the comparison takes 1 cycle. Four
// speculated iterations times two-cycle II gives 8 cycles to cover this
// evaluation.
while (m*m*m < N) {
m += 1;
}
dst[0] = m;
}
component void opt_int_cube_root (int *dst, int N) {
int m = 0;
// Increasing to 7 speculated iterations to cover the 7 cycle exit condition
// calculation allows us to achieve II=1
#pragma speculated_iterations 7
while (m*m*m < N) {
m += 1;
}
dst[0] = m;
}
component void unopt2_int_cube_root (int *dst, int N) {
int m = 0;
// by setting to pragma to 0, user can verify that the II has increased to 7
// which matches the exit condition bottleneck
#pragma speculated_iterations 0
while (m*m*m < N) {
m += 1;
}
dst[0] = m;
}
The Loop Analysis Report for these components looks like the following example:
When you click the line with unopt2_int_cube_root.B2 (spec.cpp:31) in the Loop Analysis Report, the Details
pane shows the following information:
Loop Pipelining Control (disable_loop_pipelining Pragma)
When the loop iterations effectively execute sequentially due to loop-carried dependencies, use the disable_loop_pipelining pragma to generate a simple sequential datapath and avoid loop resource hardware duplication. The simpler datapath and lack of resource duplication in hardware reduces the FPGA area utilization of your component.
Use the Loop Analysis section of the high-level design reports (report.html) to help determine if you should apply this pragma to your loops.
#pragma disable_loop_pipelining
for (int i = 1; i < N; i++) {
int j = a[i-1];
// Memory dependency induces a high-latency loop feedback path
a[i] = foo(j)
}
You can also disable pipelining the datapath of your entire component with the hls_disable_component_pipelining component attribute. For more information about this attribute, see Component Pipelining Control (hls_disable_component_pipelining Attribute).
Component Concurrency
The Intel® HLS Compiler provides you with the hls_max_concurrency component attribute to help you control the maximum concurrency of your component.
Serial Equivalence within a Memory Space or I/O
When visualizing a single shared memory space, think of multiple function calls as executing sequentially, one after another. This way, when the component asserts the done signal, the results of a component invocation in hardware are guaranteed to be visible to both the next component invocation and the external system.
The HLS compiler leverages pipeline parallelism to execute component invocations and loop iterations in parallel if the associated dependencies allow for parallel execution. Because the HLS compiler generates hardware that keeps track of dependencies across component invocations, it can support pipeline parallelism while guaranteeing serial equivalence across memory spaces. Ordering between independent I/O instructions is not guaranteed.
Concurrency Control (hls_max_concurrency Attribute)
You can use the hls_max_concurrency component attribute to increase or limit the maximum concurrency of your component. The concurrency of a component is the number of invocations of the component that can be in progress at one time. By default, the Intel® HLS Compiler tries to maximize concurrency so that the component runs at peak throughput.
#include "HLS/hls.h"
hls_max_concurrency(3)
component void foo ( /* arguments */ ){
// Component code
}
- At the component level, the Intel HLS compiler does not automatically
create private copies of component memory to increase the throughput. If your component
invocation uses a (non-static) component memory system, the next invocation cannot start
until the previous invocation has finished all of its accesses to and from that component
memory. This limitation is shown in the Loop analysis report as load-store dependencies on
the component memory. Adding the hls_max_concurrency(N) attribute to the component creates private
copies of the component memory so that you can have multiple invocations of your component
in progress at the same time.
For finer-grained control of which component memories to create local copies of, use the hls_max_concurrency memory attribute. For details, see hls_max_concurrency Memory Attribute.
- In some cases, the compiler reduces concurrency to save a great deal of area. In these cases, the hls_max_concurrency(N) attribute can increase the concurrency from 1.
- This attribute can also accept a value of 0. When this attribute is set to 0, the component should be able to accept new invocations as soon as the downstream datapath frees up. Only use this value when you see loop initiation interval (II) issues (such as extra bubbles) in your component, because using this attribute can increase the component area.
You can also control the concurrency of loops in components with the max_concurrency(N) pragma. For more information about the max_concurrency(N) pragma, see Loop Concurrency (max_concurrency Pragma).
Component Pipelining Control (hls_disable_component_pipelining Attribute)
If running simultaneous invocations of your component does not improve throughput, or if you do not intend to invoke your component repeatedly, avoid extra FPGA area utilization by using the hls_disable_component_pipelining component attribute.
When you specify the hls_disable_component_pipelining, the Intel® HLS Compiler generates a simpler, sequential datapath for your component.
#include "HLS/hls.h"
hls_disable_component_pipelining
component void baz ( /* arguments */ ){
// component code
}
You can also disable pipelining the datapath of a only a loop in your component with the disable_loop_pipelining pragma. For more information about this pragma see Loop Pipelining Control (disable_loop_pipelining Pragma).
Component Target Frequency
For details about the --clock option, see Command Options Affecting Linking.
For details about the hls_scheduler_target_fmax_mhz component attribute, see hls_scheduler_target_fmax_mhz Component Attribute.
- The --clock option applies to all components compiled with the invocation of the i++ command that contains the --clock option.
- The hls_scheduler_target_fmax_mhz component attribute applies only to the component that has the attribute.
<quartus_installdir>/hls/examples/tutorials/best_practices/set_component_target_fmax
component int test1(){
…
}
hls_scheduler_target_fmax_mhz(200)
component int test2(){
…
}
The compiler schedules component test1 at 300 MHz (from the command option) and component test2 at 200 MHz (from the component attribute).
Systems of Tasks
The component keyword marks a single function and its subfunctions as a component. Within this component function, directly-called functions are in-lined while functions that use the systems of tasks API calls (ihc::launch and ihc::collect) generate hardware outside the component datapath and behave like an asynchronous call.
The function tagged with the component keyword marks the boundary of a system of tasks. Your external system can interact with all the interfaces that the component exposes.
- Improving the performance of operations like executing loops in parallel
- Reducing FPGA area utilization by sharing an expensive compute block with different parts of your component
| Template Object or Argument | Description |
|---|---|
| ihc::launch | Marks a function as an Intel® HLS Compiler task for hardware generation, and launches the task function asynchronously. |
| ihc::collect | Synchronizes the completion of the specified task function in the component. |
| ihc::stream | Allows streaming communication between different task functions. |
Task Functions
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.
Pointer or Reference Arguments
Task functions cannot have pointer or reference arguments. Therefore, the only ways to pass data into a task function are through scalar arguments (as described above), or use a global-scope streams (as described in Interaction with External Systems).
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 an array.
Communication Between HLS Task Functions
For multiple task functions to communicate with each other, use 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
HLS Task Function 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).
- 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.
Task Attributes
- hls_max_concurrency
- hls_component_ii
- hls_scheduler_target_fmax_mhz
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 arguments when you define HLS task functions. For example, you cannot use hls_avalon_slave_register_argument, hls_conduit_argument, hls_stall_free_return, or hls_avalon_streaming_component
Internal Streams
For an example of using the HLS tasks ihc::stream object as a FIFO, review the tutorial in <quartus_installdir>/hls/examples/tutorials/system_of_tasks/internal_stream.
This diagram is simplified from the tutorial. It shows 10 iterations, while the tutorial goes through 32 iterations.
In the diagram, i is the index of the outer loop and j is the index of the inner loop.
Each iteration of the outer loop reads all the values written by the previous loop iteration and writes one less value to the buffer. The internal stream outperforms the array in this design because array must allocate enough space to store written values before the values are read, but an internal stream does not need to allocate this space.
In addition, the trip count of the inner loop decreases by one in each outer loop, so the space claimed by array is never filled after the first iteration, which wastes area.
System of Tasks Simulation
When you simulate a system of tasks design where the completion of a task function is not synchronized with an ihc::collect call, use the ihc_hls_set_component_wait_cycle testbench API function to allow output from that task function to be returned after the component function finishes running.
If you do not use this function in your testbench, the latency of some task functions might make your simulation output inaccurate.
For an example of a valid systems of task design where the completion of a task function is not synchronized with an ihc::collect call, see Example 3 of a Valid ihc::launch/ihc::collect Sequence.
| Function | Description |
|---|---|
| ihc_hls_set_component_wait_cycle | This function tells the simulation process to continue running for a specified number of cycles after the done signal for the specified component is observed. |
HLS Libraries
An HLS library is a single platform-specific archive file that contains multiple object files, each of which contains implementations of one or more functions. The object and library files use the same formats as the operating system that you compile your Intel® HLS Compiler code on, with additional sections that carry HLS-specific information.
On Linux platforms, an HLS library is a .a archive file that contains .o object files. On Windows platforms, an HLS library is a .lib archive file that contains .obj object files.
You can include an HLS library in your Intel® HLS Compiler component and call the functions in the HLS library from your component without needing to know the hardware design or the implementation details underlying the functions in the library.
You can create an HLS library from object files that package register transfer level (RTL) language source files. An RTL-based object file also contains an object manifest file (in XML format) that identifies the functions that are callable in the object file. An HLS library can contain multiple objects. You can then use the HLS library in your component and call the functions in the HLS library from your component.
Creating an HLS library is a two-step process. First, each object file is created from the RTL source and other required files with the fpga_crossgen command. Then, one or more object files are collected into an HLS library file with the fpga_libtool command.
To create an HLS library, you need to create the following files and components:
| File or Component | Description |
|---|---|
| RTL-based Functions | |
| RTL module source files |
Verilog (.v), System Verilog (.sv), or VHDL (.vhd) files and accompanying memory initialization files (.mif or .hex) that define the RTL modules in the library. You cannot use additional files such as Intel® Quartus® Prime IP File (.qip), Synopsys Design Constraints File (.sdc), and Tcl Script File (.tcl). |
| Object manifest file | An XML (.xml) file that describes the
properties of the callable functions available in the RTL module. The Intel® HLS Compiler uses these properties to integrate the RTL module in an HLS library into the component pipeline. |
| RTL module function signature file | A C-style header file (.h)
that declares the signatures of the functions that are implemented by the RTL module
and described in the RTL module properties file. Use this header file in your HLS component source code so that your component can call the functions provided in the HLS library. |
| HLS emulation model files | C++ files (.cpp and .h) that contain code that is functionally equivalent to the RTL component. The emulation model is used only for component emulation. Co-simulations use the RTL provided in the library. |
RTL Modules and the HLS Pipeline
HLS libraries allows you to use RTL modules that are written in Verilog, SystemVerilog, or VHDL inside HLS components. The Intel® HLS Compiler integrates the RTL modules into the HLS pipeline architecture.
Consider using HLS libraries in the following situations:
- You want to use optimized and verified RTL modules in HLS components without rewriting the modules as C++ functions.
- You want to implement HLS component functionality that you cannot express effectively in C++.
Integration of an RTL Module into the HLS Pipeline
The depicted RTL module has a latency of 3 cycles. Since the multiply and add operations have a latency of just one cycle, the compiler inserts buffering to balance the latency of the parallel data paths in the pipeline. A balanced latency allows the invocations of the HLS component to execute without stalling the pipeline.
Specifying the latency of the RTL module in the HLS library object manifest file allows the HLS compiler to balance the pipeline latencies in the HLS component. The pipeline integration protocol uses ready/valid handshaking, so the latency of the RTL module can be variable. However, the variability in the latency should be small to maximize performance. In addition, specify the latency in the HLS library object manifest file for the object in the HLS library so that the RTL module experiences a good approximation of the actual latency in steady state.
RTL Module Interfaces
For an RTL module to properly interact with other compiler-generated operations, you must support a simple ready/valid handshaking protocol at both the input and the output of an RTL module.
An RTL module must use a single streaming interface. That is, a single pair of ready and valid logic must control all the inputs.
You have the option to provide the necessary streaming ports but declare the RTL module as stall-free. In this case, you do not have to implement proper stall behavior because the Intel® HLS Compiler creates a wrapper for your module.
You must handle ivalid signals properly if your RTL module has an internal state. For more information, see Stall-Free RTL.
Consider the following interfaces for the RTL module myMod:
In this diagram, myMod interacts with the upstream module through data signals, arg1 and arg2, and control signals, ivalid (input) and oready (output). The ivalid control signal equals 1 (ivalid = 1) if and only if data signal arg1 and data signal arg2 contain valid data. When the control signal oready equals 1 (oready = 1), it indicates that the myMod RTL module can process the data signals arg1 and arg2 if they are valid (that is, ivalid = 1). When ivalid = 1 and oready = 0, the upstream module holds the values of ivalid, arg1, and arg2 in the next clock cycle.
The myMod module interacts with the downstream pipeline logic through the data signal result and the control signals, ovalid (output) and iready (input). The ovalid control signal equals 1 (ovalid = 1) if and only if the data signal result contains valid data. When the iready control signal equals 1 (ivalid = 1), the downstream module can process the data signal result if it is valid. When ovalid = 1 and iready = 0, the myMod RTL module must hold the valid of the ovalid and result signals in the next clock cycle.
RTL Reset and Clock Signals
Because of the common clock and reset drivers, an RTL module runs in the same clock domain as the HLS component that is integrating the RTL module. The module reset input is asserted whenever the HLS component is reset.
Object Manifest File Syntax
The HLS library object manifest file is an XML file that maps the RTL modules in a library object to functions that can be called by your HLS code. The Intel® HLS Compiler uses the properties defined in the manifest file to integrate an RTL module into the component pipeline.
The following example show a simple object manifest file for an RTL module that implements a double-precision square root function. The RTL module is implemented in VHDL with a Verilog wrapper.
The following object manifest file is for an RTL module named my_fp_sqrt_double (line 2) that implements a callable function with a C interface named my_sqrtfd (line 2).
1: <RTL_SPEC> 2: <FUNCTION name="my_sqrtfd" module="my_fp_sqrt_double"> 3: <ATTRIBUTES> 4: <IS_STALL_FREE value="yes"/> 5: <IS_FIXED_LATENCY value="yes"/> 6: <EXPECTED_LATENCY value="31"/> 7: <CAPACITY value="31"/> 8: <HAS_SIDE_EFFECTS value="no"/> 9: <ALLOW_MERGING value="no"/> 10: <PARAMETER name="WIDTH" value="64"/> 11: </ATTRIBUTES> 12: <INTERFACE> 13: <AVALON port="clock" type="clock"/> 14: <AVALON port="resetn" type="resetn"/> 15: <AVALON port="ivalid" type="ivalid"/> 16: <AVALON port="iready" type="iready"/> 17: <AVALON port="ovalid" type="ovalid"/> 18: <AVALON port="oready" type="oready"/> 19: <INPUT port="datain" width="64"/> 20: <OUTPUT port="dataout" width="64"/> 21: </INTERFACE> 22: <REQUIREMENTS> 23: <FILE name="my_fp_sqrt_double_s5.v" /> 24: <FILE name="fp_sqrt_double_s5.vhd" /> 25: </REQUIREMENTS> 26: <RESOURCES> 27: <ALUTS value="2057"/> 28: <FFS value="3098"/> 29: <RAMS value="15"/> 30: <MLABS value="43"/> 31: <DSPS value="1.5"/> 32: </RESOURCES> 33: </FUNCTION> 34: </RTL_SPEC>
| XML Element | Description |
|---|---|
| RTL_SPEC | Top-level element in the object manifest file. There can only be one such top-level element in the file. |
| FUNCTION |
Element that defines the HLS function that the RTL module implements. The name attribute within the FUNCTION element specifies the function name. You might have multiple FUNCTION elements, each declaring a different function that you can call from the HLS component. The same RTL module can implement multiple functions by specifying different parameters. To use the same module with different parameter combinations, create a separate FUNCTION tag for each parameter combination. |
| ATTRIBUTES | Element that contains other XML elements that describe various
characteristics (for example, latency) of the RTL module. The example RTL module takes one PARAMETER setting named WIDTH, which has a value of 64. See Table 21 for more details other ATTRIBUTES-specific elements. If you create multiple RTL-based functions using different modules or use the same RTL module with different PARAMETER settings, you must create a separate FUNCTION element for each function. |
| INTERFACE | Element that contains other XML elements that describe the RTL module
interface. The example object manifest file shows the streaming interface signals that every RTL module must provide (that is, clock, resetn, ivalid, iready, ovalid, and oready). The signal names must match the ones specified in the RTL module properties file. An error occurs during library creation if a signal name is different in the RTL code and the RTL module properties file. |
| REQUIREMENTS | Element that specifies one or more RTL resource files (that is,
.v, .sv, .vhd, .hex, and
.mif). The specified paths
to these files are relative to the location of the object manifest
file. Each RTL resource file becomes part of the associated Platform Designer component that corresponds
to the entire HLS component. HLS libraries do not support .qip files. |
| RESOURCES | Optional element that specifies an estimate of the FPGA resources that the RTL module uses. If you do not specify this element, the estimated FPGA resources that the RTL module uses defaults to zero in the HLS resource estimation report. |
XML Elements for ATTRIBUTES
| XML Element | Description |
|---|---|
| IS_STALL_FREE |
Instructs the Intel® HLS Compiler to remove all stall logic around the RTL module. Set IS_STALL_FREE to "yes" to indicate that the module does not generate stalls internally and it cannot properly handle incoming stalls. The module ignores the stall input. If you set IS_STALL_FREE to "no", the module must properly handle all stall and valid signals. If you set IS_STALL_FREE to "yes", you must also set IS_FIXED_LATENCY to "yes". Also, if the RTL module has an internal state, it must properly handle ivalid=0 inputs. |
| IS_FIXED_LATENCY |
Indicates whether the RTL module has a fixed latency. Set IS_FIXED_LATENCY to "yes" if the RTL module always takes a known number of clock cycles to compute its output. The value you assign to the EXPECTED_LATENCY element specifies the number of clock cycles. The safe value for IS_FIXED_LATENCY is "no". When you set IS_FIXED_LATENCY="no", the EXPECTED_LATENCY value must be at least 1. For a given RTL module, you may set IS_FIXED_LATENCY to "yes" and IS_STALL_FREE to "no". Such a module produces its output in a fixed number of clock cycles and handles stall signals properly. |
| EXPECTED_LATENCY |
Specifies the expected latency of the RTL module. If you set IS_FIXED_LATENCY to "yes", set the EXPECTED_LATENCY value to be the exact latency of the module. Otherwise, the Intel® HLS Compiler generates incorrect hardware. For a module with variable latency, the Intel® HLS Compiler balances the pipeline around this module to the EXPECTED_LATENCY value that you specify. For modules that can stall and require use of signals such as iready, the EXPECTED_LATENCY value must be set to at least 1. The specified value and the actual latency might differ for a module with variable latency, which might affect the number of stalls inside the pipeline. However, the resulting hardware is functionally correct. |
| CAPACITY |
Specifies the number of multiple inputs that this module can process simultaneously. You must specify a value for CAPACITY if you also set IS_STALL_FREE="no" and IS_FIXED_LATENCY="no". Otherwise, you do not need to specify a value for CAPACITY. If CAPACITY is strictly less than EXPECTED_LATENCY, the Intel® HLS Compiler automatically inserts capacity-balancing FIFO buffers after this module when necessary. A conservative but safe value for CAPACITY is 1. |
| HAS_SIDE_EFFECTS | Indicates whether the RTL module has side effects. Modules that have
internal states or communicate with external memories are examples
of modules with side effects. Set HAS_SIDE_EFFECTS to "yes" to indicate that the module has side effects. Specifying HAS_SIDE_EFFECTS to "yes" ensures that optimization efforts do not remove calls to modules with side effects. Stall-free modules with side effects (that is, IS_STALL_FREE="yes" and HAS_SIDE_EFFECTS="yes") must properly handle ivalid=0 input cases because the module might receive invalid data occasionally. A conservative but safe value for HAS_SIDE_EFFECTS is "yes". |
| ALLOW_MERGING | This attribute is reserved for future use. To prevent unexpected behavior, always set this attribute as <ALLOW_MERGING value="no"/>. |
| PARAMETER |
Specifies the value of an RTL module parameter. PARAMETER attributes:
The value for an RTL module parameter can be specified using either a value or a type attribute. |
XML Elements for INTERFACE
In the RTL module properties file of the RTL module within an HLS library, there are XML elements under INTERFACE that define aspects of the RTL module interface.
The RTL module cannot access the memories of the HLS component.
| XML Element | Description |
|---|---|
| INPUT |
Specifies the input parameter of the RTL module that receives the value of a call argument with the RTL-based function is called. INPUT attributes:
All call arguments must be passed by value. You cannot use reference, pointer, and array type arguments. |
| OUTPUT |
Specifies the output parameter of the RTL module that represents the return value of functions based on this module. OUTPUT attributes:
The return value cannot be a pointer. |
XML Elements for RESOURCES
| XML Element | Description |
|---|---|
| ALUTS | Specifies the number of combinational adaptive look-up tables (ALUTs) that the module uses. |
| FFS | Specifies the number of dedicated logic registers that the module uses. |
| RAMS | Specifies the number of block RAMs that the module uses. |
| DSPS | Specifies the number of digital signal processing (DSP) blocks that the module uses. |
| MLABS | Specifies the number of memory logic arrays (MLABs) that the module uses. This value is equal to the number of adaptive logic modules (ALMs) that is used for memory divided by 10 because each MLAB consumes 10 ALMs. |
Mapping HLS Datatypes to RTL Signals
All supported composite datatypes are represented by wide input or output signals. Typically, the components of a composite datatype are presented with the first-declared value or value of lowest index in the low-order bits of the signal.
Arrays
In C++, arrays are passed as a pointer to the memory in which the array is stored.
The Intel® HLS Compiler does not support pointer parameters for RTL modules. However, C++ allows you to pass a struct by value, so you can declare a struct datatype that has an array as one of its members and declare your function to accept an argument of this struct-type by value.
Structs
-
Unpacked Structs
When your struct declaration is not packed, the layout of the input signal corresponding to the struct datatype is determined by C language-specific padding rules that cause the Intel® HLS Compiler to insert padding bytes before struct members that require a specific alignment.
You should use packed structs as arguments to your RTL modules unless there is a specific reason to conform to a particular padded struct layout.
-
Packed Structs
If the struct type is declared as packed, member values start on an 8-bit boundary.
The Intel® HLS Compiler does not insert padding bytes to align struct members on platform-defined boundaries. The second-declared member always starts in the next highest byte after high-order byte of the first-declared struct member.
-
System Verilog Structs
If you are developing an RTL module in System Verilog, you can declare a System Verilog struct type that corresponds to the C++ struct type that is mapped to the input signal of your RTL module.
The declaration order of the struct members is reversed in the System Verilog declaration because it specifies how the member signals should be concatenated to produce the composite signal. In a System Verilog concatenation expression, the bits are specified from high to low. That is, the last byte of the C++ struct type must be listed first in the System Verilog signal concatenation.
You can compile your emulation models as HLS components to obtain an interface_structs.v file that contains declarations of the System Verilog struct types corresponding to the struct-type arguments of those functions. For details, see the following tutorial:
<quartus_installdir>/hls/examples/tutorials/libraries/rtl_struct_mapping
-
Pointers in Structs
You cannot use struct types that have reference or pointer members as arguments to or return values from RTL-based functions.
HLS Emulation Models for RTL-Based Functions
For an RTL-based function, write C++ code that serves as an emulation model for that function. When your RTL-based function has an emulation model, HLS components that use that RTL-based function can be compiled and run in emulation mode to help you debug your component more quickly than co-simulating your component.
The emulation model is not used when you co-simulate your component; co-simulations use RTL extracted from the library.
If your emulation model function uses static variables to hold internal state, the emulation is equivalent to the RTL functionality only if the function is called from only one place in the HLS component.
This emulation is limited because all calls to the function share the same state variables. This differs from state in RTL. The RTL module is instantiated once for each location in the HLS component where the function is called, and these instances do no share state.
Stall-Free RTL
If you have an RTL module with a fixed latency that you want integrated into your component pipeline without surrounding stall logic, ensure that you set attributes in the object manifest file (.xml) as follows:
- Specify a value for the EXPECTED_LATENCY
attribute (under the FUNCTION element) so that the latency
equals the number of pipeline stages in the module. Important: An inaccurate EXPECTED_LATENCY value causes the RTL module to be out of sync with the rest of the pipeline, and can lead to functionally incorrect results.
- Set the IS_STALL_FREE attribute under the
FUNCTION element to "yes".
This setting instructs the Intel® HLS Compiler to avoid placing stall logic around the RTL module. This setting also tells the compiler that the RTL module produces a result after the number cycles specified in the EXPECTED_LATENCY attribute after accepting input values. The stall free logic produces a result every cycle but the result is delayed by the number cycles specified in the EXPECTED_LATENCY attribute.
For RTL modules with a fixed latency, the output signals ( ovalid and oready) can have constant high values, and the input ready signal ( iready) can be ignored.
A stall-free RTL module might receive an invalid input signal (ivalid is low). In this case, the module must produce invalid data on the output EXPECTED_LATENCY cycles after the cycle in which the input was invalid. For a stall-free RTL module without an internal state, you might find it convenient to propagate the invalid input through the module. If the module has an internal state, that state should not be affect by data inputs that are not accompanied by ivalid = 1.
RTL Module Restrictions and Limitations for HLS Libraries
RTL Module Restrictions
When you create an RTL module, ensure that it operates within the following restrictions:
- The RTL module must work correctly at any clock frequency that passes timing analysis.
- Data input and output sizes must match the sizes of the arguments and
return value declared in the RTL module function signature (.h) file. The input and output sizes must always be the size of a C++
standard type: char, short, int,
long, float, or double.
For example, if you work with 24-bit values inside an RTL module, declare inputs to be 32 bits and declare the function signature to accept the uint data type. In the RTL module, accept the 32-bit input but discard the top 8 bits.
- RTL modules cannot connect to external I/O signals. All input and output signals must come from the HLS component that uses the library.
- An RTL module must have a clock port, a resetn port, and handshaking ports to support the data input and output interfaces. The handshake signal must be named ivalid, ovalid, iready, and oready.
- Every function call that corresponds to an RTL module instantiation is completely independent of other instantiations. No hardware is shared.
- An RTL module must receive all its inputs at the same time. A single ivalid input signifies that all inputs contain valid data.
RTL-Based Object Limitations
Using RTL modules in HLS libraries has the following limitations:
- You can only set RTL module parameters in the object manifest file
(.xml) file.
To use the same module with multiple parameter combinations, create a separate FUNCTION tag for each parameter combination.
- Pass data inputs to the RTL module only by value through the HLS
component code.
You cannot pass streams, pointers, or references as input to an RTL module.
For streaming data, extract data from the stream first in your component and then pass the extracted scalar data to the RTL module in the HLS library.
Passing data inputs to an RTL module as pointers or references causes a fatal error in the Intel® HLS Compiler.
- Names of RTL module source files cannot conflict with the names of
objects in other libraries or in file names of
Intel® HLS Compiler IP.
When you create a library, choose RTL module names that are unlike to conflict with other libraries or compiler IP. For example, prefix the name of your RTL modules with the name of your library.
If there is a naming conflict, the Intel® Quartus® Prime compilation of the HLS component might fail or result in a functionally-incorrect FPGA image.
- Names of the RTL module and its signals cannot conflict with reserved names defined by any of the supported RTL languages: Verilog, System Verilog, and VHDL.
- The Intel® HLS Compiler does not support .qip files. You must manually parse nested .qip files to create a flat list of RTL files.
Creating an Object File from an RTL Module
Before an RTL module can be included in an HLS library, create a platform-specific object (.o files on Linux, .obj files on Windows) from the RTL module. Use the fpga_crossgen command to create the object.
- RTL module source files
These files are the the Verilog (.v), System Verilog (.sv), or VHDL (.vhdl) files and the accompanying memory initialization files (.mif or .hex) that define the RTL modules.
- RTL object manifest file
This XML file describes the callable interfaces of your RTL modules. Review Object Manifest File Syntax for details about what to include in this XML file.
- HLS emulation model file
These C++ files (.cpp and .h) provide an emulation model for the RTL module that allows you to emulate your component when it includes an HLS library that contains this RTL module. Full hardware compilations use the RTL source files.
- RTL module function signature file
This C-style header file (.h) declares the signatures of the functions that are implemented by the RTL module and described in the object manifest file. Include this file in you HLS component code for the component to call the functions provided by the RTL modules packaged in the object.
fpga_crossgen <object_manifest_file_location> --target hls --emulation_model <emulation_model> [-o <object_file_name>]
Where <RTL_module_properties_file_location> is the path to the RTL module properties (.xml) file. This path can be a full or relative path.
If you do not specify an object file name with the -o option, the object file name defaults to be the same name as the object manifest file name.
The output of the command is a platform-specific object file ( (.o on Linux, .obj on Windows). The platform of the object file is determine by the platform where you run the fpga_crossgen command. When you run the command on Linux, you get a .o object file. When you run the command on Windows, you get a .obj object file.
Packaging Object Files into an HLS Library
Collect object files in an HLS library file so that an HLS component can incorporate the library and call the functions that are contained in the objects in the library. Package object files into an HLS library with the fpga_libtool command.
fpga_libtool --create library_name[.a|.obj] object_file_1 [object_file_2 ... object_file_n] --target hls
Where library_name is the name of the HLS library file. Specify the file extension according to the platform supported by the objects in the library: .a for Linux-platform objects and .lib for Windows-platform objects.
You can specify one or more object files to include in the HLS library.
fpga_libtool --create libdemo.a prim1.o prim2.o prim3.o --target hls
Using HLS Libraries in Your Component
Use HLS libraries to reuse functions created by you or others without needing to know the function implementation details. To use the functions in an HLS library, you must have the HLS library file and the corresponding C-header files available.
To include an HLS library in your component:
HLS Source Code Libraries
| Library | Description | Header file |
|---|---|---|
| Random number generator | Generate random integers or floating point numbers that follow a uniform distribution, or random floating point numbers that follow a Gaussian distribution | HLS/rand_lib.h |
| Matrix multiplication | Multiply two 2-D matrices. | HLS/matrix_mult.h |
Random Number Generator Library
The Random Number Generator Library and Cryptography
The use of these pseudo-random number generator (PRNG) algorithms are not recommended for cryptographic purposes. The PRNGs included in this library are not cryptographically-secure pseudo-random number generators (CSPRNGs) and should not be used for cryptography. CSPRNG algorithms are designed so that no polynomial-time algorithm (PTA) can compute or predict the next bit in the pseudo-random sequence, nor is there a PTA that can predict past values of the CSPRNG; these algorithms do not achieve this purpose. Additionally, these algorithms have not been reviewed nor are they recommended for use as a PRNG component of a CSPRNG, even if the input values are from a non-deterministic entropy source with an appropriate entropy extractor.
| Value distribution | Value type | Value range | Generation method |
|---|---|---|---|
| Uniform | Integer | [-2³¹, 2³¹-1] | Tausworthe Generator |
| Floating point | [0, 1) (non-inclusive) | Tausworthe Generator | |
| Gaussian | Floating point | [0, 1) | Central limit theorem (CLT) (Default) |
| Box-Muller |
Header File
#include "HLS/rand_lib.h"
The header file is self-documented. You can review the header file to learn how to use the random number generator library in your component.
Random Number Object Declarations
- Uniform distribution integer random
number
static RNG_Uniform<int> <object_name>(<seed_value>)
- Uniform distribution floating point random
number
static RNG_Uniform<float> <object_name>(<seed_value>)
- Gaussian distribution floating point random number (CLT
method)
static RNG_Gaussian<float> <object_name>(<seed_value>)
orstatic RNG_Gaussian<float, ihc::GAUSSIAN_CLT> <object_name>(<seed_value>)
- Gaussian distribution floating point random number (Box-Muller
method)
static RNG_Gaussian<float, ihc::GAUSSIAN_BOX_MULLER> <object_name>(<seed_value>)
Matrix Multiplication Library
When you use the matrix multiplication library, you can affect the number of DSP blocks and RAM blocks by controlling the dot product vector size and the number of matrix elements read at one time. Increasing the dot product vector size can achieve better latency, but at the cost of using more DSP blocks and other FPGA resources.
Header File
#include "HLS/matrix_mult.h"
The header file is self-documented. You can review the header file to learn how to use the matrix multiplication library in your component.
Template Arguments
- T
- The data type of the matrix elements (For example, int, float, long, double).
- t_rowsA
- The number of rows in matrix A.
- t_colsA
- The number of columns in matrix A. This value also the number of rows in matrix B.
- t_colsB
- The number of columns in matrix B.
- DOT_VEC_SIZE
- The number of DSP blocks to use in a single computation. This value
must be a factor of t_colsA.
You can achieve better component latency by increasing this value. However, you use more FPGA area to achieve this. Keeping this value low lowers your FPGA resource usage, but increases the latency.
- BLOCK_SIZE
- The number of elements to read at one time from matrix A. The default value of BLOCK_SIZE is the value of DOT_VEC_SIZE. You can reduce this number if the bandwidth needed by matrix A is lower than the value of DOT_VEC_SIZE, but it must remain a factor of DOT_VEC_SIZE.
- RUNNING_SUM_MULT_L
- This parameter can be adjusted to try and improve the fMAX of a component that uses this library. Review the header file for a detailed description of this argument and its effects.
Document Revision History of the Intel HLS Compiler Reference Manual
| Document Version | Intel® Quartus® Prime Version | Changes |
|---|---|---|
| 2019.07.01 | 19.2 |
|
| 2019.06.04 | 19.1 |
|
| 2019.05.03 | 19.1 |
|
| 2019.04.01 | 19.1 |
|
| 2019.01.03 | 18.1.1 |
|
| 2018.12.24 | 18.1.1 |
|
| 2018.12.24 | 18.1 |
|
| 2018.09.24 | 18.1 |
|
| 2018.07.08 | 18.0 |
|
| 2018.05.07 | 18.0 |
|
| 2017.12.22 | 17.1.1 |
|
| 2017.11.06 | 17.1 |
|
| 2017.06.23 | — |
|
| 2017.06.09 | — |
|
| 2017.02.03 | — |
|
| 2016.11.30 | — |
|
| 2016.09.12 | — | Initial release. |
Intel High Level Synthesis Compiler Quick Reference
Intel HLS Compiler 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
synthesize 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 compiler to synthesize. |
|
| -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® 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. |
| --promote-integers | Use extra FPGA resources to mimic g++ integer
promotion. In Pro Edition, the compiler always promotes integers for standard types. Use the ac_int datatypes if you want smaller (or larger) datatypes. To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/integer_promotion |
|
| --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. | |
| --simulator simulator_name | modelsim | Specifies the simulator you are using to
perform verification. This command option
can take the following values for <simulator_name>:
If you do not specify this option, --simulator modelsim is assumed. |
Command Options Affecting Linking
| Option | Default Value | Description |
|---|---|---|
| --clock clock target | 240 MHz | Optimize the RTL for the specified clock
frequency or period. For example:
i++ -march="Arria 10" test.cpp --clock 100MHz i++ -march="Arria 10" test.cpp --clock 10ns |
| --fp-relaxed | Relax the order of floating point arithmetic
operations. To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_ops |
|
| --fpc | Remove intermediate rounding and conversion
when possible. To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_ops |
|
| -ghdl | Enable full debug visibility and logging of all HDL signals in simulation. | |
| -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) Search 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. |
Intel HLS Compiler Header Files
Coding your component to be compiled by the Intel® HLS Compiler requires you to include the hls.h header file. Other header files provided with the Intel® HLS Compiler provide FPGA-optimized implementations of certain C and C++ functions.
| HLS Header File | Description |
|---|---|
| HLS/hls.h | Required for component identification and component parameter interfaces. |
| HLS/math.h | Includes FPGA-specific definitions for the math functions from the math.h for your operating system. |
| HLS/extendedmath.h | Includes additional FPGA-specific definitions of math functions not in math.h. |
| HLS/ac_int.h | Provides FPGA-optimized arbitrary width integer support. |
| HLS/ac_fixed.h |
Provides FPGA-optimized arbitrary precision fixed point support. |
| HLS/ac_fixed_math.h |
Provides FPGA-optimized arbitrary precision fixed point math functions. |
| HLS/stdio.h | Provides printf support for components so that printf statements work in x86 emulations, but are disabled in component when compiling to an FPGA architecture. |
| <iostream> | To use cout and cerr in your component, guard the statements with the HLS_SYNTHESIS macro. |
hls.h Header File
- Syntax
- #include "HLS/hls.h"
- Description
- Required for component identification and component parameter interfaces.
math.h Header File
- Syntax
- #include "HLS/math.h"
- Description
- Includes FPGA-specific definitions for the math functions from the math.h for your operating system.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/single_vs_double_precision_math.
extendedmath.h Header File
- Syntax
- #include "HLS/extendedmath.h"
- Description
- Includes additional FPGA-specific definitions of math functions not in math.h.
To learn more, review the design: <quartus_installdir>/hls/examples/QRD.
ac_int.h Header File
- Syntax
- #include "HLS/ac_int.h"
- Description
-
Intel® HLS Compiler version of ac_int header file.
Provides FPGA-optimized arbitrary width integer support.
To learn more, review the following tutorials:- <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_int_basic_ops
- <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_int_overflow
- <quartus_installdir>/hls/examples/tutorials/best_practices/struct_interfaces
ac_fixed.h Header File
- Syntax
- #include "HLS/ac_fixed.h"
- Description
-
Intel® HLS Compiler version of the ac_fixed header file.
Provides FPGA-optimized arbitrary precision fixed point support.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_fixed_constructor.
ac_fixed_math.h Header File
- Syntax
- #include "HLS/ac_fixed_math.h"
- Description
-
Intel® HLS Compiler version of the ac_fixed_math header file.
Provides FPGA-optimized arbitrary precision fixed point math functions.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_fixed_math_library.
stdio.h Header File
- Syntax
- #include "HLS/stdio.h"
- Description
- Provides printf support for components so that printf statements work in x86 emulations, but are disabled in component when compiling to an FPGA architecture.
Standard C++ <iostream> Header File
- Syntax
- #include <iostream>
- Description
- To use the C++ standard output streams (cout and
cerr) provided by the standard
<iostream> header, you must guard any standard output statements
with the HLS_SYNTHESIS macro.
This macro ensures that statements in a component work in x86 emulations but are disabled in the component when compiling to an FPGA architecture.
Compiler-Defined Preprocessor Macros
| Tool Invocation | __INTELFPGA_COMPILER__ |
|---|---|
| g++ or cl | Undefined |
| -march=x86-64 | |
| -march="<FPGA_family_or_part_number>" |
| Tool Invocation | HLS_SYNTHESIS | |
|---|---|---|
| Testbench Code | HLS Component Code | |
| g++ or cl | Undefined | Undefined |
| -march=x86-64 | Undefined | Undefined |
| -march="<FPGA_family_or_part_number>" | Undefined | Defined |
Intel HLS Compiler Keywords
| Feature | Description |
|---|---|
| component | Indicates that a
function is a
component. Example:
component void foo() |
Intel HLS Compiler Simulation API (Testbench Only)
| Function | Description |
|---|---|
| ihc_hls_enqueue | This function enqueues one invocation of an HLS component. |
| ihc_hls_enqueue_noret | This function enqueues one invocation of an HLS component. This function should be used when the return type of the HLS component is void. |
| ihc_hls_component_run_all | This function pushes all enqueued invocations of a component into the component in the HDL simulator as quickly as the component can accept new invocations. |
| ihc_hls_sim_reset | This function sends a reset signal to the component during automated simulation. |
| ihc_hls_set_component_wait_cycle | This function tells the simulation process to continue running for a specified number of cycles after the done signal for the specified component is observed. |
ihc_hls_enqueue Function
- Syntax
- ihc_hls_enqueue(void* retptr, void* funcptr, /*function arguments*/)
- Description
- This function enqueues one invocation of an HLS component. The return value is stored in
the first argument which should be a pointer to the return type. The
component is not run until the ihc_hls_component_run_all() is invoked.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/usability/enqueue_call.
ihc_hls_enqueue_noret Function
- Syntax
- ihc_hls_enqueue_noret(void* funcptr, /*function arguments*/)
- Description
- This function enqueues one invocation of an HLS component. This function
should be used when the return type of the HLS component is void. The
component is not run until the ihc_hls_component_run_all() is invoked.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/usability/enqueue_call.
ihc_hls_component_run_all Function
- Syntax
- ihc_hls_component_run_all (void* funcptr)
- Description
- This function accepts a pointer to the HLS component function. When run, all enqueued
invocations of the component will be pushed into the component in the
HDL simulator as quickly as the component can accept new invocations.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/usability/enqueue_call.
ihc_hls_sim_reset Function
- Syntax
- int ihc_hls_sim_reset(void)
- Description
- This function sends a reset signal to the component during automated simulation. It returns
1 if the reset was exercised or 0 otherwise.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/component_memories/static_var_init.
ihc_hls_set_component_wait_cycle Function
- Syntax
- ihc_hls_set_component_wait_cycle(<component function name>, <# of wait cycles>)
- Description
- This function tells the simulation process to continue running for a
specified number of cycles after the done signal for the specified component is observed. This
delay can enable task functions with a higher latency than the component
function to successfully return their output during simulation.
Use this function when you simulate a design that uses a system of tasks where the completion of a task function is not synchronized with an ihc::collect call.
Simulation API Code Example
component int foo(int val) {
// function definition
}
component void bar (int val) {
// function definition
}
int main() {
// …….
int input = 0;
int res[5];
ihc_hls_enqueue(&res, &foo, input);
ihc_hls_enqueue_noret(&bar, input);
input = 1;
ihc_hls_enqueue(&res, &foo, input);
ihc_hls_enqueue_noret(&bar, input);
ihc_hls_component_run_all(&foo);
ihc_hls_component_run_all(&bar);
}
Intel HLS Compiler Component Memory Attributes
Use the component memory attributes to control the on-chip component memory architecture of your component.
| Memory Attribute | Description |
|---|---|
| hls_register | Forces
a variable or array to be carried through the pipeline in
registers. A register variable can be implemented either exclusively in flip-flops (FFs) or in a mix of FFs and RAM-based FIFOs. |
| hls_memory | Forces a variable or array to be implemented as embedded memory. |
| hls_memory_impl | Forces a variable or array to be implemented as embedded memory of a specified type. |
| hls_singlepump | Specifies that the memory implementing the local variable must be single pumped. |
| hls_doublepump | Specifies that the memory implementing the local variable must be double pumped. |
| hls_numbanks | Specifies that the memory implementing the local variable must have a defined number of memory banks. |
| hls_bankwidth | Specifies that the memory implementing the local variable must have memory banks of a defined width. |
| hls_bankbits | Forces the memory system to split into a defined number of memory banks and defines the bits used to select a memory bank. |
| hls_numports_readonly_writeonly | Specifies that the memory implementing the local variable must have a defined number of read and write ports. |
| hls_simple_dual_port_memory | Specifies a memory configuration that is equivalent to specifying the hls_singlepump and hls_numports_readonly_writeonly(1,1) component memory attributes. |
| hls_merge (depthwise) | Allows merging two or more local variables to be implemented in component memory as a single merged memory system in a depth-wise manner. |
| hls_merge (widthwise) | Allows merging two or more local variables to be implemented in component memory as a single merged memory system in a width-wise manner. |
| hls_init_on_reset | Forces the static variables inside the component to be reset when the component reset signal is asserted. |
| hls_init_on_powerup | Sets the component memory implementing the static variable to set on power-up when the FPGA is programmed. |
| hls_max_concurrency | Specifies the memory has a defined maximum number of copies to allow simultaneous iterations of a loop at any given time. |
hls_register Memory Attribute
- Syntax
- hls_register
- Constraints
- N/A
- Default Value
- Based on the memory access pattern inferred by the compiler.
- Description
- Forces a variable or
array
to be implemented as registers.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/swap_vs_copy.
hls_memory Memory Attribute
- Syntax
- hls_memory
- Constraints
- N/A
- Default Value
- Based on the memory access pattern inferred by the compiler.
- Description
- Forces a variable or
array
to be implemented as embedded memory.
To learn more, review the design: <quartus_installdir>/hls/examples/QRD.
hls_memory_impl Memory Attribute
- Syntax
- hls_memory_impl("type")
- Constraints
- N/A
- Default Value
- Based on the memory size and memory access pattern inferred by the compiler.
- Description
-
Forces a variable or array to be implemented as embedded memory of the specified type.
The type parameter can be one of the following values:- BLOCK_RAM
- Implement the variable or array as memory blocks, such as M20K memory blocks.
- MLAB
- Implement the variable or array as memory logic array blocks (MLABs).
hls_singlepump Memory Attribute
- Syntax
- hls_singlepump
- Constraints
- N/A
- Default Value
- Based on the memory access pattern inferred by the compiler.
- Description
- Specifies that the memory implementing the local
variable must be single pumped.
That is, the memory is clocked at the same operating frequency as the operating frequency of your component.
To learn more, review the design: <quartus_installdir>/hls/examples/QRD.
hls_doublepump Memory Attribute
- Syntax
- hls_doublepump
- Constraints
- N/A
- Default Value
- Based on the memory access pattern inferred by the compiler.
- Description
- Specifies that the memory implementing the local
variable must be double pumped.
That is, the memory is clocked at twice the operating frequency of your component.
hls_numbanks Memory Attribute
- Syntax
- hls_numbanks(N)
- Constraints
- This attribute is subject to constraints outlined in Constraints on Attributes for Memory Banks.
- Default Value
- Based on the memory access pattern inferred by the compiler.
- Description
- Specifies that the memory implementing the local variable must have N banks, where N is a power-of-two constant number.
hls_bankwidth Memory Attribute
- Syntax
- hls_bankwidth(N)
- Constraints
- This attribute is subject to constraints outlined in Constraints on Attributes for Memory Banks.
- Default Value
- Based on the memory access pattern inferred by the compiler.
- Description
- Specifies that the memory implementing the local
variable must have banks that are N
bytes wide, where N is a
power-of-two constant number.
To learn more, review the design: <quartus_installdir>/hls/tutorials/component_memories/bank_bits.
hls_bankbits Memory Attribute
- Syntax
- hls_bankbits(b 0 , b 1 , ..., b n )
- Constraints
- This attribute is subject to constraints outlined in Constraints on Attributes for Memory Banks.
- Default Value
- Lowest bits of the address based on number of banks.
- Description
- Forces the memory system to split into 2n+1 banks, with {b
0
, b
1
, ...,
b
n
} forming the
bank-select bits.Important: b 0 , b 1 , ..., b n must be consecutive, positive integers. You can specify the consecutive, positive integers in ascending or descending order.
If you do not specify the hls_bankwidth(N) attribute along with this attribute, then b 0 , b 1 , ..., b n are mapped to array index bits 0 to n-1 in the memory bank implementation.
To learn more, review the design: <quartus_installdir>/hls/tutorials/component_memories/bank_bits.
hls_numports_readonly_writeonly Memory Attribute
- Syntax
- hls_numports_readonly_writeonly(M, N)
- Constraints
- N/A
- Default Value
- Based on the memory access pattern inferred by the compiler.
- Description
- Specifies that the memory implementing the local variable must have M read ports and N write ports, where M and N are constant numbers greater than zero.
hls_simple_dual_port_memory Memory Attribute
- Syntax
- hls_simple_dual_port_memory
- Constraints
- N/A
- Default Value
- N/A
- Description
- Specifies a memory configuration that is equivalent to
specifying the following component memory attributes:
- hls_singlepump
- hls_numports_readonly_writeonly(1,1)
hls_merge (depthwise) Memory Attribute
- Syntax
- hls_merge("mem_name", "depth")
- Constraints
- N/A
- Default Value
- N/A
- Description
- Allows merging two or more local variables to be
implemented in component memory as a single merged memory system in a
depth-wise manner.
All variables with same <mem_name> label specified in their hls_merge attribute are merged into the same memory system.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/depth_wise_merge.
hls_merge (widthwise) Memory Attribute
- Syntax
- hls_merge("mem_name", "width")
- Constraints
- N/A
- Default Value
- N/A
- Description
- Allows merging two or more local variables to be
implemented in component memory as a single merged memory system in a
width-wise manner.
All variables with same <mem_name> label specified in their hls_merge attribute are merged into the same memory system.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/width_wise_merge.
hls_init_on_reset Memory Attribute
- Syntax
- hls_init_on_reset
- Constraints
- N/A
- Default Value
- Default behavior for static variables.
- Description
- Forces the static variables inside the component to be
reset when the component reset signal
is asserted. This requires an additional write port to the component
memory implemented and can increase the power-up latency when the
component is reset.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/component_memories/static_var_init.
hls_init_on_powerup Memory Attribute
- Syntax
- hls_init_on_powerup
- Constraints
- N/A
- Default Value
- N/A
- Description
- Sets the component memory implementing the static
variable to set on power-up when the FPGA is programmed. When the
component is reset, the component memory is not reset back to the
initialized value of the static.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/component_memories/static_var_init.
hls_max_concurrency Memory Attribute
- Syntax
- hls_max_concurrency(N)
- Constraints
- N/A
- Default Value
- N/A
- Description
- Specifies that the memory can have a maximum N private copies to allow N simultaneous iterations of a loop at
any given time, where N is rounded
up to the nearest power of 2.
Apply this attribute only when the scope of a variable (through its declaration or access pattern) is limited to a loop. If the loop has the max_concurrency pramga applied to it, the number of private copies created is the lesser of the hls_max_concurrency memory attribute value and the max_concurrency pragma value.
Intel HLS Compiler Loop Pragmas
Use the Intel® HLS Compiler loop pragmas to control how the compiler pipelines the loops in your component.
| Pragma | Description |
|---|---|
| disable_loop_pipelining | Prevents compiler from pipelining a loop, |
| ii | Forces a loop to have a loop initiation interval (II) of a specified value. |
| ivdep | Ignores memory dependencies between iterations of this loop. |
| loop_coalesce | Tries to fuse all loops nested within this loop into a single loop. |
| max_concurrency | Limits the number of iterations of a loop that can simultaneously execute at any time. |
| speculated_iterations | Specifies the number of clock cycles that a loop exit condition can take to compute. |
| unroll | Unrolls the loop completely or by a number of times. |
disable_loop_pipelining Loop Pragma
- Syntax
- #pragma disable_loop_pipelining
- Description
- Tells the compiler to not pipeline this loop.
Disable loop pipelining for a loop when the loop-carried dependencies cause the loop iterations to effectively execute sequentially. With loop pipelining disabled, the Intel® HLS Compiler can generate a simpler datapath and reduce the FPGA area utilization of your component.
Example:#pragma disable_loop_pipelining for (int i = 1; i < N; i++) { int j = a[i-1]; // Memory dependency induces a high-latency loop feedback path a[i] = foo(j) }
ii Loop Pragma
- Syntax
- #pragma ii N
- Description
- Forces the loop to which you apply this pragma to have a loop
initiation interval (II) of <N>, where
<N> is a positive integer value.
Forcing a loop II value can have an adverse effect on the fMAX of your component because using this pragma to get a lower loop II combines pipeline stages together and creates logic with a long propagation delay.
Using this pragma with a larger loop II inserts more pipeline stages and can give you a better component fMAX value.
Example:#pragma ii 2 for (int i = 0; i < 8; i++) { // Loop body }
ivdep Loop Pragma
- Syntax
- #pragma ivdep safelen(N) array(array_name)
- Description
- Tells the compiler to ignore memory dependencies between
iterations of this loop.
It can accept an optional argument that specifies the name of the array. If array is not specified, all component memory dependencies are ignored. If there are loop-carried dependencies, your generated RTL produces incorrect results.
The safelen parameter specifies the dependency distance. The dependency distance is the number of iterations between successive load/stores that depend on each other. It is safe to not include safelen is only when the dependence distance is infinite (that is, there are no real dependencies).
Example:#pragma ivdep safelen(2) for (int i = 0; i < 8; i++) { // Loop body }To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/loop_memory_dependency.
loop_coalesce Loop Pragma
- Syntax
- #pragma loop_coalesce N
- Description
- Tells the compiler to try to fuse all loops nested within this
loop into a single loop. This pragma accepts an optional value N which indicates the number of levels of loops to
coalesce together.
#pragma loop_coalesce 2 for (int i = 0; i < 8; i++) { for (int j = 0; j < 8; j++) { // Loop body } }
max_concurrency Loop Pragma
- Syntax
- #pragma max_concurrency N
- Description
- This pragma limits the number of iterations of a loop that can
simultaneously execute at any time.
This pragma is useful mainly when private copies of are created to improve the throughput of the loop. This is mentioned in the details pane for the loop in the Loop Analysis pane and the Bank view of the Function Memory Viewer of the high level design report (report.html).
This can occur only when the scope of a component memory (through its declaration or access pattern) is limited to this loop. Adding this pragma can be used to reduce the area that the loop consumes at the cost of some throughput.
Example:// Without this pragma, // multiple private copies // of the array "arr" #pragma max_concurrency 1 for (int i = 0; i < 8; i++) { int arr[1024]; // Loop body }
speculated_iterations Loop Pragma
- Syntax
- speculated_iterations N
- Description
- This pragma specifies the number of loop iterations to wait before
considering a loop exit condition. That is, you estimate that a loop takes at least
N loop iterations before the exit condition is
met.
If you specify a value that is too low, then the loop II increases to accommodate the iterations required to determine whether the loop exit condition is met.
Example:
component int loop_speculate (int N) { int m = 0; // The exit path has 2 multiplies and // compare is most critical in loop feedback path #pragma speculated_iterations 2 while (m*m*m < N) { m += 1; } return m; }
unroll Loop Pragma
- Syntax
- #pragma unroll N
- Description
- This pragma unrolls the loop completely or by <N> times, where <N> is optional and is a positive integer value.Example:
#pragma unroll 8 for (int i = 0; i < 8; i++) { // Loop body }To learn more, review the tutorial: <quartus_installdir>/hls/examples/best_practices/resource_sharing_filter.
Intel HLS Compiler Component Attributes
| Feature | Description |
|---|---|
| hls_component_ii | Force the component to which you apply this attribute to have a specified component initiation interval (II). |
| hls_disable_component_pipelining | Prevents the creation of the pipelined component datapath. Multiple invocations of this component now occur sequentially and not simultaneously. |
| hls_max_concurrency | Request more copies of the component memory so that the component can run multiple invocations in parallel. |
| hls_scheduler_target_fmax_mhz | Specify the target clock frequency of your component. |
hls_component_ii Component Attribute
- Syntax
- hls_component_ii(<N>)
- Description
- Forces the component to which you apply this attribute
to have a component initiation interval (II) of <N>, where <N> is a positive integer value.
This can have an adverse effect on the fMAX of your component because using this attribute to get a lower II combines pipeline stages together and creates logic with a long propagation delay.
Using this attribute with a larger II inserts more pipeline stages and can give you a better component fMAX value.
hls_disable_component_pipelining Component Attribute
- Syntax
- hls_disable_component_pipelining
- Description
- Tells the compiler to not create a pipelined datapath
for the component. An unpipelined component datapath can save FPGA area
utilization in some cases.
Use this attribute when a pipelined datapath does not improve your component throughput or when the component is not invoked repeatedly.
- Example
-
#include "HLS/hls.h" hls_disable_component_pipelining component void baz ( /* arguments */ ){ // component code }
hls_max_concurrency Component Attribute
- Syntax
- hls_max_concurrency(<N>)
- Description
- In some cases, the concurrency of a component is
limited to 1. This limit occurs
when the generated hardware cannot be shared across component
invocations. For example, when using component memories for a non-static
variable.
You can use this attribute to request more copies of the component memory so that the component can run multiple invocations in parallel.
This attribute can accept any non-negative whole number, including 0.- Value greater than 0
- A value greater than 0 indicates how many copies of the component memory to instantiate as well as how many component invocations can be in flight at once.
- Value equal to 0
- Setting hls_max_concurrency to a value of 0 is useful in cases when there is no component memory but the component still has a poor dynamic loop initiation interval (II) even if you believe your component II should be 1. You can review the II for loops in your component in the high level design report.
To learn more, review the design example: <quartus_installdir>/hls/examples/inter_decim_filter.
- Example
-
hls_max_concurrency(2) component void foo(ihc::stream_in<int> &data_in, ihc::stream_out<int> &data_out) { int arr[N]; for (int i = 0; i < N; i++) { arr[i] = data_in.read(); } // Operate on the data and modify in place for (int i = 0; i < N; i++) { data_out.write(arr[i]); } }
hls_scheduler_target_fmax_mhz Component Attribute
- Syntax
- hls_scheduler_target_fmax_mhz(<N>)
- Description
- Apply the hls_scheduler_target_fmax_mhz component attribute to have
the compiler target a specific fMAX value.
Specify the target fMAX value in MHz.
The component is not guaranteed to close timing at the specified frequency, and any tasks in a system of tasks use the same clock regardless of having different scheduling targets.
Intel HLS Compiler Component Default Interfaces
| Feature | Description |
|---|---|
| Component invocation interface (component call and return) |
The component call is implemented as an
interface consisting of the component start and busy
conduits. The component return is also implemented as an interface that includes the component done and stall signals. |
| Scalar parameter interface (passed by value) |
Scalar parameters are implemented as input conduits that are synchronized with the component invocation interface. |
| Pointer parameter interface (passed by reference) |
Pointer parameters are implemented as an
implicit Avalon Memory-Mapped Master (mm_master) interface with the default
parametrization. By default, the base address is treated as a scalar parameter so it is implemented as a conduit that is synchronized to the component invocation interface. A memory mapped interface is also exposed on the component. |
Intel HLS Compiler Component Invocation Interface Arguments
| Invocation Argument | Description |
|---|---|
| hls_avalon_streaming_component |
This is the default component invocation interface. The component uses start, busy, stall, and done signals for handshaking. |
| hls_avalon_slave_component | The start, done, and returndata (if applicable) signals are registered in the component slave memory map. |
| hls_always_run_component | The start signal is tied to 1 internally in the component. There is no done signal output. |
| hls_stall_free_return | If the downstream component never stalls, the stall signal is removed by internally setting it to 0. |
hls_avalon_streaming_component Argument
- Description
-
This is the default component invocation interface.
This attribute follows the Avalon®-ST protocol for both the function call and the return streams. The component consumes the unstable arguments when the start signal is asserted and the busy signal is deasserted. The component produces the return data when the done signal is asserted.
- Top-level module ports
-
- Function call:
- start
- busy
- Function return:
- done
- stall
- Function call:
- Example
-
component hls_avalon_streaming_component void foo(/*component arguments*/)
hls_avalon_slave_component Argument
- Description
- The start, done, and
returndata (if applicable) signals
are registered in the component slave memory map.
These component must take either slave, stream, or stable arguments. If you do not specify these types of arguments, the compiler generates an error message when you compile this component.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/interfaces/mm_slaves.
- Top-level module ports
-
- Avalon-MM slave interface
- irq_done signal
- Example
-
component hls_avalon_slave_component void foo(/*component arguments*/)
hls_always_run_component Argument
- Description
- The start signal is tied to 1 internally in the component. There is no done signal output. The control logic is
optimized away when
Intel®
Quartus® Prime
compiles the generated RTL for your FPGA.
Use this protocol when the component datapath relies only on explicit streams for data input and output.
IP verification does not support components with this component invocation protocol.
- Top-level module ports
- None
- Example
-
component hls_always_run_component void foo(/*component arguments*/)
hls_stall_free_return Argument
- Description
- If the downstream component never stalls, the stall
signal is removed by internally setting it to 0.
This feature can be used with the hls_avalon_streaming_component, hls_avalon_slave_component, and hls_always_run_component arguments. This attribute can be used to specify that the downstream component is stall free.
- Top-level module ports
- N/A
- Example
-
component hls_stall_free_return int dut(int a, int b) { return a * b;}
Intel HLS Compiler Component Macros
| Feature | Description |
|---|---|
| hls_conduit_argument | Implement the argument as an input conduit that is synchronous to the component call (start and busy). |
| hls_avalon_slave_register_argument | Implement the argument as a register that can be read from and written to over an Avalon-MM slave interface. |
| hls_avalon_slave_memory_argument | Implement the argument, in on-chip memory blocks, which can be read from or written to over a dedicated slave interface. |
| hls_stable_argument | A stable argument is an argument that does not change while there is live data in the component (that is, between pipelined function invocations). |
hls_conduit_argument Component Macro
- Syntax
- hls_conduit_argument
- Description
-
This is the default interface for scalar arguments.
The compiler implements the argument as an input conduit that is synchronous to the component's call (start and busy).
- Example
-
component void foo( hls_conduit_argument int b)
hls_avalon_slave_register_argument Component Macro
- Syntax
- hls_avalon_slave_register_argument
- Description
- The compiler implements the argument as a register that can be read from and written to
over an Avalon-MM slave interface. The argument will be read into the
component's pipeline, similar to the conduit implementation. The
implementation is synchronous to the start and busy interface.
Changes to the value of this argument made by the component data path will not be reflected on this register.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/interfaces/mm_slaves.
- Example
-
component void foo( hls_avalon_slave_register_argument int b)
hls_avalon_slave_memory_argument Component Macro
- Syntax
- hls_avalon_slave_memory_argument(N)
- Description
- The compiler implements the argument, where N
specifies the size of the memory in bytes, in on-chip memory blocks,
which can be read from or written to over a dedicated slave interface.
The generated memory has the same architectural optimizations as all
other internal component memories (such as banking or coalescing).
If the compiler performs static coalescing optimizations, the slave interface data width is the coalesced width. This attribute applies only to a pointer argument.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/interfaces/mm_slaves.
- Example
-
component void foo( hls_avalon_slave_memory_argument(128*sizeof(int)) int *a)
hls_stable_argument Component Macro
- Syntax
- hls_stable_argument
- Description
- A stable argument is an argument that does not change while there is live data in the
component (that is, between pipelined function invocations).
Changing a stable argument during component execution results in undefined behavior; each use of the stable argument might be the old value or the new value, but with no guarantee of consistency. The same variable in the same invocation can appear with multiple values.
Using stable arguments, where appropriate, might save a significant number of registers in a design.Stable arguments can be used with conduits, mm_master interfaces, and slave_registers.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/interfaces/stable_arguments.
- Example
-
component int dut( hls_stable_argument int a, hls_stable_argument int b) { return a * b;}
Systems of Tasks API
Systems of tasks are available only for Intel® HLS Compiler Pro Edition.
| Template Object or Argument | Description |
|---|---|
| ihc::launch | Marks a function as an Intel® HLS Compiler task for hardware generation, and launches the task function asynchronously. |
| ihc::collect | Synchronizes the completion of the specified task function in the component. |
| ihc::stream | Allows streaming communication between different task functions. |
ihc::launch Function
- Syntax
-
ihc::launch(<function>,<fuction_argument_list>)
Where the function parameters are defined as follows:
-
<function>
The name of the function that you are calling as an Intel® HLS Compiler task in your component.
If the task function is a templated function, wrap the function handle in a pair of parenthesis. For example: ihc::launch((foo<int>)), arg_a, arg_b);
-
<fuction_argument_list>
The list of arguments to pass to the task function.
This list must match the arguments (in names and types) that the task function expects.
-
- Description
- The ihc::launch API
function identifies a function as
Intel® HLS Compiler task for hardware generation. Calling
this function starts the task function asynchronously.
If the task function cannot accept a new thread, the ihc::launch function can block the function that calls the ihc::launch function.
The list of arguments that supply the ihc::launch API function must match (in names and types) the list of arguments expected by the task function.
ihc::collect Function
- Syntax
-
ihc::collect(function)
Where the function parameters are defined as follows:
-
<function>
The name of the Intel® HLS Compiler task function to synchronize the completion of.
If the task function is a templated function, wrap the function handle in a pair of parenthesis. For example: ihc::collect((foo<int>);
-
<function>
- Description
- The ihc::collect
API function synchronizes the completion of the specified task function
in the component.
For a non-void task function, the ihc::collect API function collects the result from the specified task function.
For a void task function, the ihc::collect API function synchronizes against the done signal of the task function.
The number of ihc::collect calls for a task function must match the number of ihc::launch calls for the same task function to flush all of the calls to the task.
Special Case: If you do not use ihc::collect at all, the compiler optimizes and ties-off the return stream of the task to be stall free and ignores any data on the return stream. Other streaming interfaces can still back-pressure the task function. Additionally, the caller might finish before the task function.
Intel® HLS Compiler System of Tasks Code Example
int mul(int a, int b)
{
return a * b;
}
Template<typename T>
T add(T a, T b)
{
return a + b;
}
component int foo(int a, int b)
{
ihc::launch(mul, a, b);
ihc::launch((add<int>), a, b);
int prod = ihc::collect(mul);
int sum = ihc::collect(add<int>);
return sum + prod;
}
ihc::stream Class
| Template Object or Argument | Description |
|---|---|
| ihc::stream | Streaming interface to the component or task function. |
| ihc::buffer | Specifies the capacity (in words) of the FIFO buffer on the input data that associates with the stream. |
| ihc::usesPackets | Exposes the startofpacket and endofpacket sideband signals on the stream interface. |
ihc::stream Template Object
- Syntax
- ihc::stream<datatype, template arguments >
- Valid Values
- Any valid C++ datatype
- Default Value
- N/A
- Description
- Streaming interface to the component or task.
The width of the stream data bus is equal to a width of sizeof(datatype).
ihc::buffer Template Argument
- 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.
ihc::usesPackets Template Argument
- 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.
Intel® HLS Compiler System of Tasks Streaming Interface stream Function APIs
| Function API | Description |
|---|---|
| T read() | Blocking read call to be used from within the component or task |
| T read(bool& sop, bool& eop) |
Available only if usesPackets<true> is set. Blocking read with out-of-band startofpacket and endofpacket signals. |
| T tryRead(bool &success) | Non-blocking read call to be used from within the component or task. The success bool is set to true if the read was valid. |
| 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. |
| void write(T data) | Blocking write call from the component or task. |
| void write(T data, bool sop, bool eop) |
Available only if usesPackets<true> is set. Blocking write with out-of-band startofpacket and endofpacket signals. |
| bool tryWrite(T data) | Non-blocking write call from the component or task. The return value represents whether the write was successful. |
| bool tryWrite(T data, bool sop, bool eop) |
Available only if usesPackets<true> is set. Non-blocking write with out-of-band startofpacket and endofpacket signals.The return value represents whether the write was successful. |
Intel HLS Compiler 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.
| Template Object or Argument | 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 arguments >
- 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/mulitple_stream_call_sites
ihc::buffer Template Argument
- 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 co-simulation (and therefore in hardware).
Review the Function Viewer report in 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 co-simulation.
This parameter is available only on input streams.
ihc::readylatency Template Argument
- 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 Argument
- 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.
Data is always broken down in little endian order.
ihc::firstSymbolInHighOrderBits Template Argument
- 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 Argument
- 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 Argument
- 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 Argument
- 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 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 co-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
// 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);
}
Intel HLS Compiler Streaming Output Interfaces
Use the stream_out object and template arguments to explicitly declare Avalon® Streaming (ST) output interfaces. You can also use the stream_out Function APIs.
| Template Object or Argument | Description |
|---|---|
| ihc::stream_out | Streaming output interface from the component. |
| 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::usesReady | Controls whether a ready signal is present. |
ihc::stream_out Template Object
- Syntax
- ihc::stream_out<datatype, template arguments >
- Valid Values
- Any valid POD (plain old data) C++ datatype.
- Default Value
- N/A
- Description
- Streaming output interface from the component. The testbench can read from this buffer
once the component returns. 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/ mulitple_stream_call_sites
ihc::readylatency Template Argument
- 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 sink can no longer
accept new inputs.
Conceptually, you can view this parameter as an almost ready latency on the input FIFO buffer for the data that associates with the stream.
ihc::bitsPerSymbol Template Argument
- Syntax
- ihc::bitsPerSymbol<value>
- Valid Values
- Positive integer value that evenly divides 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.
Data is always broken down in little endian order.
ihc::firstSymbolInHighOrderBits Template Argument
- 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 Argument
- 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 Argument
- 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 write 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 write 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::usesReady Template Argument
- Syntax
- ihc::usesReady<value>
- Valid Values
- true or false
- Default Value
- true
- Description
- Controls whether a ready signal is present. If false,
the downstream sink must be able to accept data on every cycle that
valid is asserted. This is equivalent to changing the stream read calls
to tryWrite and assuming that success is always true.
If set to false, readyLatency must be 0.
Intel® HLS Compiler Streaming Output Interface stream_in Function APIs
| Function API | Description |
|---|---|
| void write(T data) | Blocking write call from the component |
| void write(T data, bool sop, bool eop) |
Available only if usesPackets<true> is set. Blocking write 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 with out-of-band startofpacket, endofpacket, and empty signals. |
| bool tryWrite(T data) | Non-blocking write call from the component. The return value represents whether the write was successful. |
| bool tryWrite(T data, bool sop, bool eop) |
Available only if usesPackets<true> is set. Non-blocking write with out-of-band startofpacket and endofpacket signals.The return value represents whether the write was successful. That is, the downstream interface was pulling the ready signal high while the HLS component tried to write to the stream. |
| bool tryWrite(T data, bool sop, bool eop, int empty) | Available only if usesPackets<true> and usesEmpty<true> are set. Non-blocking write with out-of-band startofpacket, endofpacket, and empty signals. The return value represents whether the write was successful. |
| T read() | Blocking read call to be used from the testbench to read back the data from the component |
| T read(bool &sop, bool &eop) |
Available only if usesPackets<true> is set. Blocking read call to be used from the testbench to read back the data from the component 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 call to be used from the testbench to read back the data from the component with out-of-band startofpacket, endofpacket, and empty signals. |
Intel® HLS Compiler Streaming Output Interfaces Code Example
// Blocking write
void foo (ihc::stream_out<int> &a) {
static int count = 0;
for(int idx = 0; idx < 5; idx ++){
a.write(count++); // Blocking write
}
}
// Non-blocking write
void foo_nb (ihc::stream_out<int> &a) {
static int count = 0;
for(int idx = 0; idx < 5; idx ++){
bool success = a.tryWrite(count++); // Non-blocking write
if (success) {
// write was successful
}
}
}
int main() {
ihc::stream_out<int> a;
foo(a); // or foo_nb(a);
// copy output to an array
int outputData[5];
for (int i = 0; i < 5; i++) {
outputData[idx] = a.read();
}
}
Intel HLS Compiler Memory-Mapped Interfaces
Use the mm_master object and template arguments to explicitly declare Avalon® Memory-Mapped (MM) Master interfaces for your component.
| Template Object or Argument | Description |
|---|---|
| ihc::mm_master | The underlying pointer type. |
| ihc::dwidth | The width of the memory-mapped data bus in bits |
| ihc::awidth | The width of the memory-mapped address bus in bits. |
| ihc::aspace | The address space of the interface that associates with the master. |
| ihc::latency | The guaranteed latency from when a read command exits the component when the external memory returns valid read data. |
| ihc::maxburst | The maximum number of data transfers that can associate with a read or write transaction. |
| ihc::align | The alignment of the base pointer address in bytes. |
| ihc::readwrite_mode | The port direction of the interface. |
| ihc::waitrequest |
Adds the waitrequest signal that is asserted by the slave when it is unable to respond to a read or write request. |
| getInterfaceAtIndex | This testbench function is used to index into an mm_master object. |
ihc::mm_master Template Object
- Syntax
- ihc::mm_master<datatype, template arguments >
- Valid values
- Any valid C++ datatype
- Default value
- Default interface for pointer arguments.
- Description
- The underlying pointer type. Pointer arithmetic performed on the master
object conforms to this type. Dereferences of the master results in a
load-store site with a width of sizeof(datatype).
The default alignment is aligned to the size of the datatype.
You can use multiple template arguments in any combination as long the combination of arguments describes a valid hardware configuration.
Example:component int dut( ihc::mm_master<int, ihc::aspace<2>, ihc::latency<3>, ihc::awidth<10>, ihc::dwidth<32> > &a)
To learn more, review the following tutorials:- <quartus_installdir>/hls/examples/tutorials/interfaces/pointer_mm_master
- <quartus_installdir>/hls/examples/tutorials/interfaces/mm_master_testbench_operators
ihc::dwidth Template Argument
- Syntax
- ihc::dwidth<value>
- Valid Values
- 8, 16, 32, 64, 128, 256, 512, or 1024
- Default value
- 64
- Description
- The width of the memory-mapped data bus in bits.
ihc::awidth Template Argument
- Syntax
- ihc::awidth<value>
- Valid Values
- Integer value in the range 1 – 64
- Default value
- 64
- Description
- The width of the memory-mapped address bus in bits.
This value affects only the width of the Avalon® MM Master interface. The size of the conduit of the base address pointer is always set to 64-bits.
ihc::aspace Template Argument
- Syntax
- ihc::aspace<value>
- Valid Values
- Integer value greater than 0.
- Default value
- 1
- Description
- The address space of the interface that associates with the master. Each unique value results in a separate Avalon MM Master interface on your component. All masters with the same address space are arbitrated within the component to a single interface. As such, these masters must share the same template parameters that describe the interface.
ihc::latency Template Argument
- Syntax
- ihc::latency<value>
- Valid Values
- Non-negative integer value
- Default value
- 1
- Description
- The guaranteed latency from when a read command exits the component when the external memory returns valid read data. If this latency is variable (such as when accessing DRAM), set it to 0.
ihc::maxburst Template Argument
- Syntax
- ihc::maxburst<value>
- Valid Values
- Integer value in the range 1 – 1024
- Default value
- 1
- Description
- The maximum number of data transfers that can
associate with a read or write transaction. This value controls the
width of the burstcount signal.
For fixed latency interfaces, this value must be set to 1.
For more details, review information about burst signals and the burstcount signal role in "Avalon Memory-Mapped Interface Signal Roles" in Avalon Interface Specifications.
ihc::align Template Argument
- Syntax
- ihc::align<value>
- Valid Values
- Integer value greater than the alignment of the datatype
- Default value
- Alignment of the datatype
- Description
- The alignment of the base pointer address in bytes.
The Intel® HLS Compiler uses this information to determine how many simultaneous loads and stores this pointer can permit.
For example, if you have a bus with 4 32-bit integers on it, you should use ihc::dwidth<128> (bits) and ihc::align<16> (bytes). This means that up to 16 contiguous bytes (or 4 32-bit integers) can be loaded or stored as a coalesced memory word per clock cycle.
Important: The caller is responsible for aligning the data to the set value for the align argument; otherwise, functional failures might occur.
ihc::readwrite_mode Template Argument
- Syntax
- ihc::readwrite_mode<value>
- Valid Values
- readwrite, readonly, or writeonly
- Default value
- readwrite
- Description
- The port direction of the interface. Only the relevant Avalon master signals are generated.
ihc::waitrequest Template Argument
- Syntax
- ihc::waitrequest<value>
- Valid Values
- true or false
- Default value
- false
- Description
- Adds the waitrequest signal that is asserted by the slave when it is unable to respond to a read or write request. For more information about the waitrequest signal, see "Avalon Memory-Mapped Interface Signal Roles" in Avalon Interface Specifications.
getInterfaceAtIndex testbench function
- Syntax
- getInterfaceAtIndex(int index)
- Description
- This testbench function is used to index into an mm_master object. It can be useful when iterating over an array and invoking a component on different indicies of the array. This function is supported only in the testbench.
- Code Example
-
int main() { // ……. for(int idx = 0; idx < N; idx++) { dut(src_mm.getInterfaceAtIndex(idx)); } // ……. }
Intel HLS Compiler AC Datatypes
| AC Datatype | Intel Header File | Description |
|---|---|---|
| ac_int | HLS/ac_int.h | Arbitrary width integer support To learn
more, review the following tutorials:
|
| ac_fixed | HLS/ac_fixed.h | Arbitrary precision fixed-point support To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_fixed_constructor |
| HLS/ac_fixed_math.h | Support for some nonstandard math functions for arbitrary
precision fixed-point datatypes To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_fixed_math_library |
|
| ac_complex | HLS/ac_complex.h | Arbitrary precision complex number support |
| Tool | Description |
|---|---|
| DEBUG_AC_INT_WARNING | Emits a warning for each detected overflow. |
| DEBUG_AC_INT_ERROR |
Emits a message for the first overflow that is detected and then exits the component with an error. |
DEBUG_AC_INT_WARNING ac_int Debugging Tool
- Macro Syntax
-
#define DEBUG_AC_INT_WARNING
If you use this macro, declare it in your code before you declare #include HLS/ac_int.h.
- i++ Command Option Syntax
- -D DEBUG_AC_INT_WARNING
- Description
-
Enables runtime tracking of ac_int datatypes during x86 emulation (the -march=x86-64 option, which the default option, of the i++ command).
This tool uses additional resources for tracking the overflow and empty constructors, and emits a warning for each detected overflow.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_int_overflow.
DEBUG_AC_INT_ERROR ac_int Debugging Tool
- Macro Syntax
- #define DEBUG_AC_INT_ERROR
-
If you use this macro, declare it in your code before you declare #include HLS/ac_int.h.
- i++ Command Option Syntax
- -D DEBUG_AC_INT_ERROR
- Description
-
Enables runtime tracking of ac_int datatypes during x86 emulation of your component (the -march=x86-64 option, which the default option, of the i++ command).
This tool uses additional resources to track the overflow and empty constructors, and emits a message for the first overflow that is detected and then exits the component with an error.
To learn more, review the tutorial: <quartus_installdir>/hls/examples/tutorials/ac_datatypes/ac_int_overflow
Supported Math Functions
#include "HLS/math.h"
#include "HLS/extendedmath.h"The extendedmath.h header is compatible only with Intel® HLS Compiler. It is not compatible with GCC or Microsoft Visual Studio.
#include "HLS/ac_fixed_math.h"
To see examples of how to use the math functions provided by these header files, review the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/single_vs_double_precision_math.
Math Functions Provided by the math.h Header File
The Intel® HLS Compiler supports a subset of functions that are present in your native compiler through the HLS/math.h header file.
For each math.h function listed below, "●" indicates that the HLS compiler supports the function; "X" indicates that the function is not supported.
The math functions supported on Linux operating systems might differ from the math functions supported on Windows operating systems. Review the comments in the HLS/math.h header file to see which math functions are supported on the different operating systems.
| Trigonometric Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| cos | cosf | ● | ● |
| sin | sinf | ● | ● |
| tan | tanf | ● | ● |
| acos | acosf | ● | ● |
| asin | asinf | ● | ● |
| atan | atanf | ● | ● |
| atan2 | atan2f | ● | ● |
| Hyperbolic Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| cosh | coshf | ● | ● |
| sinh | sinhf | ● | ● |
| tanh | tanhf | ● | ● |
| acosh | acoshf | ● | X |
| asinh | asinhf | ● | X |
| atanh | atanhf | ● | X |
| Exponential or Logarithmic Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| exp | expf | ● | ● |
| frexp | frexpf | ● | ● |
| ldexp | ldexpf | ● | ● |
| log | logf | ● | ● |
| log10 | log10f | ● | ● |
| modf | modff | ● | ● |
| exp2 | exp2f | ● | ● |
| exp10 (Linux only) | exp10f (Linux only)* | ● | X |
| expm1 | expm1f | ● | ● |
| ilogb | ilogbf | ● | X |
| log1p | log1pf | ● | ● |
| log2 | log2f | ● | ● |
| logb | logbf | ● | X |
| scalbn | scalbnf | X | X |
| scalbln | scalblnf | X | ● |
| Power Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| pow | powf | ● | ● |
| sqrt | sqrtf | ● | ● |
| cbrt | cbrtf | ● | X |
| hypot | hypotf | ● | X |
| Error or Gamma Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| erf | erff | ● | X |
| erfc | erfcf | ● | X |
| tgamma | tgammaf | ● | X |
| lgamma | lgammaf | ● | X |
| lgamma_r (Linux only)2 | lgamma_rf (Linux only)2 | ● | X |
| Rounding or Remainder Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| ceil | ceilf | ● | ● |
| floor | floorf | ● | ● |
| fmod | fmodf | ● | ● |
| trunc | truncf | ● | ● |
| round | roundf | ● | ● |
| lround | lroundf | X | X |
| llround | llroundf | X | X |
| rint | rintf | ● | ● |
| lrint | lrintf | X | X |
| llrint | llrintf | X | X |
| nearbyint | nearbyintf | X | X |
| remainder | remainderf | ● | X |
| remquo | remquof | ● | X |
| Floating-Point Manipulation Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| copysign | copysignf | ● | X |
| nan | nanf | X | X |
| nextafter | nextafterf | ● | X |
| nexttoward | nexttowardf | X | X |
| Minimum, Maximum, or Difference Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| fdim | fdim | ● | ● |
| fmax | fmax | ● | ● |
| fmin | fmin | ● | ● |
| Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| fabs | fabsf | ● | ● |
| fma | fmaf | ● | X |
| Classification Macro | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| fpclassify (Linux only) | fpclassifyf (Linux only) | ● | X |
| isfinite | isfinitef | ● | ● |
| isinf | isinff | ● | ● |
| isnan | isnanf | ● | ● |
| isnormal (Linux only) | isnormalf (Linux only) | ● | X |
| signbit (Linux only) | signbitf (Linux only) | ● | X |
| Comparison Macro | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| isgreater | isgreaterf | X | X |
| isgreaterequal | isgreaterequalf | X | X |
| isless | islessf | X | X |
| islessequal | islessequalf | X | X |
| islessgreater | islessgreaterf | X | X |
| isunordered (Linux only) | isunorderedf (Linux only) | ● | X |
Math Functions Provided by the extendedmath.h Header File
Adding the HLS/extendedmath.h header file adds support for the following functions:
| Extended Math Functions | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| sincos | sincosf | ● | ● |
| acospi | acospif | ● | ● |
| asinpi | asinpif | ● | ● |
| atanpi | atanpif | ● | ● |
| cospi | cospif | ● | ● |
| sinpi | sinpif | ● | ● |
| tanpi | tanpif | ● | ● |
| pown | pownf | ● | ● |
| powr | powrf | ● | ● |
| rsqrt | rsqrtf | ● | ● |
| Exponential or Logarithmic Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| exp10 (Windows only) | exp10f (Windows only) * | ● | X |
| Error or Gamma Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| lgamma_r (Windows only)4 | lgamma_rf (Windows only)4 | ● | X |
| Minimum, Maximum, or Difference Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| maxmag | maxmagf | ● | X |
| minmag | minmagf | ● | X |
| Function | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| fract | fractf | ● | X |
| mad | madf | ● | X |
| oclnan | oclnanf | ● | X |
| rootn | rootnf | ● | X |
| Classification Macro | Supported by Intel® HLS Compiler? | ||
|---|---|---|---|
| Double-precision floating point function | Single-precision floating point function | ||
| isordered | isorderedf | ● | X |
| Data type | Function |
|---|---|
| Unsigned char | popcountc |
| Unsigned short | popcounts |
| Unsigned int | popcount |
| Unsigned long | popcountl |
| Unsigned long long | popcountll |
To see an example of how to use the math functions provided by the extendedmath.h header file and how to override a math function in the header file so that you can compile your design with GCC or Microsoft Visual Studio, review the following example design: <quartus_installdir>/hls/examples/QRD.
Math Functions Provided by the ac_fixed_math.h Header File
- sqrt_fixed
- reciprocal_fixed
- reciprocal_sqrt_fixed
- sin_fixed
- cos_fixed
- sincos_fixed
- sinpi_fixed
- cospi_fixed
- sincospi_fixed
- log_fixed
- exp_fixed