设备电源管理数据类型【ChatGPT】

• https://www.kernel.org/doc/html/v6.6/driver-api/pm/types.html

struct dev_pm_ops

device PM callbacks.

Definition:

struct dev_pm_ops {
    int (*prepare)(struct device *dev);
    void (*complete)(struct device *dev);
    int (*suspend)(struct device *dev);
    int (*resume)(struct device *dev);
    int (*freeze)(struct device *dev);
    int (*thaw)(struct device *dev);
    int (*poweroff)(struct device *dev);
    int (*restore)(struct device *dev);
    int (*suspend_late)(struct device *dev);
    int (*resume_early)(struct device *dev);
    int (*freeze_late)(struct device *dev);
    int (*thaw_early)(struct device *dev);
    int (*poweroff_late)(struct device *dev);
    int (*restore_early)(struct device *dev);
    int (*suspend_noirq)(struct device *dev);
    int (*resume_noirq)(struct device *dev);
    int (*freeze_noirq)(struct device *dev);
    int (*thaw_noirq)(struct device *dev);
    int (*poweroff_noirq)(struct device *dev);
    int (*restore_noirq)(struct device *dev);
    int (*runtime_suspend)(struct device *dev);
    int (*runtime_resume)(struct device *dev);
    int (*runtime_idle)(struct device *dev);
};

Members

这段文本详细描述了Linux内核中设备驱动程序中的回调函数，用于实现设备的电源管理。这些回调函数包括：

• prepare：这个回调的主要作用是在返回后防止设备的新子设备被注册（一旦prepare()成功，驱动程序的子系统和通常内核的其余部分也应该防止对probe方法的新调用）。如果prepare()检测到无法处理的情况（例如正在进行子设备的注册），它可以返回-EAGAIN，以便PM核心可以再次执行它（例如在新的子设备已经注册后）来恢复竞争条件。这个方法对所有种类的挂起转换都会执行，并且会在suspend()、freeze()或poweroff()之一之后执行。如果转换是从挂起到内存或待机（即与休眠无关），prepare()的返回值可以用来指示PM核心在适用的情况下将设备保持在运行时挂起状态。换句话说，如果prepare()返回一个正数，PM核心将理解为声明设备似乎已经处于运行时挂起状态，并且在整个转换期间以及后续的恢复期间，如果它的所有子设备也保持在运行时挂起状态，可以将其保持在该状态。如果发生这种情况，complete()将在prepare()之后直接执行，并且必须确保系统恢复后设备的正常运行。PM核心在开始调用任何设备的挂起回调之前，会为所有设备执行子系统级别的prepare()，因此通常可以假定在执行prepare()时设备是可用的或者可以响应运行时恢复请求。但是，设备驱动程序在此时不应假定用户空间的可用性，并且在prepare()中请求固件是无效的（现在做这个已经太晚了）。在GFP_KERNEL模式下，从prepare()中分配大量内存也是无效的。[为了解决这些限制，驱动程序可以注册挂起和休眠通知程序，在冻结任务之前执行。]

• complete：撤消prepare()所做的更改。这个方法对所有种类的恢复转换都会执行，并且会在resume()、thaw()或restore()之一之后执行。如果在驱动程序的挂起回调（suspend()、freeze()或poweroff()）执行之前状态转换失败（例如，如果PM核心先前尝试挂起的其他设备中有一个设备的挂起回调失败），也会执行complete()。PM核心在为所有设备执行适当的恢复回调之后，会执行子系统级别的complete()。如果在挂起转换开始时对应的prepare()返回了一个正数，并且设备被保持在运行时挂起状态（没有为其执行任何挂起和恢复回调），那么在恢复期间complete()将是唯一为设备执行的回调。在这种情况下，complete()必须准备好执行任何必要的操作，以确保系统恢复后设备的正常运行。为此，complete()可以检查设备的power.direct_complete标志，以了解之前的挂起和恢复回调是否已为其执行（未设置）或未执行（已设置）。

