This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Power Management

System PM APIs

group subsys_pm_sys

System Power Management API.

Functions

bool pm_power_state_force(uint8_t cpu, struct pm_state_info info)

Force usage of given power state.

This function overrides decision made by PM policy forcing usage of given power state upon next entry of the idle thread.

Note

This function can only run in thread context

Parameters
  • cpu – CPU index.

  • info – Power state which should be used in the ongoing suspend operation.

void pm_notifier_register(struct pm_notifier *notifier)

Register a power management notifier.

Register the given notifier from the power management notification list.

Parameters
int pm_notifier_unregister(struct pm_notifier *notifier)

Unregister a power management notifier.

Remove the given notifier from the power management notification list. After that this object callbacks will not be called.

Parameters
Returns

0 if the notifier was successfully removed, a negative value otherwise.

struct pm_state_info pm_power_state_next_get(uint8_t cpu)

Gets the next power state that will be used.

This function returns the next power state that will be used by the SoC.

Parameters
  • cpu – CPU index.

Returns

next pm_state_info that will be used

struct pm_notifier
#include <pm.h>

Power management notifier struct

This struct contains callbacks that are called when the target enters and exits power states.

As currently implemented the entry callback is invoked when transitioning from PM_STATE_ACTIVE to another state, and the exit callback is invoked when transitioning from a non-active state to PM_STATE_ACTIVE. This behavior may change in the future.

Note

These callbacks can be called from the ISR of the event that caused the kernel exit from idling.

Note

It is not allowed to call pm_notifier_unregister or pm_notifier_register from these callbacks because they are called with the spin locked in those functions.

Public Members

void (*state_entry)(enum pm_state state)

Application defined function for doing any target specific operations for power state entry.

void (*state_exit)(enum pm_state state)

Application defined function for doing any target specific operations for power state exit.

States

group subsys_pm_states

System Power Management States.

Defines

PM_STATE_INFO_DT_ITEM_BY_IDX(node_id, i)

Construct a pm_state_info from ‘cpu-power-states’ property at index ‘i’.

Parameters
  • node_id – A node identifier with compatible zephyr,power-state

  • i – index into cpu-power-states property

Returns

pm_state_info item from ‘cpu-power-states’ property at index ‘i’

PM_STATE_DT_ITEM_BY_IDX(node_id, i)

Construct a pm_state enum from ‘cpu-power-states’ property at index ‘i’.

Parameters
  • node_id – A node identifier with compatible zephyr,power-state

  • i – index into cpu-power-states property

Returns

pm_state item from ‘cpu-power-states’ property at index ‘i’

PM_STATE_DT_ITEMS_LEN(node_id)

Length of ‘cpu-power-states’ property.

Parameters
  • node_id – A node identifier with compatible zephyr,power-state

Returns

length of ‘cpu-power-states’ property

PM_STATE_INFO_DT_ITEMS_LIST(node_id)

Macro function to construct a list of ‘pm_state_info’ items by UTIL_LISTIFY func.

Example devicetree fragment:

cpus {
   ...
   cpu0: cpu@0 {
           device_type = "cpu";
           ...
           cpu-power-states = <&state0 &state1>;
   };
};

...
power-states {
   state0: state0 {
           compatible = "zephyr,power-state";
           power-state-name = "suspend-to-idle";
           min-residency-us = <10000>;
           exit-latency-us = <100>;
   };

   state1: state1 {
           compatible = "zephyr,power-state";
           power-state-name = "suspend-to-ram";
           min-residency-us = <50000>;
           exit-latency-us = <500>;
   };
};

Example usage:

const struct pm_state_info states[] =
     PM_STATE_INFO_DT_ITEMS_LIST(DT_NODELABEL(cpu0));

Parameters
  • node_id – A node identifier with compatible zephyr,power-state

Returns

an array of struct pm_state_info.

PM_STATE_DT_ITEMS_LIST(node_id)

