doc: services: pm: Reword System PM Doc
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:
parent
8adb7c17ca
commit
12f48fe896
2 changed files with 45 additions and 42 deletions
|
@ -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.
|
||||
|
||||
|
|
|
@ -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/`
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue