1. SmartHLS Pragmas Manual¶

SmartHLS accepts pragma directives in the source code to guide the hardware generation. This reference section explains all of the pragmas available for SmartHLS.

The pragmas follow the following syntax:

#pragma HLS <category> <feature> <parameter>(<value>)

The category refers to the general usage class of the pragma. Each pragma has one of the following categories:

function: configure a hardware function.

loop: configure loop optimizations.

interface: configure hardware interfaces (arguments / global variables).

memory: configure hardware memory implementation.

Each category can have different configurable features. Some categories / features have parameters to passed to the pragma. A parameter can be optional with a default behaviour if not specified.

The value of a parameter can be either integer, boolean (true|false), name (variable / argument), or a set of pre-specified values.

Note

For integer parameters, the user is allowed to use constants (or expressions of constants) defined using #define directive. For example, this is allowed:

#define N 10
void fun() {
  #pragma HLS loop unroll factor(N+1)
  for (int i = 0; i < 100; i++)
    ...
}

The pragma position is not arbitrary and placing the pragma in an incorrect position will cause an error. Each pragma can has one of the following positions:

At the beginning of function definition block before any other statements.

Before global / local variable declaration.

Before loop block.

1.1. Set Custom Top-Level Function¶

Syntax

#pragma HLS function top

Description

This pragma specifies the top-level C/C++ function. The top-level function and all of its descendant functions will be compiled to hardware.

Position

At the beginning of the function definition block.

Examples

int sum(int *a) {
#pragma HLS function top
  ...
}

1.2. Pipeline Function¶

Syntax

#pragma HLS function pipeline II(<int>)

Description

This pragma enables pipelining for a given function in the code. Function pipelining allows a new invocation of a function to begin before the current one has completed, achieving higher throughput. Optional arguments:

Parameters

Parameter	Value	Optional	Default	Description
`II`	Integer	Yes	1	Pipeline initiation interval

Position

At the beginning of the function definition block.

Examples

int sum(int *a) {
#pragma HLS function pipeline
  ...
}

int conv(int a[], int b[]) {
#pragma HLS function pipeline II(3)
  ...
}

1.3. Inline Function¶

Syntax

#pragma HLS function inline

Description

This pragma forces a given function to be inlined.

Position

At the beginning of the function definition block.

Examples

int sum(int *a) {
#pragma HLS function inline
  ...
}

1.4. Noinline Function¶

Syntax

#pragma HLS function noinline

Description

This pragma prevents a given function from being inlined.

Position

At the beginning of the function definition block.

Examples

int sum(int *a) {
#pragma HLS function noinline
  ...
}

1.5. Flatten Function¶

Syntax

#pragma HLS function flatten

Description

This pragma unrolls all loops and inlines all subfunctions for a given function.

Position

At the beginning of the function definition block.

Examples

int sum(int *a) {
#pragma HLS function flatten
  ...
}

1.6. Replicate Function¶

Syntax

#pragma HLS function replicate

Description

This pragma specifies a function to be replicated every time it is called. By default, when the circuit is not pipelined, SmartHLS creates a single instance for each function which is shared across multiple calls to the function. When using this pragma on the function, SmartHLS will create a new instance of the function for every function call.

Position

At the beginning of the function definition block.

Examples

int sum(int *a) {
#pragma HLS function replicate
  ...
}

1.7. Pipeline Loop¶

Syntax

#pragma HLS loop pipeline II(<int>)

Description

This pragma enables pipelining for a given loop in the code. Loop pipelining allows a new iteration of the loop to begin before the current one has completed, achieving higher throughput. It can be specified to pipeline a single loop or a nested loop. If specified on a single loop or on a inner loop of a nested loop, that loop will be pipelined. If specified on the outer loop of a nested loop, the outer loop will be pipelined and all of its inner loops will be automatically unrolled.

Parameters

Parameter	Value	Optional	Default	Description
`II`	Integer	Yes	1	Pipeline initiation interval

Position

Before the beginning of the loop. If there is a loop label, the pragma should be placed after the label.

Examples

#pragma HLS loop pipeline II(2)
for (int i = 0; i < 10; i++) {
  ...
}

