--clock Options - 2024.1 English

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

Document ID

UG1393

Release Date

2024-07-03

Version

2024.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 clock directives are not used, the Vitis tool decides the clock frequency based on whether --part or --platform is used in the command.

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 should 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). 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

Different directives can be given through the configuration file as well:

```
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 declared in MHz, while --freqhz is declared in Hz.

Table 2. Clocking directives for HLS compilation (Unified CLI)
Mode	Design	Clock Directive	Vitis Tool considers
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>

Different directives can also be given via the configuration file:

```
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 the linking, clock directives are used to connect HLS components to the requested clock frequency. In v++ linking, how the Vitis tool connects the requested clock frequency to HLS components and how the v++ linker handles the scenario depends on the clock directives used. Refer to the section Managing Clock Frequencies for more information about the v++ linking behavior for the clocking directives discussed below.

Table 3. Clocking directives for v++ linking:
Mode	Design	Clock Directive	Vitis Tool Considerations
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>

Different directives can be given through 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 specified frequency in the v++ link phase. Clocks available in the platform can be considered either as a clock frequency or as a clock source by the Vitis tool, which depends on the directive. The clock directive --freqhz or --clock.freqHz can be used to connect the clock as a clock frequency and--clock.id can be used to connect the clock as a clock 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 the particular clock, you must use the directive --clock.id in place of --freqhz.
- If a platform does not have a match for the requested frequency, the Vitis tool generates the requested 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 attribute for the PFM.CLOCK status is status=fixed_non_ref, and it can be used to mark the clock as a non-reference clock. In other words, non reference clocks cannot be used to generate other clock frequencies using MMCM. Non reference clocks can be used to connect IPs and kernels only. To set the clock attribute, open the Vivado design, go to Platform Setup, under the Clock section set the status property of the clock as shown below:

Figure 1. Platform Setup for Clock

Table 4. PFM.CLK Status Options
Status Value	Description
`Scalable`	Scalable clocks used by XRT. Mostly used in 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_202410_1.xpfm:

Go to plaftorminfo ../ xilinx_vck190_base_bdc_202410_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. <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