--clock Options - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
Release Date
2023.2 English
Important: The --clock options described here can be used with --freqhz to manage clocks as described in Managing Clock Frequencies.

The --clock options are used to assign the clock frequency during the compilation of AI Engine, HLS kernels and linking of the design. It is supported in both --part and --platform options. If no option is provided, Vitis assigns the default clock per the respective mode selected as shown in the following table.

Table 1. Default clock assigned
V++ -c --mode aie -c --mode hls -c -k -l
--part ¼ of AIE PLL Freq Default HLS (100 MHz) N/A 300 MHz for Versal device
--platform Default Platform Clock Freq Default Platform Clock Freq Default Platform Clock Freq Default Platform Clock Freq

There are different clock directives for different v++ -c modes and v++ -l. --freqhz is a new clock directive introduced in 2023.2 that can be used in all v++ -c modes and v++ -l, helping you to use one clock directive in all different modes. Older directives are still supported.

There are two ways to connect the kernel to the specified frequency using the --clock option:

  1. --clock.freqhz or --freqhz: This option is used to connect the specified clock frequency from the platform to the kernel. If a platform has one or more clocks at the specified frequency, one of them will be selected. If a platform doesn’t have the specified frequency, the specified frequency is generated using the platform reference clock.
  2. --clock.id: This option can also be used to connect a specified clock frequency to the kernel; however, in this option the clock is considered as a clock source. This option can be used to connect the kernel or multiple kernels on the same clock source. See the following example for details.
Note: You can determine the available clock IDs for a target platform using the platforminfo utility as described in platforminfo Utility.

To determine the fixed clocks available in the platform xilinx_vck190_base_bdc_202320_1.xpfm:

Plaftorminfo ../ xilinx_vck190_base_bdc_202320_1.xpfm

Refer to “Clock Information” in the report:

Clock Information
Default Clock Index: 2
Clock Index: 0
Frequency: 104.166666
Clock Index: 1
Frequency: 156.250000
Clock Index: 2
Frequency: 312.500000
Clock Index: 3
Frequency: 78.125000
Clock Index: 4
Frequency: 208.333333
Clock Index: 5
Frequency: 416.666666
Clock Index: 6
Frequency: 625.000000

Suppose you want to connect kernel X to 312.5 MHz and kernel Y to 625.00 MHz, considering that both frequencies are generated in the platform. It is recommended to use the --freqhz option to assign the specific clock to kernel X and Y during the compilation and linking phase.

In compile mode (v++ -c --mode aie or v++ -c --mode hls), the --clock option --freqhz can be used in CLI as:

v++ -c --mode hls --platform <xx.xpfm> --freqhz=312500000 --config ./X.cfg

v++ -c --mode hls --platform <xx.xpfm> --freqhz=625000000 --config ./Y.cfg

In the config file, it can be given as per the following.

For the X.cfg file:


For the Y.cfg file:


In link mode (v++ -l), the syntax is <cu>.<clk_pin_name>.

In CLI, the command can be used as:

v++ -l -t hw --platform ./<.xpfm> ./libadf.a ./Y.xo --freqhz=312500000:X.clk --freqhz=625000000:Y.clk -s --config ./system.cfg -o fixed.xsa
Note: The key portion is --freqhz=312500000:X.clk --freqhz=625000000:Y.clk.

In the config file, it can be given as:

freqhz=312500000: X.clk
freqhz=625000000 : Y.clk

Here, clk is the pin name of the kernel.

Note: The clock directive can be used either in CLI or in the configuration file.


--clock.tolerance <arg>

Specifies a clock tolerance as a value, or as a percentage of the clock frequency. When specifying --clock.freqhz, you can also specify the tolerance with either a value or percentage. This updates the timing constraints to reflect the accepted tolerance. <arg> is specified as <tolerance>:<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]

  • Can be specified either as a whole number, indicating the clock.freqhz ± the specified tolerance value; or as a percentage of the clock frequency specified as a decimal value.
  • <cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]: Applies the defined clock tolerance to the specified CUs, and optionally to the specified clock pin on the CU.
Applies the defined clock tolerance to the specified CUs, and optionally to the specified clock pin on the CU.
Important: The default clock tolerance is 5% of the specified frequency when this option is not specified.

For example:

v++ --link --clock.tolerance 0.10:vadd_1,vadd_3 
Tip: This option can be specified in a configuration file under the [clock] section head using the following format: