HLS Pragmas

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, theVivadoHigh-Level Synthesis (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:Leaving this option out of the pragma enables expression balancing, which is the default mode.

Example 1

This example explicitly enables expression balancing in functionmy_Func:

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

Example 2

Disables expression balancing within functionmy_Func:

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

See Also

• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

The FUNCTION_INSTANTIATE pragma is an optimization technique that has the area benefits of maintaining the function hierarchy but provides an additional powerful option: performing targeted local optimizations on specific instances of a function. This can simplify the control logic around the function call and potentially improve latency and throughput.

By default:

• Functions remain as separate hierarchy blocks in the register transfer level (RTL).
• All instances of a function, at the same level of hierarchy, make use of a single RTL implementation (block).

The FUNCTION_INSTANTIATE pragma is used to create a unique RTL implementation for each instance of a function, allowing each instance to be locally optimized according to the function call. This pragma exploits the fact that some inputs to a function may be a constant value when the function is called, and uses this to both simplify the surrounding control structures and produce smaller more optimized function blocks.

Without the FUNCTION_INSTANTIATE pragma, the following code results in a single RTL implementation of functionfoo_subfor all three instances of the function infoo. Each instance of functionfoo_subis implemented in an identical manner. This is fine for function reuse and reducing the area required for each instance call of a function, but means that the control logic inside the function must be more complex to account for the variation in each call offoo_sub.

char foo_sub(char inval, char incr) { #pragma HLS function_instantiate variable=incr return inval + incr; } void foo(char inval1, char inval2, char inval3, char *outval1, char *outval2, char * outval3) { *outval1 = foo_sub(inval1, 1); *outval2 = foo_sub(inval2, 2); *outval3 = foo_sub(inval3, 3); }

In the code sample above, the FUNCTION_INSTANTIATE pragma results in three different implementations of functionfoo_sub, each independently optimized for theincrargument, reducing the area and improving the performance of the function. After FUNCTION_INSTANTIATE optimization,foo_subis effectively be transformed into three separate functions, each optimized for the specified values ofincr.

Syntax

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

#pragma HLS function_instantiate variable=

Where:

• variable=: A required argument that defines the function argument to use as a constant.

Example 1

In the following example, the FUNCTION_INSTANTIATE pragma placed in functionswInt) allows each instance of functionswIntto be independently optimized with respect to themaxvfunction argument:

void swInt(unsigned int *readRefPacked, short *maxr, short *maxc, short *maxv){ #pragma HLS function_instantiate variable=maxv uint2_t d2bit[MAXCOL]; uint2_t q2bit[MAXROW]; #pragma HLS array partition variable=d2bit,q2bit cyclic factor=FACTOR intTo2bit((readRefPacked + MAXROW/16), d2bit); intTo2bit(readRefPacked, q2bit); sw(d2bit, q2bit, maxr, maxc, maxv); }

See Also

• pragma HLS allocation
• pragma HLS inline
• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

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 register transfer level (RTL). In some cases, inlining a function allows operations within the function to be shared and optimized more effectively with surrounding operations. An inlined function cannot be shared. This can increase 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 may be automatically inlined, or inlined as part of a region or recursion.

INLINE REGION

This 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

This 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, therecursiveoption 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 

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. Therecursiveoption inlines all functions recursively within the specified function or region.
• off: Disables function inlining to prevent specified functions from being inlined. For example, ifrecursiveis specified in a function, this option can prevent a particular called function from being inlined when all others are.
  TIP:The VivadoHigh-Level Synthesis (HLS) tool automatically inlines small functions, and using the INLINE pragma with the offoption may 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 offoo_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 offoo_top, inlining recursively down through the function hierarchy, except functionfoo_subis not inlined. The recursive pragma is placed in functionfoo_top. The pragma to disable inlining is placed in the functionfoo_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 thecopy_outputfunction into any functions or regions callingcopy_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

• pragma HLS allocation
• pragma HLS function_instantiate
• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

In C-based design, all input and output operations are performed, in zero time, through formal function arguments. In a register transfer level (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, refer to "Managing Interfaces" in theVivado Design Suite User Guide: High-Level Synthesis(UG902).

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:

• Any function-level protocol that is specified: Function-level protocols, also called 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 thevaluesap_ctrl_none,ap_ctrl_hsorap_ctrl_chain. Theap_ctrl_hsblock-level I/O protocol is the default.
  • Are 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 theExamplesbelow.

When the INTERFACE pragma is used on sub-functions, only theregisteroption can be used. The option is not supported on sub-functions.

Specifying Burst Mode

When specifying burst-mode for interfaces, using themax_read_burst_lengthormax_write_burst_lengthoptions (as described in theSyntaxsection) 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 (i.e. 32, 64, 128, 256, 512 bits) or in bytes: 4, 8, 16, 32, 64.

With the 4KB limit, the max burst length for a bus width of:

• 32-bits is 256 words transferred in a single burst transaction. In this case, the total bytes transferred per transaction would be 1024.
• 64-bits is 256 words transferred in a single burst transaction. The total bytes transferred per transaction would be 2048.
• 128-bits is 256 words transferred in a single burst transaction. The total bytes transferred per transaction would be 4096.
• 256-bits is 128 words transferred in a single burst transaction. The total bytes transferred per transaction would be 4096.
• 512-bits is 64 words transferred in a single burst transaction. The total bytes transferred per transaction would be 4096.

Syntax

Place the pragma within the boundaries of the function.

#pragma HLS interface  port= bundle= \ register register_mode= depth= offset= \ clock= name= \ num_read_outstanding= num_write_outstanding= \ max_read_burst_length= max_write_burst_length=

Where:

• : Specifies the interface protocol mode for function arguments, global variables used by the function, or the block-level control protocols. For detailed descriptions of these different modes see "Interface Synthesis Reference" in theVivado Design Suite User Guide: High-Level Synthesis(UG902). 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 associatedvalidport to indicate when the data is valid for reading or writing.
  • ap_ack: Implements the data port with an associatedacknowledgeport to acknowledge that the data was read or written.
  • ap_hs: Implements the data port with associatedvalidandacknowledgeports 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 associatedvalidport 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 FIFOemptyandfullports.
    Note:You can only use this interface on read arguments or write arguments. The ap_fifomode does not support bidirectional read/write arguments.
  • ap_bus: Implements pointer and pass-by-reference ports as a bus interface.
  • ap_memory: Implements array arguments as a standard RAM interface. If you use the RTL design in theVivadoIP integrator, the memory interface appears as discrete ports.
  • bram: Implements array arguments as a standard RAM interface. If you use the RTL design in theIP integrator, the memory interface appears as a single port.
  • axis: Implements all ports as anAXI4-Streaminterface.
  • s_axilite: Implements all ports as anAXI4-Liteinterface. The HLS tool produces an associated set of C driver files during the Export RTL process.
  • m_axi: Implements all ports as anAXI4interface. You can use theconfig_interfacecommand to specify either 32-bit (default) or 64-bit address ports and to control any address offset.
  • ap_ctrl_none: No block-level I/O protocol.
    Note:Using the ap_ctrl_nonemode might prevent the design from being verified using the C/RTL co-simulation feature.
  • ap_ctrl_hs: Implements a set of block-level control ports tostartthe design operation and to indicate when the design isidle,done, andreadyfor new input data.
    Note:The ap_ctrl_hsmode is the default block-level I/O protocol.
  • ap_ctrl_chain: Implements a set of block-level control ports tostartthe design operation,continueoperation, and indicate when the design isidle,done, andreadyfor new input data.
    Note:The ap_ctrl_chaininterface mode is similar to ap_ctrl_hsbut provides an additional input signal ap_continueto apply back pressure. Xilinxrecommends using the ap_ctrl_chainblock-level I/O protocol when chaining the HLS tool blocks together.
• port=: Specifies the name of the function argument, function return, or global variable which theINTERFACEpragma 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 returnvalue.
• bundle=: Groups function arguments into AXI interface ports. By default, the HLS tool groups all function arguments specified as anAXI4-Lite(s_axilite) interface into a singleAXI4-Liteport. Similarly, all function arguments specified as anAXI4(m_axi) interface are grouped into a singleAXI4port. This option explicitly groups all interface ports with the samebundle=into the same AXI interface port and names the RTL port the value specified by .
  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_iooption of the config_interfacecommand globally controls registering all inputs/outputs on the top function. Refer to the Vivado Design Suite User Guide: High-Level Synthesis(UG902)for more information.
• register_mode= : Used with theregisterkeyword, this option specifies if registers are placed on theforwardpath (TDATA and TVALID), thereversepath (TREADY), onbothpaths (TDATA, TVALID, and TREADY), or if none of the port signals are to be registered (off). The defaultregister_modeisboth.AXI4-Stream(axis) side-channel signals are considered to be data signals and are registered whenever the TDATA is registered.
• depth=: 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 depthis usually an option, it is required for m_axiinterfaces.
• offset=: Controls the address offset inAXI4-Lite(s_axilite) andAXI4(m_axi) interfaces.
  • For thes_axiliteinterface, specifies the address in the register map.
  • For them_axiinterface, specifies on of the following values:
    • direct: Generate a scalar input offset port.
    • slave: Generate an offset port and automatically map it to anAXI4-Liteslave interface.
    • off: Do not generate an offset port.
    TIP:The -m_axi_offsetoption of the config_interfacecommand globally controls the offset ports of all M_AXI interfaces in the design.
• clock=: Optionally specified only for interface modes_axilite. This defines the clock signal to use for the interface. By default, theAXI4-Liteinterface clock is the same clock as the system clock. This option is used to specify a separate clock for theAXI4-Lite(s_axilite) interface.
  TIP:If the bundleoption is used to group multiple top-level function arguments into a single AXI4-Liteinterface, the clock option need only be specified on one of the bundle members.
• latency=: Whenmodeism_axi, this specifies the expected latency of theAXI4interface, allowing the design to initiate a bus request a number of cycles (latency) before the read or write is expected. If this figure it too low, the design will be ready too soon and may stall waiting for the bus. If this figure is too high, bus access may be granted but the bus may stall waiting on the design to start the access.
• num_read_outstanding=: ForAXI4(m_axi) interfaces, this option specifies how many read requests can be made to theAXI4bus, 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=: ForAXI4(m_axi) interfaces, this option specifies how many write requests can be made to theAXI4bus, 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=: ForAXI4(m_axi) interfaces, this option specifies the maximum number of data values read during a burst transfer.
• max_write_burst_length=: ForAXI4(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=1and max_write_burst_length=2to conserve memory resources. For write-only ports, set the num_read_outstanding=1and max_read_burst_length=2.
• name=: This option is used to rename the port based on your own specification. The generated RTL port will use this name.

Example 1

In this example, both function arguments are implemented using anAXI4-Streaminterface:

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 argumentInDatais specified to use theap_vldinterface, and also indicates the input should be registered:

#pragma HLS interface ap_vld register port=InData

This exposes the global variablelookup_tableas a port on the RTL design, with anap_memoryinterface:

pragma HLS interface ap_memory port=lookup_table

Example 3

This example defines the INTERFACE standards for the ports of the top-leveltransposefunction. Notice the use of thebundle=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

• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

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

In the register transfer level (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: Is an optional keyword that prevents flattening from taking place. Can prevent some loops from being flattened while all others in the specified location are flattened.
  Note:The presence of the LOOP_FLATTEN pragma enables the optimization.

Example 1

Flattensloop_1in functionfooand all (perfect or semi-perfect) loops above it in the loop hierarchy, into a single loop. Place the pragma in the body ofloop_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 inloop_1:

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

See Also

• pragma HLS loop_merge
• pragma HLS loop_tripcount
• pragma HLS unroll
• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

Merge 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 register transfer level (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, theVivadoHigh-Level Synthesis (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: An optional keyword to force loops to be merged even when the HLS tool issues a warning.
  IMPORTANT:In this case, you must manually insure that the merged loop will function correctly.

Examples

Merges all consecutive loops in functionfoointo a single loop.

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

All loops insideloop_2(but notloop_2itself) are merged by using theforceoption. Place the pragma in the body ofloop_2.

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

See Also

• pragma HLS loop_flatten
• pragma HLS loop_tripcount
• pragma HLS unroll
• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

The LOOP_TRIPCOUNT pragma can be applied to a loop to manually specify the total number of iterations performed by a loop.

TheVivadoHigh-Level Synthesis (HLS) tool reports the total latency of each loop, which is the number of clock cycles to execute all iterations of the loop. The loop latency is therefore a function of the number of loop iterations, or tripcount.

The tripcount can be a constant value. It may 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 and maximum iterations for a loop. This allows 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= max= avg=

Where:

• max=: Specifies the maximum number of loop iterations.
• min=: Specifies the minimum number of loop iterations.
• avg=: Specifies the average number of loop iterations.

Examples

In the following example,loop_1in functionfoois 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

• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

When pipelining functions or loops, the OCCURRENCE pragma specifies that the code in a region is executed less frequently than the code in the enclosing function or loop. This allows the code that is executed less often to be pipelined at a slower rate, and potentially shared within the top-level pipeline. To determine the OCCURRENCE:

• A loop iterates times.
• However, part of the loop body is enabled by a conditional statement, and as a result only executes times, where is an integer multiple of .
• The conditional code has an occurrence that is N/M times slower than the rest of the loop body.

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=

Where:

• cycle=: Specifies the occurrence N/M:
  • is the number of times the enclosing function or loop is executed.
  • is the number of times the conditional region is executed.
    IMPORTANT: must be an integer multiple of .

Examples

In this example, the regionCond_Regionhas 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

• pragma HLS pipeline
• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

The PIPELINE pragma reduces the initiation interval (II) for a function or loop by allowing the concurrent execution of operations.

A pipelined function or loop can process new inputs every clock cycles, where 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.

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

Figure:Loop Pipeline

If theVivadoHigh-Level Synthesis (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.

Syntax

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

#pragma HLS pipeline II= enable_flush rewind

Where:

• II=: 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.
• enable_flush: Optional keyword that implements a pipeline that will flush and empty if the data valid at the input of the pipeline goes inactive.
  TIP:This feature is only supported for pipelined functions: it is not supported for pipelined loops.
• rewind: Optional keyword that 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 functionfoois pipelined with an initiation interval of 1:

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

See Also

• pragma HLS dependence
• xcl_pipeline_loop
• Vivado Design Suite User Guide: High-Level Synthesis(UG902)
• SDAccel Environment Profiling and Optimization Guide

Description

The RESET pragma adds or removes resets for specific state variables (global or static).

The reset port is used in an FPGA to restore the registers and block RAM connected to the reset port to an initial value any time the reset signal is applied. The presence and behavior of the register transfer level (RTL) reset port is controlled using theconfig_rtlconfiguration file. 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. See "Clock, Reset, and RTL Output" in theVivado Design Suite User Guide: High-Level Synthesis(UG902)for more information.

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 turningoffthe 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= off

• variable=: Specifies the variable to which the pragma is applied.
• off: Indicates that reset is not generated for the specified variable.

Description

The RESOURCE pragma specifies that a specific library resource (core) is used to implement a variable (array, arithmetic operation, or function argument) in the register transfer level (RTL). If the RESOURCE pragma is not specified, theVivadoHigh-Level Synthesis (HLS) tool determines the resource to use. The HLS tool implements the operations in the code using hardware cores. When multiple cores in the library can implement the operation, you can specify which core to use with the RESOURCE pragma. To generate a list of available cores, use thelist_corecommand.

For example, to specify which memory element in the library to use to implement an array, use the RESOURCE pragma. This allows you control whether the array is implemented as a single or a dual-port RAM, or in UltraRAM. This usage is important for arrays on the top-level function interface, because the memory type associated with the array determines the ports needed in the RTL.

You can use thelatency=option to specify the latency of the core. For block RAMs on the interface, thelatency=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, thelatency=option allows the operation to be implemented using more pipelined stages. These additional pipeline stages can help resolve timing issues during RTL synthesis.

For more information, see "Arrays on the Interface" in theVivado Design Suite User Guide: High-Level Synthesis(UG902).

For best results,Xilinxrecommends that you use-std=c99for C and-fno-builtinfor C and C++. To specify the C compile options, such as-std=c99, use the Tcl commandadd_fileswith the-cflagsoption. Alternatively, select theEdit CFLAGsbutton in the Project Settings dialog box. See "Creating a New Synthesis Project" in theVivado Design Suite User Guide: High-Level Synthesis(UG902).

Syntax

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

#pragma HLS resource variable= core=\ latency=

Where:

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

Example 1

In the following example, a two-stage pipelined multiplier is specified to implement the multiplication for variable of the functionfoo. The HLS tool selects the core to use for variable .

int foo (int a, int b) { int c, d; #pragma HLS RESOURCE variable=c latency=2 c = a*b; d = a*c; return d; }

Example 2

In the following example, the variable is an argument to the top-level functionfoo_top. This example specifies thatcoeffsis implemented with core RAM_1P from the library:

#pragma HLS resource variable=coeffs core=RAM_1P

See Also

Description

The STABLE pragma marks variables within a DATAFLOW region as being stable. The STABLE pragma applies to both scalar and array variables whose content can be either written or read by the process inside the DATAFLOW region. This pragma eliminates the extra synchronization involved for the DATAFLOW region.

Syntax

Place the pragma in the C source within the boundaries of a region, function, or loop that is also marked for DATAFLOW.

#pragma HLS stable variable=

Where:

• variable=: Specifies the name of a variable within the DATAFLOW region.

Examples

The following example specifies the array A as stable. If A is read by proc2, then it will not be written by another process while the DATAFLOW region is being executed.

void foo(int A[...], int B[…] ... #pragma HLS dataflow #pragma HLS stable variable=A proc1(...); proc2(A, ...);

See Also

• pragma HLS dataflow
• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

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.
• In sub-functions involved inDATAFLOWoptimizations, the array arguments are implemented using a RAM ping pong buffer channel.
• Arrays involved in 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= depth= dim= off

Where:

• variable=: Specifies the name of the array to implement as a streaming interface.
• depth=: 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 and specify a different depth.

  When the array is implemented in a DATAFLOW region, it is common to the use thedepth=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, thedepth=option may be used to reduce the FIFO size to 1 to substantially reduce the area of the RTL design.

  TIP:The config_dataflow -depthcommand provides the ability to stream all arrays in a DATAFLOWregion. The depth=option specified here overrides the config_dataflowcommand for the assigned .
• dim=: Specifies the dimension of the array to be streamed. The default is dimension 1. Specified as an integer from 0 to , for an array with dimensions.
• off: Disables streaming data. Relevant only for array streaming in dataflow channels.
  TIP:The config_dataflow -default_channel fifocommand globally implies a STREAMpragma on all arrays in the design. The offoption specified here overrides the config_dataflowcommand for the assigned variable, and restores the default of using a RAM ping pong buffer based channel.

Example 1

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

#pragma HLS STREAM variable=A

Example 2

In this example arrayBis set to streaming with a FIFO depth of 12:

#pragma HLS STREAM variable=B depth=12

Example 3

Array C has streaming disabled. In the below example, it is assumed to be enabled byconfig_dataflow:

#pragma HLS STREAM variable=C off

See Also

• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

The STABLE pragma marks variables within a DATAFLOW region as being stable. The STABLE pragma applies to both scalar and array variables whose content can be either written or read by the process inside the DATAFLOW region. This pragma eliminates the extra synchronization involved for the DATAFLOW region.

Syntax

Place the pragma in the C source within the boundaries of a region, function, or loop that is also marked for DATAFLOW.

#pragma HLS stable variable=

Where:

• variable=: Specifies the name of a variable within the DATAFLOW region.

Examples

The following example specifies the array A as stable. If A is read by proc2, then it will not be written by another process while the DATAFLOW region is being executed.

void foo(int A[...], int B[…] ... #pragma HLS dataflow #pragma HLS stable variable=A proc1(...); proc2(A, ...);

See Also

• pragma HLS dataflow
• Vivado Design Suite User Guide: High-Level Synthesis(UG902)

Description

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 register transfer level (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,breakconditions 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 , to create copies of the loop body and reduce the loop iterations accordingly. To unroll a loop completely, the loop bounds must be known at compile time. This is not required for partial unrolling.

Partial loop unrolling does not require to be an integer factor of the maximum loop iteration count. TheVivadoHigh-Level-Synthesis (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]; }

Because the maximum iteration count is a variable, the HLS tool might not be able to determine its value and so 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 , theskip_exit_checkoption 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= region skip_exit_check

Where:

• factor=: 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. Iffactor=is not specified, the loop is fully unrolled.
• region: An optional keyword that unrolls all loops within the body (region) of the specified loop, without unrolling the enclosing loop itself.
• skip_exit_check: An optional keyword that applies only if partial unrolling is specified withfactor=. The elimination of the exit check is dependent on whether the loop iteration count is known or unknown:
  • Fixed (known) 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:
    1. Prevents unrolling.
    2. Issues a warning that the exit check must be performed to proceed.
  • Variable (unknown) bounds: The exit condition check is removed as requested. You must ensure that:
    1. The variable bounds is an integer multiple of the specified unroll factor.
    2. No exit check is in fact required.

Example 1

The following example fully unrollsloop_1in functionfoo. Place the pragma in the body ofloop_1as 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 unrollloop_2of functionfoo, and removes the exit check:

void foo (...) { int8 array1[M]; int12 array2[N]; ... loop_2: for(i=0;i