[RFC] Enhancements to Zephyr Power Management

[ceolin]

Proposal for Enhancements to Zephyr Power Management

Introduction

Zephyr’s current power management framework provides mechanisms for managing device power states. However, we propose a refinement to focus exclusively on device runtime power management for better control, simplicity, and efficiency. Additionally, we will simplify power management build options and provide clear guidelines for device behavior during power state transitions.

This RFC takes #75963 into account.

Proposed Changes

Device Power Management via Runtime API Only

• Eliminate calls to pm_device_action_run for managing device power states.
• Power transitions will be exclusively managed through the runtime power management API.

Application Responsibility for Device Power Management

• Applications must call pm_device_runtime_get to acquire a reference for a device before using it.
• Applications must release the device using pm_device_runtime_put when done.

Subsystem Responsibility for Device Power Management

• Subsystems must adopt similar responsibilities as applications:
  • Acquire references to devices they use via pm_device_runtime_get.
  • Release references when usage ends via pm_device_runtime_put.

Devices Initialized in Powered-Down State

• All devices will initialize in a powered-down state.
• Devices will transition to active states only when explicitly needed by an application or subsystem.

Simplify Build Options

Consolidate build options to only two power management modes:

• System Power Management: Manages system-wide power transitions (e.g., suspend, resume).
  • Zephyr’s System Power Management focuses on managing the system power states (e.g., sleep, deep sleep, suspend, or power off).
  • System state changes are primarily motivated by two factors:
    • The system attempts to enter the lowest possible power state based on the next scheduled event. (IDLE thread)
    • Constraints: Devices and applications can define wake-up latency requirements, which restrict deeper low-power states, and power state constraints.
• Device Power Management: Manages individual device power states via runtime APIs.
  • When device power management is disabled, devices will be initialized and kept active by default.

The following table by @decsny helps describe the affects of the two power management modes from the perspective of a single device and a system with three sleep states:

Possible SOC power states (example): mode_0 (active), mode_1 (idle), mode_2 (standby)

Example device DT:

dev@x {
    reg = <x>;
    compat = "some_dev";
    zephyr,disabling-states = <&mode_2>;
};

System PM	Device PM	Initial Device State	Lowest possible SOC mode
n	n	Active *	mode_0
y	n	Active *	mode_1
n	y	Suspend	mode_0
y	y	Suspend	mode_2+

^* will never be suspended if CONFIG_PM_DEVICE=n
⁺ can only enter mode_2 if dev is suspended (device constraint)

Device Behavior for Suspend and Turn Off

• Devices must assume the following:
  • Suspend: Devices retain their context (e.g., internal states, configuration, and data). Devices can quickly resume operation without reinitialization.
  • Turn Off: Devices lose their context, including all states and configuration. This is a consequence of the suspension of the power domain the device belongs to. The device is completely powered down and requires reinitialization when powered on.
• Application does not have control whether a device is suspended or powered off. The application only can inform if a device is needed. Turn off action is only triggered by the power domain the device belongs to.
• States X actions:

• Power Domains/Rails Mapping:
  • A direct consequence of this behavior distinction is the need to map and control additional power domains and rails, such as those for internal SoC devices. This ensures precise control over which parts of the system are powered during suspend or turn-off states.
  • Updates to the power management framework will include support for mapping power domains to devices, allowing finer control and enabling the platform to power down unused regions of the SoC efficiently.

Benefits

• Improved Efficiency: Devices powered only when needed reduce overall power consumption.
• Simplified Build Configuration: Unified power management options make configuration easier for developers.
• Consistent Device Behavior: Clearly defined rules for suspend and turn off actions ensure device drivers behave predictably.
• Clear Responsibilities: Applications and subsystems explicitly manage power usage, aligning with modular design principles.
• Scalability: The proposed changes lay the groundwork for more advanced power management features in the future.

Conclusion

This proposal aims to streamline and improve Zephyr’s power management framework by consolidating device power management under the runtime API, simplifying build options, and defining clear behaviors for suspend and turn-off actions. These changes will enhance power efficiency, simplify device power control, and reduce the complexity of power management configuration.

Scope of required changes

• Implement pm device hook in all device drivers
• Update all subsystems to use pm runtime
• Stop using pm actions directly
• Samples don’t need to be updated (except if they currently use pm actions directly)
• SoCs must map internal devices to appropriated power domains

[ceolin]

@bjarki-andreasen @erwango @fabiobaltieri @mmahadevan108 @kartben @JordanYates @henrikbrixandersen @nashif at all :)

[de-nordic]

If the hook is pm_device_action_cb_t , would it be also possible to take it out of struct pm_device_base and put it directly to struct device? It then allows to do virtual devices that have no state without adding the state object. Such devices, when called to change state, would just pass the call to the parent device they are handing off.

As an example of virtual device: Nordic has Flash over IPC device that is completely software construct - here actually PM is not needed as such, because the device is always on and takes no power, but we could also do a device like Flash Partition device or Flash to Uart device - and these would would need to pass state to a real device they actually operate on.

[JordanYates]

Proposal looks good, probably because it matches how I have thought about PM for some time.
An additional action would be a pass over all drivers that removes internal PM state checks.
I have one pending for sensors, but I suspect other systems may have the same pattern: #83017

[erwango]

I'll need to dig into power domains, but proposal looks a priori complete and indeed simplified.