• suspend：在将系统置于保留主存储器内容的睡眠状态之前执行。要执行的确切操作取决于设备的子系统（PM域、设备类型、类别或总线类型），但通常在子系统级别的suspend()返回后，设备必须处于静止状态，不执行任何I/O或DMA。在为所有设备执行子系统级别的prepare()之后，会为所有设备执行子系统级别的suspend()。

• resume：在从保留主存储器内容的睡眠状态唤醒系统后执行。要执行的确切操作取决于设备的子系统，但通常期望驱动程序重新开始工作，响应硬件事件和软件请求（设备本身可能处于低功耗状态，等待运行时恢复的发生）。在大多数平台上，在执行resume()期间，资源如时钟的可用性没有限制。在为所有设备执行子系统级别的resume_noirq()之后，会为所有设备执行子系统级别的resume()。

• freeze：特定于休眠，用于创建休眠镜像之前执行。类似于suspend()，但不应使设备发出唤醒事件或更改其电源状态。大多数子系统（PCI总线类型是一个明显的例外）期望驱动级别的freeze()将设备设置保存在内存中，以便在随后的从休眠恢复期间由restore()使用。在为所有设备执行子系统级别的prepare()之后，会为所有设备执行子系统级别的freeze()。

• thaw：特定于休眠，用于创建休眠镜像后执行，或者如果创建镜像失败后执行。也会在尝试从镜像中恢复主存储器内容失败后执行。撤消前面的freeze()所做的更改，使设备可以像在调用freeze()之前一样操作。在为所有设备执行子系统级别的thaw_noirq()之后，会为所有设备执行子系统级别的thaw()。在发生转换错误的情况下，也可能直接在freeze()之后执行。

• poweroff：特定于休眠，用于保存休眠镜像后执行。类似于suspend()，但不需要在内存中保存设备的设置。在为所有设备执行子系统级别的prepare()之后，会为所有设备执行子系统级别的poweroff()。

• restore：特定于休眠，用于从休眠镜像中恢复主存储器内容后执行，类似于resume()。

• suspend_late：继续由suspend()开始的操作。对于许多设备，suspend_late()可能指向与运行时挂起回调相同的回调例程。

• resume_early：准备执行resume()。对于许多设备，resume_early()可能指向与运行时恢复回调相同的回调例程。

• freeze_late：继续由freeze()开始的操作。类似于suspend_late()，但不应使设备发出唤醒事件或更改其电源状态。

• thaw_early：准备执行thaw()。撤消前面的freeze_late()所做的更改。

• poweroff_late：继续由poweroff()开始的操作。类似于suspend_late()，但不需要在内存中保存设备的设置。

• restore_early：准备执行restore()，类似于resume_early()。

• suspend_noirq：完成由suspend()开始的操作。执行可能与其驱动程序的中断处理程序竞争的任何需要的挂起设备的附加操作，保证在执行suspend_noirq()时不会运行其驱动程序的中断处理程序。通常预期在子系统级别的suspend_noirq()成功返回后，设备将处于适合目标系统睡眠状态的低功耗状态。如果设备可以生成系统唤醒信号并且已启用唤醒系统，则应在此时配置它。但是，根据平台和设备的子系统，可能允许suspend()或suspend_late()将设备置于低功耗状态并配置其生成唤醒信号，在这种情况下通常不需要定义suspend_noirq()。

• resume_noirq：准备执行resume()，执行可能与其驱动程序的中断处理程序竞争的任何需要的恢复设备的附加操作，保证在执行resume_noirq()时不会运行其驱动程序的中断处理程序。

• freeze_noirq：完成由freeze()开始的操作。执行可能与其驱动程序的中断处理程序竞争的任何需要的冻结设备的附加操作，保证在执行freeze_noirq()时不会运行其驱动程序的中断处理程序。设备的电源状态不应该被freeze()、freeze_late()或freeze_noirq()改变，也不应该被配置为通过这些回调发出系统唤醒信号。

• thaw_noirq：准备执行thaw()，执行可能与其驱动程序的中断处理程序竞争的任何需要的解冻设备的附加操作，保证在执行thaw_noirq()时不会运行其驱动程序的中断处理程序。

