doc: pm: rework main documentation

The power management subsystem allows different Zephyr components and

applications to set constraints on various power states preventing the

system to go these states. This can be used by devices when executing

tasks in background to avoid the system to go to state where it would

system from transitiioning into these states. This can be used by devices when executing

tasks in background to avoid the system to go to a specific state where it would

lose context. Constraints can be set, released and checked using the

follow APIs:

The power management subsystem supports the following power management policies:

* Residency

* Application

* Dummy

* Residency based

* Application defined

The policy manager is responsible to inform the power subsystem which

power state the system should go based on states available in the

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 possible runtime :ref:`constraints<pm_constraints>`

Information about states can be get from device tree, see

Information about states can be found in the device tree, see

:zephyr_file:`dts/bindings/power/state.yaml`.

Residency

   struct pm_state_info pm_policy_next_state(int32_t ticks);

In this policy the application is free to decide which power state the

system should go based on the remaining time for the next scheduled

system should transition to based on the remaining time for 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/`.

Dummy

-----

This policy returns the next supported power state in a loop. It is used mainly

for testing purposes.

Device Power Management Infrastructure

**************************************

The device power management infrastructure consists of interfaces to the

Zephyr RTOS device model. These APIs send control commands to the device driver

:ref:`device_model_api`. These APIs send control commands to the device driver

to update its power state or to get its current power state.

Zephyr RTOS supports two methods of doing device power management.

* Distributed method

* Central method

* Runtime Device Power Management

* System Power Management

Distributed method

==================

Runtime Device Power Management

===============================

In this method, the application or any component that deals with devices directly

and has the best knowledge of their use does the device power management. This

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. In this method, the

SOC interface can enter CPU or SOC power states quickly when

be able to make decisions related to managing device power.

In this method, the SOC interface can enter CPU or SOC power states quickly when

:code:`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.

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.

Central method

==============

System Power Management

=======================

In this method device power management is mostly done inside

:code:`pm_system_suspend()` along with entering a CPU or SOC power state.

If a decision to enter deep sleep is made, the implementation would enter it

If a decision to enter a lower power state is made, the implementation would enter it

only after checking if the devices are not in the middle of a hardware

transaction that cannot be interrupted. This method can be used in

implementations where the applications and components using devices are not

expected to be power aware and do not implement device power management.

expected to be power aware and do not implement runtime device power management.

.. image:: central_method.svg

   :align: center

This method can also be used to emulate a hardware feature supported by some

SOCs which cause automatic entry to deep sleep when all devices are idle.

SOCs which triggers automatic entry to a lower power state when all devices are idle.

Refer to `Busy Status Indication`_ to see how to indicate whether a device is busy

or idle.

Device Power Management States

==============================

The Zephyr RTOS power management subsystem defines four device states.

The power management subsystem defines four device states.

These states are classified based on the degree of device context that gets lost

in those states, kind of operations done to save power, and the impact on the

device behavior due to the state transition. Device context includes device

	  Select this option for PM policy based on CPU residencies.

config PM_POLICY_DUMMY

	bool "Dummy PM Policy"

	bool "Dummy PM Policy for testing purposes"

	help

	  Dummy PM Policy which simply returns next PM state in a loop.

	  This policy is used for testing purposes only.

config PM_POLICY_APP

	bool "Application PM Policy"

	help