In this publication, <quartus_installdir> refers to the location where you installed Intel^® Quartus^® Prime Design Suite. The Intel^® High Level Synthesis (HLS) Compiler is installed as part of your Intel^® Quartus^® Prime Design Suite installation.

With the Intel^® High Level Synthesis Compiler, your component can have a variety of interfaces: from basic wires to the Avalon Streaming and Avalon Memory-Mapped Master interfaces. Review the interface best practices to help you choose and configure the right interface for your component.

Each interface type supported by the Intel^® HLS Compiler has different benefits. However, the system that surrounds your component might limit your choices. Keep your requirements in mind when determining the optimal interface for your component.

<quartus_installdir>/hls/examples/tutorials

Add a restrict type qualifier to pointer types whenever possible. By having restrict-qualified pointers, you prevent the Intel^® HLS Compiler from creating unnecessary memory dependencies between nonconflicting read and write operations.

Consider a loop where each iteration reads data from one array, and then it writes data to another array in the same physical memory. Without adding the restrict type qualifier to these pointer arguments, the compiler must assume that the two arrays overlap. Therefor, the compiler must keep the original order of memory accesses to both arrays, resulting in poor loop optimization or even failure to pipeline the loop that contains the memory accesses.

<quartus_installdir>/hls/examples/tutorials/best_practices/parameter_aliasing

Loops are a useful way to re-use hardware. If your component function calls another function, the called function will be the top-level component. Calling a function multiple times results in hardware duplication.

int foo(int a)
{
    return 4 + sqrt(a) /
}

component
void myComponent()
{
  ...
  int x =
  x += foo(0);
  x += foo(1);
  x += foo(2);
  ...
}

component
void myComponent()
{
  ...
  int x = 0;
#pragma unroll 1
  for (int i = 0; i < 3; i++)
  {
    x += foo(i);
  }
  ...
}

You can learn more about reusing hardware and minimizing inlining be reviewing the resource sharing tutorial available in <quartus_installdir>/hls/examples/tutorials/best_practices/resource_sharing_filter.

The Intel^® HLS Compiler lets you know if there are any dependencies that prevent it from optimizing your loops. Try to eliminate these dependencies in your code for optimal component performance. You can also provide additional guidance to the compiler by using the available loop pragmas.

<quartus_installdir>/hls/examples/tutorials

You can take advantage of the spatial compute structure to accelerate the loops by having multiple iterations of a loop executing concurrently. To have multiple iterations of a loop execute concurrently, unroll loops when possible and structure your loops so that dependencies between loop iterations are minimized and can be resolved within one clock cycle.

Consider the following basic loop with three stages and three iterations. A loop stage is defined as the operations that occur in the loop within one clock cycle.

Figure 6. Basic loop with three stages and three iterations

If each stage of this loop takes one clock cycle to execute, then this loop has a latency of nine cycles.

The following figure shows the pipelining of the loop from Figure 6.

Figure 7. Pipelined loop with three stages and four iterations

The pipelined loop has a latency of five clock cycles for three iterations (and six cycles for four iterations), but there is no area tradeoff. During the second clock cycle, Stage 1 of the pipeline loop is processing iteration 2, Stage 2 is processing iteration 1, and Stage 3 is inactive.

This loop is pipelined with a loop initiation interval (II) of 1. An II of 1 means that there is a delay of 1 clock cycle between starting each successive loop iteration.

The Intel^® HLS Compiler attempts to pipeline loops by default, and loop pipelining is not subject to the same constant iteration count constraint that loop unrolling is.

Not all loops can be pipelined as well as the loop shown in Figure 7, particularly loops where each iteration depends on a value computed in a previous iteration.

For example, consider if Stage 1 of the loop depended on a value computed during Stage 3 of the previous loop iteration. In that case, the second (orange) iteration could not start executing until the first (blue) iteration had reached Stage 3. This type of dependency is called a loop-carried dependency.

In this example, the loop would be pipelined with II=3. Because the II is the same as the latency of a loop iteration, the loop would not actually be pipelined at all. You can estimate the overall latency of a loop with the following equation:

