Linux 内核功耗子系统(二):CCF 如何把 时钟树种出来?

功耗子系统设备资源管理这一组文章，主要写的是 Linux 如何把 SoC 上分散的硬件资源，整理成设备模型可以引用、驱动可以消费、框架可以编排的对象。clock 适合放在前面讲，因为它同时具备硬件拓扑、设备树引用、驱动接口和运行期状态传播这几类特征。

Common Clock Framework，简称 CCF。它处理的是一棵 SoC clock tree，单个寄存器开关只是其中的硬件动作。晶振、PLL、mux、divider、gate 共同组成时钟路径；不同 IP 挂在不同分支上；部分分支可以切 parent节点，部分分支可以调 divider进行分频，部分分支只负责 gate开关。CCF 的作用，是把这棵硬件树种成 Linux 内核里的 clock object graph，让驱动通过统一接口使用 clock 资源。

从架构上看，CCF 连接了四类东西：硬件时钟树、clock provider、CCF core、clock consumer。provider 描述硬件，CCF core 维护对象和拓扑，consumer 通过 struct clk 表达需求。设备树夹在 provider 和 consumer 中间，用 phandle 加 clock ID 建立引用关系。

CCF 在设备资源底座中的职责

设备驱动不适合直接操作 clock controller。以 UART、I2C、GPU、VOP、PCIe 这些 IP 为例，驱动实际需要的是“寄存器访问时钟已经打开”“功能时钟达到目标频率”“上游 parent 能提供稳定输入”。至于 PLL 从哪里来、mux 选哪一路、divider 怎么编码、gate 位在哪个 CRU 寄存器里，这些都属于 SoC clock provider 的职责。

CCF 把这条边界固定下来。provider 把硬件能力注册给 CCF core；驱动只拿到 consumer 侧句柄，并通过 clk_prepare_enable()、clk_disable_unprepare()、clk_set_rate()、clk_get_rate() 这类接口表达需求。core 位于中间，负责引用计数、parent 关系、rate 传播、锁和 notifier，再把硬件相关动作交给 provider 的 clk_ops。

放到功耗系统里，clock 不只是“设备能不能跑”的前置条件。runtime PM 进入 idle 时，clock gate 是否关闭会影响动态功耗；OPP 或 devfreq 改性能点时，clock rate 和 regulator 电压约束需要配合；genpd 控制 PM domain 状态时，也常常要和 clock、reset 的时序一起考虑。CCF 因此属于设备资源底座，而不是某个驱动子系统的局部工具。

模型对象：provider、core、consumer 三个视角

读 CCF 源码容易混乱，常见原因是把几个层面的对象混在一起：provider 的私有描述、struct clk_hw、struct clk_core、consumer 拿到的 struct clk。这些对象描述的是同一条 clock 的不同视角。

provider 侧会保留自己的硬件描述结构。Rockchip 平台常见的是 rockchip_clk_branch，它记录寄存器偏移、bit 位、parent 名称、clock ID、flags，以及这条分支是 gate、mux、divider 还是 composite clock。这个对象服务于 SoC driver，目标是把硬件表述清楚。

struct clk_hw 是 provider 暴露给 CCF core 的硬件侧入口。provider 不直接管理 core 内部状态，而是通过 clk_hw 绑定 clk_ops。当 core 需要 enable、disable、set_rate、recalc_rate 时，会进入 provider 的 ops，由 provider 完成寄存器级动作或频率计算。

struct clk_core 是 CCF core 的内部节点。clock tree 在内核中以一组 clk_core 组织起来，每个节点保存 parent/child 拓扑、rate、flags、prepare_count、enable_count、notifier 等状态。rate 传播、parent 切换、引用计数这些通用逻辑，主要发生在 clk_core 这一层。

consumer 侧看到的是 struct clk。驱动通过 devm_clk_get(dev, "baudclk") 之类接口拿到句柄，后续调用 clock API。驱动不关心背后是 CRU、CCU 还是其他 clock controller，也不关心这条 clock 在硬件里由几级 mux/divider/gate 组成。

这几个对象之间形成一条清晰边界：provider 用硬件描述和 clk_hw 暴露能力，CCF core 用 clk_core 维护通用模型，consumer 用 struct clk 消费资源。接口隔离做得越清楚，SoC 差异越容易被压在 provider 内部。

接口与交联：clock ID、clock name、parent name

CCF 的运行不是只靠对象本身，还依赖几类标识关系。设备树里的 phandle 和 clock ID 用来连接 provider 与 consumer；provider 注册时的 clock name 用来建立 clock tree；parent name 用来把单个 clock 节点挂到上游；clock-names 用来把 DTS 中的 clock 列表映射到驱动内部的逻辑名字。

provider node 通常会声明 #clock-cells。consumer node 通过 clocks = <&cru SCLK_UART2> 这类写法引用 provider 表里的某个 clock。这里的 SCLK_UART2 是 dt-binding 中定义的 clock ID，面向设备树 ABI，不等同于 provider 注册时的 clock name。

