HLS Pragmas

Description

Collects and groups the data fields of a struct into a single scalar with a wider word width.

The AGGREGATE pragma is used for grouping all the elements of a struct into a single wide vector to allow all members of the struct to be read and written to simultaneously. The bit alignment of the resulting new wide-word can be inferred from the declaration order of the struct elements. The first element takes the LSB of the vector, and the final element of the struct is aligned with the MSB of the vector.

If the struct contains arrays, the AGGREGATE pragma performs a similar operation as ARRAY_RESHAPE, and combines the reshaped array with the other elements in the struct. Any arrays declared inside the struct are completely partitioned and reshaped into a wide scalar and packed with other scalar elements.

Syntax

Place the pragma near the definition of the struct variable to aggregate:

#pragma HLS aggregate variable=<variable>

Where:

variable=<variable>

Specifies the variable to be grouped.

Example 1

Aggregates struct pointer AB with three 8-bit fields (typedef struct {unsigned char R, G, B;} pixel) in function foo, into a new 24-bit pointer.

typedef struct{
unsigned char R, G, B;
} pixel;

pixel AB;
#pragma HLS aggregate variable=AB

Example 2

Aggregates struct array AB[17] with three 8-bit field fields (R, G, B) into a new 17 element array of 24-bits.

typedef struct{
unsigned char R, G, B;
} pixel;

pixel AB[17];
#pragma HLS aggregate variable=AB

See Also

• set_directive_aggregate
• pragma HLS array_reshape
• pragma HLS disaggregate

Description

Specifies restrictions to limit resource allocation in the implemented kernel. The ALLOCATION pragma or directive can limit the number of RTL instances and hardware resources used to implement specific functions, loops, or operations. The ALLOCATION pragma is specified inside the body of a function, a loop, or a region of code.

For example, if the C source has four instances of a function foo_sub, the ALLOCATION pragma can ensure that there is only one instance of foo_sub in the final RTL. All four instances of the C function are implemented using the same RTL block. This reduces resources used by the function, but negatively impacts performance by sharing those resources.

The operations in the C code, such as additions, multiplications, array reads, and writes, can also be limited by the ALLOCATION pragma.

Syntax

Place the pragma inside the body of the function, loop, or region where it will apply.

#pragma HLS allocation instances=<list> 
limit=<value> <type>

Where:

instances=<list>

Specifies the names of functions from the C code, or operators.

For a complete list of operations that can be limited using the ALLOCATION pragma, refer to the config_op command.

limit=<value>

Optionally specifies the limit of instances to be used in the kernel.

<type>

The type is specified as one of the following:

function

Specifies that the allocation applies to the functions listed in the instances= list. The function can be any function in the original C or C++ code that has not been:

• Inlined by the pragma HLS inline, or the set_directive_inline command, or
• Inlined automatically by the Vitis HLS tool.

operation

Specifies that the allocation applies to the operations listed in the instances= list.

Example 1

Given a design with multiple instances of function foo, this example limits the number of instances of foo in the RTL for the hardware kernel to two.

#pragma HLS allocation instances=foo limit=2 function

Example 2

Limits the number of multiplier operations used in the implementation of the function my_func to one. This limit does not apply to any multipliers outside of my_func, or multipliers that might reside in sub-functions of my_func.

void my_func(data_t angle) {
#pragma HLS allocation instances=mul limit=1 operation
...
}

See Also

• set_directive_allocation
• pragma HLS inline

Description

Partitions an array into smaller arrays or individual elements and provides the following:

• Results in RTL with multiple small memories or multiple registers instead of one large memory.
• Effectively increases the amount of read and write ports for the storage.
• Potentially improves the throughput of the design.
• Requires more memory instances or registers.

Syntax

Place the pragma in the C source within the boundaries of the function where the array variable is defined.

#pragma HLS array_partition variable=<name> \
<type>  factor=<int>  dim=<int>

Where:

variable=<name>

A required argument that specifies the array variable to be partitioned.

<type>

Optionally specifies the partition type. The default type is complete. The following types are supported:

cyclic

Cyclic partitioning creates smaller arrays by interleaving elements from the original array. The array is partitioned cyclically by putting one element into each new array before coming back to the first array to repeat the cycle until the array is fully partitioned. For example, if factor=3 is used:

• Element 0 is assigned to the first new array
• Element 1 is assigned to the second new array.
• Element 2 is assigned to the third new array.
• Element 3 is assigned to the first new array again.

block

Block partitioning creates smaller arrays from consecutive blocks of the original array. This effectively splits the array into N equal blocks, where N is the integer defined by the factor= argument.

complete

Complete partitioning decomposes the array into individual elements. For a one-dimensional array, this corresponds to resolving a memory into individual registers. This is the default <type>.

factor=<int>

Specifies the number of smaller arrays that are to be created.

IMPORTANT: For complete type partitioning, the factor is not specified. For block and cyclic partitioning, the factor= is required.

dim=<int>

Specifies which dimension of a multi-dimensional array to partition. Specified as an integer from 0 to <N>, for an array with <N> dimensions:

• If a value of 0 is used, all dimensions of a multi-dimensional array are partitioned with the specified type and factor options.
• Any non-zero value partitions only the specified dimension. For example, if a value 1 is used, only the first dimension is partitioned.

Example 1

This example partitions the 13 element array, AB[13], into four arrays using block partitioning:

#pragma HLS array_partition variable=AB block factor=4

Example 2

This example partitions dimension two of the two-dimensional array, AB[6][4] into two new arrays of dimension [6][2]:

#pragma HLS array_partition variable=AB block factor=2 dim=2

Example 3

This example partitions the second dimension of the two-dimensional in_local array into individual elements.

int in_local[MAX_SIZE][MAX_DIM];
#pragma HLS ARRAY_PARTITION variable=in_local complete dim=2

See Also

• set_directive_array_partition
• pragma HLS array_reshape

Description

The ARRAY_RESHAPE pragma breaks an array into smaller arrays, combined with vertical remapping, concatenating elements of arrays by increasing bit-widths. This reduces the number of block RAM consumed while providing the primary benefit of partitioning: parallel access to the data. This pragma creates a new array with fewer elements but with greater bit-width, allowing more data to be accessed in a single clock cycle.

Given the following code:

void foo (...) {
int array1[N];
int array2[N];
int array3[N];
#pragma HLS ARRAY_RESHAPE variable=array1 block factor=2 dim=1
#pragma HLS ARRAY_RESHAPE variable=array2 cycle factor=2 dim=1
#pragma HLS ARRAY_RESHAPE variable=array3 complete dim=1
...
}

The ARRAY_RESHAPE pragma transforms the arrays into the form shown in the following figure:

Syntax

Place the pragma in the C source within the region of a function where the array variable is defines.

#pragma HLS array_reshape variable=<name> \
<type>  factor=<int>  dim=<int>

Where:

<name>

Required argument that specifies the array variable to be reshaped.

<type>

Optionally specifies the partition type. The default type is complete. The following types are supported:

cyclic

Cyclic reshaping creates smaller arrays by interleaving elements from the original array. For example, if factor=3 is used, element 0 is assigned to the first new array, element 1 to the second new array, element 2 is assigned to the third new array, and then element 3 is assigned to the first new array again. The final array is a vertical concatenation (word concatenation, to create longer words) of the new arrays into a single array.

block

Block reshaping creates smaller arrays from consecutive blocks of the original array. This effectively splits the array into <N> equal blocks where <N> is the integer defined by factor=, and then combines the <N> blocks into a single array with word-width*N.

complete

Complete reshaping decomposes the array into temporary individual elements and then recombines them into an array with a wider word. For a one-dimension array this is equivalent to creating a very-wide register (if the original array was N elements of M bits, the result is a register with N*M bits). This is the default type of array reshaping.

factor=<int>

Specifies the amount to divide the current array by (or the number of temporary arrays to create). A factor of 2 splits the array in half, while doubling the bit-width. A factor of 3 divides the array into three, with triple the bit-width.

IMPORTANT: For complete type partitioning, the factor is not specified. For block and cyclic reshaping, the factor= is required.

dim=<int>

Specifies which dimension of a multi-dimensional array to partition. Specified as an integer from 0 to <N>, for an array with <N> dimensions:

• If a value of 0 is used, all dimensions of a multi-dimensional array are partitioned with the specified type and factor options.
• Any non-zero value partitions only the specified dimension. For example, if a value 1 is used, only the first dimension is partitioned.

object

A keyword relevant for container arrays only. When the keyword is specified the ARRAY_RESHAPE pragma applies to the objects in the container, reshaping all dimensions of the objects within the container, but all dimensions of the container itself are preserved. When the keyword is not specified the pragma applies to the container array and not the objects.

Example 1

Reshapes an 8-bit array with 17 elements, AB[17], into a new 32-bit array with five elements using block mapping.

#pragma HLS array_reshape variable=AB block factor=4

Example 2

Reshapes the two-dimensional array AB[6][4] into a new array of dimension [6][2], in which dimension 2 has twice the bit-width.

#pragma HLS array_reshape variable=AB block factor=2 dim=2

Example 3

Reshapes the three-dimensional 8-bit array, AB[4][2][2] in function foo, into a new single element array (a register), 128-bits wide (4×2×2×8).

#pragma HLS array_reshape variable=AB complete dim=0

See Also

• pragma HLS array_reshape
• pragma HLS array_partition

Description

Vitis HLS implements the operations in the code using specific implementations. The BIND_OP pragma specifies that for a specific variable, an operation (mul, add, div) should be mapped to a specific device resource (impl) in the RTL. If the BIND_OP pragma is not specified, Vitis HLS automatically determines the resources to use for operations.

For example, to indicate that a specific multiplier operation (mul) is implemented in the device fabric rather than a DSP, you can use the BIND_OP pragma.

You can also specify the latency of the operation using the latency option.

Syntax

Place the pragma in the C source within the body of the function where the variable is defined.

#pragma HLS bind_op variable=<variable> op=<type>\
impl=<value> latency=<int>

Where:

variable=<variable>

Defines the variable to assign the BIND_OP pragma to.

op=<type>

Specifies the type of operation for the specified variable. Supported values include: mul, add, sub, fadd, fsub, fdiv, fexp, flog, fmul, frsqrt, frecip, fsqrt, dadd, dsub, ddiv, dexp, dlog, dmul, drsqrt, drecip, dsqrt, hadd, hsub, hdiv, hmul, hsqrt.

impl=<value>

Defines the implementation to use for the specified operation (op). Supported values include: dsp, fabric, meddsp, fulldsp, maxdsp, primitivedsp.

