set_directive_occurrence - 2023.2 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2023-12-18
Version
2023.2 English

Description

set_directive_occurrence can be applied to a function call within a region. The feature works with pipelined function calls within a conditional block such as an if statement or switch statement. The directive specifies how often the pipelined function is called inside the current pipeline. Identifying a function within a condition block with set_directive_occurrence 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.

When pipelining functions or loops, set_directive_occurrence specifies that a pipelined function call within the pipelined function or loop is executed less frequently than the enclosing function or loop. This allows the pipelined function call that is executed less often to be pipelined at a slower rate, thus potentially improving the resource sharing potential within the top-level pipeline.

Use the following process to determine set_directive_occurrence -cycle value:

  • A loop iterates <N> times.
  • However, part of the loop body is enabled by a conditional statement, and as a result only executes <M> times, where <N> is an integer multiple of <M>.
  • 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 that only executes two times has an occurrence of 5 (or 10/2).

Syntax

set_directive_occurrence [OPTIONS] <location>
  • <location> specifies the block of code that contains the pipelined function call(s) with a slower rate of execution.

Options

-cycle <int>
Specifies the occurrence N/M, where <N> is the number of times the enclosing function or loop executes, and <M> is the number of times the conditional region executes.
Important: N must be an integer multiple of M.
-off or off=true
Disable occurrence for the specified function.

Examples

In this example, the call of sub-function within the if statement (but not the memory read and write, because they are not inside a pipelined function) has an occurrence of 4 (it executes at a rate four times less often than the surrounding code that contains it). Hence, while without set_directive_occurrence it would be pipelined with the same II as the caller, with the directive it will be pipelined with an II=4. This will expose more resource sharing opportunities within it and with other functions.

void subfunction(...) {
#pragma HLS pipeline II=...
// Without the occurrence pragma, 
// this will be automatically pipelined with an II=1, 
// regardless of its own pipeline pragma, 
// since it is called in a pipeline with II=1
// With the pragma, it has an II=4.
  ...
}
for (int i = 0; i < 16; i++) {
#pragma HLS pipeline II=1
Cond_Region:
  if (i % 4 == 0) {
    subfunction(...);
    a[i+1] = b[i];
  }
}

Region Cond_Region in function subfunction has an occurrence of 4. It executes at a rate four times slower than the code that encompasses it.

set_directive_occurrence -cycle 4 foo/Cond_Region