Managing Clocks in an RTL Kernel - 2020.2 English

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

Document ID
UG1393
Release Date
2021-03-22
Version
2020.2 English

An RTL kernel can have up to two external clock interfaces; a primary clock, ap_clk, and an optional secondary clock, ap_clk_2. Both clocks can be used for clocking internal logic. However, all external RTL kernel interfaces must be clocked on the primary clock. Both primary and secondary clocks support independent automatic frequency scaling.

Note: When targeting an embedded processor platform or an Alveo accelerator card from the 2020.2 release, you can use the techniques described in Managing Clock Frequencies to map any number of kernel clocks to clock frequencies from the hardware platform.

If you require additional clocks within the RTL kernel, a frequency synthesizer such as the Clocking Wizard IP or MMCM/PLL primitive can be instantiated within the RTL kernel. Therefore, your RTL kernel can use just the primary clock, both primary and secondary clock, or primary and secondary clock along with an internal frequency synthesizer. The following shows the advantages and disadvantages of using these three RTL kernel clocking methods:

  • Single input clock: ap_clk
    • External interfaces and internal kernel logic run at the same frequency.
    • No clock-domain-crossing (CDC) issues.
    • Frequency of ap_clk can automatically be scaled to allow kernel to meet timing.
  • Two input clocks: ap_clk and ap_clk_2
    • Kernel logic can run at either clock frequency.
    • Need proper CDC technique in the RTL kernel to move from one frequency to another.
    • Both ap_clk and ap_clk_2 can automatically scale their frequencies independently to allow the kernel to meet timing.
  • Using a frequency synthesizer inside the kernel:
    • Additional device resources required to generate clocks.
    • Must have ap_clk and optionally ap_clk_2 interfaces.
    • Generated clocks can have different frequencies for different CUs.
    • Kernel logic can run at any available clock frequency.
    • Need proper CDC technique to move from one frequency to another.

When using a frequency synthesizer in the RTL kernel there are some constraints you should be aware of:

  1. RTL external interfaces are clocked at ap_clk.
  2. The frequency synthesizer can have multiple output clocks that are used as internal clocks to the RTL kernel.
  3. You must provide a Tcl script to downgrade DRCs related to clock resource placement in Vivado placement to prevent a DRC error from occurring. Refer to CLOCK_DEDICATED_ROUTE in the Vivado Design Suite Properties Reference Guide (UG912) for more information. The following is an example of the needed Tcl command that you will add to your Tcl script:
    set_property CLOCK_DEDICATED_ROUTE ANY_CMT_COLUMN 
    [get_nets pfm_top_i/static_region/base_clocking/clkwiz_kernel/inst/CLK_CORE_DRP_I/clk_inst/clk_out1
    Note: This constraint should be edited to reflect the clock structure of your target platform.
  4. Specify the Tcl script from step 3 for use by Vivado implementation, after optimization, by using the v++ --vivado.prop option as described in --vivado Options. The following option specifies a Tcl script for use by Vivado implementation, after completing the optimization step:
    --vivado.prop:run.impl_1.STEPS.OPT_DESIGN.TCL.POST={<PATH>/<Script_Name>.tcl}
  5. Specify the two global clock input frequencies which can be used by the kernels (RTL or HLS-based). Use the v++ --kernel_frequency option to ensure the kernel input clock frequency is as expected. For example to specify one clock use:
    v++ --kernel_frequency 250
    For two clocks, you can specify multiple frequencies based on the clock ID. The primary clock has clock ID 0 and the secondary has clock ID 1.
    v++ --kernel_frequency 0:250|1:500
    Tip: Ensure that the PLL or MMCM output clock is locked before RTL kernel operations. Use the locked signal in the RTL kernel to ensure the clock is operating correctly.
After adding the frequency synthesizer to an RTL kernel, the generated clocks are not automatically scalable. Ensure the RTL kernel passes timing requirements, or v++ will return an error like the following:
ERROR: [VPL-1] design did not meet timing - Design did not meet timing. One 
or more unscalable system clocks did not meet their required target 
frequency. Please try specifying a clock frequency lower than 300 MHz using 
the '--kernel_frequency' switch for the next compilation. For all system 
clocks, this design is using 0 nanoseconds as the threshold worst negative 
slack (WNS) value. List of system clocks with timing failure.

In this case you will need to change the internal clock frequency, or optimize the kernel logic to meet timing.