Macro function to construct a list of enum pm_state items by UTIL_LISTIFY func.

Example devicetree fragment:

cpus {
   ...
   cpu0: cpu@0 {
           device_type = "cpu";
           ...
           cpu-power-states = <&state0 &state1>;
   };
};

...
state0: state0 {
   compatible = "zephyr,power-state";
   power-state-name = "suspend-to-idle";
   min-residency-us = <10000>;
   exit-latency-us = <100>;
};

state1: state1 {
   compatible = "zephyr,power-state";
   power-state-name = "suspend-to-ram";
   min-residency-us = <50000>;
   exit-latency-us = <500>;
};

Example usage:

const enum pm_state states[] = PM_STATE_DT_ITEMS_LIST(DT_NODELABEL(cpu0));

Parameters
  • node_id – A node identifier with compatible zephyr,power-state

Returns

an array of enum pm_state items.

Enums

enum pm_state

Power management state

Values:

enumerator PM_STATE_ACTIVE

Runtime active state.

The system is fully powered and active.

Note

This state is correlated with ACPI G0/S0 state

enumerator PM_STATE_RUNTIME_IDLE

Runtime idle state.

Runtime idle is a system sleep state in which all of the cores enter deepest possible idle state and wait for interrupts, no requirements for the devices, leaving them at the states where they are.

Note

This state is correlated with ACPI S0ix state

enumerator PM_STATE_SUSPEND_TO_IDLE

Suspend to idle state.

The system goes through a normal platform suspend where it puts all of the cores in deepest possible idle state and may puts peripherals into low-power states. No operating state is lost (ie. the cpu core does not lose execution context), so the system can go back to where it left off easily enough.

Note

This state is correlated with ACPI S1 state

enumerator PM_STATE_STANDBY

Standby state.

In addition to putting peripherals into low-power states all non-boot CPUs are powered off. It should allow more energy to be saved relative to suspend to idle, but the resume latency will generally be greater than for that state. But it should be the same state with suspend to idle state on uniprocesser system.

Note

This state is correlated with ACPI S2 state

enumerator PM_STATE_SUSPEND_TO_RAM

Suspend to ram state.

This state offers significant energy savings by powering off as much of the system as possible, where memory should be placed into the self-refresh mode to retain its contents. The state of devices and CPUs is saved and held in memory, and it may require some boot- strapping code in ROM to resume the system from it.

Note

This state is correlated with ACPI S3 state

enumerator PM_STATE_SUSPEND_TO_DISK

Suspend to disk state.

This state offers significant energy savings by powering off as much of the system as possible, including the memory. The contents of memory are written to disk or other non-volatile storage, and on resume it’s read back into memory with the help of boot-strapping code, restores the system to the same point of execution where it went to suspend to disk.

Note

This state is correlated with ACPI S4 state

enumerator PM_STATE_SOFT_OFF

Soft off state.

This state consumes a minimal amount of power and requires a large latency in order to return to runtime active state. The contents of system(CPU and memory) will not be preserved, so the system will be restarted as if from initial power-up and kernel boot.

Note

This state is correlated with ACPI G2/S5 state

enumerator PM_STATE_COUNT

Number of power management states (internal use)

struct pm_state_info
#include <state.h>

Information about a power management state

Public Members

uint8_t substate_id

Some platforms have multiple states that map to one Zephyr power state. This property allows the platform distinguish them. e.g:

power-states {
   state0: state0 {
           compatible = "zephyr,power-state";
           power-state-name = "suspend-to-idle";
           substate-id = <1>;
           min-residency-us = <10000>;
           exit-latency-us = <100>;
   };
   state1: state1 {
           compatible = "zephyr,power-state";
           power-state-name = "suspend-to-idle";
           substate-id = <2>;
           min-residency-us = <20000>;
           exit-latency-us = <200>;
   };
};

uint32_t min_residency_us

Minimum residency duration in microseconds. It is the minimum time for a given idle state to be worthwhile energywise.