LOOP_LABEL:
#pragma HLS loop pipeline
while (i < 10) {
  ...
}

1.8. Unroll Loop¶

Syntax

#pragma HLS loop unroll factor(<int>)

Description

Specifies a loop to be unrolled.

Parameters

The factor indicates how many times to unroll the loop. If it is not specified, or specified as N (the total number of loop iterations), the loop will be fully unrolled. If it is specified as 2, the loop will be unrolled 2 times, where the number of loop iterations will be halved and the loop body will be replicated twice. If it is specified as 1, the loop will NOT be unrolled.

Parameter	Value	Optional	Default	Description
`factor`	Integer	Yes	N (fully unroll)	Unroll count

Position

Before the beginning of the loop.

Note

If there is a loop label, the pragma should be placed after the label.

Examples

Fully unroll a loop.

#pragma HLS loop unroll
for (int i = 0; i < 10; i++) {
  ...
}

Unroll the loop by 2 times only.

LOOP_LABEL:
#pragma HLS loop unroll factor(2)
while (i < 10) {
  ...
}

Small loops may be unrolled even without the unroll pragma. Make sure the loop is not unrolled.

#pragma HLS loop unroll factor(1)
for (int i = 0; i < 10; i++) {
  ...
}

1.9. Configure Scalar Argument Interface¶

Syntax

#pragma HLS interface argument(<arg_name>) type(simple) stable(<false|true>)

Description

This pragma configures the scalar input port. The stable option informs SmartHLS that the port can be held valid and unchanged throughout the whole iteration of the execution and potentially can save register usage in the generated module. Note that the type option is not configurable in the current release but still needs to be specified if you wish to add the stable option. If ‘stable’ is false, the pragma is not necessary because SmartHLS assumes not stable by default. More details in Top-Level RTL Interface section.

Parameters

Parameter	Type	Optional	Default	Description
`argument`	String	No		Argument name
`type`	`simple`	No		Interface type
`stable`	`true\|false`	Yes	`false`	`true` if the argument is stable

Position

At the beginning of the function definition block.

Examples

int fun(int a) {
#pragma HLS interface argument(a) type(simple) stable(true)
  ...
}

1.10. Configure Argument as Memory Interface¶

Syntax

#pragma HLS interface argument(<arg_name>) type(memory) num_elements(<int>)

Description

This pragma specifies the memory interface type for an array/struct argument. The array size can be specified or overridden (over the declared size in C++) by specifying the num_elements option. More details in Top-Level RTL Interface section.

Parameters

Parameter	Type	Optional	Description
`argument`	String	No	Argument name
`type`	`memory`	No	Interface type
`num_elements`	Integer	Yes	Specifies the number of elements of the argument array. Can override the array size in the argument.

Position

At the beginning of the function definition block.

Examples

int fun(int a[], int b[]) {
#pragma HLS interface argument(a) type(memory) num_elements(100)
#pragma HLS interface argument(b) type(memory)
  ...
}

1.11. Configure Global Variable as Memory Interface¶

Syntax

#pragma HLS interface variable(<var_name>) type(memory) num_elements(<int>)

Description

This pragma specifies the memory interface type for a shared array/struct global variable. The array size can be specified or overridden (over the declared size in C++) by specifying the num_elements option. More details in Top-Level RTL Interface section.

Parameters

Parameter	Type	Optional	Description
`varaible`	String	No	Variable name
`type`	`memory`	No	Interface type
`num_elements`	Integer	Yes	Specifies the number of elements of the variable array. Can override the array size of the variable.

Position

Before the global variable declaration.

Examples

#pragma HLS interface variable(b) type(memory) num_elements(100)
int b[100];

int fun() {
  ...
}

1.12. Configure Argument as Scalar Memory Interface¶

Syntax

#pragma HLS interface argument(<arg_name>) type(memory) num_elements(<int>)

Description

This pragma specifies the scalar memory interface for an argument. The scalar memory interface is used by SmartHLS module to access external memory that has only one element. More details in Top-Level RTL Interface section.

Parameters

Parameter	Type	Optional	Description
`argument`	String	No	Argument name
`type`	`scalar_memory`	No	Interface type
`num_elements`	Integer	Yes	Specifies the number of elements of the argument array. Can override the array size in the argument.

Position

At the beginning of the function definition block.

Examples

int fun(int a[]) {
#pragma HLS interface argument(b) type(scalar_memory) num_elements(100)
  ...
}

1.13. Configure Global Variable as Scalar Memory Interface¶

Syntax

#pragma HLS interface variable(<var_name>) type(scalar_memory)

Description

This pragma specifies the scalar memory interface for a shared global variable. The scalar memory interface is used by SmartHLS module to access external memory that has only one element. More details in Top-Level RTL Interface section.

Parameters

Parameter	Type	Optional	Default	Description
`variable`	String	No		Variable name
`type`	`scalar_memory`	No		Interface type

Position

Before the global variable declaration.

Examples

#pragma HLS interface variable(b) type(scalar_memory)
int b[SIZE];

1.14. Configure Global as AXI4 Interface¶

Syntax

#pragma HLS interface variable(<var_name>) type(axi_slave) concurrent_access(true|false)

Description

This pragma specifies an AXI4 slave interface. When the concurrent_access option is set to true (default to false), the external logic can read/write the AXI4 slave interface while the SmartHLS module is running. The concurrent access will however reduce the SmartHLS module’s throughput to access the memory. More details in Top-Level RTL Interface section.

Parameters

Parameter	Value	Optional	Default	Description
`variable`	String	No		Variable name
`type`	`axi_slave`	No		Interface type
`concurrent_access`	`true\|false`	Yes	`false`	Enable/disable concurrent access

Position

Before the global variable declaration.

Examples

#pragma HLS interface variable(b) type(axi_slave) concurrent_access(true)
int b[SIZE];

1.15. Partition Memory¶

Syntax

#pragma HLS memory partition variable`(<arg_name>) type(complete|none) dim(<int>)

Description

This pragma specifies a variable to be partitioned. Dimension 0 corresponds to the right-most dimension of an array and higher dimensions correspond to leftward dimensions.

Parameters

Parameter	Value	Optional	Default	Description
`variable`	String	No		Variable name
`type`	`complete\|none`	Yes	`complete`	Partition type
`dim`	Integer	Yes	0	Partition dimension

Position

Before the global / local variable declaration.

Examples

#pragma HLS memory partition variable(b) type(none)
int b[100];

int fun(int *a) {
  ...
  #pragma HLS memory partition variable(c) dim(1)
  int c[100][100];
  ...
}

1.16. Partition Top-Level Interface¶

Syntax

#pragma HLS memory partition argument(<arg_name>) type(complete|none) dim(<int>)

Description

This pragma specifies a top-level argument to be partitioned. Dimension 0 corresponds to the right-most dimension of an array and higher dimensions correspond to leftward dimensions. Note that this only applies to top level functions.

Parameters

Parameter	Value	Optional	Default	Description
`argument`	String	No		Argument name
`type`	`complete\|none`	Yes	`complete`	Partition type
`dim`	Integer	Yes	0	Partition dimension

Position

At the beginning of the function definition block.

Examples

int sum(int *a, int *b) {
#pragma HLS function top
#pragma HLS memory partition argument(a) type(none)
#pragma HLS memory partition argument(b)
}

1.17. Contention-Free Memory Access¶

Syntax

#pragma HLS memory impl variable(<arg_name>) contention_free(true|false)

Description

The pragma is to be used for variables accessed by parallel functions (hls::thread) so that SmartHLS does not create arbiters for the specified variable. The specified variable can still be accessed by multiple concurrently running functions, but without contention. It will be the users’ responsibility to ensure at most one function may access the shared variable in a clock cycle. If not specified, by default, SmartHLS creates arbiters for variables that are accessed by parallel functions.

Parameters

Parameter	Value	Optional	Default	Description
`variable`	String	No		Variable name
`contention_free`	`true - false`	Yes	`false`	`true` for contention-free access

Position

Before the global / local variable declaration.

Examples

#pragma HLS memory impl variable(b) contention_free(true)
int b[100];