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>

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
+The architecture and SOC independence is achieved by separating the core PM
-infrastructure and the SOC specific implementations. The SOC specific
+infrastructure from implementations of the SOC specific components.
-implementations are abstracted to the application and the OS using hardware
+Thus a coherent abstraction is presented to the rest of the OS and the application layer.
-abstraction layers.
 
 The power management features are classified into the following categories.
 

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 kernel enters the idle state when it has nothing to schedule.
-the :kconfig:option:`CONFIG_PM` Kconfig option, the Power Management
+Enabling :kconfig:option:`CONFIG_PM` allows the kernel to call upon the
-Subsystem can put an idle system in one of the supported power states, based
+power management subsystem to put an idle system into one of the supported power states.
-on the selected power management policy and the duration of the idle time
+The kernel requests an amount of time it would like to suspend, then the PM subsystem decides
-allotted by the kernel.
+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
+It is the application's responsibility to set up a wake-up event.
-will typically be an interrupt triggered by one of the SoC peripheral modules
+A wake-up event will typically be an interrupt triggered by an SoC peripheral module.
-such as a SysTick, RTC, counter, or GPIO. Depending on the power mode entered,
+Examples include a SysTick, RTC, counter, or GPIO.
-only some SoC peripheral modules may be active and can be used as a wake up
+Keep in mind that depending on the SoC and the power mode in question,
-source.
+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
+The power management subsystem defines a set of states described by the
-power consumption and context retention.
+power consumption and context retention associated with each of them.
 
-The list of available power states is defined by :c:enum:`pm_state`. In
+The set of power states is defined by :c:enum:`pm_state`. In general, lower power states
-general power states with higher indexes will offer greater power savings and
+(higher index in the enum) will offer greater power savings and have higher wake latencies.
-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
+The policy manager is the component of the power management subsystem responsible
-power state the system should transition to based on states defined by the
+for deciding which power state the system should transition to.
-platform and other constraints such as a list of allowed states.
+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
+Under the residency policy, the system will enter the power state which offers the highest
-power savings, and with a minimum residency value (see
+power savings, with the constraint that the sum of the minimum residency value (see
-:dtcompatible:`zephyr,power-state`) less than or equal to the scheduled system
+:dtcompatible:`zephyr,power-state`) and the latency to exit the mode must be
-idle time duration.
+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
+Thus the core logic can be summarized with the following expression:
-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))) {
+   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/`