Note

0 means that this property is not available for this state.

uint32_t exit_latency_us

Worst case latency in microseconds required to exit the idle state.

Note

0 means that this property is not available for this state.

Constraints

group subsys_pm_sys_constraint

System Power Management Constraints API.

Functions

void pm_constraint_set(enum pm_state state)

Set a constraint for a power state.

Disabled state cannot be selected by the Zephyr power management policies. Application defined policy should use the pm_constraint_get function to check if given state is enabled and could be used.

Note

This API is refcount

Parameters
  • state[in] Power state to be disabled.

void pm_constraint_release(enum pm_state state)

Release a constraint for a power state.

Enabled state can be selected by the Zephyr power management policies. Application defined policy should use the pm_constraint_get function to check if given state is enabled and could be used. By default all power states are enabled.

Note

This API is refcount

Parameters
  • state[in] Power state to be enabled.

bool pm_constraint_get(enum pm_state state)

Check if particular power state is enabled.

This function returns true if given power state is enabled.

Parameters
  • state[in] Power state.

Hooks

group subsys_pm_sys_hooks

System Power Management Hooks.

Functions

void pm_power_state_set(struct pm_state_info info)

Put processor into a power state.

This function implements the SoC specific details necessary to put the processor into available power states.

Parameters
  • info – Power state which should be used in the ongoing suspend operation.

void pm_power_state_exit_post_ops(struct pm_state_info info)

Do any SoC or architecture specific post ops after sleep state exits.

This function is a place holder to do any operations that may be needed to be done after sleep state exits. Currently it enables interrupts after resuming from sleep state. In future, the enabling of interrupts may be moved into the kernel.

Parameters
  • info – Power state that the given cpu is leaving.

Device PM APIs

group subsys_pm_device

Device Power Management API.

Defines

PM_DEVICE_DEFINE(dev_name, pm_action_cb)

Define device PM resources for the given device name.

See

PM_DEVICE_DT_DEFINE, PM_DEVICE_DT_INST_DEFINE

Note

This macro is a no-op if CONFIG_PM_DEVICE is not enabled.

Parameters
  • dev_name – Device name.

  • pm_action_cb – PM control callback.

PM_DEVICE_DT_DEFINE(node_id, pm_action_cb)

Define device PM resources for the given node identifier.

See

PM_DEVICE_DT_INST_DEFINE, PM_DEVICE_DEFINE

Note

This macro is a no-op if CONFIG_PM_DEVICE is not enabled.

Parameters
  • node_id – Node identifier.

  • pm_action_cb – PM control callback.

PM_DEVICE_DT_INST_DEFINE(idx, pm_action_cb)

Define device PM resources for the given instance.

See

PM_DEVICE_DT_DEFINE, PM_DEVICE_DEFINE

Note

This macro is a no-op if CONFIG_PM_DEVICE is not enabled.

Parameters
  • idx – Instance index.

  • pm_action_cb – PM control callback.

PM_DEVICE_REF(dev_name)

Obtain a reference to the device PM resources for the given device.

Parameters
  • dev_name – Device name.

Returns

Reference to the device PM resources (NULL if device CONFIG_PM_DEVICE is disabled).

PM_DEVICE_DT_REF(node_id)

Obtain a reference to the device PM resources for the given node.

Parameters
  • node_id – Node identifier.

Returns

Reference to the device PM resources (NULL if device CONFIG_PM_DEVICE is disabled).

PM_DEVICE_DT_INST_REF(idx)

Obtain a reference to the device PM resources for the given instance.

Parameters
  • idx – Instance index.

Returns

Reference to the device PM resources (NULL if device CONFIG_PM_DEVICE is disabled).

Enums

enum pm_device_state

Device power states.

Values:

enumerator PM_DEVICE_STATE_ACTIVE

Device is in active or regular state.

enumerator PM_DEVICE_STATE_SUSPENDED

Device is suspended.

Note

Device context may be lost.