• poweroff_noirq：完成由poweroff()开始的操作。类似于suspend_noirq()，但不需要在内存中保存设备的设置。

• restore_noirq：准备执行restore()，执行可能与其驱动程序的中断处理程序竞争的任何需要的解冻设备的附加操作，保证在执行restore_noirq()时不会运行其驱动程序的中断处理程序，类似于resume_noirq()。

• runtime_suspend：准备设备进入无法与CPU和RAM通信的状态，不一定意味着将设备置于低功耗状态。例如，如果设备位于即将关闭的链路后面，设备可能保持全功率。如果设备确实进入低功耗状态并且能够生成运行时唤醒事件，应该为其启用远程唤醒（即，一种允许设备通过中断请求改变其电源状态的硬件机制）。

• runtime_resume：响应硬件生成的唤醒事件或软件请求，将设备置于完全活动状态。如果必要，将设备置于全功率状态并恢复其寄存器，使其完全可操作。

• runtime_idle：设备似乎处于非活动状态，如果满足所有必要条件，可能会被置于低功耗状态。检查这些条件，如果适合让PM核心为设备排队一个挂起请求，则返回0。

描述

多个设备电源状态转换对外可见，影响待处理的I/O队列的状态和（对于接触硬件的驱动程序）中断、唤醒、DMA和其他硬件状态。还可能存在对各种低功耗模式的内部转换，对于驱动程序堆栈的其余部分来说是透明的（例如，一个驱动程序正在关闭未处于活动使用状态的时钟）。

外部可见的转换是通过在此结构中包含的回调函数来处理的，通常涉及两个级别的回调。首先，PM核心执行由PM域、设备类型、类和总线类型提供的回调函数。它们是预期执行由设备驱动程序提供的回调函数的子系统级回调函数，尽管它们可以选择不这样做。如果执行驱动程序回调函数，则它们必须与子系统级回调函数协作，以实现适合给定系统转换、转换阶段和设备所属子系统的目标。

除了complete()之外，上述所有回调函数都返回错误代码。但是，resume()、thaw()、restore()、resume_noirq()、thaw_noirq()和restore_noirq()返回的错误代码不会导致PM核心在返回它们的恢复转换期间中止。在这些情况下返回的错误代码仅用于打印到系统日志以进行调试。尽管如此，建议驱动程序仅在发生无法恢复的故障（即，正在处理的设备拒绝恢复并变得不可用）时从其恢复方法返回错误代码，以便将来可以修改PM核心，以避免尝试处理无法恢复和其子设备的设备。

在执行上述回调函数时，允许注销设备。但是，回调例程不得尝试注销为其调用的设备，尽管它可以注销该设备的子设备（例如，如果它检测到在系统休眠时拔下了一个子设备）。

还有与设备的运行时电源管理相关的回调函数。同样，通常情况下，这些回调函数由PM核心执行，用于子系统（PM域、设备类型、类和总线类型），并且预期子系统级回调函数调用驱动程序回调函数。此外，设备驱动程序的回调函数要执行的确切操作通常取决于设备所属的平台和子系统。

有关设备运行时电源管理中runtime_suspend()、runtime_resume()和runtime_idle()回调函数的作用的更多信息，请参阅I/O设备的运行时电源管理框架。

struct dev_pm_domain

power management domain representation.

Definition:

struct dev_pm_domain {
    struct dev_pm_ops       ops;
    int (*start)(struct device *dev);
    void (*detach)(struct device *dev, bool power_off);
    int (*activate)(struct device *dev);
    void (*sync)(struct device *dev);
    void (*dismiss)(struct device *dev);
};

成员

ops

与该域关联的电源管理操作。

start

当用户需要通过该域启动设备时调用。

detach

从该域中移除设备时调用。

activate

在执行总线类型和驱动程序的探测例程之前调用。

sync

在成功驱动程序探测后调用。

dismiss

在驱动程序探测失败后以及驱动程序移除后调用。

描述

电源域提供回调函数，在系统挂起、休眠、系统恢复以及运行时电源管理转换期间执行，而不是在子系统级和驱动程序级回调函数中执行。