doc: update power management subystem documentation

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>

doc/reference/power_management/index.rst

@@ -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
+architectures.
-the system integrator the flexibility of implementing custom power schemes.
 
 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
+The kernel enters the idle state when it has nothing to schedule. If enabled via
-when the kernel enters and exits the idle state, in other words, when the kernel
+the :option:`CONFIG_SYS_POWER_MANAGEMENT` Kconfig option, the Power Management
-has nothing to schedule. Enabling system power management compels Zephyr kernel
+Subsystem can put an idle system in one of the supported power states, based
-scheduler to work in tickless idle mode (see :option:`CONFIG_TICKLESS_IDLE`).
+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
+The power management subsystem classifies power states into two categories,
-:code:`sys_suspend()` function, notifying the SOC interface that the kernel
+Sleep State and Deep Sleep State, based on whether the CPU loses execution
-is ready to enter the idle state.
+context during the power state transition.
 
-At this point, the kernel has disabled interrupts and computed the maximum
+The list of available power states is defined by :code:`enum power_states`. In
-time the system can remain idle. The function passes the time that
+general power states with higher indexes will offer greater power savings and
-the system can remain idle. The SOC interface performs power operations that
+have higher wake latencies.
-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
 
 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
 **************************************
 

include/power.h

@@ -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
+ * This function is optionally called when exiting from deep sleep if the SOC
- * deep sleep. The implementation of this function can vary
+ * interface does not have bootloader support to handle resume from deep sleep.
- * depending on the soc specific boot flow.
+ * 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
+ * If the function is called at cold boot it should return immediately.
- * 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.
  *
+ * @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.
+ * When the kernel is about to go idle, it calls this function to notify the
- * It is passed the number of clock ticks that the kernel calculated
+ * power management subsystem, that the kernel is ready to enter the idle state.
- * as available time to idle.
  *
- * The implementation of this function is dependent on the soc specific
+ * At this point, the kernel has disabled interrupts and computed the maximum
- * components and the various schemes they support. Some implementations
+ * time the system can remain idle. The function passes the time that the system
- * may choose to do device PM operations in this function, while others
+ * can remain idle. The SOC interface performs power operations that can be done
- * would not need to, because they would have done it at other places.
+ * 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
+ * This function assumes that a wake up event has already been set up by the
- * supported power states. The wake event should be set to wake up
+ * application.
- * 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
+ * This function is entered with interrupts disabled. It should re-enable
- * re-enable interrupts if it had entered a power state.
+ * 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.
  *