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

ID 683342
Date 4/22/2019
Document Table of Contents Restrictions and Limitations in RTL Support for the Intel® FPGA SDK for OpenCL™ Standard Edition Library Feature

The Intel® FPGA SDK for OpenCL™ supports the use of RTL modules in an OpenCL library with some restrictions and limitations.

When creating your RTL module, ensure that it operates within the following restrictions:

  • An RTL module must use a single input Avalon®-ST interface. That is, a single pair of ready and valid logic must control all the inputs.

    You have the option to provide the necessary Avalon-ST ports but declare the RTL module as stall-free. In this case, you do not have to implement proper stall behavior because the Intel® FPGA SDK for OpenCL™ Offline Compiler creates a wrapper for your module. Refer to XML Syntax of an RTL Module and Using an OpenCL Library that Works with Simple Functions (Example 1) for more syntax and usage information, respectively.

    Note: You must handle ivalid signals properly if your RTL module has an internal state. Refer to Stall-Free RTL for more information.
  • The RTL module must work correctly with exactly one clock, regardless of clock frequency.
  • Data input and output sizes must match valid OpenCL data types, from 8 bits for char to 1024 bits for long16.

    For example, if you work with 24-bit values inside an RTL module, declare inputs to be 32 bits and declare function signature in the SDK's library header file to accept the uint data type. Then, inside 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 an OpenCL kernel.
  • An RTL module must have a clock port, a resetn port, and Avalon-ST input and output ports (that is, ivalid, ovalid, iready, oready). Name the ports as specified here.
  • RTL modules that communicate with external memory must have Avalon Memory-Mapped (Avalon-MM) port parameters that match the corresponding Custom Platform parameters. The offline compiler does not perform any width or burst adaptation.
  • RTL modules that communicate with external memory must behave as follows:
    • They cannot burst across the burst boundary.
    • They cannot make requests every clock cycle and stall the hardware by monopolizing the arbitration logic. An RTL module must pause its requests regularly to allow other load or store units to execute their operations.
  • RTL modules cannot act as stand-alone OpenCL kernels. RTL modules can only be helper functions and be integrated into an OpenCL kernel during kernel compilation.
  • Every function call that corresponds to RTL module instantiation is completely independent of other instantiations. There is no hardware sharing.
  • Do not incorporate kernel code (that is, functions marked as kernel) into a .aoclib library file. Incorporating kernel code into the library file causes the offline compiler to issue an error message. You may incorporate helper functions into the library file.
  • An RTL component must receive all its inputs at the same time. A single ivalid input signifies that all inputs contain valid data.
  • The SDK does not support I/O RTL modules.
  • You can only set RTL module parameters in the <RTL module description file name>.xml specification file, not the OpenCL kernel source file. To use the same RTL module with multiple parameters, create a separate FUNCTION tag for each parameter combination.

Currently, the SDK's RTL module support for the library feature has the following limitations:

  • You can only pass data inputs to an RTL module by value via the OpenCL kernel code. Do not pass data inputs to an RTL module via pass-by reference, structs, or channels. In the case of channel data, extract the data from the channel first and then pass the extracted the scalar data to the RTL module.
    Note: Passing data inputs to an RTL module via pass-by reference or structs will cause a fatal error to occur in the offline compiler.
  • The debugger (for example, GDB for Linux) cannot step into a library function during emulation. In addition, optimization and area reports will not include code line numbers beside the library functions.
  • Names of RTL module source files cannot conflict with the file names of Intel® FPGA SDK for OpenCL™ Offline Compiler IP. Both the RTL module source files and the offline compiler IP files are stored in the <kernel file name>/system/synthesis/submodules directory. Naming conflicts will cause existing offline compiler IP files in the directory to be overwritten by the RTL module source files.
  • The SDK does not support .qip files. You must manually parse nested .qip files to create a flat list of RTL files.
  • It is very difficult to debug an RTL module that works correctly on its own but works incorrectly as part of an OpenCL kernel. Double check all parameters under the ATTRIBUTES element in the <RTL module description file name>.xml file.
  • All offline compiler area estimation tools assume that RTL module area is 0. The SDK does not currently support the capability of specifying an area model for RTL modules.
  • RTL modules cannot access a 2x clock that is in-phase with the kernel clock and at twice the kernel clock frequency.