Intel® High Level Synthesis Compiler Pro Edition: Reference Manual

ID 683349
Date 12/04/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

2.1. Intel® HLS Compiler Pro Edition Command Options

Use the Intel® HLS Compiler Pro Edition command options to customize how the compiler performs general functions, customize file linking, or customize compilation.
Table 2.  General Command OptionsThese i++ command options perform general compiler functions.
Command Option Description
-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.

--debug-log Instructs the compiler to generate a log file that contains diagnostic information.

The debug.log file is in the <result>.prj subdirectory within your current working directory.

If your compilation fails, the debug.log file is generated whether you set this option or not.

-v Verbose mode that instructs the compiler to display messages describing the progress of the compilation.

Example command: i++ -v multiplier.cpp, where multiplier.cpp is the input file.

--version Instructs the compiler to display its version information on screen.

Command: i++ --version

Table 3.  Command Options that Customize CompilationThese i++ command options perform compiler functions that impact the translation from source file to object file.
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 link 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 compile to RTL.

-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 Agilex® 7 and 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 Agilex® 7 and Intel® Stratix® 10 devices. If you use this option when you target devices other than Intel Agilex® 7 and 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:
x86-64
Instructs the compiler to compile the code for an emulator flow.
"<FPGA_family>"
Instructs the compiler to compile the code for a target FPGA device family.
The <FPGA_family> value can be any of the following device families:
  • Agilex
  • Arria10 or "Arria 10"
  • CycloneV 1
  • Cyclone10GX or "Cyclone 10 GX"
  • Stratix10 or "Stratix 10"
Quotation marks are required only if you specify a FPGA family name specifier that contains spaces
<FPGA_part_number>
Instructs the compiler to compile the code for a target device. The compiler determines the FPGA device family from the FPGA part number that you specify here.

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.

--quartus-compile Compiles your design 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 RTL 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.

--quartus-seed <seed> Specifies the seed numeric value that is used by Intel® Quartus® Prime project located in the <result>.prj/quartus directory.

This seed value is used by the Intel® Quartus® Prime Fitter for initial placement configuration when optimizing design placement to meet timing requirements (fMAX).

For more information about the Fitter seed, refer to Fitter Initial Placement Seed in the "Fitter Settings Reference" section of Intel® Quartus® Prime Pro Edition User Guide: Design Compilation .

--simulator <simulator_name> Specifies the simulator you are using to perform verification.
This command option can take the following values for <simulator_name>:
  • modelsim

    Use Siemens* EDA ModelSim* or Questa* for component verification.

  • none

    Disable verification. That is, generate RTL for components without the test bench.

If you do not specify this option, --simulator modelsim is assumed.

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 simulate your design. Without data from simulation, the report must omit verification statistics such as component latency.

Example command: i++ -march="<FPGA_family_or_part_number>" ‑‑simulator none multiplier.c

-ffp-contract=[ fast | on ]

For double-precision data types, controls whether the compiler can contract floating-point multiply and add or subtract operations into a single fused multiply-add (FMA), and controls whether the compiler skips intermediate rounding and conversions, except for code blocks fenced by #pragma clang fp contract(off).

This option has no effect on operations that involve single-precision data types.

The -ffp-contract option can take one of the following values:
fast
Math operations can be fused across multiple adjacent lines of code unless they are fenced by #pragma clang fp contract(off).

Math operations in code fenced by #pragma clang fp contract(on) can be fused only across a single line of code.

on
Math operations can be fused only across a single line of code unless they are fenced by #pragma clang fp contract(off).

Math operations in code fenced by #pragma clang fp contract(fast) can still be fused across multiple adjacent lines of code.

To learn more, review the following tutorials:
  • <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_contract
  • <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_ops
-ffp-reassociate

Controls whether the compiler can rearrange the order of floating-point arithmetic operations of any precision if the rearrangement improves throughput, latency, or both.

Code blocks fenced by #pragma clang fp reassociate(off) are not rearranged.

To learn more, review the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/floating_point_ops

--daz For double data types only, disable subnormal support in native IEEE-754 double-precision floating-point computations.

To learn more, review the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/submnormal_and_rounding

--rounding= [ieee | faithful]

For double data types only, control rounding scheme for native IEEE-754 double-precision adders, multipliers, and dividers.

If you do not specify this option, adders and multipliers use IEEE-754 round to nearest, ties to even (RNE) rounding (0.5 ULP) and dividers use faithful rounding (1 ULP).

The --rounding option can take one of the following values:
ieee
All adders, multipliers, and dividers use IEEE-754 RNE rounding.

IEEE-754 RNE rounding rounds results to the nearest value. If the number falls midway, it is rounded to the nearest value with an even least-significant digit. This is the default rounding mode defined by IEEE 754-2008 standard.

IEEE-754 RNE rounding has a accuracy of 0.5 ULP.

faithful
All adders, multipliers, and dividers use faithful rounding.

Faithful rounding rounds results to either the upper or lower nearest single-precision numbers. Therefore, faithful rounding produces one of two possible values. The choice between the two is not defined.

Faithful rounding has a maximum error of one ULP. Errors are not guaranteed to be evenly distributed.

Faithful rounding mode is not defined by the IEEE-754 standard.

To learn more, review the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/submnormal_and_rounding

--clock <clock target> Optimizes the RTL for the specified clock frequency or period.

The <clock target> value must include a unit.

For example:
i++ -march="Arria 10" test.cpp --clock 100MHz
i++ -march="Arria 10" test.cpp --clock 10ns
--dsp_mode= [prefer-dsp | prefer-softlogic | default] For supported data types and math operations, controls the hardware implementation of math functions on a global scope.
prefer-dsp
The compiler tries to implement supported math operations with DSPs.
prefer-softlogic
The compiler tries to implement supported math operations with soft logic using ALMs.
default
The compiler implements supported math operations based on data type and operation.

This value is the default.

For details about the implementation of math functions in hardware, refer to Math Function Hardware Implementation Summary.

To learn more, refer to the following tutorial: <quartus_installdir>/hls/examples/tutorials/best_practices/control_of_dsp_usage

Table 4.  Command Options that Customize File LinkingThese HLS command options specify compiler actions that impact the translation of the object file to the binary or RTL component.
Option Description
-ghdl[=<depth>]

Logs signals when running the verification executable to help you debug the generated RTL. After running the executable, the simulator logs waveforms to the a.prj/verification/vsim.wlf file.

Use the optional <depth> attribute to specify how many levels of hierarchy are logged. If you do not specify a value for the <depth> attribute, all signals are logged.

Use -ghdl=1 to log only the top-level signals.

For details about the ModelSim* waveform, see Debugging during Verification in Intel® High Level Synthesis Compiler Pro Edition User Guide.

-L <dir>

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

1 Cyclone® V device support is subject to restrictions. For details, refer to Cyclone V Restrictions.