Device Power Management Data Types¶

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

prepare: The principal role of this callback is to prevent new children of the device from being registered after it has returned (the driver’s subsystem and generally the rest of the kernel is supposed to prevent new calls to the probe method from being made too once prepare() has succeeded). If prepare() detects a situation it cannot handle (e.g. registration of a child already in progress), it may return -EAGAIN, so that the PM core can execute it once again (e.g. after a new child has been registered) to recover from the race condition. This method is executed for all kinds of suspend transitions and is followed by one of the suspend callbacks: suspend(), freeze(), or poweroff(). If the transition is a suspend to memory or standby (that is, not related to hibernation), the return value of prepare() may be used to indicate to the PM core to leave the device in runtime suspend if applicable. Namely, if prepare() returns a positive number, the PM core will understand that as a declaration that the device appears to be runtime-suspended and it may be left in that state during the entire transition and during the subsequent resume if all of its descendants are left in runtime suspend too. If that happens, complete() will be executed directly after prepare() and it must ensure the proper functioning of the device after the system resume. The PM core executes subsystem-level prepare() for all devices before starting to invoke suspend callbacks for any of them, so generally devices may be assumed to be functional or to respond to runtime resume requests while prepare() is being executed. However, device drivers may NOT assume anything about the availability of user space at that time and it is NOT valid to request firmware from within prepare() (it’s too late to do that). It also is NOT valid to allocate substantial amounts of memory from prepare() in the GFP_KERNEL mode. [To work around these limitations, drivers may register suspend and hibernation notifiers to be executed before the freezing of tasks.]
complete: Undo the changes made by prepare(). This method is executed for all kinds of resume transitions, following one of the resume callbacks: resume(), thaw(), restore(). Also called if the state transition fails before the driver’s suspend callback: suspend(), freeze() or poweroff(), can be executed (e.g. if the suspend callback fails for one of the other devices that the PM core has unsuccessfully attempted to suspend earlier). The PM core executes subsystem-level complete() after it has executed the appropriate resume callbacks for all devices. If the corresponding prepare() at the beginning of the suspend transition returned a positive number and the device was left in runtime suspend (without executing any suspend and resume callbacks for it), complete() will be the only callback executed for the device during resume. In that case, complete() must be prepared to do whatever is necessary to ensure the proper functioning of the device after the system resume. To this end, complete() can check the power.direct_complete flag of the device to learn whether (unset) or not (set) the previous suspend and resume callbacks have been executed for it.
suspend: Executed before putting the system into a sleep state in which the contents of main memory are preserved. The exact action to perform depends on the device’s subsystem (PM domain, device type, class or bus type), but generally the device must be quiescent after subsystem-level suspend() has returned, so that it doesn’t do any I/O or DMA. Subsystem-level suspend() is executed for all devices after invoking subsystem-level prepare() for all of them.
resume: Executed after waking the system up from a sleep state in which the contents of main memory were preserved. The exact action to perform depends on the device’s subsystem, but generally the driver is expected to start working again, responding to hardware events and software requests (the device itself may be left in a low-power state, waiting for a runtime resume to occur). The state of the device at the time its driver’s resume() callback is run depends on the platform and subsystem the device belongs to. On most platforms, there are no restrictions on availability of resources like clocks during resume(). Subsystem-level resume() is executed for all devices after invoking subsystem-level resume_noirq() for all of them.
freeze: Hibernation-specific, executed before creating a hibernation image. Analogous to suspend(), but it should not enable the device to signal wakeup events or change its power state. The majority of subsystems (with the notable exception of the PCI bus type) expect the driver-level freeze() to save the device settings in memory to be used by restore() during the subsequent resume from hibernation. Subsystem-level freeze() is executed for all devices after invoking subsystem-level prepare() for all of them.
thaw: Hibernation-specific, executed after creating a hibernation image OR if the creation of an image has failed. Also executed after a failing attempt to restore the contents of main memory from such an image. Undo the changes made by the preceding freeze(), so the device can be operated in the same way as immediately before the call to freeze(). Subsystem-level thaw() is executed for all devices after invoking subsystem-level thaw_noirq() for all of them. It also may be executed directly after freeze() in case of a transition error.
poweroff: Hibernation-specific, executed after saving a hibernation image. Analogous to suspend(), but it need not save the device’s settings in memory. Subsystem-level poweroff() is executed for all devices after invoking subsystem-level prepare() for all of them.
restore: Hibernation-specific, executed after restoring the contents of main memory from a hibernation image, analogous to resume().
suspend_late: Continue operations started by suspend(). For a number of devices suspend_late() may point to the same callback routine as the runtime suspend callback.
resume_early: Prepare to execute resume(). For a number of devices resume_early() may point to the same callback routine as the runtime resume callback.
freeze_late: Continue operations started by freeze(). Analogous to suspend_late(), but it should not enable the device to signal wakeup events or change its power state.
thaw_early: Prepare to execute thaw(). Undo the changes made by the preceding freeze_late().
poweroff_late: Continue operations started by poweroff(). Analogous to suspend_late(), but it need not save the device’s settings in memory.
restore_early: Prepare to execute restore(), analogous to resume_early().
suspend_noirq: Complete the actions started by suspend(). Carry out any additional operations required for suspending the device that might be racing with its driver’s interrupt handler, which is guaranteed not to run while suspend_noirq() is being executed. It generally is expected that the device will be in a low-power state (appropriate for the target system sleep state) after subsystem-level suspend_noirq() has returned successfully. If the device can generate system wakeup signals and is enabled to wake up the system, it should be configured to do so at that time. However, depending on the platform and device’s subsystem, suspend() or suspend_late() may be allowed to put the device into the low-power state and configure it to generate wakeup signals, in which case it generally is not necessary to define suspend_noirq().
resume_noirq: Prepare for the execution of resume() by carrying out any operations required for resuming the device that might be racing with its driver’s interrupt handler, which is guaranteed not to run while resume_noirq() is being executed.
freeze_noirq: Complete the actions started by freeze(). Carry out any additional operations required for freezing the device that might be racing with its driver’s interrupt handler, which is guaranteed not to run while freeze_noirq() is being executed. The power state of the device should not be changed by either freeze(), or freeze_late(), or freeze_noirq() and it should not be configured to signal system wakeup by any of these callbacks.
thaw_noirq: Prepare for the execution of thaw() by carrying out any operations required for thawing the device that might be racing with its driver’s interrupt handler, which is guaranteed not to run while thaw_noirq() is being executed.
poweroff_noirq: Complete the actions started by poweroff(). Analogous to suspend_noirq(), but it need not save the device’s settings in memory.
restore_noirq: Prepare for the execution of restore() by carrying out any operations required for thawing the device that might be racing with its driver’s interrupt handler, which is guaranteed not to run while restore_noirq() is being executed. Analogous to resume_noirq().
runtime_suspend: Prepare the device for a condition in which it won’t be able to communicate with the CPU(s) and RAM due to power management. This need not mean that the device should be put into a low-power state. For example, if the device is behind a link which is about to be turned off, the device may remain at full power. If the device does go to low power and is capable of generating runtime wakeup events, remote wakeup (i.e., a hardware mechanism allowing the device to request a change of its power state via an interrupt) should be enabled for it.
runtime_resume: Put the device into the fully active state in response to a wakeup event generated by hardware or at the request of software. If necessary, put the device into the full-power state and restore its registers, so that it is fully operational.
runtime_idle: Device appears to be inactive and it might be put into a low-power state if all of the necessary conditions are satisfied. Check these conditions, and return 0 if it’s appropriate to let the PM core queue a suspend request for the device.

