Using Directives in Scripts vs. Pragmas in Code - 2023.1 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2023-07-17
Version
2023.1 English

In the Vitis HLS Directive Editor dialog box, you can specify either of the following Destination settings:

Directive File
Vitis HLS inserts the directive as a Tcl command into the file directives.tcl in the solution directory.
Source File
Vitis HLS inserts the directive directly into the C source file as a pragma.

The following table describes the advantages and disadvantages of both approaches.

Table 1. Tcl Directives Versus Pragmas
Directive Format Advantages Disadvantages
Directives file (Tcl Script)

Each solution has independent directives. This approach is ideal for design exploration.

If any solution is re-synthesized, only the directives specified in that solution are applied.

If the C source files are transferred to a third-party or archived, the directives.tcl file must be included.

The directives.tcl file is required if the results are to be re-created.

Source Code (Pragma)

The optimization directives are embedded into the C source code.

Ideal when the C sources files are shipped to a third-party as C IP. No other files are required to recreate the same results.

Useful approach for directives that are unlikely to change, such as TRIPCOUNT and INTERFACE.

If the optimization directives are embedded in the code, they are automatically applied to every solution when re-synthesized.
Tip: When using the Vitis core development kit to define hardware acceleration of your C/C++ code, you should use pragmas in your source code, rather than trying to work with directives in a Tcl file. In the Vitis HLS bottom-up flow (or the Vitis kernel flow) you can use directives to develop different solutions, but should convert your final directives to pragmas in the finished project.

When specifying values for pragma arguments, you can use literal values (for example, 1, 55, 3.14), or pass a macro using #define. The following example shows a pragma with literal values:

#pragma HLS ARRAY_PARTITION variable=k_matrix_val  type=cyclic factor=5

This example uses defined macros:

#define E 5
#pragma HLS ARRAY_PARTITION variable=k_matrix_val  type=cyclic factor=E