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

ID 683846
Date 12/19/2022
Public
Document Table of Contents

11.1.2.7.1. XML Elements for ATTRIBUTES

In the object manifest file of the RTL module within an Intel® FPGA SDK for OpenCL™ library, there are XML elements under ATTRIBUTES that you can specify to set the module's characteristics.
Table 14.  XML Elements Associated with the ATTRIBUTES Element in the Object Manifest File of an RTL Module
Attention: Except for IS_STALL_FREE and EXPECTED_LATENCY, all elements have safe values. If you are unsure which value you should specify for an attribute, set it to the safe value. Compiling your kernel with a library that uses safe values results in functional hardware. However, the hardware might be larger than the actual size.
XML Element Description
IS_STALL_FREE

Instructs the Intel® FPGA SDK for OpenCL™ Offline Compiler to remove all stall logic around the RTL module.

Set IS_STALL_FREE to "yes" to indicate that the module neither generates stalls internally nor can it properly handle incoming stalls. The module simply ignores its stall input. If you set IS_STALL_FREE to "no", the module must properly handle all stall and valid signals.

Note: 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.

An incorrect IS_STALL_FREE setting leads to incorrect results in hardware.

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.

Note: For a given 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", the EXPECTED_LATENCY value indicates the number of pipeline stages inside the module. In this case, you must set this value to be the exact latency of the module. Otherwise, the offline compiler generates incorrect hardware.

For a module with variable latency, the offline 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, which might affect the number of stalls inside the pipeline. However, the resulting hardware is 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 offline compiler automatically inserts capacity-balancing FIFO buffers after this module when necessary.

The 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.

The safe value for HAS_SIDE_EFFECTS is "yes".

ALLOW_MERGING Instructs the offline compiler to merge multiple instances of the RTL module.

Set ALLOW_MERGING to "yes" to allow merging of multiple instances of the module. Intel® recommends setting ALLOW_MERGING to "yes".

The safe value for ALLOW_MERGING is "no".

Note: Marking the module with HAS_SIDE_EFFECTS="yes" does not prevent merging.
PARAMETER

Specifies the value of an RTL module parameter.

PARAMETER attributes:

  • name—Specifies the name of the RTL module parameter.
  • value—Specifies a decimal numeric value for the parameter.
  • type—Specifies a system parameter the value of which is used as the RTL module parameter value. You can use the following system parameter name with the type attribute:
    • bspaddresswidth—Specifies the Avalon® memory bus width required to address the memory range configured for OpenCL global memory in the board support package.
Note: The value for an RTL module parameter can be specified using either a value or a type attribute.