Description

Several device power state transitions are externally visible, affecting the state of pending I/O queues and (for drivers that touch hardware) interrupts, wakeups, DMA, and other hardware state. There may also be internal transitions to various low-power modes which are transparent to the rest of the driver stack (such as a driver that’s ON gating off clocks which are not in active use).

The externally visible transitions are handled with the help of callbacks included in this structure in such a way that, typically, two levels of callbacks are involved. First, the PM core executes callbacks provided by PM domains, device types, classes and bus types. They are the subsystem-level callbacks expected to execute callbacks provided by device drivers, although they may choose not to do that. If the driver callbacks are executed, they have to collaborate with the subsystem-level callbacks to achieve the goals appropriate for the given system transition, given transition phase and the subsystem the device belongs to.

All of the above callbacks, except for complete(), return error codes. However, the error codes returned by resume(), thaw(), restore(), resume_noirq(), thaw_noirq(), and restore_noirq(), do not cause the PM core to abort the resume transition during which they are returned. The error codes returned in those cases are only printed to the system logs for debugging purposes. Still, it is recommended that drivers only return error codes from their resume methods in case of an unrecoverable failure (i.e. when the device being handled refuses to resume and becomes unusable) to allow the PM core to be modified in the future, so that it can avoid attempting to handle devices that failed to resume and their children.

