4. Runtime PM 回调函数：struct dev_pm_ops 中的 runtime_suspend、runtime_resume、runtime_idle

Runtime PM 的核心机制依赖于设备驱动向 PM 核心注册的三个回调函数。它们定义在 struct dev_pm_ops 结构体中，分别对应设备进入低功耗状态、恢复全速运行以及空闲通知。理解这三个回调的触发时机与实现规范，是编写正确 Runtime PM 驱动的关键。

4.1 回调函数定义与数据结构

在 Linux 内核中，Runtime PM 回调是 struct dev_pm_ops 的一部分。该结构体同时包含了系统睡眠（Suspend-to-RAM、Hibernate）的回调，但 Runtime PM 只使用其中三个特定成员：

struct dev_pm_ops {
    // ... 系统睡眠回调（suspend, resume, freeze, poweroff, restore）
    int (*runtime_suspend)(struct device *dev);
    int (*runtime_resume)(struct device *dev);
    int (*runtime_idle)(struct device *dev);
};

4.2 触发时机与状态机

这三个回调的触发由 Runtime PM 核心的状态机控制。设备状态在 RPM_ACTIVE、RPM_SUSPENDED 和 RPM_SUSPENDING/RPM_RESUMING 之间转换。下图展示了核心的触发流程：

4.3 回调实现规范与最佳实践

4.3.1 runtime_suspend 实现规范

• 硬件操作： 关闭设备时钟、关闭电源域、将引脚置于高阻态或下拉状态。
• 上下文保存： 如果设备在挂起后会丢失寄存器状态，必须在关闭时钟前保存关键寄存器。
• 原子性： 该回调在 spinlock 或 mutex 保护下执行，但禁止调用可能导致睡眠的函数（如 msleep），除非明确知道当前上下文允许。
• 返回值： 返回 -EAGAIN 或 -EBUSY 可以暂缓挂起，PM 核心会稍后重试。

static int my_device_runtime_suspend(struct device *dev)
{
    struct my_device *mdev = dev_get_drvdata(dev);

    dev_dbg(dev, "Runtime suspend: saving context and powering off\n");

    // 1. 保存硬件上下文（如果必要）
    mdev->saved_reg = readl(mdev->regs + REG_CTRL);

    // 2. 关闭设备时钟
    clk_disable_unprepare(mdev->clk);

    // 3. 可选：通知电源域控制器
    // regulator_disable(mdev->regulator);

    return 0;
}

4.3.2 runtime_resume 实现规范

• 硬件操作： 开启时钟、恢复电源、重新初始化硬件。
• 上下文恢复： 在硬件准备好后，将保存的寄存器值写回。
• 顺序： 先恢复电源/时钟，再恢复寄存器，最后清除可能挂起的 IRQ。
• 性能： 该回调在设备访问路径上频繁调用，应尽量轻量，避免不必要的延迟。

static int my_device_runtime_resume(struct device *dev)
{
    struct my_device *mdev = dev_get_drvdata(dev);

    dev_dbg(dev, "Runtime resume: powering on and restoring context\n");

    // 1. 开启设备时钟
    clk_prepare_enable(mdev->clk);

    // 2. 恢复硬件上下文
    writel(mdev->saved_reg, mdev->regs + REG_CTRL);

    // 3. 重新初始化硬件状态机
    writel(INIT_VAL, mdev->regs + REG_STATUS);

    return 0;
}

4.3.3 runtime_idle 实现规范

• 决策点： 驱动在此回调中判断设备是否真的可以进入低功耗状态。
• 典型操作： 调用 pm_runtime_autosuspend() 或 pm_request_autosuspend() 来启动延迟挂起。
• 避免直接挂起： 通常不直接在 runtime_idle 中调用 pm_runtime_suspend()，而是使用自动挂起机制，以避免频繁的挂起/恢复震荡。
• 返回值： 返回 -EAGAIN 表示驱动暂不处理空闲通知，PM 核心会继续尝试。

static int my_device_runtime_idle(struct device *dev)
{
    struct my_device *mdev = dev_get_drvdata(dev);

    dev_dbg(dev, "Runtime idle: device is idle, scheduling autosuspend\n");

    // 使用自动挂起，延迟 100ms 后执行挂起
    pm_runtime_autosuspend(dev);

    // 返回 0 表示已处理空闲通知
    return 0;
}

4.4 回调函数对比速查表

4.5 回调注册与驱动绑定

驱动通过 struct platform_driver 或 struct i2c_driver 等总线驱动结构体中的 driver.pm 字段注册回调：

static const struct dev_pm_ops my_device_pm_ops = {
    .runtime_suspend = my_device_runtime_suspend,
    .runtime_resume  = my_device_runtime_resume,
    .runtime_idle    = my_device_runtime_idle,
};

static struct platform_driver my_device_driver = {
    .driver = {
        .name = "my_device",
        .pm   = &my_device_pm_ops,
    },
    .probe  = my_device_probe,
    .remove = my_device_remove,
};

module_platform_driver(my_device_driver);

4.6 回调执行上下文与锁

Runtime PM 回调的执行上下文取决于调用路径：

• 进程上下文： 当通过 pm_runtime_get_sync()、pm_runtime_put_sync() 等同步接口调用时，回调在调用者进程上下文中执行，可以睡眠。
• 中断上下文： 当通过 pm_runtime_get()、pm_runtime_put() 等异步接口调用时，回调在 PM 工作队列（pm_wq）中执行，同样可以睡眠。
• 原子上下文： 在 spinlock 保护的临界区内，禁止调用任何可能触发 Runtime PM 回调的函数。

PM 核心在调用回调前会持有设备的 power.lock（spinlock_t 类型），因此回调内部不能再次尝试获取该锁，否则会导致 spinlock 递归死锁。

4.7 调试与验证

在开发阶段，可以通过以下方式验证回调是否正确触发：

• 动态调试： 在回调中加入 dev_dbg() 或 trace_printk()，通过 echo 'file my_driver.c +p' > /sys/kernel/debug/dynamic_debug/control 开启。
• PM 统计： 查看 /sys/devices/.../power/ 下的 runtime_status、runtime_usage、runtime_active_time 等文件。
• ftrace： 使用 trace-cmd record -e power:cpu_frequency -e rpm:* 捕获 Runtime PM 事件。