diff --git a/doc/services/pm/overview.rst b/doc/services/pm/overview.rst index 2395ce44a95..6e8edfa0052 100644 --- a/doc/services/pm/overview.rst +++ b/doc/services/pm/overview.rst @@ -6,10 +6,9 @@ are designed to be architecture and SOC independent. This enables power management implementations to be easily adapted to different SOCs and architectures. -The architecture and SOC independence is achieved by separating the core -infrastructure and the SOC specific implementations. The SOC specific -implementations are abstracted to the application and the OS using hardware -abstraction layers. +The architecture and SOC independence is achieved by separating the core PM +infrastructure from implementations of the SOC specific components. +Thus a coherent abstraction is presented to the rest of the OS and the application layer. The power management features are classified into the following categories. diff --git a/doc/services/pm/system.rst b/doc/services/pm/system.rst index f3e52b93d87..8f337929dd3 100644 --- a/doc/services/pm/system.rst +++ b/doc/services/pm/system.rst @@ -3,17 +3,18 @@ System Power Management ####################### -The kernel enters the idle state when it has nothing to schedule. If enabled via -the :kconfig:option:`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 kernel enters the idle state when it has nothing to schedule. +Enabling :kconfig:option:`CONFIG_PM` allows the kernel to call upon the +power management subsystem to put an idle system into one of the supported power states. +The kernel requests an amount of time it would like to suspend, then the PM subsystem decides +the appropriate power state to transition to based on the configured power management policy. + +It is the application's responsibility to set up a wake-up event. +A wake-up event will typically be an interrupt triggered by an SoC peripheral module. +Examples include a SysTick, RTC, counter, or GPIO. +Keep in mind that depending on the SoC and the power mode in question, +not all peripherals may be active, and therefore +some wake-up sources may not be usable in all power modes. The following diagram describes system power management: @@ -64,24 +65,15 @@ The following diagram describes system power management: pm_system_resume:e -> lock:e [constraint=false lhed="cluster_0"] } -Some handful examples using different power management features: - -* :zephyr_file:`samples/boards/stm32/power_mgmt/blinky/` -* :zephyr_file:`samples/boards/esp32/deep_sleep/` -* :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_states_api/` Power States ============ -The power management subsystem contains a set of states based on -power consumption and context retention. +The power management subsystem defines a set of states described by the +power consumption and context retention associated with each of them. -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. +The set of power states is defined by :c:enum:`pm_state`. In general, lower power states +(higher index in the enum) will offer greater power savings and have higher wake latencies. Power Management Policies ========================= @@ -91,9 +83,11 @@ 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 other constraints such as a list of allowed states. +The policy manager is the component of the power management subsystem responsible +for deciding which power state the system should transition to. +The policy manager can only choose between states that have been defined for the platform. +Other constraints placed upon the decision may include locks disallowing certain power states, +or various kinds of minimum and maximum latency values, depending on the policy. More details on the states definition can be found in the :dtcompatible:`zephyr,power-state` binding documentation. @@ -101,18 +95,16 @@ More details on the states definition can be found in the Residency --------- -The power management system enters the power state which offers the highest -power savings, and with a minimum residency value (see -:dtcompatible:`zephyr,power-state`) less than or equal to the scheduled system -idle time duration. +Under the residency policy, the system will enter the power state which offers the highest +power savings, with the constraint that the sum of the minimum residency value (see +:dtcompatible:`zephyr,power-state`) and the latency to exit the mode must be +less than or equal to the system idle time duration scheduled by the kernel. -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: +Thus the core logic can be summarized with the following expression: .. code-block:: c - if (time_to_next_scheduled_event >= (state.min_residency_us + state.exit_latency))) { + if (time_to_next_scheduled_event >= (state.min_residency_us + state.exit_latency)) { return state } @@ -120,9 +112,9 @@ Application ----------- The application defines the power management policy by implementing the -:c:func:`pm_policy_next_state` function. In this policy the application is free +: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. +remaining time until 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/`. @@ -131,7 +123,19 @@ Policy and Power States ------------------------ The power management subsystem allows different Zephyr components and -applications to configure the policy manager to block system from transitioning +applications to configure the policy manager to block the system from transitioning into certain power states. This can be used by devices when executing tasks in background to prevent the system from going to a specific state where it would -lose context. +lose context. See :c:func:`pm_policy_state_lock_get`. + +Examples +======== + +Some helpful examples showing different power management features: + +* :zephyr_file:`samples/boards/stm32/power_mgmt/blinky/` +* :zephyr_file:`samples/boards/esp32/deep_sleep/` +* :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_states_api/`