set_directive_stream

Description

By default, array variables are implemented as RAM:

  • Top-level function array parameters are implemented as a RAM interface port.
  • General arrays are implemented as RAMs for read-write access.
  • Arrays involved in sub-functions, or loop-based DATAFLOW optimizations are implemented as a RAM ping pong buffer channel.

If the data stored in the array is consumed or produced in a sequential manner, a more efficient communication mechanism is to use streaming data, where FIFOs are used instead of RAMs. When an argument of the top-level function is specified as INTERFACE type ap_fifo, the array is automatically implemented as streaming. See Managing Interface Synthesis for more information.

IMPORTANT: To preserve the accesses, it might be necessary to prevent compiler optimizations (in particular dead code elimination) by using the volatile qualifier as described in Type Qualifiers.

Syntax

set_directive_stream [OPTIONS] <location> <variable>
  • <location> is the location (in the format function[/label]) which contains the array variable.
  • <variable> is the array variable to be implemented as a FIFO.

Options

-depth <integer>
Note: Relevant only for array streaming in dataflow channels.

By default, the depth of the FIFO implemented in the RTL is the same size as the array specified in the C code. This options allows you to modify the size of the FIFO.

When the array is implemented in a DATAFLOW region, it is common to the use the -depth option to reduce the size of the FIFO. For example, in a DATAFLOW region where all loops and functions are processing data at a rate of II=1, there is no need for a large FIFO because data is produced and consumed in each clock cycle. In this case, the -depth option may be used to reduce the FIFO size to 2 to substantially reduce the area of the RTL design.

This same functionality is provided for all arrays in a DATAFLOW region using the config_dataflow command with the -depth option. The -depth option used with set_directive_stream overrides the default specified using config_dataflow.

-dim <integer>
Specifies the dimension of the array to implement as a streaming interface.
-off
Disables streaming data. Relevant only for array streaming in dataflow channels.

The config_dataflow -default_channel fifo command globally implies a STREAM pragma on all arrays in the design. The off option specified here overrides the config_dataflow command for the specified <variable>, and restores the default of using a RAM ping pong buffer-based channel.

TIP: If the -off option is selected, the -depth option sets the depth (number of blocks) of the ping-pong. The depth should be at least 2.

Examples

Specifies array A[10] in function foo to be streaming, and implemented as a FIFO.

set_directive_stream foo A

Array B in named loop loop_1 of function foo is set to streaming with a FIFO depth of 12. In this case, place the pragma inside loop_1.

set_directive_stream -depth 12 foo/loop_1 B

Array C has streaming disabled. It is assumed enabled by config_dataflow in this example.

set_directive_stream -off foo C

See Also