Intel® High Level Synthesis Compiler Pro Edition: Reference Manual

ID 683349
Date 12/19/2022
Public

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

Document Table of Contents

13.15. Intel® HLS Compiler Pro Edition Streaming Input Interfaces

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

Table 53.   Intel® HLS Compiler Pro Edition Streaming Input Interface Template Summary
Template Object or Parameter Description
ihc::stream_in Streaming input interface to the component.
ihc::buffer Specifies the capacity (in words) of the FIFO buffer on the input data that associates with the stream.
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::usesValid Controls whether a valid signal is present on the stream interface.

ihc::stream_in Template Object

Syntax
ihc::stream_in<datatype, template parameters >
Valid Values
Any valid C++ datatype
Default Value
N/A
Description
Streaming input interface to the component.

The width of the stream data bus is equal to a width of sizeof(datatype).

The testbench must populate this buffer (stream) fully before the component can start to read from the buffer.

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/multiple_stream_call_sites

ihc::buffer Template Parameter

Syntax
ihc::buffer<value>
Valid Values
Non-negative integer value.
Default Value
0
Description
The capacity, in words, of the FIFO buffer on the input data that associates with the stream. The buffer has latency. It immediately consumes data, but this data is not immediately available to the logic in the component.

If you use the tryRead() function to access this stream and the stream read is scheduled within the first cycles of operation, the first (or more) calls to the tryRead() function might return false in simulation (and therefore in hardware).

Review the function viewer in the System Viewer of the High-Level Design Reports to see when operations are scheduled in your component. If you see this behavior, use the blocking read() function to ensure consistency between emulation and simulation.

This parameter is available only on input streams.

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 input stream can no longer accept new inputs.

ihc::bitsPerSymbol Template Parameter

Syntax
ihc::bitsPerSymbol<value>
Valid Values
A positive integer value that evenly divides by 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 read 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 read 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::usesValid Template Parameter

Syntax
ihc::usesValid<value>
Valid Values
true or false
Default Value
true
Description
Controls whether a valid signal is present on the stream interface. If false, the upstream source must provide valid data on every cycle that ready is asserted.

This is equivalent to changing the stream read calls to tryRead and assuming that success is always true.

If set to false, buffer and readyLatency must be 0.

Intel® HLS Compiler Pro Edition Streaming Input Interface stream_in Function APIs

Table 54.   Intel® HLS Compiler Pro Edition Streaming Input Interface stream_in Function APIs
Function API Description
T read() Blocking read call to be used from within the component
T read(bool& sop, bool& eop)

Available only if usesPackets<true> is set.

Blocking read 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 with out-of-band startofpacket, endofpacket, and empty signals.

T tryRead(bool &success) Non-blocking read call to be used from within the component. The success bool is set to true if the read was valid. That is, the Avalon® -ST valid signal was high when the component tried to read from the stream.

The emulation model of tryRead() is not cycle-accurate, so the behavior of tryRead() might differ between emulation and simulation.

T tryRead(bool& success, bool& sop, bool& eop)

Available only if usesPackets<true> is set.

Non-blocking read with out-of-band startofpacket and endofpacket signals.
T tryRead(bool& success, bool& sop, bool& eop, int& empty) Available only if usesPackets<true> and usesEmpty<true> are set.

Non-blocking read with out-of-band startofpacket, endofpacket, and emptysignals.

void write(T data) Blocking write call to be used from the testbench to populate the FIFO to be sent to the component.
void write(T data, bool sop, bool eop)

Available only if usesPackets<true> is set.

Blocking write call 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 call with out-of-band startofpacket, endofpacket, and empty signals.

Intel® HLS Compiler Streaming Input Interfaces Code Example

The following code example illustrates both stream_in declarations and stream_in function APIs.
 // Blocking read
void foo (ihc::stream_in<int> &a) {
 int x = a.read(); 

}
 // Non-blocking read
void foo_nb (ihc::stream_in<int> &a) {
 bool success = false;
 int x = a.tryRead(success);

 if (success) {
 // x is valid
 }
}

int main() {
 ihc::stream_in<int> a;
 ihc::stream_in<int> b;
 for (int i = 0; i < 10; i++) {
  a.write(i);
  b.write(i);
 }
 foo(a);
 foo_nb(b);
}