rt-thread/documentation/6.components/device-driver/clk/fixed.md

@page page_device_clk_fixed Fixed clock provider

fixed-clock platform driver

Implementation: components/drivers/clk/clk-fixed-rate.c. Driver name: clk-fixed-rate. Overview: @ref page_device_clk.

Registers a constant-frequency, always-on clock with no gate, parent, or rate programming — the leaf most SoC trees hang PLLs from.

---

Device tree

osc24m: fixed-clock {
    compatible = "fixed-clock";
    #clock-cells = <0>;
    clock-frequency = <24000000>;
    clock-accuracy = <0>;          /* optional, ppb */
    clock-output-names = "osc24m"; /* optional; becomes cell name */
};

Consumers:

uart0: serial@40000000 {
    clocks = <&osc24m>;
    /* clock-names optional when only one clock */
};

With #clock-cells = <0>, the specifier in clocks = <&osc24m> has no extra integers (implicit index 0).

---

Probe flow

1. rt_platform_driver_register via INIT_SUBSYS_EXPORT(fixed_clk_drv_register) — early registration so crystal nodes probe before CCM consumers.
2. fixed_clk_probe: rt_calloc struct clk_fixed (embeds rt_clk_node + one rt_clk_fixed_rate).
3. rt_dm_dev_prop_read_u32(dev, "clock-frequency", &val) — required; probe fails without it.
4. Optional clock-accuracy, clock-output-names → fcell.cell.name.
5. Wire cells[0], fixed_clk_ops (only .recalc_rate).
6. rt_clk_register(&cf->parent) — may run rt_ofw_clk_set_defaults if the fixed-clock node has assigned-clocks* (unusual on leaf osc).

---

Data structures

struct clk_fixed {
    struct rt_clk_node parent;
    struct rt_clk_fixed_rate fcell;
    struct rt_clk_cell *cells[1];
};

struct rt_clk_fixed_rate {
    struct rt_clk_cell cell;
    rt_ubase_t fixed_rate;
    rt_ubase_t fixed_accuracy;
};

Member	Role
fixed_rate	Hz from clock-frequency
fixed_accuracy	Optional ppb from DT
cell.ops->recalc_rate	Returns fixed_rate; ignores parent

No enable/disable/prepare — enabling is a no-op at ops level; framework refcount still works for consumers.

---

OFW matching

static const struct rt_ofw_node_id fixed_clk_ofw_ids[] = {
    { .compatible = "fixed-clock" },
    { /* sentinel */ }
};

Linux-compatible binding; same node can be shared across BSP DTS and upstream dt-bindings.

---

When to use vs SoC CCM

Use fixed-clock	Use SoC driver (e.g. rockchip,*-cru)
Crystal, RC oscillator, external clock input	PLL, mux, divider, gate
Rate fixed at boot	DVFS, dynamic reparent
No MMIO (or MMIO not managed here)	Large clock controller IP

---

Consumer example

struct rt_clk *clk = rt_clk_get_by_name(dev, "uart_clk");
/* or index 0 if no clock-names */
rt_err_t err = rt_clk_prepare_enable(clk);
rt_ubase_t hz = rt_clk_get_rate(clk);

Fixed clocks rarely need rt_clk_set_rate — rate is fixed; rt_clk_get_rate reads recalc_rate.

---

Pitfalls

• Missing clock-frequency — probe fails, phandle resolution returns NULL for consumers.
• Wrong Hz in DT — all derived PLL math wrong; UART baud, SDIO timing, etc. break silently.
• Using fixed-clock for gated peripherals — use a gate driver cell instead.
• Name collisions — clock-output-names should be unique enough for rt_clk_get_by_name fallback lookup.

See also

• @ref page_device_clk
• components/drivers/clk/clk-fixed-rate.c
• components/drivers/include/drivers/clk.h