Doc: Update plans for TCPMv2 type-c power policy

This updates the existing planned type-c power policy behavior, and adds
a note clarifying that this page represents an ideal which has not yet
been added to the codebase.

BRANCH=None
BUG=b:168862110
TEST=rendered the .md file and images to ensure they work correctly

Signed-off-by: Diana Z <dzigterman@chromium.org>
Change-Id: I82ea19b7b7ac84080bed6fd1841ec7273b55e84a
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2460857
Reviewed-by: Keith Short <keithshort@chromium.org>
Reviewed-by: Jett Rink <jettrink@chromium.org>

3 files changed, 54 insertions, 54 deletions

diff --git a/docs/images/usb_power_on_attach.png b/docs/images/usb_power_on_attach.png
new file mode 100644
index 0000000000..2f2fb19743
--- /dev/null
+++ b/docs/images/usb_power_on_attach.png
diff --git a/docs/images/usb_power_on_detach.png b/docs/images/usb_power_on_detach.png
new file mode 100644
index 0000000000..f0e4a5a9d4
--- /dev/null
+++ b/docs/images/usb_power_on_detach.png
diff --git a/docs/usb_power.md b/docs/usb_power.md
index e066a7bba6..860e7fe589 100644
--- a/docs/usb_power.md
+++ b/docs/usb_power.md
@@ -135,43 +135,42 @@ in-depth information can be found in the [USB Type-C Specification] \(section
 
 ### ChromeOS as Source - Policy for Type-C
 
+**Note:** Behavior outlined in this .md file reflects future-planned behavior,
+and is not present in the codebase currently.
+
 ChromeOS devices currently source power to external USB devices at 5V with a
-typical current of 1.5A for each Type-C port. In certain scenarios, a single
+typical current of 1.5A for each Type-C port. In certain scenarios, a
 Type-C port can source up to 3A @ 5V.
 
-ChromeOS prefers that the first PD-capable Type-C device **that claims 3A**
-should get 3A guaranteed at 5V. Once a PD-capable Type-C device has claimed 3A,
-then other PD-capable Type-C devices will only be offered a maximum of 1.5A.
-
-If there are no PD-capable Type-C devices claiming 3A, then the first non-PD
-device will be given 3A until a PD-capable device **that claims 3A** is
-inserted.
-
-The 3A is only offered after a minimum delay of 200 ms following the initial
-connection. One main reason for this delay is to protect against non-PD capabale
-devices that only sample the CC resistors once at initial connection from
-continuing to consume 3A after we downgrade the CC resistors to 1.5A at a later
-point in the future. The motivation for this is that any non-PD device that
-notices that it can draw more current from a CC resistor change that happens 200
-ms after the initial connection will also notice a CC resistor change if we
-downgrade the CC resistors to a lower current advertisement. We want consistent
-behavior across non-PD capable devices and PD-capable devices, so we will only
-offer the additional 1.5A to PD ports after the same delay.
-
-When a device that is currently claiming 3A is removed or proactively reduces
-its power contract to 1.5A or less, then the next oldest PD-capable device is
-offered 3A in order. If no PD-capable devices claims 3A, then the oldest non-PD
-capable device is given 3A through a CC resistor change.
+ChromeOS prefers that the first PD-capable Type-C device **that requires 3A**
+should get 3A guaranteed at 5V. Once the maximum supported number of PD-capable
+Type-C device has claimed 3A, then other PD-capable Type-C devices will only be
+offered a maximum of 1.5A.
+
+If there are no PD-capable Type-C devices requiring 3A, then the first non-PD
+device will be given 3A until a PD-capable device **that requires 3A** is
+inserted.  Devices will indicate they require 3A in their sink capabilities,
+and this will be used as the trigger to let the EC know to offer that port a
+3A source contract.  This policy is laid out in the following flow chart.
+
+![Partner Attach](images/usb_power_on_attach.png "Partner Attach")
+
+When a device that is currently claiming 3A is removed, then the next oldest
+PD-capable device is offered 3A. If no PD-capable devices require 3A,
+then the oldest non-PD capable device is given 3A through a CC resistor change.
+
+![Partner Detach](images/usb_power_on_detach.png "Partner Detach")
 
 Inserting a Type-A device does not affect the power assignment for Type-C ports;
 only Type-C devices affect the power of Type-C ports.
 
-For example, the below sequence of events illustrates the above Type-C policy:
+For example, the below sequence of events illustrates the above Type-C policy
+with a board with a maximum number of 1 3A-ports supported:
 
 1.  A non-PD capable Type-C keyboard is inserted first
     *   Keyboard will be offered 1.5A initially
     *   Current state: `keyboard @ 1.5A`.
-2.  More than 200ms pass.
+2.  Partner is established to be non-PD through reaching PE\_SRC\_Disabled.
     *   Since there are no other PD-capable devices and this is the first
         device, offer this device 3A via CC resistor change.
     *   Current state: `keyboard @ 3A`.
@@ -180,52 +179,53 @@ For example, the below sequence of events illustrates the above Type-C policy:
         claiming 3A.
     *   Current state: `keyboard @ 3A` and `mouse @ 1.5A`.
 4.  A PD-capable Type-C dock is inserted third
-    *   Initially negotiate for 1.5A, then wait 200ms after negotiating.
-    *   Since this is the first PD device, we offer it 3A after 200ms from
-        initial power negotiation.
-    *   Dock does not want high power from Chromebook; dock continues to selects
+    *   Initially negotiate for 1.5A.
+    *   Since this is a PD device, query its operational current through
+        requesting Sink Capabilities.
+    *   Dock does not want high power from Chromebook; dock continues to receive
         1.5A.
     *   Keyboard gets to maintain higher 3A current supply.
     *   Current state: `keyboard @ 3A` and `mouse @ 1.5A` and `dock @ 1.5A`.
 5.  A PD-capable Type-C phone is inserted fourth
     *   Phone is initially offered 1.5A.
-    *   Since there isn't an existing PD-capable device claiming 3A, the phone
-        is offered 3A after waiting the 200ms delay from initial negotiation.
-    *   The phone wants high power; phone selects 3A.
+    *   Since this is a PD device, query its operational current through
+        requesting Sink Capabilities.
+    *   The phone reports it wants 3A.
     *   Since PD devices are preferred for 3A, the non-PD keyboard will be
         downgraded from 3A to 1.5A via a CC resistor change.
+    *   After tSinkAdj (60 ms), phone is offered 3A through new Source
+        Capabilities.
     *   Current state: `keyboard @ 1.5A` and `mouse @ 1.5A` and `dock @ 1.5A`
         and `phone @ 3A`.
 6.  A PD-capable Type-C tablet is inserted fifth
-    *   Since there is already a PD-capable device claiming 3A, the tablet is
-        only offered 1.5A.
+    *   Tablet is initially offered 1.5A.
+    *   Since this is a PD device, query its operational current through
+        requesting Sink Capabilities.
+    *   Tablet would like 3A, but the board has reached its maximum number of
+        supported 3A ports.  Note this port's desired current for later.
     *   Current state: `keyboard @ 1.5A` and `mouse @ 1.5A` and `dock @ 1.5A`
         and `phone @ 3A` and `tablet @ 1.5A`.
-7.  The PD-capable phone is done charging so it downgrades its power contract to
-    1.5A without any user interaction
-    *   The next oldest PD-capable device is offered 3A in order: dock then
-        phone then tablet.
-    *   The dock and phone continue to select 1.5A, then the tablet takes 3A.
+7.  The PD-capable phone is removed
+    *   The next oldest PD-capable device is offered 3A: the tablet
     *   Current state: `keyboard @ 1.5A` and `mouse @ 1.5A` and `dock @ 1.5A`
-        and `phone @ 1.5A` and `tablet @ 3A`.
+        and `tablet @ 3A`.
 8.  The PD-capable tablet is removed
-    *   The next oldest PD-capable device is offered 3A. If there are no
-        PD-capable devices claiming 3A, then the oldest non-PD capable device is
-        given 3A.
-    *   The dock and phone continue to select 1.5A, so keyboard is given 3A via
-        CC resistor change.
-    *   Current state: `keyboard @ 3A` and `mouse @ 1.5A` and `dock @ 1.5A` and
-        `phone @ 1.5A`.
+    *   The next oldest PD-capable device requiring 3A is offered 3A. If there
+        are no PD-capable devices requiring 3A, then the oldest non-PD capable
+        device is given 3A.
+    *   The dock only requires 1.5A, so keyboard is given 3A via CC resistor
+        change.
+    *   Current state: `keyboard @ 3A` and `mouse @ 1.5A` and `dock @ 1.5A`
 9.  The non-PD capable keyboard is removed
-    *   The next oldest PD-capable device is offered 3A. If there are no
-        PD-capable devices claiming 3A, then the next oldest non-PD capable
+    *   The next oldest PD-capable  device requiring 3A is offered 3A.. If there
+        are no PD-capable devices requiring 3A, then the next oldest non-PD capable
         device is given 3A.
-    *   The dock and phone continue to select 1.5A, so mouse is given 3A via CC
+    *   The dock only requires 1.5A, so mouse is given 3A via CC
         resistor change.
-    *   Current state: `mouse @ 3A` and `dock @ 1.5A` and `phone @ 1.5A`.
+    *   Current state: `mouse @ 3A` and `dock @ 1.5A`.
 10. The non-PD capable mouse is removed
-    *   The dock and phone continue to select 1.5A.
-    *   Current state: `dock @ 1.5A` and `phone @ 1.5A`.
+    *   The dock does not require 3A.
+    *   Current state: `dock @ 1.5A`.
 
 Note: Not all released Chromebooks implement the above policy due to
 pre-existing hardware design constraints.