Clocking the PL Kernels - 2022.1 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)
Document ID
UG1076
Release Date
2022-05-25
Version
2022.1 English

PLIO represents an ADF graph interface to the PL. This PL could be a PL kernel, a platform IP representing a signal source or sink, or it could be a data mover to interface the ADF graph to memory. You should provide clock frequency values for these interfaces to ensure simulation results match the results from running the design in hardware.  In addition, when you link the ADF graph into the platform, at the Vitis linker (v++ -link) step, you have the ability to provide more accurate clock values depending on the specific clock frequency values supported by the platform. To set the exact frequency of a PLIO interface in the graph and the clock frequency of the corresponding PL kernel you must specify the clock frequency in three locations:

  • ADF graph (Optional)
  • Vitis compilation of a PL kernel (v++ -c)
  • Vitis linking (v++ -l)

You must specify the clocking depending on where the kernels are located. The following table describes the default clocks based on the kernel location.

Table 1. Default Kernel Clocks
Kernel Location Description
AI Engine kernels Clocked per the AI Engine clock frequency. All cores run with the same clock frequency.
PL kernels connected to AI Engine graph HLS: Default frequency for all HLS kernels - 150 MHz

RTL: Frequency is set to the frequency that the XO file was compiled with.

AI Engine: Set in the PLIO constructor in the AI Engine graph. Setting the frequency here is optional. See Adaptive Data Flow Graph Specification Reference for more information. 1

PL kernels added to platform using the Vitis linker Platforms have a default clock. If no clocking option is set at the command line or configuration file the default clock is used. This default can be overridden depending on the design and required clock value, as shown in the following table.
  1. If the PLIO frequency is not provided in the PLIO constructor the AI Engine compiler defaults the frequency to one quarter of the AI Engine clock frequency. When you determine the target platform, Xilinx recommends setting the PLIO clock frequencies explicitly, to make your AI Engine simulations more representative of your application.
Note: The maximum supported PLIO interface clock frequency is half the AI Engine clock frequency, depending on the device speed-grade. If you specify a higher frequency, the Vitis linker will cap the frequency to the maximum supported frequency and will issue a critical warning in linker stage.

Setting the clocks at the Vitis linker step allows you to choose a frequency based on the platform. The following table describes the Vitis compiler clocking options during the link step.

Table 2. Vitis Linking Clock Options
[clock] Options Description
--clock.defaultFreqHz arg Specify a default clock frequency to use in Hz.
--clock.defaultId arg Specify a default clock reference ID to use.
--clock.defaultTolerance arg Specify a default clock tolerance to use.
--clock.freqHz arg <frequency_in_Hz>:<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]

Specify a clock frequency in Hz and a list of associated compute unit names and optionally their clock pins.
--clock.id arg <reference_ID>:<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]

Specify a clock reference ID and a list of associated compute unit names and optionally their clock pins.
--clock.tolerance arg <tolerance>:<cu_0>[.<clk_pin_0>][,<cu_n>[.<clk_pin_n>]]

Specify a clock tolerance and a list of associated compute unit names and optionally their clock pins.

The following table describes the steps to set clock frequencies for PLIOs that interface to the platform, including to PL kernels specified outside of the ADF graph.

Table 3. Compiling PL Kernels with Non-default Clocking
PL Kernel Location Clock Specification
PLIO interface specified in ADF graph Specify the clock frequency per PLIO interface in the graph.

For the PLIO interface, you can optionally specify FreqMHz.

adf::input_plio <interface_name> = adf::input_plio::create(<logical_name>, <plio_width>, <file>, <FreqMHz>);
HLS kernels Compile the HLS code using the Vitis compiler. 
v++ -c -k kernelName kernel.cpp --hls.clock freqHz:kernelName

To change the frequency at which HLS kernels are compiled use: --hls.clock arg:kernelName.

arg must be in Hz (for example, 250000000Hz is 250 MHz).

Per kernel, specify the clock in the Vitis linker.
v++ -l ... --clock.freqHz <freqHz>:kernelName.ap_clk
RTL kernels Per kernel, specify the clock in the Vitis linker.
v++ -l ... --clock.freqHz <freqHz>:kernelName.ap_clk
Note: Clock frequencies for PL kernels at the Vitis linker stage take precedence over Vitis compile time clock frequency values. However the clock frequency value specified at the Vitis linker stage should not exceed the Vitis compiler clock frequency value significantly, because the Vitis compiler generates RTL based on the target frequency specified.

See Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393) for more detailed information on how to compile kernels for specific platform clocks and clocking information.