Power Management APIs

Power Management Hook Interface

static void _sys_soc_pm_idle_exit_notification_disable(void)

Function to disable power management idle exit notification.

_sys_soc_resume() would be called from the ISR of the event that caused exit from kernel idling after PM operations. For some power operations, this notification may not be necessary. This function can be called in _sys_soc_suspend to disable the corresponding _sys_soc_resume notification.

void _sys_soc_resume_from_deep_sleep(void)

Hook function to notify exit from deep sleep.

The purpose of this function is to notify exit from deep sleep. The implementation of this function can vary depending on the soc specific boot flow.

This function would switch cpu context to the execution point at the time system entered deep sleep power state. Some implementations may not require use of this function e.g. the BSP or boot loader may do the context switch.

In boot flows where this function gets called even at cold boot, the function should return immediately.

void _sys_soc_resume(void)

Hook function to notify exit from kernel idling after PM operations.

This function would notify exit from kernel idling if a corresponding _sys_soc_suspend() notification was handled and did not return SYS_PM_NOT_HANDLED.

This function would be called from the ISR context of the event that caused the exit from kernel idling. This will be called immediately after interrupts are enabled. This is called to give a chance to do any operations before the kernel would switch tasks or processes nested interrupts. This is required for cpu low power states that would require interrupts to be enabled while entering low power states. e.g. C1 in x86. In those cases, the ISR would be invoked immediately after the event wakes up the CPU, before code following the CPU wait, gets a chance to execute. This can be ignored if no operation needs to be done at the wake event notification. Alternatively _sys_soc_pm_idle_exit_notification_disable() can be called in _sys_soc_suspend to disable this notification.

int _sys_soc_suspend(int32_t ticks)

Hook function to allow entry to low power state.

This function is called by the kernel when it is about to idle. It is passed the number of clock ticks that the kernel calculated as available time to idle.

The implementation of this function is dependent on the soc specific components and the various schemes they support. Some implementations may choose to do device PM operations in this function, while others would not need to, because they would have done it at other places.

Typically a wake event is set and the soc or cpu is put to any of the supported low power states. The wake event should be set to wake up the soc or cpu before the available idle time expires to avoid disrupting the kernel’s scheduling.

This function is entered with interrupts disabled. It should re-enable interrupts if it had entered a low power state.

Parameters
  • ticks: the upcoming kernel idle time
Return Value
  • SYS_PM_NOT_HANDLED: If low power state was not entered.
  • SYS_PM_LOW_POWER_STATE: If CPU low power state was entered.
  • SYS_PM_DEEP_SLEEP: If SOC low power state was entered.

Device Power Management APIs

void device_busy_set(struct device *busy_dev)

Indicate that the device is in the middle of a transaction.

Called by a device driver to indicate that it is in the middle of a transaction.

Parameters
  • busy_dev: Pointer to device structure of the driver instance.

void device_busy_clear(struct device *busy_dev)

Indicate that the device has completed its transaction.

Called by a device driver to indicate the end of a transaction.

Parameters
  • busy_dev: Pointer to device structure of the driver instance.

int device_pm_nop(struct device *unused_device, int unused_policy)

No-op function to initialize unimplemented pm hooks.

This function should be used to initialize device pm hooks for which a device has no operation.

Parameters
  • unused_device: Unused
  • unused_policy: Unused
Return Value
  • 0: Always returns 0

static inline int device_suspend(struct device *device, int pm_policy)

Call the suspend function of a device.

Called by the Power Manager application to let the device do any policy based PM suspend operations.

Warning
This function is deprecated and will be removed in a future version, use device_set_power_state instead.

Parameters
  • device: Pointer to device structure of the driver instance.
  • pm_policy: PM policy for which this call is made.
Return Value
  • 0: If successful.
  • Errno: Negative errno code if failure.

static inline int device_resume(struct device *device, int pm_policy)

Call the resume function of a device.

Called by the Power Manager application to let the device do any policy based PM resume operations.

Warning
This function is deprecated and will be removed in a future version, use device_set_power_state instead.

Parameters
  • device: Pointer to device structure of the driver instance.
  • pm_policy: PM policy for which this call is made.
Return Value
  • 0: If successful.
  • Errno: Negative errno code if failure.

int device_pm_control_nop(struct device *unused_device, uint32_t unused_ctrl_command, void *unused_context)

No-op function to initialize unimplemented hook.

This function should be used to initialize device hook for which a device has no PM operations.

Parameters
  • unused_device: Unused
  • unused_ctrl_command: Unused
  • unused_context: Unused
Return Value
  • 0: Always returns 0

static int device_set_power_state(struct device *device, uint32_t device_power_state)

Call the set power state function of a device.

Called by the application or power management service to let the device do required operations when moving to the required power state Note that devices may support just some of the device power states

Parameters
  • device: Pointer to device structure of the driver instance.
  • device_power_state: Device power state to be set
Return Value
  • 0: If successful.
  • Errno: Negative errno code if failure.

static int device_get_power_state(struct device *device, uint32_t *device_power_state)

Call the get power state function of a device.

This function lets the caller know the current device power state at any time. This state will be one of the defined power states allowed for the devices in that system

Parameters
  • device: pointer to device structure of the driver instance.
  • device_power_state: Device power state to be filled by the device
Return Value
  • 0: If successful.
  • Errno: Negative errno code if failure.

void device_list_get(struct device **device_list, int *device_count)

Gets the device structure list array and device count.

Called by the Power Manager application to get the list of device structures associated with the devices in the system. The PM app would use this list to create its own sorted list based on the order it wishes to suspend or resume the devices.

Parameters
  • device_list: Pointer to receive the device list array
  • device_count: Pointer to receive the device count

int device_any_busy_check(void)

Check if any device is in the middle of a transaction.

Called by an application to see if any device is in the middle of a critical transaction that cannot be interrupted.

Return Value
  • 0: if no device is busy
  • -EBUSY: if any device is busy

int device_busy_check(struct device *chk_dev)

Check if a specific device is in the middle of a transaction.

Called by an application to see if a particular device is in the middle of a critical transaction that cannot be interrupted.

Parameters
  • chk_dev: Pointer to device structure of the specific device driver the caller is interested in.
Return Value
  • 0: if the device is not busy
  • -EBUSY: if the device is busy

DEFINE_DEVICE_PM_OPS(_name, _suspend, _resume) static struct device_pm_ops _CONCAT(_name, _dev_pm_ops) = { \ .suspend = _suspend, \ .resume = _resume, \ }

Helper macro to define the device_pm_ops structure.

Parameters
  • _name: name of the device
  • _suspend: name of the suspend function
  • _resume: name of the resume function

DEVICE_PM_OPS_GET(_name) &_CONCAT(_name, _dev_pm_ops)

Macro to get a pointer to the device_ops_structure.

Will return the name of the structure that was created using DEFINE_PM_OPS macro if CONFIG_DEVICE_POWER_MANAGEMENT is defined. Otherwise, will return NULL.

Parameters
  • _name: name of the device

struct device_pm_ops
#include <device.h>

Structure holding handlers for device PM operations.

Warning
This struct is deprecated and will be removed in a future version.
Parameters
  • suspend: Pointer to the handler for suspend operations
  • resume: Pointer to the handler for resume operations