It is allowed to unregister devices while the above callbacks are being executed. However, a callback routine MUST NOT try to unregister the device it was called for, although it may unregister children of that device (for example, if it detects that a child was unplugged while the system was asleep).

There also are callbacks related to runtime power management of devices. Again, as a rule these callbacks are executed by the PM core for subsystems (PM domains, device types, classes and bus types) and the subsystem-level callbacks are expected to invoke the driver callbacks. Moreover, the exact actions to be performed by a device driver’s callbacks generally depend on the platform and subsystem the device belongs to.

Refer to Runtime Power Management Framework for I/O Devices for more information about the role of the runtime_suspend(), runtime_resume() and runtime_idle() callbacks in device runtime power management.

struct dev_pm_info: Device power management information.

Definition:

struct dev_pm_info {
    pm_message_t power_state;
    bool can_wakeup:1;
    bool async_suspend:1;
    bool in_dpm_list:1;
    bool is_prepared:1;
    bool is_suspended:1;
    bool is_noirq_suspended:1;
    bool is_late_suspended:1;
    bool no_pm:1;
    bool early_init:1;
    bool direct_complete:1;
    u32 driver_flags;
    spinlock_t lock;
#ifdef CONFIG_PM_SLEEP;
    struct list_head        entry;
    struct completion       completion;
    struct wakeup_source    *wakeup;
    bool work_in_progress;
    bool wakeup_path:1;
    bool syscore:1;
    bool no_pm_callbacks:1;
    bool smart_suspend:1;
    bool must_resume:1;
    bool may_skip_resume:1;
    bool out_band_wakeup:1;
    bool strict_midlayer:1;
#else;
    bool should_wakeup:1;
#endif;
#ifdef CONFIG_PM;
    struct hrtimer          suspend_timer;
    u64 timer_expires;
    struct work_struct      work;
    wait_queue_head_t wait_queue;
    struct wake_irq         *wakeirq;
    atomic_t usage_count;
    atomic_t child_count;
    unsigned int            disable_depth:3;
    bool idle_notification:1;
    bool request_pending:1;
    bool deferred_resume:1;
    bool needs_force_resume:1;
    bool runtime_auto:1;
    bool ignore_children:1;
    bool no_callbacks:1;
    bool irq_safe:1;
    bool use_autosuspend:1;
    bool timer_autosuspends:1;
    bool memalloc_noio:1;
    unsigned int            links_count;
    enum rpm_request        request;
    enum rpm_status         runtime_status;
    enum rpm_status         last_status;
    int runtime_error;
    int autosuspend_delay;
    u64 last_busy;
    u64 active_time;
    u64 suspended_time;
    u64 accounting_timestamp;
#endif;
    struct pm_subsys_data   *subsys_data;
    void (*set_latency_tolerance)(struct device *, s32);
    struct dev_pm_qos       *qos;
    bool detach_power_off:1;
};

Members

