--clock Options - --clock Options - 2026.1 English

The --clock options are used by the Vitis tool to assign the clock frequency during the compilation of the AI Engine graph, HLS kernels and linking of the design.

For clock directives supported by Vitis compilation, the Vitis tool compiles the AI Engine graph and HLS components. There are different modes to compile AI Engine graph and HLS components. The AI Engine runs at a single rate, although the compiler supports directives to specify expected PLIO peer clock frequencies. If you do not use clock directives, the Vitis tool selects the clock frequency based on whether you specify --part or --platform.

Table 1. Clock Directives for AI Engine Graph Compilation
Mode	Design	Clock Directive	Vitis Tool Consideration
v++ -c --mode aie	--platform	No Directive	Platform default clock
v++ -c --mode aie	--part	No Directive	0.25 x (AI Engine PLL Frequency)
v++ -c --mode aie	--platform OR --part	--pl-freq=200 --freqhz=200000000 --freqhz=200MHz	Compiles at 200 MHz

Note: The value of


				--freqhz

supports either no units (in which case, Vitis considers the unit to be Hz) or MHz. The unit MHz is case insensitive. The frequency must not be a hertz fractional value. For example, --freqhz=312.005MHz is supported whereas --freqhz=312.0000005MHz is not supported. There must be no space between the value and the units (in MHz).

Note: freqhz is applicable to all Vitis compilation modes and linking.

The following are the commands with different directives in CLI mode:

v++ -c --mode aie --platform <pfm.xpfm> --config <aie.cfg> --freqhz=200000000 ./aie_graph.cpp
v++ -c --mode aie --platform <pfm.xpfm> --config <aie.cfg> --freqhz=200MHz ./aie_graph.cpp
v++ -c --mode aie --platform <pfm.xpfm> --config <aie.cfg> --aie.pl-freq=200 ./aie_grapch.cpp

Provide the directives through the configuration file:

```
freqhz=200000000
```
```
freqhz=200MHz
```

The directive --aie.pl-freq (the same is applicable to --freqhz) can be used to address other PLIO design scenarios as shown below:

To compile all AI Engine PLIO at 200MHz (Default): --aie.pl-freq=200
To compile specific PLIO at 200MHz: --aie.pl-freq=<PLIO_PORT_NAME>:<FREQ>
To compile multiple graphs at 200MHz: --aie.pl-freq=<AIE_GRAPH_NAME>.<PLIO_PORT_NAME>:<FREQ>

Note: --aie.pl-freq is in MHz, while --freqhz is in Hz.

Table 2. Clocking Directives for HLS Compilation
Mode	Design	Clock Directive	Vitis Tool Consideration
v++ -c --mode hls	--platform	No Directive	Platform default clock
v++ -c --mode hls	--part	No Directive	Default clock=100 MHz
v++ -c --mode hls	--platform OR --part	--hls.clock=200 --hls.clock=0.5ns --freqhz=200000000 --freqhz=200MHz	Compiles HLS kernel at 200 MHz

The following are the commands with different directives in CLI mode:

v++ -c --mode hls --platform <pfm.xpfm> --config <hls.cfg> --freqhz=200000000 --work_dir <work_dir_path>

v++ -c --mode hls --platform <pfm.xpfm> --config <hls.cfg> --freqhz=200MHz --work_dir <work_dir_path>

v++ -c --mode hls --platform <pfm.xpfm> --config <hls.cfg> --hls.clock=200 --work_dir <work_dir_path>
v++ -c --mode hls --platform <pfm.xpfm> --config <hls.cfg> --hls.clock=5ns --work_dir <work_dir_path>

You can provide different directives in the configuration

```
freqhz=200000000
```
```
freqhz=200MHz
```
```
[hls]
clock=200
```
```
[hls]
clock=5ns
```

Note: Clocking directive support for v++ -c --mode hls is analogous to v++ -c -k.

For clock directives supported for Vitis linking, the Vitis tool links AI Engine graph, HLS components, and hardware configuration (platform/part) using a configuration file.

During linking, clock directives connect HLS components to the clock frequency. In v++ linking, Vitis connects the requested clock frequency to HLS components. The v++ linker handles the scenario depends on the clock directives. Refer to Managing Clock Frequencies in the Data Center Acceleration using Vitis (UG1700) for more information about the v++ linking behavior for the clocking directives.