${\mathrm{latency}}_{\mathrm{loop}}=(\mathrm{iterations}-1)*\mathrm{II}+{\mathrm{latency}}_{\mathrm{body}}$

where ${\mathrm{latency}}_{\mathrm{loop}}$ is the number of cycles the loop takes to execute and ${\mathrm{latency}}_{\mathrm{body}}$ is the number of cycles a single loop iteration takes to execute.

The Intel^® HLS Compilersupports pipelining nested loops without unrolling inner loops. When calculating the latency of nested loops, apply this formula recursively. This recursion means that having II>1 is more problematic for inner loops than for outer loops. Therefore, algorithms that do most of their work on an inner loop with II=1 still perform well, even if their outer loops have II>1.

Consider the following basic loop with three stages and three iterations. Each stage represents the operations that occur in the loop within one clock cycle.

Figure 8. Basic loop with three stages and three iterations

If each stage of this loop takes one clock cycle to execute, then this loop has a latency of nine cycles.

The following figure shows the loop from Figure 8 unrolled three times.

Figure 9. Unrolled loop with three stages and three iterations

Three iterations of the loop can now be completed in only three clock cycles, but three times as many hardware resources are required.

You can control how the compiler unrolls a loop with the #pragma unroll directive, but this directive works only if the compiler knows the trip count for the loop in advance or if you specify the unroll factor. In addition to replicating the hardware, the compiler also reschedules the circuit such that each operation runs as soon as the inputs for the operation are ready.

For an example of using the #pragma unroll directive, see the best_practices/resource_sharing_filter tutorial.

1.	#define ROWS 4
2.	#define COLS 4
3.	
4.	component void dut(...) {
5.		float a_matrix[COLS][ROWS]; // store in column-major format
6.		float r_matrix[ROWS][COLS]; // store in row-major format
7.	
8.		// setup...
9.	
10.		for (int i = 0; i < COLS; i++) {
11.			for (int j = i + 1; j < COLS; j++) {
12.	
13.				float dotProduct = 0;
14.				for (int mRow = 0; mRow < ROWS; mRow++) {
15.					dotProduct += a_matrix[i][mRow] * a_matrix[j][mRow];
16.				}
17.				r_matrix[i][j] = dotProduct;
18.			}
19.		}
20.	 	
21.	 // continue...
22.		
23.	}

You can improve the performance of this component by unrolling the loops that iterate across each entry of a particular column. If the loop operations are independent, then the compiler executes them in parallel.

Floating-point operations typically must be carried out in the same order that they are expressed in your source code to preserve numerical precision. However, you can use the --fp-relaxed compiler flag to relax the ordering of floating-point operations. With the order of floating-point operations relaxed, all of the multiplications in this loop can occur in parallel. To learn more, review the tutorial: <quartus_installdir>/hls/examples/ tutorials/best_practices/ floating_point_ops

The compiler tries to unroll loops on its own when it thinks unrolling improves performance. For example, the loop at line 14 is automatically unrolled because the loop has a constant number of iterations, and does not consume much hardware (ROWS is a constant defined at compile-time, ensuring that this loop has a fixed number of iterations).

01: #define ROWS 4
02: #define COLS 4
03: 
04: component void dut(...) {
05: 	float a_matrix[COLS][ROWS]; // store in column-major format
06: 	float r_matrix[ROWS][COLS]; // store in row-major format
07: 
08: 	// setup...
09: 
10: 	for (int i = 0; i < COLS; i++) {
11: 
12: #pragma unroll
13: 			for (int j = 0; j < COLS; j++) {
14: 				float dotProduct = 0;
15: 
16: #pragma unroll

17: 				for (int mRow = 0; mRow < ROWS; mRow++) {
18: 					dotProduct += a_matrix[i][mRow] * a_matrix[j][mRow];
19: 				}
20: 
21: 				r_matrix[i][j] = (j > i) ? dotProduct : 0; // predication
22: 			}
23: 		}
24:  	}
25:  	
26: 	// continue...
27: 	
28: }

Now the j-loop is fully unrolled. Because they do not have any dependencies, all four iterations run at the same time.

Refer to the resource_sharing_filter tutorial located at <quartus_installdir>/hls/examples/tutorials/best_practices/resource_sharing_filter for more details.

You could continue and also unroll the loop at line 10, but unrolling this loop would result in the area increasing again. By allowing the compiler to pipeline this loop instead of unrolling it, you can avoid increasing the area and pay about only four more clock cycles assuming that the i-loop only has an II of 1. If the II is not 1, the Details pane of the Loops Analysis page in the high level design report (report.html) gives you tips on how to improve it.

A well-formed loop has an exit condition that compares against an integer bound and has a simple induction increment of one per iteration. The Intel^® HLS Compiler can analyze well-formed loops efficiently, which can help improve the performance of your component.

for(int i=0; i < N; i++)
{
    //statements
}

Well-formed nested loops can also help maximize the performance of your component.

for(int i=0; i < N; i++)
{
   //statements
   for(int j=0; j < M; j++)
   {
      //statements
   }
}

If a loop in your component has complex exit conditions, memory accesses or complex operations might be required to evaluate the condition. Subsequent iterations of the loop cannot launch in the loop pipeline until the evaluation completes, which can decrease the overall performance of the loop.

To maximize performance, combine nested loops into a single loop whenever possible. The control flow for a loop adds overhead both in logic required and FPGA hardware footprint. Combining nested loops into a single loop reduces these aspects, improving the performance of your component.

The following code examples illustrate the conversion of a nested loop into a single loop:

for (i = 0; i < N; i++)
{
    //statements
    for (j = 0; j < M; j++)
    {
        //statements          
    }
    //statements
} 

for (i = 0; i < N*M; i++)
{
    //statements
}

You can also specify the loop_coalesce pragma to coalesce nested loops into a single loop without affecting the loop functionality. The following simple example shows how the compiler coalesces two loops into a single loop when you specify the loop_coalesce pragma.

#pragma loop_coalesce
for (int i = 0; i < N; i++)
 for (int j = 0; j < M; j++)
  sum[i][j] += i+j;

int i = 0;
int j = 0;
while(i < N){

  sum[i][j] += i+j;
  j++;
  
  if (j == M){
    j = 0;
    i++;
  }
}

For more information about the loop_coalesce pragma, see "Loop Coalescing (loop_coalesce Pragma)" in Intel^® High Level Synthesis Compiler Reference Manual.

To reduce the FPGA hardware resources necessary for implementing a variable, declare the variable just before you use it in a loop. Declaring variables in the deepest scope possible minimizes data dependencies and FPGA hardware usage because the Intel^® HLS Compiler does not need to preserve the variable data across loops that do not use the variables.

Consider the following example:

int a[N];
for (int i = 0; i < m; ++i)
{
    int b[N];
    for (int j = 0; j < n; ++j)
	{
        // statements
    }
}

The array a requires more resources to implement than the array b. To reduce hardware usage, declare array a outside the inner loop unless it is necessary to maintain the data through iterations of the outer loop.

In most cases, you can optimize the memory architecture by modifying the access pattern. However, the Intel^® HLS Compiler gives you some control over the memory architecture.

<quartus_installdir>/hls/examples/tutorials

Using memory attributes in various combinations in your code allows you to override the memory architecture that the Intel^® HLS Compiler infers for your component.

The following code examples demonstrate how you can use the following memory attributes to override coalesced memory to conserve memory blocks on your FPGA:

• hls_bankwidth(n)
• hls_numbanks(n)
• hls_singlepump
• hls_numports_readonly_writeonly(m,n)

The original code coalesces memory to 256 locations deep by 64 bits wide (256x64 bits), that is, two on-chip memory blocks:

component unsigned int mem_coalesce_default(unsigned int raddr,
                                    unsigned int waddr,
                                    unsigned int wdata){
    unsigned int data[512];
    data[2*waddr] = wdata;
    data[2*waddr + 1] = wdata + 1;
    unsigned int rdata = data[2*raddr] + data[2*raddr + 1];
    return rdata;
}

