--clock Options - 2023.1 English

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

Document ID

UG1393

Release Date

2023-07-17

Version

2023.1 English

Important: The --clock options described here are supported on embedded processor platforms and AMD Alveo™ platforms with fixed clocks, as described in Managing Clock Frequencies.

You can specify the --clock option using either a clock ID from the platform shell, or by specifying a frequency for the kernel clock. When specifying the clock ID, the kernel frequency is defined by the frequency of that clock ID on the platform. When specifying the kernel frequency, the platform attempts to create the specified frequency by scaling one of the available fixed platform clocks. In some cases, the clock frequency can only be achieved in some approximation, and you can specify the --clock.tolerance or --clock.default_tolerance to indicate an acceptable range. If the available fixed clock cannot be scaled within the acceptable tolerance, a warning is issued and the kernel is connected to the default clock.

The --clock.XXX options provide a method for assigning clocks to kernels from the v++ command line and locating the required kernel clock frequency source during the linking process. There are a number of options that can be used with increasing specificity. The order of precedence is determined by how specific a clock option is. The rules are listed in order from general to specific, where more specific rules take precedence over general rules:

When no --clock.XXX option is specified, the platform default clock is applied to each compute unit (CU). For kernels with two clocks, clock ID 0 from the platform is assigned to ap_clk, and clock ID 1 is assigned to ap_clk_2.
Specifying --clock.defaultId=<id> defines a specific clock ID for all kernels, overriding the platform default clock assignments.
Specifying --clock.defaultFreqHz=<Hz> defines a specific clock frequency for all kernels that overrides a user specified default clock ID, and the platform default clock.
Specifying --clock.id=<id>:<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]] assigns a clock ID to a list of associated CUs, and optionally the clock pin for the CU.
Specifying --clock.freqHz=<Hz>:<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]] assigns the specified clock frequency to a list of associated CUs, and optionally the clock pin for the CU.

--clock.defaultFreqHz

--clock.defaultFreqHz <arg>

Specifies a default clock frequency in Hz to use for all kernels. This lets you override the default platform clock and assign the specified clock frequency as the default. <arg> is specified as the clock frequency in Hz.

For example:

v++ --link --clock.defaultFreqHz 300000000

Tip: This option can be specified in a configuration file under the [clock] section head using the following format:

[clock]
defaultFreqHz=300000000

--clock.defaultId

--clock.defaultId <arg>

Specifying --clock.defaultId=<id> defines a specific clock ID for all kernels, overriding the platform default clock. <arg> is specified as the clock ID from one of the clocks defined on the target platform, other than the default clock ID.

Tip: You can determine the available clock IDs and clock status for a target platform using the platforminfo -v command as described in platforminfo Utility.

For example:

v++ --link --clock.defaultId 1

Tip: This option can be specified in a configuration file under the [clock] section head using the following format:

[clock]
defaultId=1

--clock.defaultTolerance

--clock.defaultTolerance <arg>

Specifies a default clock tolerance as a value, or as a percentage of the default clock frequency. When specifying clock.defaultFreqHz, you can also specify the tolerance with either a value or percentage. This updates the timing constraints to reflect the accepted tolerance.

The tolerance value, <arg>, can be specified as a whole number, indicating the clock.defaultFreqHz ± the specified tolerance; or as a percentage of the default clock frequency specified as a decimal value.

Important: The default clock tolerance is 5% when this option is not specified.

For example:

v++ --link --clock.defaultFreqHz 300000000 --clock.defaultTolerance 0.10

Tip: This option can be specified in a configuration file under the [clock] section head using the following format:

[clock]
defaultTolerance=0.10

--clock.freqHz

--clock.freqHz <arg>

Specifies a clock frequency in Hz and assigns it to a list of associated compute units (CUs) and optionally specific clock pins on the CU. <arg> is specified as <frequency_in_Hz>:<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]:

<frequency_in_Hz>: Defines the clock frequency specified in Hz.
<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]: Applies the defined frequency to the specified CUs, and optionally to the specified clock pin on the CU.

For example:

v++ --link --clock.freqHz 300000000:vadd_1,vadd_3

Tip: This option can be specified in a configuration file under the [clock] section head using the following format:

[clock]
freqHz=300000000:vadd_1,vadd_3

--clock.id

--clock.id <arg>

Specifies an available clock ID from the target platform and assigns it to a list of associated compute units (CUs) and optionally specific clock pins on the CU. <arg> is specified as <reference_ID>:<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]:

<reference_ID>: Defines the clock ID to use from the target platform.
Tip: You can determine the available clock IDs for a target platform using the platforminfo utility as described in platforminfo Utility.
<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]: Applies the defined frequency to the specified CUs and optionally to the specified clock pin on the CU.

For example:

v++ --link --clock.id 1:vadd_1,vadd_3

Tip: This option can be specified in a configuration file under the [clock] section head using the following format:

[clock]
id=1:vadd_1,vadd_3

--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 clock.FreqHz 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