--clock Options - 2023.2 English

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

Document ID
UG1393
Release Date
2023-12-13
Version
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:

[clock]
freqhz=312500000 

For the Y.cfg file:

[clock]
freqhz=625000000

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:

[clock]
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

--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>]]

<tolerance>
  • 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.
<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.
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:
[clock]
tolerance=0.10:vadd_1,vadd_3