The following images show how the 256x64 bit memory for this code sample is structured, as well how the component memory structure is shown in the high-level design report (report.html)

Figure 10. Memory Structure Generated for mem_coalesce_default

The modified code implements a simple dual-port on-chip memory block that is 512 locations deep by 32 bits wide (512x32 bits) with stallable arbitration:

component unsigned int mem_coalesce_override(unsigned int raddr,
                                    unsigned int waddr,
                                    unsigned int wdata){
    //Attributes that stop memory coalescing
    hls_bankwidth(4) hls_numbanks(1)
    //Attributes that specify a simple dual port
    hls_singlepump hls_numports_readonly_writeonly(1,1)
    unsigned int data[512];
    data[2*waddr] = wdata;
    data[2*waddr + 1] = wdata + 1;
    unsigned int rdata = data[2*raddr] + data[2*raddr + 1];
    return rdata;
} 

The following images show how the 512x32 bit memory with stallable arbitration for this code sample is structured, as well how the component memory structure is shown in the high-level design report (report.html).

Figure 11. Memory Structure Generated for mem_coalesce_override

While it might appear that you save hardware area by reducing the number of RAM blocks needed for the component, the introduction of stallable arbitration causes the amount of hardware needed to implement the component to increase. In the following table, you can compare the number ALMs and FFs required by the components.

Using memory attributes in various combinations in your code allows you to override the memory architecture that the Intel^® HLS Compiler infers for your component.

The following code examples demonstrate how you can use the following memory attributes to override banked memory to conserve memory blocks on your FPGA:

• hls_bankwidth(n)
• hls_numbanks(n)
• hls_singlepump
• hls_doublepump

The original code creates two banks of single-pumped on-chip memory blocks that are 16 bits wide:

component unsigned short mem_banked(unsigned short raddr,
                                    unsigned short waddr,
                                    unsigned short wdata){
    unsigned short data[1024];
    
    data[2*waddr] = wdata;
    data[2*waddr + 9] = wdata +1;

    unsigned short rdata = data[2*raddr] + data[2*raddr + 9];

    return rdata;
}

To save banked memory, you can implement one bank of double-pumped 32-bit wide on-chip memory block by adding the following attributes before the declaration of data[1024]. These attributes fold the two half-used memory banks into one fully-used memory bank that is double-pumped, so that it can be accessed as quickly as the two half-used memory banks.

hls_bankwidth(2) hls_numbanks(1)
hls_doublepump
unsigned short data[1024];

Alternatively, you can avoid the double-clock requirement of the double-pumped memory by implementing one bank of single-pumped on-chip memory block by adding the following attributes before the declaration of data[1024]. However, in this example, these attributes add stallable arbitration to your component memories, which hurts your component performance.

hls_bankwidth(2) hls_numbanks(1)
hls_singlepump
unsigned short data[1024];

In some cases, you can save FPGA memory blocks by merging your component memories so that they consume fewer memory blocks, reducing the FPGA area your component uses. Use the hls_merge attribute to force the Intel^® HLS Compiler to implement different variables in the same memory system.

When you merge memories, multiple component variables share the same memory block. You can merge memories by width (width-wise merge) or depth (depth-wise merge). You can merge memories where the data in the memories have different datatypes.

Use the hls_merge("<mem_name>","depth") attribute to force the Intel^® HLS Compiler to implement variables in the same memory system, merging their memories by depth.

All variables with the same <mem_name> label set in their hls_merge attributes are merged.

Consider the following component code:

component int depth_manual(bool use_a, int raddr, int waddr, int wdata) {
  int a[128];
  int b[128];

  int rdata;

  // mutually exclusive write
  if (use_a) {
    a[waddr] = wdata;
  } else {
    b[waddr] = wdata;
  }

  // mutually exclusive read
  if (use_a) {
    rdata = a[raddr];
  } else {
    rdata = b[raddr];
  }

  return rdata;
}

The code instructs the Intel^® HLS Compiler to implement local memories a and b as two on-chip memory blocks, each with its own load and store instructions.

