doc: pm: Update device power management documentation

Update information about device power management.

Signed-off-by: Flavio Ceolin <[email protected]>

Author: Flavio Ceolin

doc/services/pm/api/index.rst

@@ -28,6 +28,8 @@ Device PM APIs
 
 .. doxygengroup:: subsys_pm_device
 
+.. _device_runtime_apis:
+
 Device Runtime PM APIs
 **********************
 

doc/services/pm/device.rst

@@ -10,7 +10,7 @@ setting :kconfig:option:`CONFIG_PM_DEVICE` to ``y``. When this option is
 selected, device drivers implementing power management will be able to take
 advantage of the device power management subsystem.
 
-Zephyr supports two types of device power management:
+Zephyr supports two methods of device power management:
 
  - :ref:`Device Runtime Power Management <pm-device-runtime-pm>`
  - :ref:`System-Managed Device Power Management <pm-device-system-pm>`
@@ -20,18 +20,50 @@ Zephyr supports two types of device power management:
 Device Runtime Power Management
 *******************************
 
-In this method, the application or any component that deals with devices directly
-and has the best knowledge of their use, performs the device power management. This
-saves power if some devices that are not in use can be turned off or put
-in power saving mode. This method allows saving power even when the CPU is
-active. The components that use the devices need to be power aware and should
-be able to make decisions related to managing device power.
-
-When using this type of device power management, the kernel can change CPU
-power states quickly when :c:func:`pm_system_suspend()` gets called. This is
-because it does not need to spend time doing device power management if the
-devices are already put in the appropriate power state by the application or
-component managing the devices.
+Device runtime power management involves coordinated interaction between
+device drivers, subsystems, and applications. While device drivers
+play a crucial role in directly controlling the power state of
+devices, the decision to suspend or resume a device can also be
+influenced by higher layers of the software stack.
+
+Each layer—device drivers, subsystems, and applications—can operate
+independently without needing to know about the specifics of the other
+layers because the subsystem uses reference count to check when it needs
+to suspend or resume a device.
+
+- **Device drivers** are responsible for managing the
+  power state of devices. They interact directly with the hardware to
+  put devices into low-power states (suspend) when they are not in
+  use, and bring them back (resume) when needed. Drivers should use the
+  :ref:`device runtime power management APIs <device_runtime_apis>` provided
+  by Zephyr to control the power state of devices.
+
+- **Subsystems**, such as sensors, file systems,
+  and network, can also influence device power management.
+  Subsystems may have better knowledge about the overall system
+  state and workload, allowing them to make informed decisions about
+  when to suspend or resume devices. For example, a networking
+  subsystem may decide to keep a network interface powered on if it
+  expects network activity in the near future.
+
+- **Applications** running on Zephyr can impact device
+  power management as well. An application may have specific
+  requirements regarding device usage and power consumption. For
+  example, an application that streams data over a network may need
+  to keep the network interface powered on continuously.
+
+Coordination between device drivers, subsystems, and applications is
+key to efficient device power management. For example, a device driver
+may not know that a subsystem will perform a series of sequential
+operations that require a device to remain powered on. In such cases,
+the subsystem can use device runtime power management to ensure that
+the device remains in an active state until the operations are
+complete.
+
+When using this Device Runtime Power Management, the System Power
+Management subsystem is able to change power states quickly because it
+does not need to spend time suspending and resuming devices that are
+runtime enabled.
 
 For more information, see :ref:`pm-device-runtime`.
 
@@ -40,7 +72,7 @@ For more information, see :ref:`pm-device-runtime`.
 System-Managed Device Power Management
 **************************************
 
-When using this type, device power management is mostly done inside
+When using this method, device power management is mostly done inside
 :c:func:`pm_system_suspend()` along with entering a CPU or SOC power state.
 
 If a decision to enter a CPU lower power state is made, the power management
@@ -56,20 +88,30 @@ suspended.
    As functions in this context cannot block, transitions that intend to use blocking
    APIs **must** check whether they can do so with :c:func:`k_can_yield`.
 
-This type of device power management can be useful when the application is not
-power aware and does not implement runtime device power management. Though,
-:ref:`Device Runtime Power Management <pm-device-runtime-pm>` is the **preferred**
-option for device power management.
+This method of device power management can be useful in the following scenarios:
+
+- Systems with no device requiring any blocking operations when suspending and
+  resuming. This implementation is reasonably simpler than device runtime
+  power management.
+- For devices that can not make any power management decision and have to be
+  always active. For example a firmware using Zephyr that is controlled by an
+  external entity (e.g Host CPU). In this scenario, some devices have to be
+  always active and should be suspended together with the SoC when requested by
+  this external entity.
+
+It is important to emphasize that this method has drawbacks (see above) and
+:ref:`Device Runtime Power Management <pm-device-runtime-pm>` is the
+**preferred** method for implementing device power management.
 
 .. note::
 
-    When using this type of device power management, the CPU will only enter
-    a low power state only if no device is in the middle of a hardware
+    When using this method of device power management, the CPU will enter
+    a low power state only if no devices are in the middle of a hardware
     transaction that cannot be interrupted.
 
 .. note::
 
-    This type of device power management is disabled when
+    This method of device power management is disabled when
     :kconfig:option:`CONFIG_PM_DEVICE_RUNTIME_EXCLUSIVE` is set to ``y`` (that is
     the default value when :kconfig:option:`CONFIG_PM_DEVICE_RUNTIME` is enabled)
 
@@ -82,7 +124,7 @@ Device Power Management States
 ******************************
 
 The power management subsystem defines device states in
-:c:enum:`pm_device_state`. This type is used to track power states of
+:c:enum:`pm_device_state`. This method is used to track power states of
 a particular device. It is important to emphasize that, although the
 state is tracked by the subsystem, it is the responsibility of each device driver
 to handle device actions(:c:enum:`pm_device_action`) which change device state.