C Modeling and RTL Implementation - 2021.1 English - UG1399

Streams are modeled as an infinite queue in software (and in the test bench during RTL co-simulation). There is no need to specify any depth to simulate streams in C++. Streams can be used inside functions and on the interface to functions. Internal streams may be passed as function parameters.

Streams can be used only in C++ based designs. Each hls::stream<> object must be written by a single process and read by a single process.

If an hls::stream is used on the top-level interface, it is by default implemented in the RTL as a FIFO interface (ap_fifo) but may be optionally implemented as a handshake interface (ap_hs) or an AXI4-Stream interface (axis).

If an hls::stream is used inside the design function and synthesized into hardware, it is implemented as a FIFO with a default depth of 2. In some cases, such as when interpolation is used, the depth of the FIFO might have to be increased to ensure the FIFO can hold all the elements produced by the hardware. Failure to ensure the FIFO is large enough to hold all the data samples generated by the hardware can result in a stall in the design (seen in C/RTL co-simulation and in the hardware implementation). The depth of the FIFO can be adjusted using the STREAM directive with the depth option. An example of this is provided in the example design hls_stream.

If an hls::stream is used to transfer data between tasks (sub-functions or loops), you should immediately consider implementing the tasks in a DATAFLOW region where data streams from one task to the next. The default (non-DATAFLOW) behavior is to complete each task before starting the next task, in which case the FIFOs used to implement the hls::stream variables must be sized to ensure they are large enough to hold all the data samples generated by the producer task. Failure to increase the size of the hls::stream variables results in the error below:

ERROR: [XFORM 203-733] An internal stream xxxx.xxxx.V.user.V' with default size is 
used in a non-dataflow region, which may result in deadlock. Please consider to 
resize the stream using the directive 'set_directive_stream' or the 'HLS stream' 
pragma.

This error informs you that in a non-DATAFLOW region (the default FIFOs depth is 2) may not be large enough to hold all the data samples written to the FIFO by the producer task.