HLS第十八课（pragma，interface, resource, stream）

对函数的端口和存储单元的任何编译控制，都体现在pragma中。
下面对一些常用的pragma进行详细说明。
+++++++++++++++++++++++++++++++++++++++
pragma HLS interface

The INTERFACE pragma specifies how RTL ports are created from the function definition during
interface synthesis.

Port Level interface protocols are created for each argument in the top-level function and the function return,
The default I/O protocol created depends on the type of C argument.
When the INTERFACE pragma is used on sub-functions, only the register option can be used.
Vivado HLS automatically determines the I/O protocol used by any sub-functions.

ap_none: No protocol. The interface is a data port.Vivado HLS implements the input argument or the input half of any read/write arguments with mode ap_none.
ap_stable: No protocol. The interface is a data port. Vivado HLS assumes the data port is
always stable after reset,
ap_vld: Implements the data port with an associated valid port to indicate when the
data is valid for reading or writing.
ap_ack: Implements the data port with an associated acknowledge port to acknowledge
that the data was read or written.
ap_hs: Implements the data port with associated valid and acknowledge ports to
provide a two-way handshake to indicate when the data is valid for reading and writing and
to acknowledge that the data was read or written.
ap_ovld: Implements the output data port with an associated valid port to indicate
when the data is valid for reading or writing.

ap_fifo: Implements the port with a standard FIFO interface using data input and output
ports with associated active-Low FIFO empty and full ports.The ap_fifo mode does not support bidirectional read/write arguments.
ap_memory: Implements array arguments as a standard RAM interface. If you use the RTL design in Vivado IP integrator, the memory interface appears as discrete ports.

bram: Implements array arguments as a standard RAM interface.

ap_bus: Implements pointer and pass-by-reference ports as a bus interface.

axis: Implements all ports as an AXI4-Stream interface.
s_axilite: Implements all ports as an AXI4-Lite interface.
m_axi: Implements all ports as an AXI4 interface.

ap_ctrl_none: No block-level I/O protocol.
ap_ctrl_hs: Implements a set of block-level control ports to start the design operation
and to indicate when the design is idle, done, and ready for new input data.The ap_ctrl_hs mode is the default block-level I/O protocol.

ap_ctrl_chain: Implements a set of block-level control ports to start the design
operation, continue operation, and indicate when the design is idle, done, and ready
for new input data.

port=<name>: Specifies the name of the function argument, function return, or global
variable which the INTERFACE pragma applies to.

bundle=<string>: Groups function arguments into AXI interface ports. By default, Vivado HLS groups all function arguments specified as an AXI4-Lite (s_axilite) interface into a single AXI4-Lite port. Similarly, all function arguments specified as an AXI4 (m_axi) interface are grouped into a single AXI4 port.
This option explicitly groups all interface ports with the same bundle=<string> into the same AXI interface port and names the RTL port the value specified by <string>.

register: An optional keyword to register the signal and any relevant protocol signals, and
causes the signals to persist until at least the last cycle of the function execution.

register_mode= <forward|reverse|both|off>: Used with the register keyword,
this option specifies if registers are placed
on the forward path (TDATA and TVALID),
the reverse path (TREADY),
on both paths (TDATA, TVALID, and TREADY),
or if none of theport signals are to be registered (off).
The default register_mode is both.
AXI-Stream (axis) side-channel signals are considered to be data signals and are registered whenever the TDATA is registered.

offset=<string>: Controls the address offset in AXI4-Lite (s_axilite) and AXI4 (m_axi) interfaces.
For the s_axilite interface, <string> specifies the address in the register map.
For the m_axi interface, specifies on of the following values:
----slave: Generate an offset port and automatically map it to an AXI4-Lite slave interface.
----direct: Generate a scalar input offset port.
----off: Do not generate an offset port.

