Power Management APIs

Power Management Hook Interface

group power_management_hook_interface

Power Management Hooks.

Functions

static void sys_pm_idle_exit_notification_disable(void)

Function to disable power management idle exit notification.

sys_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_suspend to disable the corresponding sys_resume notification.

void sys_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_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_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_pm_idle_exit_notification_disable() can be called in sys_suspend to disable this notification.

int sys_suspend(s32_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

group device_power_management_api

Device Power Management APIs.

Defines

DEVICE_PM_ACTIVE_STATE

device is in ACTIVE power state

Normal operation of the device. All device context is retained.

DEVICE_PM_LOW_POWER_STATE

device is in LOW power state

Device context is preserved by the HW and need not be restored by the driver.

DEVICE_PM_SUSPEND_STATE

device is in SUSPEND power state

Most device context is lost by the hardware. Device drivers must save and restore or reinitialize any context lost by the hardware

DEVICE_PM_FORCE_SUSPEND_STATE

device is in force SUSPEND power state

Driver puts the device in suspended state after completing the ongoing transactions and will not process any queued work or will not take any new requests for processing. Most device context is lost by the hardware. Device drivers must save and restore or reinitialize any context lost by the hardware.

DEVICE_PM_OFF_STATE

device is in OFF power state

  • Power has been fully removed from the device. The device context is lost when this state is entered, so the OS software will reinitialize the device when powering it back on

DEVICE_PM_SET_POWER_STATE
DEVICE_PM_GET_POWER_STATE

Functions

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_control_nop(struct device *unused_device, u32_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, u32_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, u32_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