HLS Stream Library - 2023.2 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2023-12-18
Version
2023.2 English

Streaming data is a type of data transfer in which data samples are sent in sequential order starting from the first sample. Streaming requires no address management.

Modeling designs that use streaming data can be difficult in C. The approach of using pointers to perform multiple read and/or write accesses can introduce issues, because there are implications for the type qualifier and how the test bench is constructed.

Important: The hls::stream class is only used in C++ designs.

Vitis HLS provides a C++ template class hls::stream<> for modeling streaming data structures. The streams implemented with the hls::stream<> class have the following attributes.

  • In the C code, an hls::stream<> behaves like a FIFO of infinite depth. There is no requirement to define the size of an hls::stream<>.
  • They are read from and written to sequentially. That is, after data is read from an hls::stream<>, it cannot be read again.
  • An hls::stream<> on the top-level interface is by default implemented with an ap_fifo interface for the AMD Vivado™ IP flow, or as an axis interface for the AMD Vitis™ kernel flow.
  • Streams can be defined either locally or globally and are always implemented as internal FIFOs. Streams defined in the global scope follow the same rules as any other global variables.
  • There are two possible stream declarations:
    • hls::stream<Type>: specify the data type for the stream.

      An hls::stream<> internal to the design is implemented as a FIFO with a default depth of 2. The STREAM pragma or directive can be used to change the depth.

    • hls::stream<Type, Depth> : specify the data type for the stream, and the FIFO depth.

      Set the depth to prevent stalls. If any task in the design can produce or consume samples at a greater rate than the specified depth, the FIFOs might become empty (or full) resulting in stalls, because it is unable to read (or write).

This section shows how the hls::stream<> class can more easily model designs with streaming data. The topics in this section provide:

  • An overview of modeling with streams and the RTL implementation of streams.
  • How to use streams.
  • Blocking reads and writes.
  • Non-Blocking Reads and writes.
  • Controlling the FIFO depth.
Note: The hls::stream class should always be passed between functions as a C++ reference argument. For example, &my_stream.