michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: update power management subystem documentation

Browse source 
This commit brings power management subystem documentation up to date
with the implementation. The main changes since the last time the
documentation was updated include introduction of power managment
policies.

Signed-off-by: Piotr Mienkowski <piotr.mienkowski@gmail.com>
This commit is contained in:
Piotr Mienkowski 2019-03-18 10:31:29 +01:00 • committed by Anas Nashif
commit 1b66d900a8
2 changed files with 87 additions and 119 deletions
Download patch file Download diff file Expand all files Collapse all files

138
doc/reference/power_management/index.rst
View file

@ -45,8 +45,7 @@ Overview
The interfaces and APIs provided by the power management subsystem
are designed to be architecture and SOC independent. This enables power
management implementations to be easily adapted to different SOCs and
architectures. The kernel does not implement any power schemes of its own, giving
the system integrator the flexibility of implementing custom power schemes.
architectures.
The architecture and SOC independence is achieved by separating the core
infrastructure and the SOC specific implementations. The SOC specific
@ -90,93 +89,34 @@ is a thread ready to run or if an external event occurred.
System Power Management
***********************
This consists of the hook functions that the power management subsystem calls
when the kernel enters and exits the idle state, in other words, when the kernel
has nothing to schedule. Enabling system power management compels Zephyr kernel
scheduler to work in tickless idle mode (see :option:`CONFIG_TICKLESS_IDLE`).
The kernel enters the idle state when it has nothing to schedule. If enabled via
the :option:`CONFIG_SYS_POWER_MANAGEMENT` Kconfig option, the Power Management
Subsystem can put an idle system in one of the supported power states, based
on the selected power management policy and the duration of the idle time
allotted by the kernel.
Suspend Hook function
=====================
It is an application responsibility to set up a wake up event. A wake up event
will typically be an interrupt triggered by one of the SoC peripheral modules
such as a SysTick, RTC, counter, or GPIO. Depending on the power mode entered,
only some SoC peripheral modules may be active and can be used as a wake up
source.
.. code-block:: c
Enabling system power management compels the Zephyr kernel scheduler to work in
tickless idle mode (see :option:`CONFIG_TICKLESS_IDLE`).
int sys_suspend(s32_t ticks);
Power States
============
When the kernel is about to go idle, the power management subsystem calls the
:code:`sys_suspend()` function, notifying the SOC interface that the kernel
is ready to enter the idle state.
The power management subsystem classifies power states into two categories,
Sleep State and Deep Sleep State, based on whether the CPU loses execution
context during the power state transition.
At this point, the kernel has disabled interrupts and computed the maximum
time the system can remain idle. The function passes the time that
the system can remain idle. The SOC interface performs power operations that
can be done in the available time. The power management operation must halt
execution on a CPU or SOC power state. Before entering the power state,
the SOC interface must setup a wake event.
The power management subsystem expects the :code:`sys_suspend()` to return
the power state which was used or :code:`SYS_POWER_STATE_ACTIVE` if SoC was
kept in active state.
Resume Hook function
====================
.. code-block:: c
void sys_resume(void);
The power management subsystem optionally calls this hook function when exiting
kernel idling if power management operations were performed in
:code:`sys_suspend()`. Any necessary recovery operations can be performed
in this function before the kernel scheduler schedules another thread. Some
power states may not need this notification. It can be disabled by calling
:code:`sys_pm_idle_exit_notification_disable()` from
:code:`sys_suspend()`.
Resume From Deep Sleep Hook function
====================================
.. code-block:: c
void sys_resume_from_deep_sleep(void);
This function is optionally called when exiting from deep sleep if the SOC
interface does not have bootloader support to handle resume from deep sleep.
This function should restore context to the point where system entered
the deep sleep state.
.. note::
Since the hook functions are called with the interrupts disabled, the SOC
interface should ensure that its operations are completed quickly. Thus, the
SOC interface ensures that the kernel's scheduling performance is not
disrupted.
Power Schemes
*************
When the power management subsystem notifies the SOC interface that the kernel
is about to enter a system idle state, it specifies the period of time the
system intends to stay idle. The SOC interface can perform various power
management operations during this time. For example, put the processor or the
SOC in a power state, turn off some or all of the peripherals or power gate
device clocks.
Different levels of power savings and different wake latencies characterize
these power schemes. In general, operations that save more power have a
higher wake latency. When making decisions, the SOC interface chooses the
scheme that saves the most power. At the same time, the scheme's total
execution time must fit within the idle time allotted by the power management
subsystem.
The power management subsystem classifies power management schemes
into two categories based on whether the CPU loses execution context during the
power state transition.
* Sleep State
* Deep Sleep State
The list of available power states is defined by :code:`enum power_states`. In
general power states with higher indexes will offer greater power savings and
have higher wake latencies.
Sleep State
===========
-----------
CPU is stopped but does not lose execution context. Some of the SoC clocks are
gated. Configuration of the peripherals is preserved but some of them may be no
@ -184,7 +124,7 @@ longer functional. Execution will resume at the place it stopped. The wake
latencies of power states in this category are relatively low.
Deep Sleep State
================
----------------
CPU is power gated and loses execution context. Execution will resume at
OS startup code or at a resume point determined by a bootloader that supports
@ -194,6 +134,38 @@ implementations, while others may remove power from RAM saving considerable
power. Power states in this category save more power than Sleep states
and would have higher wake latencies.
Power Management Policies
=========================
The power management subsystem supports the following power management policies:
* Residency
* Application
* Dummy
Residency
---------
The power management system enters the power state which offers the highest
power savings, and with a minimum residency value (defined by the respective
Kconfig option) less than or equal to the scheduled system idle time duration.
Application
-----------
The power management policy is defined by the application which has to implement
the following function.
.. code-block:: c
enum power_states sys_pm_policy_next_state(s32_t ticks);
Dummy
-----
This policy returns the next supported power state in a loop. It is used mainly
for testing purposes.
Device Power Management Infrastructure
**************************************

