doc: add documentation for usb-c on platform/ec

Add documentation for common configuration and touch points that need to
be considered when implementing the USB-C stack on the platform/ec
codebase.

BRANCH=none
BUG=chromium:974302
TEST=none

Change-Id: I24aef187989c14688985d3cba48a6734ee519d23
Signed-off-by: Jett Rink <jettrink@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1648609
Reviewed-by: Daisuke Nojiri <dnojiri@chromium.org>

3 files changed, 213 insertions, 1 deletions

diff --git a/docs/sitemap.md b/docs/sitemap.md
index b377f1f45a..0a70d1ac9c 100644
--- a/docs/sitemap.md
+++ b/docs/sitemap.md
@@ -14,6 +14,10 @@
 
 *   [USB Updater](./usb_updater.md)
 
+## USB-C
+
+*   [USB-C Power Delivery and Alternate Modes](./usb-c.md)
+
 ## Miscellaneous
 
 *   [Low Battery Startup](./low_battery_startup.md)
diff --git a/docs/usb-c.md b/docs/usb-c.md
new file mode 100644
index 0000000000..5f45058b56
--- /dev/null
+++ b/docs/usb-c.md
@@ -0,0 +1,200 @@
+# EC Implementation of USB-C Power Delivery and Alternate Modes
+
+USB-C PD requires a complex state machine as USB-C PD can operate in many
+different modes. This includes but isn't limited to:
+
+*   Negotiated power contracts. Either side of the cable can source or sink
+    power up to 100W (if supported by device).
+*   Reversed cable mode. This requires a mux to switch the signals before
+    getting to the SoC (or AP).
+*   Debug accessory mode, e.g.
+    [Case Closed Debugging (CCD)](case_closed_debugging_cr50.md)
+*   Multiple uses for the 4 differential pair signals including
+    *   USB SuperSpeed mode (up to 4 lanes for USB data)
+    *   DisplayPort Alternate Mode (up to 4 lanes for DisplayPort data)
+    *   Dock Mode (2 lanes for USB data, and 2 lanes for DisplayPort)
+    *   Audio Accessory mode. (1 lane is used for L and R analog audio signal)
+
+For a more complete list of USB-C Power Delivery features, see the
+[USB-C PD spec][USB PD Spec Id].
+
+This document covers various touch points to consider for USB-C PD and Alternate
+Modes in the EC codebase.
+
+[TOC]
+
+## Glossary
+
+*   PD
+    *   Power Delivery. Protocol over USB-C connector that allows up to 100W of
+        power. Not supported on USB-A or USB-B connectors.
+*   TCPC
+    *   Type-C Port Controller. Typically a separate IC connected through I2C,
+        sometimes embedded within the EC as a hardware sub module. The TCPC
+        interprets physical layer signals on CC lines and Vbus, and sends that
+        information to the TCPM to decide what action to take. In older designs,
+        there was a separate EC (running this codebase) that acted as the TCPC
+        that communicated with the main EC (also running this codebase), which
+        acted as the TCPM. More info in the official
+        [TCPC spec][USB TCPM Spec Id].
+*   TCPM
+    *   Type-C Port Manager. Manages the state of the USB-C connection. Makes
+        decisions about what state to transition to. This is the code running on
+        the EC itself.
+*   PE
+    *   Policy Engine. According to the [TypeC spec][USB TC Spec Id], the policy
+        engine is the state machine that decides how the USB-C connection
+        progresses through different states and which USB-C PD features are
+        available, such as Try.SRC
+*   TC
+    *   Type-C physical layer.
+*   PPC
+    *   Power Path Controller. An optional, separate IC that isolates various
+        USB-C signals from each other and the rest of the board. This IC should
+        prevent shorts and over current/voltage scenarios for Vbus. Some PPCs
+        will protect signals other than Vbus as well.
+*   SSMUX
+    *   SuperSpeed Mux. This is typically the same IC as the TCPC; it enables
+        the mirrored orientation of the USB-C cable to go to the correct pins on
+        SoC. Also, allows the SuperSpeed signal to be used for different
+        purposes, such as USB data or DisplayPort.
+*   DRP
+    *   Dual Role Power Port. A USB-C port that can act as either a power Source
+        or power Sink.
+*   UFP
+    *   Upstream Facing Port. The USB data role that is typical for a peripheral
+        (e.g. HID keyboard).
+*   DFP
+    *   Downstream Facing Port. The USB Data role that is typical for a host
+        machine (e.g. device running ChromeOS).
+
+## Different PD stacks
+
+Right now platform/ec has two different implementations of USB-C PD stack.
+
+1.  The older implementation is mainly contained within
+    [`usb_pd_protocol.c`](../common/usb_pd_protocol.c)
+2.  The newer implementation is broken up into multiple different files and
+    state machines
+    *   Policy engine state machine files, such as `usb_pe_*_sm.c`.
+    *   Type-C physical layer state machine: `usb_tc_sm.c`
+
+The older implementation supports firmware for device types other than
+Chromebooks. For example, the older stack supports the Zinger, which is the
+USB-C charging device that shipped with Samus, the Google Chromebook Pixel 2.
+The Zinger implements the charger only side of the USB PD protocol.
+
+The newer implementation only supports Chromebooks at the moment. There are
+multiple policy engine definitions to choose from depending on the different
+USB-C features the Chromebook should support. As of now, you must choose one and
+only one policy engine state machine implementation. The policy engine mostly
+defines what PD features (e.g. Try.SRC) are implemented on the Chromebook.
+
+## Implementation Considerations
+
+In both older and newer implementations, the following details apply:
+
+*   For each USB-C port, there must be two tasks: `PD_C#` and `PD_INT_C#`, where
+    `#` is the port number starting from `0`.
+    *   The `PD_C#` task runs the state machine (old or new) for the port and
+        communicates with the TCPC, MUX, and PPC. This task needs a large task
+        stack.
+    *   The `PD_INT_C#` tasks runs at a higher priority than the state machine
+        task, and its sole job is to receive interrupts from the TCPC as quickly
+        as possible then send appropriate messages to other tasks (including
+        `PD_C#`). This task shouldn't need much stack space, but the i2c
+        recovery code requires a decent amount of stack space so it ends up
+        needing a fair amount too.
+*   Saving PD state between EC jumps
+    *   PD communication is disabled in locked RO images (normal state for
+        customer devices). When the jump from RO to RW happens relatively
+        quickly (e.g. there is not a long memory training step), then there
+        aren't many problems when RW takes over and negotiates higher PD
+        contracts.
+    *   To support factory use cases that don't have a battery (and are
+        therefore unlocked), PD communication is enabled in unlocked RO. This
+        allows systems without software sync enabled to get a higher power
+        contract than 15W in RO.
+    *   We save and restore PD state between RO -> RW and RW -> RO jump to allow
+        us to maintain a higher negotiated power through the full jump and
+        re-initialization process. For example, for each port we save the power
+        role, data role, and Vconn sourcing state in battery-backed or
+        non-volatile RAM. This allows the firmware image that is initializing to
+        restore an existing SNK contract (Chromebook as SNK) without cutting
+        power. We don't cut the power from the external supplier because we
+        issue a SoftReset (leaves Vbus intact) instead of a HardReset (drops
+        Vbus) in this contract resume case.
+    *   Both use cases where we actually are able to restore the PD contract
+        require an unlocked RO (e.g. factory) otherwise RO cannot communicate
+        via PD and will drop the higher PD contract (by applying Rp/Rp on the CC
+        lines temporarily)
+        *   The RO->RW use case is for an unlocked (e.g. factory) device that
+            negotiated power and we want to keep that contract after we jump to
+            RW in the normal software sync boot process. This is especially
+            useful when there is no battery and Vbus is our only power source.
+        *   The RW->RO use case happens when we are performing auxiliary FW
+            upgrades during software sync and BIOS instructs the EC to jump back
+            to RO. We'll also try to maintain contracts over an EC reset when
+            unlocked.
+
+## Configuration
+
+There are many `CONFIG_*` options and driver structs that are needed in the
+board.h and board.c implementation.
+
+### TCPC Config
+
+The `tcpc_config` array of `tcpc_config_t` structs defined in `board.c` (or
+baseboard equivalent) should be defined for every board. The index in the
+`tcpc_config` array corresponds to the USB-C port number. This struct should
+point to the specific TCPC driver that corresponds to the TCPC that is being
+used on that port. The i2c port and address for the TCPC are also specified
+here.
+
+### SSMUX Config
+
+The `usb_muxes` array of `usb_mux` structs defined in `board.c` (or baseboard
+equivalent) should be defined for every board. Normally the standard
+`tcpci_tcpm_usb_mux_driver` driver works, especially if TCPC and MUX are the
+same IC.
+
+If the signal strength for the high-speed data lines needs to be tuned for a
+specific hardware layout, the `board_init` field on the `usb_mux` is called
+every time the mux is woken up from a low power state and should be used for
+setting custom board tuning parameters.
+
+### PPC Config
+
+Some boards have an additional IC that sits between the physical USB-C connector
+and the rest of the board. The PPC IC gates whether the Vbus line is an input or
+output signal, based on i2c settings or gpio pins. A PPC also typically provides
+over voltage and over current protection on multiple USB-C pins.
+
+The `ppc_chips` array of `ppc_config_t` structs defined in `board.c` (or
+baseboard equivalent) sets the appropriate driver and i2c port/address for the
+PPC IC.
+
+### Useful Config Options
+
+Many USB-C policies and features are gated by various `CONFIG_*` options that
+should be defined in `board.h` (or baseboard equivalent).
+
+To use the newer USB-C PD stack implementation, see `CONFIG_USB_SM_FRAMEWORK`
+description in [config.h][config header link].
+
+Most USB-C options will start with `CONFIG_USB_PD_` or `CONFIG_USBC_`. For their
+full descriptions see [config.h][config header link]
+
+## Interactions with other tasks
+
+TODO(crbug.com/974302): mention `USB_CHG_P#` and `CHARGER`
+
+## Upgrading FW for TCPCs
+
+TODO(crbug.com/974302): Mention how this works even though it is in depthcharge.
+Probing now. Need new driver in depthcharge
+
+[USB PD Spec Id]: https://www.usb.org/document-library/usb-power-delivery
+[USB TCPM Spec Id]: https://www.usb.org/document-library/usb-type-ctm-port-controller-interface-specification
+[USB TC Spec Id]: https://www.usb.org/document-library/usb-type-ctm-cable-and-connector-specification-revision-14-march-29-2019
+[config header link]: ../include/config.h
diff --git a/include/config.h b/include/config.h
index 9c88792f12..502fdf2598 100644
--- a/include/config.h
+++ b/include/config.h
@@ -850,7 +850,15 @@
  */
 #undef CONFIG_CHARGER_BQ25710_IDCHG_LIMIT_MA
 
-/* Define to use Power Delivery State Machine Framework */
+/*
+ * Define to use Power Delivery State Machine Framework. Along with
+ * CONFIG_USB_SM_FRAMEWORK, you must ensure the follow options are defined to
+ * use the new statemachine for USB-C:
+ *
+ * CONFIG_USB_TYPEC_SM (defined by default)
+ * CONFIG_USB_PRL_SM (defined by default)
+ * One of CONFIG_USB_PE_* policy engine options.
+ */
 #undef CONFIG_USB_SM_FRAMEWORK
 
 /*