enumerator PM_DEVICE_STATE_SUSPENDING

Device is being suspended.

enumerator PM_DEVICE_STATE_OFF

Device is turned off (power removed).

Note

Device context is lost.

enum pm_device_action

Device PM actions.

Values:

enumerator PM_DEVICE_ACTION_SUSPEND

Suspend.

enumerator PM_DEVICE_ACTION_RESUME

Resume.

enumerator PM_DEVICE_ACTION_TURN_OFF

Turn off.

enumerator PM_DEVICE_ACTION_FORCE_SUSPEND

Force suspend.

Functions

const char *pm_device_state_str(enum pm_device_state state)

Get name of device PM state.

Parameters
  • state – State id which name should be returned

int pm_device_state_set(const struct device *dev, enum pm_device_state state)

Set the power state of a device.

Deprecated:

Use pm_device_action_run() instead.

This function calls the device PM control callback so that the device does the necessary operations to put the device into the given state.

Note

Some devices may not support all device power states.

Parameters
  • dev – Device instance.

  • state – Device power state to be set.

Returns

  • 0 – If successful.

  • -ENOTSUP – If requested state is not supported.

  • -EALREADY – If device is already at the requested state.

  • -EBUSY – If device is changing its state.

  • -ENOSYS – If device does not support PM.

  • Errno – Other negative errno on failure.

int pm_device_state_get(const struct device *dev, enum pm_device_state *state)

Obtain the power state of a device.

Parameters
  • dev – Device instance.

  • state – Pointer where device power state will be stored.

Returns

  • 0 – If successful.

  • -ENOSYS – If device does not implement power management.

int pm_device_action_run(const struct device *dev, enum pm_device_action action)

Run a pm action on a device.

This function calls the device PM control callback so that the device does the necessary operations to execute the given action.

Parameters
  • dev – Device instance.

  • action – Device pm action.

Returns

  • 0 – If successful.

  • -ENOTSUP – If requested state is not supported.

  • -EALREADY – If device is already at the requested state.

  • -EBUSY – If device is changing its state.

  • -ENOSYS – If device does not support PM.

  • Errno – Other negative errno on failure.

void pm_device_busy_set(const struct device *dev)

Mark a device as busy.

Devices marked as busy will not be suspended when the system goes into low-power states. This can be useful if, for example, the device is in the middle of a transaction.

See

pm_device_busy_clear()

Parameters
  • dev – Device instance.

void pm_device_busy_clear(const struct device *dev)

Clear a device busy status.

See

pm_device_busy_set()

Parameters
  • dev – Device instance.

bool pm_device_is_any_busy(void)

Check if any device is busy.

Returns

  • false – If no device is busy

  • true – If one or more devices are busy

bool pm_device_is_busy(const struct device *dev)

Check if a device is busy.

Parameters
  • dev – Device instance.

Returns

  • false – If the device is not busy

  • true – If the device is busy

bool pm_device_wakeup_enable(struct device *dev, bool enable)

Enable or disable a device as a wake up source.

A device marked as a wake up source will not be suspended when the system goes into low-power modes, thus allowing to use it as a wake up source for the system.

Parameters
  • dev – Device instance.

  • enabletrue to enable or false to disable

Returns

  • true – If the wakeup source was successfully enabled.

  • false – If the wakeup source was not successfully enabled.

bool pm_device_wakeup_is_enabled(const struct device *dev)

Check if a device is enabled as a wake up source.

Parameters
  • dev – Device instance.

Returns

  • true – if the wakeup source is enabled.

  • false – if the wakeup source is not enabled.

bool pm_device_wakeup_is_capable(const struct device *dev)

Check if a device is wake up capable.

Parameters
  • dev – Device instance.

Returns

  • true – If the device is wake up capable.

  • false – If the device is not wake up capable.

static inline void device_busy_set(const struct device *dev)

Mark a device as busy.

Deprecated:

Use pm_device_busy_set() instead