clock=<name>: Optionally specified only for interface mode s_axilite.
By default, the AXI-Lite interface clock is the same clock as the system clock. This option is used to specify a separate clock for the AXI-Lite (s_axilite) interface.
If the bundle option is used to group multiple top-level function arguments into a single AXI-Lite interface, the clock option need only be specified on one of the bundle members.

num_read_outstanding=<int>: For AXI4 (m_axi) interfaces, this option specifies how
many read requests can be made to the AXI4 bus, without a response.This implies internal storage in the design, a FIFO of size:

num_write_outstanding=<int>: For AXI4 (m_axi) interfaces, this option specifies how many write requests can be made to the AXI4 bus, without a response. This implies internal storage in the design, a FIFO of size:

max_read_burst_length=<int>: For AXI4 (m_axi) interfaces, this option specifies the maximum number of data values read during a burst transfer.

max_write_burst_length=<int>: For AXI4 (m_axi) interfaces, this option specifies the maximum number of data values written during a burst transfer.

void example(int A[50], int B[50]) {
//Set the HLS native interface types
#pragma HLS INTERFACE axis port=A
#pragma HLS INTERFACE axis port=B
	
	int i;
	for(i = 0; i < 50; i++){
		B[i] = A[i] + 5;
	}
}

In this example, both function arguments are implemented using an AXI4-Stream interface:

#pragma HLS interface ap_ctrl_none port=return

The following turns off block-level I/O protocols, and is assigned to the function return value:

#pragma HLS interface ap_vld register port=InData

The function argument InData is specified to use the ap_vld interface, and also indicates the
input should be registered:

#pragma HLS interface ap_memory port=lookup_table

This exposes the global variable lookup_table as a port on the RTL design, with an
ap_memory interface:

void transpose(int* input, int* output) {
#pragma HLS INTERFACE m_axi port=input offset=slave bundle=gmem0
#pragma HLS INTERFACE m_axi port=output offset=slave bundle=gmem1

#pragma HLS INTERFACE s_axilite port=input bundle=control
#pragma HLS INTERFACE s_axilite port=output bundle=control
#pragma HLS INTERFACE s_axilite port=return bundle=control

	#pragma HLS dataflow
	...
}

+++++++++++++++++++++++++++++++++++++++++++++++
pragma HLS resource

Specify that a specific library resource (core) is used to implement a variable (array, arithmetic
operation or function argument) in the RTL.
For example, to specify which memory element in the library to use to implement an array, use
the RESOURCE pragma.

#pragma HLS resource variable=<variable> core=<core> latency=<int>

variable=<variable>: A required argument that specifies the array, arithmetic operation, or function argument to assign the RESOURCE pragma to.
core=<core>: A required argument that specifies the core, as defined in the technology library.
latency=<int>: Specifies the latency of the core.

#pragma HLS resource variable=coeffs core=RAM_1P

In the following example, the variable coeffs[128] is an argument to the top-level function
foo_top. This example specifies that coeffs be implemented with core RAM_1P:

++++++++++++++++++++++++++++++++++++++++++++++++++++
pragma HLS stream

By default, array variables are implemented as RAM:
If the data stored in the array is consumed or produced in a sequential manner, specified by the STREAM pragma, 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.

#pragma HLS stream variable=<variable> depth=<int> dim=<int> off

variable=<variable>: Specifies the name of the array to implement as a streaming
interface.
depth=<int>: Relevant only for array streaming in DATAFLOW channels.
dim=<int>: Specifies the dimension of the array to be streamed. The default is dimension 1.
Specified as an integer from 0 to N, for an array with N dimensions.
off: Disables streaming data. Relevant only for array streaming in dataflow channels

#pragma HLS STREAM variable=A

The following example specifies array A[10] to be streaming, and implemented as a FIFO:

#pragma HLS STREAM variable=B depth=12

In this example array B is set to streaming with a FIFO depth of 12:

#pragma HLS STREAM variable=C off

Array C has streaming disabled.