Zephyr Clocking Wizard Driver Implementation

This page provides details on the implementation of the Xilinx AXI Clocking Wizard (xlnx,clkx5-wiz-1.0) Zephyr driver.

Clock Control Layer

The driver registers with the Zephyr clock control framework (clock_control.h). Callers use the generic clock_control_* API instead of touching the Clocking Wizard register map directly. Callers select the output clock to operate on by passing its 0-based index (0 to xlnx,num-out-clks - 1) as the clock_control_subsys_t argument.

Clocking Wizard Node

clk_wiz_0: clock-controller@b2000000 {
        compatible = "xlnx,clkx5-wiz-1.0";
        reg = <0x0 0xb2000000 0x0 0x10000>;
        clocks = <&ref_clk_100mhz>;
        #clock-cells = <1>;
        xlnx,num-out-clks = <1>;
        status = "okay";
};

zephyr/drivers/clock_control/CMakeLists.txt

zephyr_library_sources_ifdef(CONFIG_CLOCK_CONTROL_XCLK_WIZ clock_control_xclk_wiz.c)

zephyr/drivers/clock_control/Kconfig

source "drivers/clock_control/Kconfig.xclk_wiz"

zephyr/drivers/clock_control/Kconfig.xclk_wiz

config CLOCK_CONTROL_XCLK_WIZ
        bool "Xilinx Clock Wizard driver"
        default y
        depends on DT_HAS_XLNX_CLKX5_WIZ_1_0_ENABLED
        help
                Enable the Xilinx Clocking Wizard (clkx5-wiz-1.0) clock
                control driver for AMD Versal Gen 2 platforms.

zephyr/dts/bindings/clock/xlnx,clkx5-wiz-1.0.yaml

description: Xilinx Clocking Wizard (clkx5-wiz-1.0) for Versal Gen 2.

compatible: "xlnx,clkx5-wiz-1.0"

include: [clock-controller.yaml, base.yaml]

properties:
  reg:
    required: true

  clocks:
    required: true
    description: Phandles to the input reference clocks for the MMCM.

  "#clock-cells":
    const: 1

  xlnx,num-out-clks:
    type: int
    required: true
    description: Number of active output clocks configured in the IP (1 to 7).
    enum: [1, 2, 3, 4, 5, 6, 7]

clock-cells:
  - clkid

Probe Data From Node

The driver assigns the compatible string to DT_DRV_COMPAT (xlnx_clkx5_wiz_1_0). On init, it maps the register region and looks up the clocks phandle’s device. It then calls clock_control_get_rate() on that device to learn the reference input frequency, and caches that value together with xlnx,num-out-clks in its per-instance config/data structures. Finally, it registers its API table with the clock control framework.

#define CLK_WIZ_DEVICE_INIT(inst)                                              \
    static struct xlnx_clk_wiz_data xlnx_clk_wiz_data_##inst;                  \
                                                                               \
    static const struct xlnx_clk_wiz_config xlnx_clk_wiz_config_##inst = {     \
        DEVICE_MMIO_ROM_INIT(DT_DRV_INST(inst)),                               \
        .parent_clk = DEVICE_DT_GET(DT_INST_CLOCKS_CTLR(inst)),                \
        .num_out_clks = DT_INST_PROP(inst, xlnx_num_out_clks),                 \
    };                                                                         \
                                                                               \
    DEVICE_DT_INST_DEFINE(inst, xlnx_clk_wiz_init, NULL,                       \
                          &xlnx_clk_wiz_data_##inst,                           \
                          &xlnx_clk_wiz_config_##inst, POST_KERNEL,            \
                          CONFIG_CLOCK_CONTROL_INIT_PRIORITY,                  \
                          &xlnx_clk_wiz_api);

DT_INST_FOREACH_STATUS_OKAY(CLK_WIZ_DEVICE_INIT)

Clock Control Framework

The clock control framework has a structure where drivers register their APIs by following the same protocol used in the structure that follows.

Framework Structure

__subsystem struct clock_control_driver_api {
    clock_control                on;
    clock_control                off;
    clock_control_async_on_fn    async_on;
    clock_control_get            get_rate;
    clock_control_get_status_fn  get_status;
    clock_control_set            set_rate;
    clock_control_configure_fn   configure;
};

The driver populates only on, off, get_rate, and set_rate. It leaves async_on, get_status, and configure as NULL.

Functional Implementation

on

Args: const struct device *dev, clock_control_subsys_t sys

  • Checks the output index is within the xlnx,num-out-clks range, then sets the “used” bit in that output’s control register under a spinlock. Does not touch the shared MMCM/VCO.

off

Args: const struct device *dev, clock_control_subsys_t sys

  • Clears the “used” bit in the selected output’s control register under a spinlock.

get_rate

Args: const struct device *dev, clock_control_subsys_t sys, uint32_t *rate

  • Reconstructs the current VCO frequency from the shared M/D divider registers and the cached reference input frequency, then divides by the selected output’s programmed leaf divider to compute the output frequency. Returns -EIO if the reconstructed VCO frequency is zero.

set_rate

Args: const struct device *dev, clock_control_subsys_t sys, clock_control_subsys_rate_t rate

  • Searches for the M/D/O divisor combination closest to the requested rate within the IP’s VCO/M/D/O ranges (stopping early on an exact match); returns -EINVAL if none exists.

  • If no other output of the instance is currently active: programs M, D, and O, triggers a reconfiguration load, and polls the MMCM locked status bit (100 ms timeout, returns -ETIMEDOUT on failure).

  • If another output is already active: keeps the existing (shared) VCO fixed and only recomputes/reprograms the requested output’s leaf divider; fails with -EINVAL if the rate is not exactly reachable that way.