Conditional Control of Pragmas - Conditional Control of Pragmas - 2026.1 English

Conditional Control of Pragmas - Conditional Control of Pragmas - 2026.1 English - UG1399

Vitis High-Level Synthesis User Guide (UG1399)

Document ID

UG1399

Release Date

2026-06-23

Version

2026.1 English

Conditional control of HLS pragmas enables you to analyze performance and resource usage for different pragmas by applying conditions at compile time. This feature allows you to selectively enable or disable specific pragmas based on constant expressions, making it easier to experiment with various optimization strategies.

How It Works

You can add an if (condition) clause to a pragma, placed before the directive name.

The syntax is:

#pragma HLS if(condition) <Pragma> {pragma options}

The condition must be a constant expression that can be evaluated at compile time.
This approach is supported for both C/C++ source code pragmas and Tcl set_directive commands.
The template functions conditions can be based on either type or non-type template parameters.

Using Preprocessor Defines

In this example, the applied pragma depends on the value of the OPT macro. If OPT is 1, the loop is pipelined; if OPT is 2, the loop is unrolled by a factor of 16.

#define OPT 2

int dot_product(int A[SIZE], int B[SIZE]) {
#pragma HLS INTERFACE mode=ap_memory port=A
#pragma HLS INTERFACE mode=ap_memory port=B
#pragma HLS INTERFACE mode=s_axilite port=return

    int result = 0;
   
    DP_LOOP: for (int i = 0; i < SIZE; i++) {            
    #pragma HLS if (OPT==1) PIPELINE II=1       
    #pragma HLS if (OPT==2) UNROLL factor=16    
                
        result += A[i] * B[i];
    }
    return result;
}

Using Template Function Parameters

In this example, the pragma applied within the loop depends on the TripCount non-type template parameter. If TripCount is greater than 20, pipelining is used; otherwise, the loop is unrolled.

template<int TripCount>
void dot_product(const int* a, const int* b, int& output) {
    output = 0;
    DP: for (int i = 0; i < TripCount; ++i) {
        #pragma HLS if (TripCount > 20) pipeline II = 1
        #pragma HLS if (TripCount <=20) unroll	
        output += a[i] * b[i];
    }
}

void top(const int* a, const int* b, int& output) {
#pragma HLS INTERFACE m_axi port=a depth=10 bundle=gmem
#pragma HLS INTERFACE m_axi port=b depth=10 bundle=gmem
#pragma HLS INTERFACE m_axi port=output depth=10 bundle=gmem

    dot_product<10>(a, b, output); // Instantiate with TripCount = 30
}