michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: services: pm: Reword System PM Doc

Browse source 
The following changes:
- Generally reword all the paragraphs to hopefully by clearer and
  easier to read by using more straighforward and direct wording,
  and avoiding run on sentences and ambiguous/wrong grammar, etc.
- Move Examples to the bottom of the page.
- Fix a typo in the code expression where there was an extra
  parentheses.

Signed-off-by: Declan Snyder <declan.snyder@nxp.com>
This commit is contained in:
Declan Snyder 2024-03-26 17:32:39 -05:00 • committed by Anas Nashif
commit 12f48fe896
2 changed files with 45 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

7
doc/services/pm/overview.rst
View file

@ -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.

80
doc/services/pm/system.rst
View file

@ -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.
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 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.
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/`