provider 注册 clock 时，一条 clock 至少要回答几个问题：这条 clock 的 ID 是什么，名字是什么，parent 是谁，支持哪些 ops，是否带特殊 flags。CCF core 收到这些信息后，会把 parent name 解析成父子关系，把一批注册项组织成 clock tree。

consumer 获取 clock 时，流程走的是另一条线。驱动调用 devm_clk_get(dev, "baudclk")，core 根据设备节点中的 clock-names 找到对应位置，再通过 clocks 属性里的 phandle 和 ID 定位 provider 中的 clock。驱动拿到的是 struct clk，后续操作再回到 clk_core 和 provider ops。

这样看，CCF 的数据流和控制流可以分开理解。数据流在初始化阶段完成：provider 表项、DTS 引用、dt-binding ID、parent name 被解析成对象图。控制流发生在运行期：driver 调用 clock API，core 处理通用语义，再调用 provider ops 修改硬件。

RK3588 运行示例：UART2 的两条 clock 如何进入 CCF

RK3588 这里只作为运行样例，用来说明上述对象和接口如何落地。它的 CRU 是 clock provider，设备树中 CRU 节点声明自己提供 clock 和 reset：

cru: clock-controller@fd7c0000 {
    compatible = "rockchip,rk3588-cru";
    reg = <0x0 0xfd7c0000 0x0 0x5c000>;
    #clock-cells = <1>;
    #reset-cells = <1>;
};

UART2 节点作为 consumer，引用了两条 clock：

uart2: serial@feb50000 {
    compatible = "rockchip,rk3588-uart", "snps,dw-apb-uart";
    clocks = <&cru SCLK_UART2>, <&cru PCLK_UART2>;
    clock-names = "baudclk", "apb_pclk";
};

SCLK_UART2 和 PCLK_UART2 是 dt-binding 中的 clock ID：

#define PCLK_UART2   160
#define SCLK_UART2   175

这段 DTS 同时建立了两组关系。&cru + SCLK_UART2 指向 CRU provider 表中的串口功能时钟；clock-names = "baudclk" 把这条 clock 绑定到 UART driver 内部的 baud clock 需求。PCLK_UART2 则对应 APB register clock，驱动里通常叫 apb_pclk。

provider 侧，clk-rk3588.c 会用表项描述 UART2 相关分支：

PNAME(clk_uart2_p) = { "clk_uart2_src", "clk_uart2_frac", "xin24m" };

COMPOSITE(CLK_UART2_SRC, "clk_uart2_src", gpll_cpll_p, 0, ...);
COMPOSITE_FRACMUX(CLK_UART2_FRAC, "clk_uart2_frac", "clk_uart2_src", ...,
                  &rk3588_uart2_fracmux);
MUX(CLK_UART2, "clk_uart2", clk_uart2_p, CLK_SET_RATE_PARENT, ...);
GATE(SCLK_UART2, "sclk_uart2", "clk_uart2", 0, ...);
GATE(PCLK_UART2, "pclk_uart2", "pclk_top_root", 0, ...);

这里能看到两条路径。SCLK_UART2 这条功能时钟来自 clk_uart2_src / clk_uart2_frac / clk_uart2 / sclk_uart2 组成的链路，里面包含 source、fractional divider、mux 和 gate。PCLK_UART2 则挂在 pclk_top_root 下，负责 APB 侧寄存器访问。

系统启动时，CRU provider 把这些分支注册成 CCF 对象。DTS 中的 ID 让 UART2 找到对应 clock，parent name 让 CCF core 建起拓扑。运行期 UART driver 调用 prepare/enable，core 先处理引用计数和父子关系，再进入 provider ops 写 CRU 寄存器。调用 set_rate 时，rate 请求会沿 clk_core parent 链传播，必要时进入 mux、divider 或 fractional divider 的 ops。

这个例子说明的是 CCF 的通用运行方式：provider 负责翻译 SoC 硬件，CCF core 负责组织对象图和传播操作，consumer 通过标准接口使用资源。RK3588 只是把这条链路具体化。

回到设备资源管理

从设备资源管理视角看，CCF 的价值在于把 clock 从硬件细节转成标准资源模型。驱动不再直接面对 CRU 寄存器，而是面对一个可以获取、使能、关闭、调频、查询的 clock 资源。这个资源有拓扑、有状态、有 provider ops，也能被设备树和 driver core 连接起来。

后续看 regulator、reset、genpd、OPP 时，可以沿用同一套视角：从硬件资源出发，看 provider 如何描述资源、core 如何抽象对象、consumer 如何引用和使用，以及运行期动作如何沿对象关系传播。CCF 是这套设备资源底座里最典型的一条线，因为它把硬件拓扑、接口契约和运行期数据流都展示得很完整。