Table 3. Clocking Directives for v++ Linking:
Mode	Design	Clock Directive	Vitis Tool Consideration
v++ -l	--platform	No Directive	Platform default clock
v++ -l	--part	No Directive	For Versal, default clock is 300 MHz. Not supported for other devices.
v++ -l	--platform --part	--clock.freqHz=200000000:<cu_0>[.<clk_pin>] --freqhz=200000000:<cu_0>[.<clk_pin>] --freqhz=200MHz:<cu_0>[.<clk_pin>] --clock.id=<id_value>:<cu_0>[.<clk_pin>]	For freqhz/clock.freqHz: Connect HLS kernel to 200 MHz For clock.id: Connect HLS kernel to clock source <id_value of 200 MHz>

The following are the commands with directives in CLI mode:

v++ -l --platform <pfm.xpfm> ./libadf.a ./<kernel_name.xo> --config <system.cfg> --freqhz=200000000:mm2s:aclk -o <fixed.xsa>

v++ -l --platform <pfm.xpfm> ./libadf.a ./<kernel_name.xo> --config <system.cfg> --freqhz=200MHz:mm2s.aclk -o <fixed.xsa>

v++ -l --platform <pfm.xpfm> ./libadf.a ./<kernel_name.xo> --config <system.cfg> --clock.freqHz=200000000:mm2s.aclk -o <fixed.xsa>

v++ -l --platform <pfm.xpfm> ./libadf.a ./<kernel_name.xo> --config <system.cfg> --clock.id=<id_value> -o <fixed.xsa>

Provide directives through the configuration file:

freqhz=200000000:mm2s.aclk
freqhz=200MHz:mm2s.aclk
```
[clock]
freqHz=200000000:mm2s.aclk
```

There are two ways to connect the kernel to the frequency in the v++ link phase. Vitis considers the clocks in the platform as either a clock frequency or clock source, depending on the directive.

Use the --freqhz or --clock.freqHz directive to connect a clock by frequency.

Use the --clock.id directive to connect a clock by source.

--clock.freqHz or --freqhz: These both directives work in a similar way and do not depend on platform clocking. You can use these directives to connect a platform clock frequency to the kernel:
- If a platform has multiple clocks available at the requested frequency using --freqhz, the Vitis tool selects any one of the platform clock by considering the clock.tolerance value (default being 5%).
- If the platform has multiple clock frequencies available at the requested clock frequency, and you want the Vitis tool to pick a particular clock, you must use the directive --clock.id in place of --freqhz.
- If a platform does not have a matching frequency, Vitis generates the clock frequency using the available platform fixed clock.
--clock.id: This option can be used to connect a particular platform clock as a clock source to the kernel. The v++ linker can add IPs such as FIFO, data width converter, and clock converter, depends on the Vivado design implemented.

The PFM.CLOCK status attribute controls how the v++ linker treats the clock. Specify fixed or fixed_non_ref; scalable clocks work only on legacy Alveo platforms. The linker does not use fixed_non_ref clocks as references for generated clocks. Set the status in Vivado under Platform Setup in the Clock section.

Figure 1. Platform Setup for Clock

Table 4. PFM.CLK Status Options
Status Value	Description
`Scalable`	Scalable clocks used by XRT. Only supported in legacy Alveo designs.
`Fixed`	Used as a reference clock to connect to IP. Used in Embedded design.
`fixed_non_ref`	Cannot be used as a reference clock; can be used to connect IPs in embedded design.

Note: Reference clocks are clocks which the Vitis tool uses (as a clock input) to generate other clocks using MMCM.

For example, suppose a clocking requirement is to generate the output clock with a divider setting of 1, 2, 4, and 8. It is recommended to use the primitive MBUFGCE in place of BUFG to reduce the clock skew between synchronous clock outputs. The output clocks of MBUFGCE cannot be used as a reference clock. Thus, you can set the attribute status=fixed_non_ref so that the Vitis tool cannot use these clocks (output of MBUFGCE) as reference clocks.

Note: You can determine the available clock IDs for a target platform using the platforminfo utility as described in platforminfo Utility. The platforminfo report includes the clock status of all the platform clocks.

To determine the fixed clocks available on the platform xilinx_vck190_base_bdc_202420_1.xpfm:

Go to plaftorminfo ../ xilinx_vck190_base_bdc_202420_1.xpfm and refer to the “Clock Information” section in the report:

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

--clock.tolerance

--clock.tolerance <arg>

Specifies a clock tolerance. When specifying --clock.freqHz, you can also specify the tolerance with either a value or percentage of the clock frequency. This updates the timing constraints to reflect the accepted tolerance. Specify <arg> 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: If you do not use this option, the default clock tolerance is 5% of the specified frequency.

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

--clock Options - --clock Options - 2026.1 English - UG1702

Vitis Reference Guide (UG1702)

--clock.tolerance