Because the load and store instructions for local memories a and b are mutually exclusive, you can merge the accesses, as shown in the example code below. Merging the memory accesses reduces the number of load and store instructions, and the number of on-chip memory blocks, by half.

component int depth_manual(bool use_a, int raddr, int waddr, int wdata) {
  int a[128] hls_merge("mem","depth");
  int b[128] hls_merge("mem","depth");

  int rdata;

  // mutually exclusive write
  if (use_a) {
    a[waddr] = wdata;
  } else {
    b[waddr] = wdata;
  }

  // mutually exclusive read
  if (use_a) {
    rdata = a[raddr];
  } else {
    rdata = b[raddr];
  }

  return rdata;
}

There are cases where merging local memories with respect to depth might degrade memory access efficiency. Before you decide whether to merge the local memories with respect to depth, refer to the HLD report ( <result>.prj/reports/report.html) to ensure that they have produced the expected memory configuration with the expected number of loads and stores instructions. In the example below, the Intel^® HLS Compiler should not merge the accesses to local memories a and b because the load and store instructions to each memory are not mutually exclusive.

component int depth_manual(bool use_a, int raddr, int waddr, int wdata) {
  int a[128] hls_merge("mem","depth");
  int b[128] hls_merge("mem","depth");

  int rdata;

  // NOT mutually exclusive write

  a[waddr] = wdata;
  b[waddr] = wdata;
  
  // NOT mutually exclusive read

  rdata = a[raddr];
  rdata += b[raddr];
  
  return rdata;
}

In this case, the Intel^® HLS Compiler might double pump the memory system to provide enough ports for all the accesses. Otherwise, the accesses must share ports, which prevent stall-free accesses.

Use the hls_merge("<mem_name>","width") attribute to force the Intel^® HLS Compiler to implement variables in the same memory system, merging their memories by width.

All variables with the same <mem_name> label set in their hls_merge attributes are merged.

Consider the following component code:

component short width_manual (int raddr, int waddr, short wdata) {

  short a[256];
  short b[256];

  short rdata = 0;
  
  // Lock step write
  a[waddr] = wdata;
  b[waddr] = wdata;

  // Lock step read 
  rdata += a[raddr];
  rdata += b[raddr];

  return rdata;
}

In this case, the Intel^® HLS Compiler can coalesce the load and store instructions to local memories a and b because their accesses are to the same address, as shown below.

component short width_manual (int raddr, int waddr, short wdata) {

  short a[256] hls_merge("mem","width");
  short b[256] hls_merge("mem","width");

  short rdata = 0;
  
  // Lock step write
  a[waddr] = wdata;
  b[waddr] = wdata;

  // Lock step read 
  rdata += a[raddr];
  rdata += b[raddr];

  return rdata;
}

The (b0, b1, ... ,bn) arguments refer to the local memory address bit positions that the Intel^® HLS Compiler should use for the bank-selection bits. Specifying the hls_bankbits(b0, b1, ..., bn) attribute implies that the number of banks equals 2^(number of bank bits).

Example of Implementing the hls_bankbits Attribute

Consider the following example component code:

component int bank_arb_consecutive_multidim (int raddr,
                                             int waddr,
                                             int wdata,
                                             int upperdim) {

  int a[2][4][128];

  #pragma unroll
  for (int i = 0; i < 4; i++) {
    a[upperdim][i][(waddr & 0x7f)] = wdata + i;
  }

  int rdata = 0;

  #pragma unroll
  for (int i = 0; i < 4; i++) {
    rdata += a[upperdim][i][(raddr & 0x7f)];
  }

  return rdata;
}

As illustrated in the following figure, this code example generates multiple load and store instructions, and therefore multiple load/store units (LSUs) in the hardware. If the memory system is not split into multiple banks, there are fewer ports than memory access instructions, leading to arbitrated accesses. This arbitration results in a high loop initiation interval (II) value. Avoid arbitration blocks whenever possible because they consume a lot of FPGA area and can hurt the performance of your component.

Figure 18. Accesses to Local Memory a for Component bank_arb_consecutive_multidim

¹