Parameters
  • dev – Device instance.

static inline void device_busy_clear(const struct device *dev)

Clear busy status of a device.

Deprecated:

Use pm_device_busy_clear() instead

Parameters
  • dev – Device instance.

static inline int device_any_busy_check(void)

Check if any device is busy.

Deprecated:

Use pm_device_is_any_busy() instead

Returns

  • 0 – No devices are busy.

  • -EBUSY – One or more devices are busy.

static inline int device_busy_check(const struct device *dev)

Check if a device is busy.

Deprecated:

Use pm_device_is_busy() instead

Parameters
  • dev – Device instance.

Returns

  • 0 – Device is not busy.

  • -EBUSY – Device is busy.

Device Runtime PM APIs

group subsys_pm_device_runtime

Device Runtime Power Management API.

Functions

void pm_device_runtime_enable(const struct device *dev)

Enable device runtime PM.

Function properties (list may not be complete)

pre-kernel-ok

Parameters
  • dev – Device instance.

int pm_device_runtime_disable(const struct device *dev)

Disable device runtime PM.

If the device is currently suspended it will be resumed.

Function properties (list may not be complete)

pre-kernel-ok

Parameters
  • dev – Device instance.

Returns

  • 0 – If the device runtime PM is disabled successfully.

  • -ENOSYS – If the functionality is not available.

  • -errno – Other negative errno, result of resuming the device.

int pm_device_runtime_get(const struct device *dev)

Resume a device based on usage count.

This function will resume the device if the device is suspended (usage count equal to 0). In case of a resume failure, usage count and device state will be left unchanged. In all other cases, usage count will be incremented.

If the device is still being suspended as a result of calling pm_device_runtime_put_async(), this function will wait for the operation to finish to then resume the device.

Function properties (list may not be complete)

pre-kernel-ok

Parameters
  • dev – Device instance.

Returns

  • 0 – If the device has been resumed successfully.

  • -ENOSTUP – If runtime PM is not enabled for the device.

  • -ENOSYS – If the functionality is not available.

  • -errno – Other negative errno, result of the PM action callback.

int pm_device_runtime_put(const struct device *dev)

Suspend a device based on usage count.

This function will suspend the device if the device is no longer required (usage count equal to 0). In case of suspend failure, usage count and device state will be left unchanged. In all other cases, usage count will be decremented (down to 0).

Function properties (list may not be complete)

pre-kernel-ok

See

pm_device_runtime_put_async()

Parameters
  • dev – Device instance.

Returns

  • 0 – If device has been suspended successfully.

  • -ENOSTUP – If runtime PM is not enabled for the device.

  • -ENOSYS – If the functionality is not available.

  • -EALREADY – If device is already suspended (can only happen if get/put calls are unbalanced).

  • -errno – Other negative errno, result of the action callback.

int pm_device_runtime_put_async(const struct device *dev)

Suspend a device based on usage count (asynchronously).

This function will schedule the device suspension if the device is no longer required (usage count equal to 0). In all other cases, usage count will be decremented (down to 0).

Function properties (list may not be complete)

pre-kernel-ok , async

See

pm_device_runtime_put()

Note

Asynchronous operations are not supported when in pre-kernel mode. In this case, the function will be blocking (equivalent to pm_device_runtime_put()).

Parameters
  • dev – Device instance.

Returns

  • 0 – If device has queued for suspend.

  • -ENOSTUP – If runtime PM is not enabled for the device.

  • -ENOSYS – If the functionality is not available.

  • -EALREADY – If device is already suspended (can only happen if get/put calls are unbalanced).

bool pm_device_runtime_is_enabled(const struct device *dev)

Check if device runtime is enabled for a given device.

Function properties (list may not be complete)

pre-kernel-ok

See

pm_device_runtime_enable()

Parameters
  • dev – Device instance.

Returns

  • true – If device has device runtime PM enabled.

  • false – If the device has device runtime PM disabled.