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-clksrange, 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
-EIOif 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
-EINVALif 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
-ETIMEDOUTon 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
-EINVALif the rate is not exactly reachable that way.