set_directive_performance - 2025.1 English - UG1399

Vitis High-Level Synthesis User Guide (UG1399)
Document ID
UG1399
Release Date
2025-09-10
Version
2025.1 English

Description

Tip: set_directive_performance applies globally to the entire Design Under Test (DUT) top function. It can also be applied to the loops as the loop-level PERFORMANCE directive.

The set_directive_performance directive in Vitis HLS provides a mechanism for defining high-level performance goals for your design, guiding the synthesis tool's optimization efforts. It can be applied at two distinct scopes: the top-level of the design (Kernel/IP) and specific loop levels within the design.

Top-Level PERFORMANCE directive

Applying the set_directive_performance directive at the top-level function of your Kernel or IP allows you to specify an overall performance target, primarily focusing on achieving a desired throughput. When applied at the kernel's top-level function, this directive triggers the HLS tool to conduct a design-wide performance analysis. This analysis evaluates the entire design structure to determine the feasibility of meeting the specified performance goal. Based on the overall goal and this analysis, the tool automatically infers appropriate Loop-Level performance directive for individual loops and loop nest within the design hierarchy.

Loop-Level PERFORMANCE directive

Applying the set_directive_performance directive directly to a specific loop or loop nest lets you define performance goals for that particular section of loop or loop nest. Loop-Level PERFORMANCE directive lets you specify a high-level constraint, target_ti defining the number of clock cycles between successive starts of a loop, and lets the tool infer lower-level UNROLL, PIPELINE, ARRAY_PARTITION, and INLINE directives needed to achieve the desired result. The PERFORMANCE directive does not guarantee the specified value will be achieved, and so it is only a target.

The set_directive_performance directive, applicable at both the top-level (entire function/DUT) and loop level, uses parameters target_ti to guide optimization toward specific performance goals.

  • target_ti (Target Initiation Interval): This defines the desired number of clock cycles between successive starts of the DUT or loop.
    • Top-Level Performane directive:
    • When applied at the top-level, target_ti specifies the target interval between the start of one function execution and the start of the next. Let's consider an example to calculate the Top-Level performance directive for an image processing design targeting a frame rate of 60 frames per second (FPS). To achieve a 60 FPS frame rate, the function/DUT must be ready to restart and read a new frame within 1/60th of a second.
    • Target TI = 1/FPS = 1/60 ~= 16.67 milliseconds.
    • This means that the function/DUT must be ready to restart and read a new frame within 16.7 milliseconds to maintain the 60 frames per second (FPS) target.
    • Loop-Level performance directive:
    • When applied at the loop-level, target_ti specifies the target interval between the start of the first iteration of the loop in successive outer loop iterations . In the following example, target_ti=T on loop L2 targets an interval of T cycles between the start of loop L2 execution for one iteration of L1 and the start of loop L2 for the subsequent iteration of L1.
    • const int T = 100; 
L1: for (int i=0; i<N; i++)  
L2: for (int j=0; j<M; j++)
{ directive HLS performance target_ti=T   ...   }

The transaction interval is the initiation interval (II) of the loop times the number of iterations, or tripcount: target_ti = II * loop tripcount. Conversely, target_ti = FreqHz / Operations per second.

For example, assuming an image processing function that processes a single frame per invocation with a throughput goal of 60 fps, then the target throughput for the function is 60 invocations per second. If the clock frequency is 180 MHz, then target_ti is 180M/60, or 3 million clock cycles per function invocation.

Syntax

Specify the directive for a labeled loop.

set_directive_performance <location> [OPTIONS]

Where:

<location> specifies the top function or loop.

Options

-target_ti=<value>
Specifies a target transaction interval defined as the number of clock cycles for the loop to complete an iteration. The transaction interval refers to the time the loop starts processing a transaction and the time it begins processing the next transaction. The <value> can be specified as an integer, floating point, or constant expression that is resolved by the tool as an integer.
Note: A warning will be returned if truncation occurs.
unit=[sec | cycle]
Specifies the unit associated with the target_ti or target_tl values. The unit can either be specified as seconds, or clock cycles. When the unit is specified as seconds, a unit can be specified with the value to indicate nanoseconds (ns), picoseconds (ps), microseconds (us).

Example 1

The loop labeled loop_1 in the function func is specified to have target transaction interval of 4 clock cycles: 

set_directive_performance func/loop_1 -target_ti=4

See Also