| /* |
| * Copyright (c) 2012-2014 Wind River Systems, Inc. |
| * |
| * SPDX-License-Identifier: Apache-2.0 |
| */ |
| |
| #ifndef ZEPHYR_INCLUDE_POWER_H_ |
| #define ZEPHYR_INCLUDE_POWER_H_ |
| |
| #include <zephyr/types.h> |
| #include <stdbool.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * @defgroup power_management_api Power Management |
| * @{ |
| * @} |
| */ |
| |
| /** |
| * @brief System power states. |
| */ |
| enum power_states { |
| SYS_POWER_STATE_AUTO = (-2), |
| SYS_POWER_STATE_ACTIVE = (-1), |
| #ifdef CONFIG_SYS_POWER_LOW_POWER_STATES |
| # ifdef CONFIG_HAS_STATE_LOW_POWER_1 |
| SYS_POWER_STATE_LOW_POWER_1, |
| # endif |
| # ifdef CONFIG_HAS_STATE_LOW_POWER_2 |
| SYS_POWER_STATE_LOW_POWER_2, |
| # endif |
| # ifdef CONFIG_HAS_STATE_LOW_POWER_3 |
| SYS_POWER_STATE_LOW_POWER_3, |
| # endif |
| #endif /* CONFIG_SYS_POWER_LOW_POWER_STATES */ |
| |
| #ifdef CONFIG_SYS_POWER_DEEP_SLEEP_STATES |
| # ifdef CONFIG_HAS_STATE_DEEP_SLEEP_1 |
| SYS_POWER_STATE_DEEP_SLEEP_1, |
| # endif |
| # ifdef CONFIG_HAS_STATE_DEEP_SLEEP_2 |
| SYS_POWER_STATE_DEEP_SLEEP_2, |
| # endif |
| # ifdef CONFIG_HAS_STATE_DEEP_SLEEP_3 |
| SYS_POWER_STATE_DEEP_SLEEP_3, |
| # endif |
| #endif /* CONFIG_SYS_POWER_DEEP_SLEEP_STATES */ |
| SYS_POWER_STATE_MAX |
| }; |
| |
| #ifdef CONFIG_SYS_POWER_MANAGEMENT |
| |
| extern unsigned char sys_pm_idle_exit_notify; |
| |
| /** |
| * @brief System Power Management API |
| * |
| * @defgroup system_power_management_api System Power Management API |
| * @ingroup power_management_api |
| * @{ |
| */ |
| |
| /** |
| * @brief Check if particular power state is a low power state. |
| * |
| * This function returns true if given power state is a low power state. |
| */ |
| static inline bool sys_pm_is_low_power_state(enum power_states state) |
| { |
| switch (state) { |
| #ifdef CONFIG_SYS_POWER_LOW_POWER_STATES |
| # ifdef CONFIG_HAS_STATE_LOW_POWER_1 |
| case SYS_POWER_STATE_LOW_POWER_1: |
| /* FALLTHROUGH */ |
| # endif |
| # ifdef CONFIG_HAS_STATE_LOW_POWER_2 |
| case SYS_POWER_STATE_LOW_POWER_2: |
| /* FALLTHROUGH */ |
| # endif |
| # ifdef CONFIG_HAS_STATE_LOW_POWER_3 |
| case SYS_POWER_STATE_LOW_POWER_3: |
| /* FALLTHROUGH */ |
| # endif |
| return true; |
| #endif /* CONFIG_SYS_POWER_LOW_POWER_STATES */ |
| |
| default: |
| return false; |
| } |
| } |
| |
| /** |
| * @brief Check if particular power state is a deep sleep state. |
| * |
| * This function returns true if given power state is a deep sleep state. |
| */ |
| static inline bool sys_pm_is_deep_sleep_state(enum power_states state) |
| { |
| switch (state) { |
| #ifdef CONFIG_SYS_POWER_DEEP_SLEEP_STATES |
| # ifdef CONFIG_HAS_STATE_DEEP_SLEEP_1 |
| case SYS_POWER_STATE_DEEP_SLEEP_1: |
| /* FALLTHROUGH */ |
| # endif |
| # ifdef CONFIG_HAS_STATE_DEEP_SLEEP_2 |
| case SYS_POWER_STATE_DEEP_SLEEP_2: |
| /* FALLTHROUGH */ |
| # endif |
| # ifdef CONFIG_HAS_STATE_DEEP_SLEEP_3 |
| case SYS_POWER_STATE_DEEP_SLEEP_3: |
| /* FALLTHROUGH */ |
| # endif |
| return true; |
| #endif /* CONFIG_SYS_POWER_DEEP_SLEEP_STATES */ |
| |
| default: |
| return false; |
| } |
| } |
| |
| /** |
| * @brief Function to disable power management idle exit notification |
| * |
| * The 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. |
| * |
| */ |
| static inline void sys_pm_idle_exit_notification_disable(void) |
| { |
| sys_pm_idle_exit_notify = 0; |
| } |
| |
| /** |
| * @brief Force usage of given power state. |
| * |
| * This function overrides decision made by PM policy |
| * forcing usage of given power state in all subsequent |
| * suspend operations. Forcing the SYS_POWER_STATE_AUTO |
| * state restores normal operation. |
| * |
| * @param state Power state which should be used in all |
| * subsequent suspend operations or |
| * SYS_POWER_STATE_AUTO. |
| */ |
| extern void sys_pm_force_power_state(enum power_states state); |
| |
| #ifdef CONFIG_SYS_PM_DEBUG |
| /** |
| * @brief Dump Low Power states related debug info |
| * |
| * Dump Low Power states debug info like LPS entry count and residencies. |
| */ |
| extern void sys_pm_dump_debug_info(void); |
| |
| #endif /* CONFIG_SYS_PM_DEBUG */ |
| |
| #ifdef CONFIG_SYS_PM_STATE_LOCK |
| /** |
| * @brief Disable particular power state |
| * |
| * @details Disabled state cannot be selected by the Zephyr power |
| * management policies. Application defined policy should |
| * use the @ref sys_pm_ctrl_is_state_enabled function to |
| * check if given state could is enabled and could be used. |
| * |
| * @param [in] state Power state to be disabled. |
| */ |
| extern void sys_pm_ctrl_disable_state(enum power_states state); |
| |
| /** |
| * @brief Enable particular power state |
| * |
| * @details Enabled state can be selected by the Zephyr power |
| * management policies. Application defined policy should |
| * use the @ref sys_pm_ctrl_is_state_enabled function to |
| * check if given state could is enabled and could be used. |
| * By default all power states are enabled. |
| * |
| * @param [in] state Power state to be enabled. |
| */ |
| extern void sys_pm_ctrl_enable_state(enum power_states state); |
| |
| /** |
| * @brief Check if particular power state is enabled |
| * |
| * This function returns true if given power state is enabled. |
| * |
| * @param [in] state Power state. |
| */ |
| extern bool sys_pm_ctrl_is_state_enabled(enum power_states state); |
| |
| #endif /* CONFIG_SYS_PM_STATE_LOCK */ |
| |
| /** |
| * @} |
| */ |
| |
| /** |
| * @brief Power Management Hooks |
| * |
| * @defgroup power_management_hook_interface Power Management Hooks |
| * @ingroup power_management_api |
| * @{ |
| */ |
| |
| /** |
| * @brief 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_from_deep_sleep(void); |
| |
| /** |
| * @brief 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_POWER_STATE_ACTIVE. |
| * |
| * 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. |
| * |
| */ |
| void sys_resume(void); |
| |
| /** |
| * @brief Hook function to allow entry to 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 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 power state. |
| * |
| * @param ticks the upcoming kernel idle time |
| * |
| * @return Power state which was selected and entered. |
| */ |
| extern enum power_states sys_suspend(s32_t ticks); |
| |
| /** |
| * @brief Put processor into power state |
| * |
| * This function implements the SoC specific details necessary |
| * to put the processor into available power states. |
| */ |
| extern void sys_set_power_state(enum power_states state); |
| |
| /** |
| * @brief Do any SoC or architecture specific post ops after low power states. |
| * |
| * This function is a place holder to do any operations that may |
| * be needed to be done after low power exits. Currently it enables |
| * interrupts after resuming from low power state. In future, the enabling |
| * of interrupts may be moved into the kernel. |
| */ |
| extern void sys_power_state_post_ops(enum power_states state); |
| |
| /** |
| * @brief Application defined function for power state entry |
| * |
| * Application defined function for doing any target specific operations |
| * for power state entry. |
| */ |
| extern void sys_pm_notify_lps_entry(enum power_states state); |
| |
| /** |
| * @brief Application defined function for low power state exit |
| * |
| * Application defined function for doing any target specific operations |
| * for low power state exit. |
| */ |
| extern void sys_pm_notify_lps_exit(enum power_states state); |
| |
| /** |
| * @} |
| */ |
| |
| #endif /* CONFIG_SYS_POWER_MANAGEMENT */ |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* ZEPHYR_INCLUDE_POWER_H_ */ |