Intel® High Level Synthesis Compiler Pro Edition: Reference Manual

ID 683349
Date 12/04/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

13.16. Intel® HLS Compiler Pro Edition Streaming Output Interfaces

Use the stream_out object and template arguments to explicitly declare Avalon® Streaming (ST) output interfaces. You can also use the stream_out Function APIs.

Table 55.   Intel® HLS Compiler Pro Edition Streaming Output Interface Template Summary
Template Object or Parameter Description
ihc::stream_out Streaming output interface from the component.
ihc::readylatency Specifies the number of cycles between when the ready signal is deasserted and when the input stream can no longer accept new inputs.
ihc::bitsPerSymbol Describes how the data is broken into symbols on the data bus.
ihc::firstSymbolInHighOrderBits Specifies whether the data symbols in the stream are in big endian order.
ihc::usesPackets Exposes the startofpacket and endofpacket sideband signals on the stream interface.
ihc::usesEmpty

Exposes the empty out-of-band signal on the stream interface.

ihc::usesReady Controls whether a ready signal is present.

ihc::stream_out Template Object

Syntax
ihc::stream_out<datatype, template parameter >
Valid Values
Any valid POD (plain old data) C++ datatype.
Default Value
N/A
Description
Streaming output interface from the component. The testbench can read from this buffer once the component returns.
To learn more, review the following tutorials:
  • <quartus_installdir>/hls/examples/tutorials/interfaces/ explicit_streams_buffer
  • <quartus_installdir>/hls/examples/tutorials/interfaces/ explicit_streams_packets_empty
  • <quartus_installdir>/hls/examples/tutorials/interfaces/ explicit_streams_packet_ready_valid
  • <quartus_installdir>/hls/examples/tutorials/interfaces/ explicit_streams_ready_latency
  • <quartus_installdir>/hls/examples/tutorials/interfaces/ mulitple_stream_call_sites

ihc::readylatency Template Parameter

Syntax
ihc::readylatency<value>
Valid Values
Non-negative integer value (between 0-8)
Default Value
0
Description
The number of cycles between when the ready signal is deasserted and when the sink can no longer accept new inputs.

Conceptually, you can view this parameter as an almost ready latency on the input FIFO buffer for the data that associates with the stream.

ihc::bitsPerSymbol Template Parameter

Syntax
ihc::bitsPerSymbol<value>
Valid Values
Positive integer value that evenly divides the data type size.
Default Value
Datatype size
Description
Describes how the data is broken into symbols on the data bus.

Data is broken down according to how you set the ihc::firstSymbolInHighOrderBits declaration. By default, data is broken down in little endian order.

ihc::firstSymbolInHighOrderBits Template Parameter

Syntax
ihc::firstSymbolInHighOrderBits<value>
Valid Values
true or false
Default Value
false
Description
Specifies whether the data symbols in the stream are in big endian order.

Tip: To confirm your setting of this parameter, view the simulation waveforms for your design. You cannot see the effects of setting this parameter in your emulation or simulation testbench.

ihc::usesPackets Template Parameter

Syntax
ihc::usesPackets<value>
Valid Values
true or false
Default Value
false
Description
Exposes the startofpacket and endofpacket sideband signals on the stream interface, which can be accessed by the packet based reads/writes.

ihc::usesEmpty Template Parameter

Syntax
ihc::usesEmpty<value>
Valid Values
true or false
Default Value
false
Description

Exposes the empty out-of-band signal on the stream interface.

Use this declaration only with streams that write more than one data symbol per clock cycle.

The empty signal indicates the number of symbols on the data bus that do not represent valid data during the final stream write of a packet.

You can control whether the empty symbols are in the low-order bits or high-order bits with the ihc::firstSymbolInHighOrderBits declaration.

ihc::usesReady Template Parameter

Syntax
ihc::usesReady<value>
Valid Values
true or false
Default Value
true
Description
Controls whether a ready signal is present. If false, the downstream sink must be able to accept data on every cycle that valid is asserted. This is equivalent to changing the stream read calls to tryWrite and assuming that success is always true.

If set to false, readyLatency must be 0.

Intel® HLS Compiler Pro Edition Streaming Output Interface stream_out Function APIs

Table 56.   Intel® HLS Compiler Pro Edition Streaming Output Interface stream_out Function APIs
Function API Description
void write(T data) Blocking write call from the component
void write(T data, bool sop, bool eop)

Available only if usesPackets<true> is set.

Blocking write with out-of-band startofpacket and endofpacket signals.
void write(T data, bool sop, bool eop, int empty) Available only if usesPackets<true> and usesEmpty<true> are set.

Blocking write with out-of-band startofpacket, endofpacket, and empty signals.

bool tryWrite(T data) Non-blocking write call from the component. The return value represents whether the write was successful.
bool tryWrite(T data, bool sop, bool eop)

Available only if usesPackets<true> is set.

Non-blocking write with out-of-band startofpacket and endofpacket signals.

The return value represents whether the write was successful. That is, the downstream interface was pulling the ready signal high while the HLS component tried to write to the stream.

bool tryWrite(T data, bool sop, bool eop, int empty) Available only if usesPackets<true> and usesEmpty<true> are set.

Non-blocking write with out-of-band startofpacket, endofpacket, and empty signals. The return value represents whether the write was successful.

T read() Blocking read call to be used from the testbench to read back the data from the component
T read(bool &sop, bool &eop)

Available only if usesPackets<true> is set.

Blocking read call to be used from the testbench to read back the data from the component with out-of-band startofpacket and endofpacket signals.
T read(bool &sop, bool &eop, int &empty) Available only if usesPackets<true> and usesEmpty<true> are set.

Blocking read call to be used from the testbench to read back the data from the component with out-of-band startofpacket, endofpacket, and empty signals.

Intel® HLS Compiler Streaming Output Interfaces Code Example

The following code example illustrates both stream_out declarations and stream_out function APIs.
// Blocking write
void foo (ihc::stream_out<int> &a) {
  static int count = 0;
  for(int idx = 0; idx < 5; idx ++){
    a.write(count++); // Blocking write
  }
}

// Non-blocking write
void foo_nb (ihc::stream_out<int> &a) {
  static int count = 0;
  for(int idx = 0; idx < 5; idx ++){
    bool success = a.tryWrite(count++); // Non-blocking write
    if (success) {
      // write was successful
    }
  }
}

int main() {
  ihc::stream_out<int> a;
  foo(a); // or foo_nb(a);
  
  // copy output to an array
  int outputData[5];
  for (int i = 0; i < 5; i++) {
    outputData[idx] = a.read();
  }
}