Though, IIUC, one missing bit is the S2RAM use case applied to devices suspension. In this use case, application (and global f/w) context is retained while hardware context is lost. In that case, devices should be able to reinitialize HW context based on stored configuration. Is that correct or maybe I am missing something ?

[bjarki-andreasen]

I'll need to dig into power domains, but proposal looks a priori complete and indeed simplified.

Though, IIUC, one missing bit is the S2RAM use case applied to devices suspension. In this use case, application (and global f/w) context is retained while hardware context is lost. In that case, devices should be able to reinitialize HW context based on stored configuration. Is that correct or maybe I am missing something ?

In case of S2RAM, devices will receive PM_DEVICE_ACTION_OFF, which will tell the driver the hardware lost all context :) This differs from suspend in which the "power domain" is still on, so the registers retain their value :)

This is also the case for bus connected devices like sensors, where "S2RAM" is similar to its power domain being suspended, which also results in the device receiving PM_DEVICE_ACTION_OFF

[fabiobaltieri]

cc @gmarull

[JordanYates]

In case of S2RAM, devices will receive PM_DEVICE_ACTION_OFF, which will tell the driver the hardware lost all context :)

This is not acceptable. For drivers to be clear and reliable, actions must correspond to exactly one logical event to handle.
Preparing the hardware for loss of power (which may involve GPIO reconfiguration etc), will not involve the same sequence of events as losing the local software context (device->data).

You can tell the statement is not quite right because the external hardware has not lost any context at all.

[ceolin]

In case of S2RAM, devices will receive PM_DEVICE_ACTION_OFF, which will tell the driver the hardware lost all context :)

This is not acceptable. For drivers to be clear and reliable, actions must correspond to exactly one logical event to handle. Preparing the hardware for loss of power (which may involve GPIO reconfiguration etc), will not involve the same sequence of events as losing the local software context (device->data).

You can tell the statement is not quite right because the external hardware has not lost any context at all.

I agree, sw context != hw power.

[bjarki-andreasen]

In case of S2RAM, devices will receive PM_DEVICE_ACTION_OFF, which will tell the driver the hardware lost all context :)

This is not acceptable. For drivers to be clear and reliable, actions must correspond to exactly one logical event to handle.
Preparing the hardware for loss of power (which may involve GPIO reconfiguration etc), will not involve the same sequence of events as losing the local software context (device->data).

I may have misunderstood your comment, I'm referring to hardware registers loosing their register values, which they do as a result of S2RAM or any other power mode where the suspended hardware is not powered. dev->data, stored in RAM, which remains powered in S2RAM, is not lost. The driver just needs to know that the hardware must be reinitialized from whatever is stored in dev->data when it is powered again, as a result of leaving S2RAM.

These are the clear and reliable actions, starting with the driver resumed:

• Driver receives suspend action
• Driver suspends hardware

At this time, no context is lost, hardware registers nor RAM

• Driver receives power off action (this is before power is actually removed from the hardware)
• Driver stores configurations (somewhere safe, which survives S2RAM, which could just be its dev->data which is stored in RAM) for reinit ones power comes back
• Driver configures GPIOs, releases clocks, releases power domains etc.
• Hardware looses power (as result of power domain going down or S2RAM or other lower power mode being entered)

Leaving S2RAM or simply having a power domain turned on again:

• Driver receives ON action
• Driver re-initializes hardware
• Driver receives resume
• Driver resumes hardware

The only thing the driver needs to know is:

• Did my hardware loose its context/register values
• Is my hardware supposed to be resumed or not

Presuming that no power mode supported by PM results in RAM being reset (that would be power off, which requires a reset of the entire chip anyway), sw context is never lost, its only the hardware which looses context

[ceolin]

In case of S2RAM, devices will receive PM_DEVICE_ACTION_OFF, which will tell the driver the hardware lost all context :)

This is not acceptable. For drivers to be clear and reliable, actions must correspond to exactly one logical event to handle.
Preparing the hardware for loss of power (which may involve GPIO reconfiguration etc), will not involve the same sequence of events as losing the local software context (device->data).

I may have misunderstood your comment, I'm referring to hardware registers loosing their register values, which they do as a result of S2RAM or any other power mode where the suspended hardware is not powered. dev->data, stored in RAM, which remains powered in S2RAM, is not lost. The driver just needs to know that the hardware must be reinitialized from whatever is stored in dev->data when it is powered again, as a result of leaving S2RAM.

These are the clear and reliable actions, starting with the driver resumed:

• Driver receives suspend action
• Driver suspends hardware

At this time, no context is lost, hardware registers nor RAM

• Driver receives power off action (this is before power is actually removed from the hardware)
• Driver stores configurations (somewhere safe, which survives S2RAM, which could just be its dev->data which is stored in RAM) for reinit ones power comes back
• Driver configures GPIOs, releases clocks, releases power domains etc.
• Hardware looses power (as result of power domain going down or S2RAM or other lower power mode being entered)

Leaving S2RAM or simply having a power domain turned on again:

• Driver receives ON action
• Driver re-initializes hardware
• Driver receives resume
• Driver resumes hardware

The only thing the driver needs to know is:

• Did my hardware loose its context/register values
• Is my hardware supposed to be resumed or not

Presuming that no power mode supported by PM results in RAM being reset (that would be power off, which requires a reset of the entire chip anyway), sw context is never lost, its only the hardware which looses context

That is indeed the workflow that we have discussed, the challenge is that we will need to have devices mapped under power domains to effectively receive turn off action.