latency=<int>

Defines the default latency for the binding of the operation type to the implementation. The valid latency varies according to the specified op and impl. The default is -1, which lets Vitis HLS choose the latency.

Example 1

In the following example, a two-stage pipelined multiplier is specified to implement the multiplication for variable <c> of the function foo.

int foo (int a, int b) {
int c, d;
#pragma HLS BIND_OP variable=c op=mul impl=MulnS latency=2
c = a*b;
d = a*c;
return d;
}

See Also

• set_directive_bind_op
• pragma HLS bind_storage

Description

The BIND_STORAGE pragma specifies that a specific storage type (type=) is assigned to a variable (array, or function argument) in the RTL. If the pragma is not specified, the Vitis HLS tool determines the storage type to assign. The HLS tool implements the specified storage type using specified implementations (impl). The types are defined in the following table.

For example, you can use the pragma to specify which memory element to use to implement an array. This lets you control whether the array is implemented as a single or a dual-port RAM for example. This usage is important for arrays on the top-level function interface, because the memory type associated with the array determines the number and type of ports needed in the RTL, as discussed in Arrays on the Interface.

You can use the latency= option to specify the latency of the implementation. For block RAMs on the interface, the latency= option allows you to model off-chip, non-standard SRAMs at the interface, for example supporting an SRAM with a latency of 2 or 3. For internal operations, the latency= option allows the operation to be implemented using more pipelined stages. These additional pipeline stages can help resolve timing issues during RTL synthesis.

Syntax

Place the pragma in the C source within the body of the function where the variable is defined.

#pragma HLS bind_storage variable=<variable> type=<type>\
[ impl=<value> latency=<int> ]

Where:

variable=<variable>

Defines the variable to assign the BIND_STORAGE pragma to. This is required when specifying the pragma.

type=<type>

Specifies the storage type to assign to the specified variable. This is required when specifying the pragma.

Supported types include: fifo, ram_1p, ram_1wnr, ram_2p, ram_s2p, ram_t2p, rom_1p, rom_2p, rom_np.

impl=<value>

Defines the hardware implementation for the specified storage type (type). Supported values include: bram, lutram, uram, srl.

latency=<int>

Defines the default latency for the binding of the type. The valid latency varies according to the specified type and impl. The default is -1, which lets Vitis HLS choose the latency.

Example 1

In the following example, the <coeffs[128]> variable is an argument to the top-level function foo_top. The pragma specifies that coeffs uses a single port RAM implemented on a BRAM.

#pragma HLS bind_storage variable=coeffs type=RAM_1P impl=bram

See Also

• set_directive_dependence

Description

Sometimes a C-based specification is written with a sequence of operations, resulting in a long chain of operations in RTL. With a small clock period, this can increase the latency in the design. By default, the Vitis HLS tool rearranges the operations using associative and commutative properties. This rearrangement creates a balanced tree that can shorten the chain, potentially reducing latency in the design at the cost of extra hardware.

The EXPRESSION_BALANCE pragma allows this expression balancing to be disabled, or to be expressly enabled, within a specified scope.

Syntax

Place the pragma in the C source within the boundaries of the required location.

#pragma HLS expression_balance off

Where:

off

Turns off expression balancing at this location.

TIP: Removing the off option from the pragma enables expression balancing, which is the default mode. This can be used to disable the pragma without removing it from your code.

Example 1

Disables expression balancing within function my_Func.

