Identifying Platform Clocks - 2023.2 English

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

Document ID
Release Date
2023.2 English

The handling of clocks in platforms has evolved to support multiple platform clocks and clock frequencies. The kernels can have any number of independent and edge-aligned clocks, and platforms can have multiple kernels running at different clock frequencies under user-control. Platforms have a variety of clocking: processor, PL, and AI Engine clocking. The following table explains the clocking for each.

Table 1. Platform Clocks
Clock Description
AI Engine Can be configured in the platform in the AI Engine IP.
Processor Can be configured in the platform in the CIPS IP.
Programmable Logic (PL) Can have multiple clocks and can be configured in the platform.
NoC Device dependent and can be configured in the platform in the CIPS and NoC IP.
  1. These clocks are derived from the platform and are affected by the device, speed grade, and operating voltage.

A platform can have scalable clocks and fixed clocks.

Scalable Clocks

An AMD Alveo™ platform provides a frequency scalable kernel clock with ID (or Index) 0 that drives all XRT managed kernels. XRT can set the clock frequency of this clock according to the metadata contained in the xclbin file, when loading the file. An Alveo platform also provides a second scalable clock with ID 1 that is also controllable based on xclbin metadata. You do not need to provide an option to connect to scalable clocks, but you can specify the clock frequency during v++ linking using the --freqhz option or --kernel_frequency, as described in v++ General Options. The v++ linker automatically connects PL kernel clocks ap_clk to clock ID 0, and ap_clk2 to clock ID 1.

Tip: In practice, ap_clk2 is primarily found on RTL kernels, because the HLS compiler does not generate kernels with multiple clocks.
Fixed Clocks

Fixed clocks can be found on both AMD Alveo™ platforms and embedded platforms using Versal devices or Zynq MPSoC. Fixed clocks are also typically used in RTL kernels.

Scalable clocks are scaled by XRT to meet the clock specified in the v++ command and the timing requirements of the design. Fixed clocks use MMCMs added to the design to generate frequencies other than the fixed frequencies defined on the platform. For example, if you specify clock frequencies: 60, 200, and 450, the Vitis compiler adds all the necessary logic to generate the required clocks from the available fixed clocks.

Use the --freqhz option to specify the clock frequency for the design. The --clock Options can be also used to specify PL kernel connections to specific platform clocks, or to specify clock frequencies that are generated from fixed clocks on the platform.

Specifying the --clock options directs v++ to use the fixed clocks of a platform, rather then the scalable clocks. For HLS kernels, the clock ID 0 is always used. For RTL kernels with one clock, clock ID 0 is used by default, but you can select a different clock.

Tip: You cannot mix fixed and scalable clocks on a single kernel, but these can be mixed across different kernels within a single .xclbin file.

If Vivado place and route tools are unable to meet the frequency specification, the tools can scale the clock frequency to an achievable frequency if the scalable clock has been used (--kernel_frequency). However, if a fixed clock is used (--clock), then you need to re-run the implementation to update the frequency target.

You can determine the clocks available in the target platform by using the platforminfo command. For example, the following command returns verbose information related to the specified platform and writes it to an output file:
platforminfo -v -p xilinx_u250_gen3x16_xdma_4_1_202210_1 -o pfmClocks.txt
The Clock Information is reported in the output file as shown below, indicating the scalable and fixed clocks in the platform:
Clock Information
  Default Clock Index: 0
  Default Clock Frequency: 300.000000
  Default Clock Pretty Name: PL 0
  Clock Index:         0
    Frequency:         300.000000
    Name:              ss_ucs_aclk_kernel_00
    Pretty Name:       PL 0
    Inst Ref:          ss_ucs
    Comp Ref:          shell_ucs_subsystem
    Period:            3.333333
    Normalized Period: .003333
    Status:            scalable
  Clock Index:         1
    Frequency:         500.000000
    Name:              ss_ucs_aclk_kernel_01
    Pretty Name:       PL 1
    Inst Ref:          ss_ucs
    Comp Ref:          shell_ucs_subsystem
    Period:            2.000000
    Normalized Period: .002000
    Status:            scalable
  Clock Index:         2
    Frequency:         50.000000
    Name:              ii_level1_wire_ulp_m_aclk_ctrl_00
    Pretty Name:       PL 2
    Inst Ref:          ii_level1_wire
    Comp Ref:          ii_level1_wire
    Period:            20.000000
    Normalized Period: .020000
    Status:            fixed
  Clock Index:         3

There are a couple of high-level considerations in practice. Scalable clocks help you to achieve timing without having to regenerate the .xclbin file, by allowing the tool to scale the clock as needed to achieve a specific frequency or to meet timing. However, scaling does not increase a scaled clock frequency above the platform frequency. Designs requiring different kernels to run at different frequencies to close timing or to meet performance targets can make use of fixed clocks. For most serious designs, the expectation is that you will at some point know what the achievable frequency targets are for the design, and will need to specify the fixed clocks when they exceed the scalable clock frequencies.

For Versal devices, the --part option can be used instead of --platform with the v++ --link and v++ --package commands. With --part the tool generates a base design for use on the device, and can generally be used while waiting for the development of a full platform specification. However, the v++ linker generated base platform design employs PLRAM only, so is unsuitable for running Linux applications on the target.