power_state: Legacy power state (mostly unused in modern kernels).
can_wakeup: Device is capable of generating wakeup signals.
async_suspend: Device can be suspended and resumed asynchronously.
in_dpm_list: Device is on the dpm_list.
is_prepared: Device’s ->prepare() callback has run successfully.
is_suspended: Device is suspended during a system sleep transition.
is_noirq_suspended: Device’s noirq suspend callback has run successfully.
is_late_suspended: Device’s late suspend callback has run successfully.
no_pm: Device does not participate in power management transitions.
early_init: Device was initialized before standard PM initialization.
direct_complete: Device can skip suspend/resume callbacks and remain runtime-suspended during system sleep.
driver_flags: Driver flags (e.g. DPM_FLAG_SMART_SUSPEND) set at probe time.
lock: Spinlock used for synchronizing PM state transitions and runtime PM operations.
entry: List head for device power management lists.
completion: Completion for synchronization during asynchronous system suspend/resume.
wakeup: Wakeup source object associated with the device.
work_in_progress: Asynchronous PM operation in progress.
wakeup_path: Device is in the wakeup path or can wake the system up.
syscore: Device participates in syscore power management operations.
no_pm_callbacks: Device has no PM callbacks; handled by parent or subsystem.
smart_suspend: Driver requested smart-suspend behavior.
must_resume: Device must be resumed during system resume.
may_skip_resume: Set by subsystems to indicate driver resume callbacks may be skipped.
out_band_wakeup: Out-of-band wakeup is supported.
strict_midlayer: Middle layer code does not want callbacks invoked via pm_runtime_force_suspend() / pm_runtime_force_resume().
should_wakeup: Wakeup flag when system sleep is not enabled.
suspend_timer: High-resolution timer used for scheduling delayed runtime suspend and autosuspend requests.
timer_expires: Timer expiration time in nanoseconds monotonic time (runtime PM).
work: Work structure used for queuing up requests into pm_wq (runtime PM).
wait_queue: Wait queue used if any helper functions need to wait for another state change to complete (runtime PM).
wakeirq: Dedicated wakeup interrupt for the device.
usage_count: Device runtime PM usage counter.
child_count: Count of active children of the device (runtime PM).
disable_depth: Disable counter for runtime PM (runtime PM is enabled when this is 0; initial value is 1).
idle_notification: Set if ->runtime_idle() is being executed.
request_pending: Set if a work item is queued into pm_wq (runtime PM).
deferred_resume: Set if ->runtime_resume() should run as soon as ->runtime_suspend() completes.
needs_force_resume: Indicates the device was forced into suspend by pm_runtime_force_suspend() and must be resumed by pm_runtime_force_resume().
runtime_auto: User space has allowed the driver to power manage the device at runtime via sysfs control attribute; also can be set by pm_runtime_allow() or pm_runtime_forbid().
ignore_children: If set, the value of child_count is ignored for runtime suspend and idle decisions.
no_callbacks: Indicates the device does not use runtime PM callbacks.
irq_safe: Indicates runtime PM callbacks will be invoked with the spinlock held and interrupts disabled.
use_autosuspend: Indicates the device driver supports delayed runtime autosuspend.
timer_autosuspends: Indicates the runtime PM core should attempt an autosuspend rather than a normal suspend when the timer expires.
memalloc_noio: Indicates memory allocation during runtime PM transitions must avoid I/O (GFP_NOIO).
links_count: Number of device links that require runtime PM coordination.
request: Type of pending runtime PM request (valid if request_pending is set).
runtime_status: Runtime PM status of the device.
last_status: Last status captured before disabling runtime PM, or RPM_BLOCKED / RPM_INVALID.
runtime_error: Fatal error code returned by a failing callback, blocking helpers until cleared.
autosuspend_delay: Delay time in milliseconds to be used for runtime autosuspend.
last_busy: Timestamp in nanoseconds when pm_runtime_mark_last_busy() was last called. Used in calculating inactivity periods for autosuspend.
active_time: Accumulated time in nanoseconds spent in RPM_ACTIVE state.
suspended_time: Accumulated time in nanoseconds spent in RPM_SUSPENDED state.
accounting_timestamp: Timestamp in nanoseconds of the last runtime PM state accounting update.
subsys_data: Subsystem-specific power management data.
set_latency_tolerance: Callback for setting latency tolerance.
qos: Per-device PM Quality of Service (QoS) constraints.
detach_power_off: Indicates device should be detached from PM domain on power off.

Description

Device power management information stored in the “power” member of struct device.

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);
    int (*set_performance_state)(struct device *dev, unsigned int state);
};

Members

ops: Power management operations associated with this domain.
start: Called when a user needs to start the device via the domain.
detach: Called when removing a device from the domain.
activate: Called before executing probe routines for bus types and drivers.
sync: Called after successful driver probe.
dismiss: Called after unsuccessful driver probe and after driver removal.
set_performance_state: Called to request a new performance state.

Description

Power domains provide callbacks that are executed during system suspend, hibernation, system resume and during runtime PM transitions instead of subsystem-level and driver-level callbacks.

The Linux Kernel

Contents

This Page

Device Power Management Data Types¶