Intel® FPGA SDK for OpenCL™ Pro Edition: Programming Guide

ID 683846
Date 6/21/2022
Public

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

Document Table of Contents

7.23.2. Additional Command Options for Incremental Compilation

The Intel® FPGA SDK for OpenCL™ incremental compilation feature includes optional functions that you can enable to customize the compilation of your OpenCL design.

Grouping Multiple Kernels into Partitions (-incremental-grouping=<filename>)

By default, the Intel® FPGA SDK for OpenCL™ Offline Compiler places each kernel in your design into a separate partition during incremental compilation. You have the option to group multiple kernels into a single partition by including the -incremental-grouping=<partition_filename> command option in your aoc command. In general, compilation speed is faster if your design contains fewer partitions.

Example: aoc -incremental-grouping=<partition_filename> <your_kernel_filename>.cl
Note: The offline compiler recompiles all kernels in a group even if you modify only one of the kernels. Intel® recommends that you group kernels that you typically want to modify at the same time.

If your grouped kernels perform many load and store operations, you can speed up compilation further by also including the -incremental=aggressive option in your aoc command.

The partition file that you pass to the -incremental-grouping option is a plain text file. Each line in the file specifies a new partition containing a semi-colon (;)-delimited list of kernel names. For example, the following lines in a partition file specify three partitions, each containing four kernels:

reader0;reader1;reader2;reader3
accum0;accum1;accum2;accum3
writer0;writer1;writer2;writer3

Compiling a Design in Aggressive Mode (-incremental=aggressive)

To increase the speed of an incremental compilation at the expense of area usage and throughput, include the -incremental=aggressive command option in your aoc command.

This feature is especially effective when the kernels in your design perform load and store operations to many buffers, or when you have grouped multiple kernels together using the -incremental-grouping command option.

Example: aoc -incremental=aggressive -incremental-grouping=<partition_filename> <your_kernel_filename>.cl

CAUTION:
  • Enabling the aggressive mode might result in throughput degradations that are larger than what the Fmax degradation indicates.
  • For each OpenCL design, avoid changing the compilation mode between incremental compilations. If you compile your design in aggressive mode, enable aggressive mode for all subsequent incremental compilations that you perform on this design. Each time you switch the incremental compilation mode, compilation takes longer to complete.

Specifying a Custom Input Directory (-incremental-input-dir=<path_to_directory>)

During incremental compilation, the offline compiler creates a default <your_kernel_filename> project directory in the current working directory to store intermediate compilation files. To base your incremental compilation on a nondefault project directory, specify the directory by including the -incremental-input-dir=<path_to_directory> command option in your aoc command.

You must include the -incremental-input-dir option if you compile your design in one or both of the following scenarios:

  • Run the aoc command from a different working directory than the previous compilation.
  • Included the -o <filename> command option in the previous compilation.

Consider the following example where there is a mykernel.cl file in the initial working directory and another revision of the same mykernel.cl file in the new_rev subdirectory:

aoc -incremental mykernel.cl
cd new_rev
aoc -incremental -fast-compile mykernel.cl -incremental-input-dir=../mykernel

In this scenario, the offline compiler reuses the files in mykernel project directory from the first compilation as the basis for the second compilation. The offline compiler creates a new_rev/mykernel project directory for the second compilation without modifying any file in the original mykernel directory.

The -incremental-input-dir command option is useful if multiple developers share the same incremental setup compilation. Each developer can run subsequent incremental compilations in their own workspace without overwriting other developers' compilation results.

Disabling Automatic Retry (-incremental-flow=no-retry)

By default, the offline compiler automatically retries a failed incremental compilation by performing a second compilation without preserving any partitions. This second compilation takes longer to complete because it recompiles the entire design.

To disable the offline compiler's automatic retry mechanism, include the -incremental-flow=no-retry command option in your aoc command. If you enable this feature, the offline compiler does not perform another incremental compilation after the first attempt fails. In addition, the offline compiler does not generate a .aocx file.

Enabling this feature allows you to implement your own failure mitigation strategies such as:

  • Compiling multiple seeds in parallel to increase the probability of at least one compilation succeeding without retrying.
  • Executing a non-incremental fast compilation instead of an incremental fast compilation (that is, aoc -fast-compile <your_kernel_filename>.cl).