4. CPUFreq 核心数据结构：结构体定义与字段解析

CPUFreq 子系统的软件架构围绕三个核心数据结构展开：cpufreq_policy（策略）、cpufreq_driver（驱动）和 cpufreq_governor（调节器）。这三个结构体共同定义了 CPU 频率调节的完整工作流：驱动提供硬件能力，调节器决定何时调频，策略则作为上下文容器串联两者。理解它们的字段含义是进行驱动开发和功耗优化的第一步。

4.1 cpufreq_policy：频率调节的“上下文容器”

cpufreq_policy 是每个 CPU 集群（policy 实例）的频率管理上下文。它记录了当前频率范围、调节器实例、驱动回调、以及调频过程中的同步状态。该结构体定义在 include/linux/cpufreq.h 中，核心字段如下：

4.2 cpufreq_driver：硬件操作的“抽象层”

cpufreq_driver 是驱动开发者需要实现的核心结构体。它定义了 CPUFreq 子系统与硬件交互的所有回调函数。每个注册的 cpufreq_driver 实例代表一种频率控制硬件方案（如 cpufreq-dt、acpi-cpufreq、intel_pstate）。

struct cpufreq_driver {
    const char          *name;
    unsigned int        flags;

    /* 必需回调 */
    int (*init)(struct cpufreq_policy *policy);
    int (*verify)(struct cpufreq_policy_data *policy);
    int (*setpolicy)(struct cpufreq_policy *policy);
    int (*target)(struct cpufreq_policy *policy,
                  unsigned int target_freq,
                  unsigned int relation);
    unsigned int (*get)(unsigned int cpu);

    /* 可选回调 */
    int (*exit)(struct cpufreq_policy *policy);
    int (*suspend)(struct cpufreq_policy *policy);
    int (*resume)(struct cpufreq_policy *policy);
    int (*online)(struct cpufreq_policy *policy);
    int (*offline)(struct cpufreq_policy *policy);
    void (*update_limits)(struct cpufreq_policy *policy);
};

4.3 cpufreq_governor：频率决策的“算法引擎”

cpufreq_governor 定义了频率调节的决策逻辑。每个 governor 通过注册该结构体来接入 CPUFreq 框架。内核内置了 performance、powersave、userspace、ondemand、conservative、schedutil 等 governor。

struct cpufreq_governor {
    const char          *name;
    unsigned int        flags;

    /* 状态机回调 */
    int (*init)(struct cpufreq_policy *policy);
    void (*exit)(struct cpufreq_policy *policy);
    int (*start)(struct cpufreq_policy *policy);
    void (*stop)(struct cpufreq_policy *policy);
    void (*limits)(struct cpufreq_policy *policy);

    /* 频率调整回调（仅用于非 schedutil 类 governor） */
    void (*dbs_update)(struct cpufreq_policy *policy);
    unsigned int (*dbs_target)(struct cpufreq_policy *policy,
                               unsigned int target_freq);
};

4.4 三大结构体的协作关系

下图展示了 cpufreq_policy、cpufreq_driver 和 cpufreq_governor 在频率调节工作流中的协作关系：

4.5 关键字段的初始化时机与生命周期

理解字段何时被赋值、何时被读取，对驱动调试至关重要。下表总结了三个结构体中关键字段的初始化时机：

4.6 结构体之间的指针关系图

下面的 SVG 图展示了三个结构体在内存中的指针连接关系，帮助理解数据流向：

4.7 驱动开发中的字段使用要点

• 不要直接修改 policy->cur：该字段由 CPUFreq 核心层在驱动 target 回调返回后自动更新。驱动只需在 get 回调中返回硬件实际频率即可。
• 使用 policy->transition_lock 保护临界区：如果驱动在 target 回调中需要访问共享寄存器，应使用 mutex_lock(&policy->transition_lock) 确保原子性。
• 正确设置 policy->cpus：对于 DSU 或集群架构，如果多个 CPU 共享同一电压域，必须通过 cpumask_set_cpu 将所有受影响 CPU 加入 cpus 掩码，否则调频操作可能遗漏某些 CPU。
• 利用 driver_data 传递平台信息：在 init 回调中分配结构体（如 struct cpufreq_dt_private），将 OPP 表句柄、regmap、时钟句柄等存入其中，避免使用全局变量。
• governor 的 limits 回调不可忽略：当用户通过 sysfs 修改 scaling_min_freq 或 scaling_max_freq 时，limits 回调会被触发。governor 必须在此回调中重新评估当前频率是否超出新范围，必要时立即调频。