By default, the Intel^® HLS Compiler splits the memory into banks if it determines that the split is beneficial to the performance of your component. When the compiler generates a memory system, it uses the lower-order memory address bits to access the different memory banks. This behavior means that if you define your component memory structure so that the lowest order addresses are accessed in parallel, the compiler automatically infers the bank-selection bits for you.

This access pattern prevents stallable arbitration on the memory. In this case, preventing stallable arbitration reduced the II value to 1. In practice, this might mean that you store a matrix in column-major format instead of row-major format, if you intend to access multiple matrix rows concurrently.

Swapping the 128-element and 4-element dimension in the code example that follows results in no stallable memory arbitration.

component int bank_arb_consecutive_multidim (int raddr, int waddr, int wdata, int upperdim) { int a[2][128][4]; #pragma unroll for (int i = 0; i < 4; i++) { a[upperdim][(waddr & 0x7f)][i] = wdata + i; } int rdata = 0; #pragma unroll for (int i = 0; i < 4; i++) { rdata += a[upperdim][(raddr & 0x7f)][i]; } return rdata; }

The dimension that is accessed in parallel is moved to be the lowest-order dimension in the memory array. The load has a width of 128 bits, which is the same as four 32-bit loads.

If you cannot change your memory structure, you can use the hls_bankbits attribute to explicitly control how load and store instructions access local memory. As shown in the following modified code example and figure, when you choose constant bank-select bits for each access to the local memory a, each pair of load and store instructions needs to connect to only one memory bank. In this example, there are four 32-bit loads, which results in a memory system similar to the earlier example.

Figure 19. Accesses to Local Memory a for Component bank_arb_consecutive_multidim with the hls_bankbits Attribute

component int bank_arb_consecutive_multidim (int raddr, int waddr, int wdata, int upperdim) { int a[2][4][128] hls_bankbits(8,7); #pragma unroll for (int i = 0; i < 4; i++) { a[upperdim][i][(waddr & 0x7f)] = wdata + i; } int rdata = 0; #pragma unroll for (int i = 0; i < 4; i++) { rdata += a[upperdim][i][(raddr & 0x7f)]; } return rdata; }

When specifying the word-address bits for the hls_bankbits attribute, ensure that the resulting bank-select bits are constant for each access to local memory. As shown in the following example, the local memory access pattern does not guarantee that the chosen bank-select bits are constant for each access. As a result, each pair of load and store instructions must connect to all the local memory banks, leading to stallable accesses.

Figure 20. Stallable Accesses to Local Memory a for Component bank_arb_consecutive_multidim with the hls_bankbits Attribute

component int bank_arb_consecutive_multidim (int raddr, int waddr, int wdata, int upperdim){ int a[2][4][128] hls_bankbits(5,4); #pragma unroll for (int i = 0; i < 4; i++) { a[upperdim][i][(waddr & 0x7f)] = wdata + i; } int rdata = 0; #pragma unroll for (int i = 0; i < 4; i++) { rdata += a[upperdim][i][(raddr & 0x7f)]; } return rdata; }

In this case, the II is estimated to be approximately 64.

After you optimize the algorithm bottlenecks of your design, you can fine-tune some datatypes in your component by using arbitrary precision datatypes to shrink data widths, which reduces FPGA area utilization. The Intel^® HLS Compiler provides debug functionality so that you can easily detect overflows in arbitrary precision datatypes.

Because C++ automatically promotes smaller datatypes such as short or char to 32 bits for operations such as addition or bit-shifting, you must use the arbitrary precision datatypes if you want to create narrow datapaths in your component.

<quartus_installdir>/hls/examples/tutorials

The ac_int datatype differs from other languages, including C and Verilog, in bit shifting. By default, if the shift amount is of a signed datatype ac_int allows negative shifts.

In hardware, this negative shift results in the implementation of both a left shifter and a right shifter. The following code example shows a shift amount that is a signed datatype.

int14 shift_left(int14 a, int14 b) {
    return (a << b);
} 

If you know that the shift is always in one direction, to implement an efficient shift operator, declare the shift amount as an unsigned datatype as follows:

int14 efficient_left_only_shift(int14 a, uint14 b) {
    return (a << b);
}