doc/guides/pm/system.rst

System Power Management
#######################

The kernel enters the idle state when it has nothing to schedule. If enabled via
the :kconfig:`CONFIG_PM` 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.

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.

The following diagram describes system power management:

.. image:: images/system-pm.svg
   :align: center
   :alt: System power management

Some handful examples using different power management features:

* :zephyr_file:`samples/boards/stm32/power_mgmt/blinky/`
* :zephyr_file:`samples/boards/nrf/system_off/`
* :zephyr_file:`samples/subsys/pm/device_pm/`
* :zephyr_file:`tests/subsys/pm/power_mgmt/`
* :zephyr_file:`tests/subsys/pm/power_mgmt_soc/`
* :zephyr_file:`tests/subsys/pm/power_state_api/`

Power States
============

The power management subsystem contains a set of states based on
power consumption and context retention.

The list of available power states is defined by :c:enum:`pm_state`. In
general power states with higher indexes will offer greater power savings and
have higher wake latencies.

.. _pm_constraints:

Power States Constraint
=======================

The power management subsystem allows different Zephyr components and
applications to set constraints on various power states preventing the
system from transitiioning into these states. This can be used by devices when executing
tasks in background to avoid the system to go to a specific state where it would
lose context. Constraints can be set using the :c:func:`pm_constraint_set`,
released using :c:func:`pm_constraint_release` and checked using the
:c:func:`pm_constraint_get`.

Power Management Policies
=========================

The power management subsystem supports the following power management policies:

* Residency based
* Application defined

The policy manager is responsible for informing the power subsystem which
power state the system should transition to based on states defined by the
platform and possible runtime :ref:`constraints<pm_constraints>`

Information about states can be found in the device tree, see
:zephyr_file:`dts/bindings/power/state.yaml`.

Residency
---------

The power management system enters the power state which offers the highest
power savings, and with a minimum residency value (in device tree, see
:zephyr_file:`dts/bindings/power/state.yaml`) less than or equal to
the scheduled system idle time duration.

This policy also accounts for the time necessary to become active
again. The core logic used by this policy to select the best power
state is:

.. code-block:: c

   if (time_to_next_scheduled_event >= (state.min_residency_us + state.exit_latency))) {
      return state
   }

Application
-----------

The power management policy is defined by the application by implementing the
:c:func:`pm_policy_next_state` function. In this policy the application is free
to decide which power state the system should transition to based on the
remaining time for the next scheduled timeout.

An example of an application that defines its own policy can be found in
:zephyr_file:`tests/subsys/pm/power_mgmt/`.