void my_func(char inval, char incr) {  
  #pragma HLS expression_balance off

Example 2

This example explicitly enables expression balancing in function my_Func.

void my_func(char inval, char incr) {  
  #pragma HLS expression_balance

See Also

• set_directive_expression_balance

Description

Removes a function as a separate entity in the hierarchy. After inlining, the function is dissolved into the calling function and no longer appears as a separate level of hierarchy in the RTL.

In some cases, inlining a function allows operations within the function to be shared and optimized more effectively with the calling function. However, an inlined function cannot be shared or reused, so if the parent function calls the inline function multiple times, this can increase the area required for implementing the RTL.

The INLINE pragma applies differently to the scope it is defined in depending on how it is specified:

INLINE

Without arguments, the pragma means that the function it is specified in should be inlined upward into any calling functions or regions.

INLINE OFF

Specifies that the function it is specified in should not be inlined upward into any calling functions or regions. This disables the inline of a specific function that can be automatically inlined, or inlined as part of a region or recursion.

INLINE REGION

Applies the pragma to the region or the body of the function it is assigned in. It applies downward, inlining the contents of the region or function, but not inlining recursively through the hierarchy.

INLINE RECURSIVE

Applies the pragma to the region or the body of the function it is assigned in. It applies downward, recursively inlining the contents of the region or function.

By default, inlining is only performed on the next level of function hierarchy, not sub-functions. However, the recursive option lets you specify inlining through levels of the hierarchy.

Syntax

Place the pragma in the C source within the body of the function or region of code.

#pragma HLS inline <region | recursive | off>

Where:

region

Optionally specifies that all functions in the specified region (or contained within the body of the function) are to be inlined, applies to the scope of the region.

recursive

By default, only one level of function inlining is performed, and functions within the specified function are not inlined. The recursive option inlines all functions recursively within the specified function or region.

off

Disables function inlining to prevent specified functions from being inlined. For example, if recursive is specified in a function, this option can prevent a particular called function from being inlined when all others are.

TIP: The Vitis HLS tool automatically inlines small functions, and using the INLINE pragma with the off option can be used to prevent this automatic inlining.

Example 1

This example inlines all functions within the region it is specified in, in this case the body of foo_top, but does not inline any lower level functions within those functions.

void foo_top { a, b, c, d} {
  #pragma HLS inline region
  ...

Example 2

The following example inlines all functions within the body of foo_top inlining recursively down through the function hierarchy, except function foo_sub is not inlined. The recursive pragma is placed in function foo_top. The pragma to disable inlining is placed in the function foo_sub:

foo_sub (p, q) {
#pragma HLS inline off
int q1 = q + 10;
foo(p1,q);// foo_3
...
}
void foo_top { a, b, c, d} {
  #pragma HLS inline region recursive 
  ...
  foo(a,b);//foo_1
  foo(a,c);//foo_2
  foo_sub(a,d);
  ...
}

Example 3

This example inlines the copy_output function into any functions or regions calling copy_output.

void copy_output(int *out, int out_lcl[OSize * OSize], int output) {
#pragma HLS INLINE
    // Calculate each work_item's result update location
    int stride = output * OSize * OSize;
    
    // Work_item updates output filter/image in DDR
    writeOut: for(int itr = 0; itr < OSize * OSize; itr++) {
    #pragma HLS PIPELINE
        out[stride + itr] = out_lcl[itr];
    }

See Also

• set_directive_inline
• pragma HLS allocation

Description

In C-based design, all input and output operations are performed, in zero time, through formal function arguments. In a RTL design, these same input and output operations must be performed through a port in the design interface and typically operate using a specific input/output (I/O) protocol. For more information, see Managing Interface Synthesis.

The INTERFACE pragma specifies how RTL ports are created from the function definition during interface synthesis. The ports in the RTL implementation are derived from the following:

• Block-level I/O protocols: provide signals to control when the function starts operation, and indicate when function operation ends, is idle, and is ready for new inputs. The implementation of a function-level protocol is:
  • Specified by the <mode> values ap_ctrl_none, ap_ctrl_hs or ap_ctrl_chain. The ap_ctrl_chain block protocol is the default.
  • Associated with the function name.
• Function arguments: Each function argument can be specified to have its own port-level (I/O) interface protocol, such as valid handshake (ap_vld), or acknowledge handshake (ap_ack). Port-level interface protocols are created for each argument in the top-level function and the function return, if the function returns a value. The default I/O protocol created depends on the type of C argument. After the block-level protocol has been used to start the operation of the block, the port-level I/O protocols are used to sequence data into and out of the block.
• Global variables accessed by the top-level function, and defined outside its scope:
  • If a global variable is accessed, but all read and write operations are local to the function, the resource is created in the RTL design. There is no need for an I/O port in the RTL. If the global variable is expected to be an external source or destination, specify its interface in a similar manner as standard function arguments. See the following Examples.

Specifying Burst Mode

When specifying burst-mode for interfaces, using the max_read_burst_length or max_write_burst_length options (as described in the Syntax section) there are limitations and related considerations that are derived from the AXI standard:

1. The burst length should be less than, or equal to 256 words per transaction, because ARLEN & AWLEN are 8 bits; the actual burst length is AxLEN+1.
2. In total, less than 4 KB is transferred per burst transaction.
3. Do not cross the 4 KB address boundary.
4. The bus width is specified as a power of 2, between 32-bits and 512-bits (that is, 32, 64, 128, 256, 512-bits) or in bytes: 4, 8, 16, 32, 64.

For example, pipelined accesses from a for-loop of 100 iterations will not fill the max burst length when max_read_burst_length or max_write_burst_length is set to 128.

However, if the design is doing longer accesses than the specified maximum burst length, the access will be split into multiple bursts. For example, a pipelined for-loop with 100 accesses, and max_read_burst_length or max_write_burst_length of 64, will be split into 2 transactions: one sized to the max burst length (64), and one with the remaining data (burst of length 36 words).

Syntax

Place the pragma within the boundaries of the function.

#pragma HLS interface <mode> port=<name> bundle=<string> \
register register_mode=<mode> depth=<int> offset=<string> latency=<value>\
clock=<string> name=<string> storage_type=<value>\
num_read_outstanding=<int> num_write_outstanding=<int> \
max_read_burst_length=<int> max_write_burst_length=<int>

Where:

<mode>

Specifies the interface protocol mode for function arguments, global variables used by the function, or the block-level control protocols. Refer to Interface Synthesis I/O Protocols for more information. The mode can be specified as one of the following:

ap_none

No protocol. The interface is a data port.

ap_stable

No protocol. The interface is a data port. The HLS tool assumes the data port is always stable after reset, which allows internal optimizations to remove unnecessary registers.

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.

IMPORTANT: The HLS tool implements the input argument or the input half of any read/write arguments with mode ap_none.

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.

Note: You can only use this interface on read arguments or write arguments. 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 the Vivado IP integrator, the memory interface appears as discrete ports.

bram

Implements array arguments as a standard RAM interface. If you use the RTL design in the IP integrator, the memory interface appears as a single port.

axis

Implements all ports as an AXI4-Stream interface.

s_axilite

Implements all ports as an AXI4-Lite interface. The HLS tool produces an associated set of C driver files during the Export RTL process.

m_axi

Implements all ports as an AXI4 interface. You can use the config_interface command to specify either 32-bit (default) or 64-bit address ports and to control any address offset.

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.

Note: The ap_ctrl_chain interface mode is similar to ap_ctrl_hs but provides an additional input signal ap_continue to apply back pressure. Xilinx recommends using the ap_ctrl_chain block-level I/O protocol when chaining the HLS tool blocks together.

Note: The ap_ctrl_chain is the default 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.

ap_ctrl_none

No block-level I/O protocol.

Note: Using the ap_ctrl_none mode might prevent the design from being verified using the C/RTL co-simulation feature.

port=<name>

Specifies the name of the function argument, function return, or global variable which the INTERFACE pragma applies to.

TIP: Block-level I/O protocols (ap_ctrl_none, ap_ctrl_hs, or ap_ctrl_chain) can be assigned to a port for the function return value.

bundle=<string>

Groups function arguments into AXI interface ports. By default, the HLS tool 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>.

IMPORTANT: When specifying the bundle= name you should use all lower-case characters.

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. This option applies to the following interface modes:

• ap_none
• ap_ack
• ap_vld
• ap_ovld
• ap_hs
• ap_stable
• axis
• s_axilite

TIP: The -register_io option of the config_interface command globally controls registering all inputs/outputs on the top function.

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 the port signals are to be registered (off). The default register_mode is both. AXI4-Stream (axis) side-channel signals are considered to be data signals and are registered whenever the TDATA is registered.

depth=<int>

Specifies the maximum number of samples for the test bench to process. This setting indicates the maximum size of the FIFO needed in the verification adapter that the HLS tool creates for RTL co-simulation.

TIP: While depth is usually an option, it is required for m_axi interfaces.

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, <string> specifies on of the following values:
  • direct: Generate a scalar input offset port.
  • slave: Generate an offset port and automatically map it to an AXI4-Lite slave interface.
  • off: Do not generate an offset port.
  TIP: The -m_axi_offset option of the config_interface command globally controls the offset ports of all M_AXI interfaces in the design.

clock=<name>

Optionally specified only for interface mode s_axilite. This defines the clock signal to use for the interface. By default, the AXI4-Lite interface clock is the same clock as the system clock. This option is used to specify a separate clock for the AXI4-Lite (s_axilite) interface.

TIP: If the bundle option is used to group multiple top-level function arguments into a single AXI4-Lite interface, the clock option need only be specified on one of the bundle members.

latency=<value>

When mode is m_axi, this specifies the expected latency of the AXI4 interface, allowing the design to initiate a bus request a number of cycles (latency) before the read or write is expected. If this figure is too low, the design will be ready too soon and might stall waiting for the bus. If this figure is too high, bus access can be granted but the bus might stall waiting on the design to start the access.

storage_type=<value>

For use with ap_memory and bram interfaces only. This options specifies a storage type (i.e. RAM_T2P) to assign to the variable.

Supported types include: fifo, ram_1p, ram_1wnr, ram_2p, ram_s2p, ram_t2p, rom_1p, rom_2p, rom_np.

TIP: This can also be specified using the BIND_STORAGE pragma or directive for an object not on the interface.

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, before the design stalls. This implies internal storage in the design, a FIFO of size: num_read_outstanding*max_read_burst_length*word_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, before the design stalls. This implies internal storage in the design, a FIFO of size: num_write_outstanding*max_write_burst_length*word_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.
  TIP: If the port is a read-only port, then set the num_write_outstanding=1 and max_write_burst_length=2 to conserve memory resources. For write-only ports, set the num_read_outstanding=1 and max_read_burst_length=2.

Example 1

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

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;
  }
}

Example 2

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

#pragma HLS interface ap_ctrl_none port=return

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

#pragma HLS interface ap_vld register port=InData

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

pragma HLS interface ap_memory port=lookup_table

Example 3

This example defines the INTERFACE standards for the ports of the top-level transpose function. Notice the use of the bundle= option to group signals.

// TOP LEVEL - TRANSPOSE
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

See Also

• set_directive_interface
• pragma HLS bind_storage

Description

Allows nested loops to be flattened into a single loop hierarchy with improved latency.

In the RTL implementation, it requires one clock cycle to move from an outer loop to an inner loop, and from an inner loop to an outer loop. Flattening nested loops allows them to be optimized as a single loop. This saves clock cycles, potentially allowing for greater optimization of the loop body logic.

Apply the LOOP_FLATTEN pragma to the loop body of the inner-most loop in the loop hierarchy. Only perfect and semi-perfect loops can be flattened in this manner:

Perfect loop nests

• Only the innermost loop has loop body content.
• There is no logic specified between the loop statements.
• All loop bounds are constant.

Semi-perfect loop nests

• Only the innermost loop has loop body content.
• There is no logic specified between the loop statements.
• The outermost loop bound can be a variable.

Imperfect loop nests

When the inner loop has variable bounds (or the loop body is not exclusively inside the inner loop), try to restructure the code, or unroll the loops in the loop body to create a perfect loop nest.

Syntax

Place the pragma in the C source within the boundaries of the nested loop.

#pragma HLS loop_flatten off

Where:

off

Optional keyword. Prevents flattening from taking place, and can prevent some loops from being flattened while all others in the specified location are flattened.

IMPORTANT: The presence of the LOOP_FLATTEN pragma or directive enables the optimization. The addition of off disables it.

Example 1

Flattens loop_1 in function foo and all (perfect or semi-perfect) loops above it in the loop hierarchy, into a single loop. Place the pragma in the body of loop_1.

void foo (num_samples, ...) {
  int i;
  ...
  loop_1: for(i=0;i< num_samples;i++) {
   #pragma HLS loop_flatten
   ...
    result = a + b;
  }
}

Example 2

Prevents loop flattening in loop_1.

loop_1: for(i=0;i< num_samples;i++) {
   #pragma HLS loop_flatten off
   ...

See Also

• set_directive_loop_flatten
• pragma HLS loop_merge
• pragma HLS unroll

Description

Merges consecutive loops into a single loop to reduce overall latency, increase sharing, and improve logic optimization. Merging loops:

• Reduces the number of clock cycles required in the RTL to transition between the loop-body implementations.
• Allows the loops be implemented in parallel (if possible).

The LOOP_MERGE pragma will seek to merge all loops within the scope it is placed. For example, if you apply a LOOP_MERGE pragma in the body of a loop, the Vitis HLS tool applies the pragma to any sub-loops within the loop but not to the loop itself.

The rules for merging loops are:

• If the loop bounds are variables, they must have the same value (number of iterations).
• If the loop bounds are constants, the maximum constant value is used as the bound of the merged loop.
• Loops with both variable bounds and constant bounds cannot be merged.
• The code between loops to be merged cannot have side effects. Multiple execution of this code should generate the same results (a=b is allowed, a=a+1 is not).
• Loops cannot be merged when they contain FIFO reads. Merging changes the order of the reads. Reads from a FIFO or FIFO interface must always be in sequence.

Syntax

Place the pragma in the C source within the required scope or region of code.

#pragma HLS loop_merge force

Where:

force

Optional keyword to force loops to be merged even when the HLS tool issues a warning.

IMPORTANT: In this case, you must manually ensure that the merged loop will function correctly.

Examples

Merges all consecutive loops in function foo into a single loop.

void foo (num_samples, ...) {
  #pragma HLS loop_merge
  int i;
  ...
  loop_1: for(i=0;i< num_samples;i++) {
   ...

All loops inside loop_2 (but not loop_2 itself) are merged by using the force option. Place the pragma in the body of loop_2.

loop_2: for(i=0;i< num_samples;i++) {
#pragma HLS loop_merge force
...

See Also

• set_directive_loop_merge
• pragma HLS loop_flatten
• pragma HLS unroll

Description

When manually applied to a loop, specifies the total number of iterations performed by a loop.

The Vitis HLS tool reports the total latency of each loop, which is the number of clock cycles to execute all iterations of the loop. Therefore, the loop latency is a function of the number of loop iterations, or tripcount.

The tripcount can be a constant value. It can depend on the value of variables used in the loop expression (for example, x < y), or depend on control statements used inside the loop. In some cases, the HLS tool cannot determine the tripcount, and the latency is unknown. This includes cases in which the variables used to determine the tripcount are:

• Input arguments or
• Variables calculated by dynamic operation.

In cases where the loop latency is unknown or cannot be calculated, the LOOP_TRIPCOUNT pragma lets you specify minimum, maximum, and average iterations for a loop. This lets the tool analyze how the loop latency contributes to the total design latency in the reports, and helps you determine appropriate optimizations for the design.

Syntax

Place the pragma in the C source within the body of the loop.

#pragma HLS loop_tripcount min=<int> max=<int> avg=<int>

Where:

max= <int>

Specifies the maximum number of loop iterations.

min=<int>

Specifies the minimum number of loop iterations.

avg=<int>

Specifies the average number of loop iterations.

Examples

In the following example, loop_1 in function foo is specified to have a minimum tripcount of 12, and a maximum tripcount of 16:

void foo (num_samples, ...) {
  int i;
  ...
  loop_1: for(i=0;i< num_samples;i++) {
   #pragma HLS loop_tripcount min=12 max=16
   ...
    result = a + b;
  }
}

See Also

• set_directive_loop_tripcount

Description

For example, in a loop that executes 10 times, a conditional statement within the loop only executes two times has an occurrence of 5 (or 10/2).

Identifying a region with the OCCURRENCE pragma allows the functions and loops in that region to be pipelined with a higher initiation interval that is slower than the enclosing function or loop.

Syntax

Place the pragma in the C source within a region of code.

#pragma HLS occurrence cycle=<int>

Where:

cycle=<int>

Specifies the occurrence N/M.

<N>

Number of times the enclosing function or loop is executed.

<M>

Number of times the conditional region is executed.

IMPORTANT: <N> must be an integer multiple of <M>.

Examples

In this example, the region Cond_Region has an occurrence of 4 (it executes at a rate four times less often than the surrounding code that contains it).

Cond_Region: {
#pragma HLS occurrence cycle=4
...
}

See Also

• set_directive_occurrence
• pragma HLS pipeline

Description

Reduces the initiation interval (II) for a function or loop by allowing the concurrent execution of operations. The default type of pipeline is defined by the config_compile -pipeline_style command, but can be overridden in the PIPELINE pragma or directive.

A pipelined function or loop can process new inputs every <N> clock cycles, where <N> is the II of the loop or function. The default II for the PIPELINE pragma is 1, which processes a new input every clock cycle. You can also specify the initiation interval through the use of the II option for the pragma.

If the Vitis HLS tool cannot create a design with the specified II, it issues a warning and creates a design with the lowest possible II.

You can then analyze this design with the warning message to determine what steps must be taken to create a design that satisfies the required initiation interval.

Pipelining a loop allows the operations of the loop to be implemented in a concurrent manner as shown in the following figure. In the figure, (A) shows the default sequential operation where there are three clock cycles between each input read (II=3), and it requires eight clock cycles before the last output write is performed. (B) shows the pipelined operations that show one cycle between reads (II=1), and 4 cycles to the last write.

Syntax

Place the pragma in the C source within the body of the function or loop.

#pragma HLS pipeline II=<int> off rewind enable_flush

Where:

enable_flush

Optional keyword overriding the default pipeline style specified by the config_compile -pipeline_style option. The enable_flush option defines the pipeline as a flushable pipeline as described in Flushing Pipelines in the Vitis HLS Flow. This type of pipeline typically consumes more resources and/or can have a larger II because resources cannot be shared among pipeline iterations.

TIP: This feature is only supported for pipelined functions; it is not supported for pipelined loops.

II=<int>

Specifies the desired initiation interval for the pipeline. The HLS tool tries to meet this request. Based on data dependencies, the actual result might have a larger initiation interval. The default II is 1.

off

Optional keyword. Turns off pipeline for a specific loop or function. This can be used to disable pipelining for a specific loop when config_compile -pipeline_loops is used to globally pipeline loops.

rewind

Optional keyword. Enables rewinding, or continuous loop pipelining with no pause between one loop iteration ending and the next iteration starting. Rewinding is effective only if there is one single loop (or a perfect loop nest) inside the top-level function. The code segment before the loop:

• Is considered as initialization.
• Is executed only once in the pipeline.
• Cannot contain any conditional operations (if-else).
  TIP: This feature is only supported for pipelined loops; it is not supported for pipelined functions.

Example 1

In this example, function foo is pipelined with an initiation interval of 1, which is the default.

void foo { a, b, c, d} {
  #pragma HLS pipeline II=1
  ...
}

See Also

• set_directive_pipeline
• pragma HLS dependence
• config_compile

Description

Adds or removes resets for specific state variables (global or static).

The reset port is used to restore the registers and block RAM, connected to the port, to an initial value any time the reset signal is applied. The presence and behavior of the RTL reset port is controlled using the config_rtl settings. The reset settings include the ability to set the polarity of the reset, and specify whether the reset is synchronous or asynchronous, but more importantly it controls, through the reset option, which registers are reset when the reset signal is applied. For more information, see Controlling the Reset Behavior.

Greater control over reset is provided through the RESET pragma. If a variable is a static or global, the RESET pragma is used to explicitly add a reset, or the variable can be removed from the reset by turning off the pragma. This can be particularly useful when static or global arrays are present in the design.

Syntax

Place the pragma in the C source within the boundaries of the variable life cycle.

#pragma HLS reset variable=<a> off

Where:

variable=<a>

Specifies the variable to which the RESET pragma is applied.

off

Indicates that reset is not generated for the specified variable.

Example 1

This example adds reset to the variable a in function foo even when the global reset setting is none or control.

void foo(int in[3], char a, char b, char c, int out[3]) {
#pragma HLS reset variable=a 

Example 2

Removes reset from variable a in function foo even when the global reset setting is state or all.

void foo(int in[3], char a, char b, char c, int out[3]) {
#pragma HLS reset variable=a off

See Also

• set_directive_reset
• config_rtl

Description

By default, array variables are implemented as RAM:

• Top-level function array parameters are implemented as a RAM interface port.
• General arrays are implemented as RAMs for read-write access.
• Arrays involved in sub-functions, or loop-based DATAFLOW optimizations are implemented as a RAM ping pong buffer channel.

If the data stored in the array is consumed or produced in a sequential manner, a more efficient communication mechanism is to use streaming data as specified by the STREAM pragma, where FIFOs are used instead of RAMs.

Syntax

Place the pragma in the C source within the boundaries of the required location.

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

Where:

variable=<variable>

Specifies the name of the array to implement as a streaming interface.

depth=<int>

Relevant only for array streaming in DATAFLOW channels. By default, the depth of the FIFO implemented in the RTL is the same size as the array specified in the C code. This option lets you modify the size of the FIFO to specify a different depth.

When the array is implemented in a DATAFLOW region, it is common to use the depth option to reduce the size of the FIFO. For example, in a DATAFLOW region when all loops and functions are processing data at a rate of II=1, there is no need for a large FIFO because data is produced and consumed in each clock cycle. In this case, the depth option can be used to reduce the FIFO size to 1 to substantially reduce the area of the RTL design.

TIP: The config_dataflow -depth command provides the ability to stream all arrays in a DATAFLOW region. The depth option specified in the STREAM pragma overrides the config_dataflow -depth setting for the specified <variable>.

dim=<int>

Specifies the dimension of the array to implement as a streaming interface.

off

Disables streaming data. Relevant only for array streaming in dataflow channels.

TIP: The config_dataflow -default_channel fifo command globally implies a STREAM pragma on all arrays in the design. The off option specified here overrides the config_dataflow command for the specified <variable>, and restores the default of using a RAM ping pong buffer-based channel.

Example 1

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

#pragma HLS STREAM variable=A

Example 2

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

#pragma HLS STREAM variable=B depth=12

Example 3

Array C has streaming disabled. In this example, it is assumed to be enabled by config_dataflow -default_channel.

#pragma HLS STREAM variable=C off

See Also

• set_directive_stream
• pragma HLS dataflow
• pragma HLS interface
• config_dataflow

Description

Attaches a name to a function, which can then be used with the set_top command to synthesize the function and any functions called from the specified top-level. This is typically used to synthesize member functions of a class in C/C++.

Specify the TOP pragma in an active solution, and then use the set_top command with the new name.

Syntax

Place the pragma in the C source within the boundaries of the required location.

#pragma HLS top name=<string>

Where:

name=<string>

Specifies the name to be used by the set_top command.

Examples

Function foo_long_name is designated the top-level function, and renamed to DESIGN_TOP. After the pragma is placed in the code, the set_top command must still be issued from the Tcl command line, or from the top-level specified in the IDE project settings.

void foo_long_name () {
  #pragma HLS top name=DESIGN_TOP
  ...
}

Followed by the set_top DESIGN_TOP command.

See Also

• set_directive_top
• set_top

Description

You can unroll loops to create multiple independent operations rather than a single collection of operations. The UNROLL pragma transforms loops by creating multiples copies of the loop body in the RTL design, which allows some or all loop iterations to occur in parallel.

Loops in the C/C++ functions are kept rolled by default. When loops are rolled, synthesis creates the logic for one iteration of the loop, and the RTL design executes this logic for each iteration of the loop in sequence. A loop is executed for the number of iterations specified by the loop induction variable. The number of iterations might also be impacted by logic inside the loop body (for example, break conditions or modifications to a loop exit variable). Using the UNROLL pragma you can unroll loops to increase data access and throughput.

The UNROLL pragma allows the loop to be fully or partially unrolled. Fully unrolling the loop creates a copy of the loop body in the RTL for each loop iteration, so the entire loop can be run concurrently. Partially unrolling a loop lets you specify a factor N, to create N copies of the loop body and reduce the loop iterations accordingly.

Partial loop unrolling does not require N to be an integer factor of the maximum loop iteration count. The Vitis HLS tool adds an exit check to ensure that partially unrolled loops are functionally identical to the original loop. For example, given the following code:

for(int i = 0; i < X; i++) {
  pragma HLS unroll factor=2
  a[i] = b[i] + c[i];
}

for(int i = 0; i < X; i += 2) {
  a[i] = b[i] + c[i];
  if (i+1 >= X) break;
  a[i+1] = b[i+1] + c[i+1];
}

In the example above, since the maximum iteration count, X, is a variable, the HLS tool might not be able to determine its value, so it adds an exit check and control logic to partially unrolled loops. However, if you know that the specified unrolling factor, 2 in this example, is an integer factor of the maximum iteration count X, the skip_exit_check option lets you remove the exit check and associated logic. This helps minimize the area and simplify the control logic.

Syntax

Place the pragma in the C/C++ source within the body of the loop to unroll.

#pragma HLS unroll factor=<N> region skip_exit_check

Where:

factor=<N>

Specifies a non-zero integer indicating that partial unrolling is requested. The loop body is repeated the specified number of times, and the iteration information is adjusted accordingly. If factor= is not specified, the loop is fully unrolled.

skip_exit_check

Optional keyword that applies only if partial unrolling is specified with factor=. The elimination of the exit check is dependent on whether the loop iteration count is known or unknown:

• Fixed bounds

  No exit condition check is performed if the iteration count is a multiple of the factor.

  If the iteration count is not an integer multiple of the factor, the tool:

  • Prevents unrolling.
  • Issues a warning that the exit check must be performed to proceed.
• Variable bounds

  The exit condition check is removed. You must ensure that:

  • The variable bounds is an integer multiple of the factor.
  • No exit check is in fact required.

Example 1

The following example fully unrolls loop_1 in function foo. Place the pragma in the body of loop_1 as shown.

loop_1: for(int i = 0; i < N; i++) {
  #pragma HLS unroll
  a[i] = b[i] + c[i];
}

Example 2

This example specifies an unroll factor of 4 to partially unroll loop_2 of function foo, and removes the exit check.

void foo (...) {
  int8 array1[M];
  int12 array2[N];
  ...
  loop_2: for(i=0;i<M;i++) {
    #pragma HLS unroll skip_exit_check factor=4
    array1[i] = ...;  
    array2[i] = ...;
    ...
  }
  ...
}

Example 3

The following example fully unrolls all loops inside loop_1 in function foo, but not loop_1 itself because the presence of the region keyword.

void foo(int data_in[N], int scale, int data_out1[N], int data_out2[N]) {
  int temp1[N];
  loop_1: for(int i = 0; i < N; i++) {  
    #pragma HLS unroll region
    temp1[i] = data_in[i] * scale;
      loop_2: for(int j = 0; j < N; j++) {
        data_out1[j] = temp1[j] * 123;
      }
      loop_3: for(int k = 0; k < N; k++) {
        data_out2[k] = temp1[k] * 456;
      }
  }
}

See Also

• set_directive_unroll
• pragma HLS loop_flatten
• pragma HLS loop_merge