68
include/power.h
View file

@ -157,6 +157,14 @@ static inline void _sys_pm_idle_exit_notification_disable(void)
*/
extern void sys_pm_force_power_state(enum power_states state);
/**
* @brief Put processor into a 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);
#ifdef CONFIG_SYS_PM_DEBUG
/**
* @brief Dump Low Power states related debug info
@ -217,24 +225,22 @@ extern bool sys_pm_ctrl_is_state_enabled(enum power_states state);
*/
/**
* @brief Hook function to notify exit from deep sleep
* @brief Restore context to the point where system entered the deep sleep
* state.
*
* 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 is optionally called when exiting from deep sleep if the SOC
* interface does not have bootloader support to handle resume from deep sleep.
* This function should restore context to the point where system entered
* the deep sleep state.
*
* 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.
* If the function is called at cold boot it should return immediately.
*
* @note This function is not supported on all architectures.
*/
void _sys_resume_from_deep_sleep(void);
/**
* @brief Hook function to notify exit from kernel idling after PM operations
* @brief 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
@ -251,44 +257,34 @@ void _sys_resume_from_deep_sleep(void);
* 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
* @brief 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.
* When the kernel is about to go idle, it calls this function to notify the
* power management subsystem, that the kernel is ready to enter the idle state.
*
* 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.
* At this point, the kernel has disabled interrupts and computed the maximum
* time the system can remain idle. The function passes the time that the system
* can remain idle. The SOC interface performs power operations that can be done
* in the available time. The power management operations must halt execution of
* the CPU.
*
* 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 assumes that a wake up event has already been set up by the
* application.
*
* This function is entered with interrupts disabled. It should
* re-enable interrupts if it had entered a power state.
* 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
* @param ticks The upcoming kernel idle time.
*
* @return Power state which was selected and entered.
* @return Power state which was entered or SYS_POWER_STATE_ACTIVE if SoC was
* kept in the active state.
*/
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 sleep state exits.
*