dts: bindings: zephyr,power-state: Add missing linux props

Add missing properties to match the linux idle-states binding.
Add a note about how these properties may or may not be used in Zephyr
(acceptable due to the fact this binding already has a `zephyr,`
prefix).
Expand the documentation around the min-residency to explain it better.

Signed-off-by: Declan Snyder <[email protected]>

Author: decsny

dts/bindings/power/zephyr,power-state.yaml

@@ -1,7 +1,51 @@
 # Copyright (c) 2020, Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
-description: Properties for power management state
+description: |
+  Properties for power management idle states. Note that not all of the timing properties will
+  be consumed by any or all of the Zephyr policy managers. See the policy manager documentation
+  for details on how the properties affect that policy. The default policy manager, for example,
+  does not abort entry sequences and therefore only makes use of
+  min-residency-us and exit-latency-us.
+
+  The following diagram depicts the CPU execution phases and related timing
+  properties required to enter and exit an idle state:
+
+  ..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__..
+              |          |           |          |          |
+
+              |<------ entry ------->|
+              |       latency        |
+                                                |<- exit ->|
+                                                |  latency |
+              |<-------- min-residency -------->|
+                         |<-------  wakeup-latency ------->|
+
+  The following diagram depicts two hypothetical idle states,
+  one with a lower power once idle but higher cost of entering,
+  meaning that it has a higher "minimum residency" to justify it being chosen over the other:
+
+        |
+        |
+        |
+        |                                                  /-- IDLE1
+     e  |                                              /---
+     n  |                                         /----
+     e  |                                     /---
+     r  |                                /-----/--------- IDLE2
+     g  |                    /-------/---------
+     y  |        ------------    /---|
+        |       /           /----    |
+        |      /        /---         |
+        |     /    /----             |
+        |    / /---                  |
+        |   ---                      |
+        |  /                         |
+        | /                          |
+        |/                           |                  time
+     ---/----------------------------+------------------------
+        |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy
+
 
 compatible: "zephyr,power-state"
 
@@ -26,11 +70,30 @@ properties:
     description: |
         Minimum residency duration in microseconds. It is the minimum time for a
         given idle state to be worthwhile energywise. It includes the time to enter
-        in this state.
+        into this state and the time spent in the state before exiting. It represents
+        the "break-even" time to justify the time and power spent
+        on the work needed for entering the state based on how much actual energy is saved
+        once in the state.
+  entry-latency-us:
+    type: int
+    description: |
+        Worst case latency in microseconds required to enter the idle state.
+        Includes the software latency involved to prepare to enter the low power state.
   exit-latency-us:
     type: int
     description: |
         Worst case latency in microseconds required to exit the idle state.
+  wakeup-latency-us: |
+    type: int
+    description: |
+        Maximum delay between the signaling of a wake-up event and the CPU
+        being able to execute normal code again. If unspecified, it is assumed
+        to be entry-latency-us + exit-latency-us, which would be the worst case.
+        But the actual wakeup latency may be lower as the intended meaning
+        of this value is actually
+        "exit-latency-us + entry-latency-us - 'software prep latency us'"
+        because the software prep happening before hardware gets committed
+        to the idle state could theoretically be aborted.
   zephyr,pm-device-disabled:
     type: boolean
     description: |