pragma HLS occurrence - 2023.2 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
Release Date
2023.2 English


The OCCURRENCE pragma or directive 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 pragma specifies how often the pipelined function is called inside the current pipeline. Identifying a function within a condition block 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.

When pipelining functions or loops, the OCCURRENCE pragma 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 the 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).


Place the pragma in the C source within a conditional block of code that contains the pipelined sub-function call(s).

#pragma HLS occurrence cycle=<int> off=true


Specifies the occurrence value 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>.
Disable occurrence for the specified function.


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 the OCCURRENCE pragma it would be pipelined with the same II as the caller, with the OCCURRENCE pragma 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
  if (i % 4 == 0) {
#pragma HLS occurrence cycle=4
    a[i+1] = b[i];