From 097012ce2e8ff93db3fc38783b65ec498156d2ee Mon Sep 17 00:00:00 2001 From: Sam Hurst Date: Wed, 9 Feb 2022 11:55:01 -0800 Subject: zephyr: docs: add USBA documentation Document the USBA Kconfig.usba options BUG=b:208437225 TEST=Browse doc in gerrit BRANCH=main Signed-off-by: Sam Hurst Change-Id: If1c791a85c2497584e28de67c2eac6fb9368b92b Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3451006 Reviewed-by: Keith Short --- docs/ec_terms.md | 4 ++ docs/zephyr/zephyr_new_board_checklist.md | 1 + docs/zephyr/zephyr_usba.md | 78 +++++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+) create mode 100644 docs/zephyr/zephyr_usba.md diff --git a/docs/ec_terms.md b/docs/ec_terms.md index fce405bfbb..b865df0078 100644 --- a/docs/ec_terms.md +++ b/docs/ec_terms.md @@ -237,6 +237,10 @@ second). Typical use is to provide a debug console to the EC. [RS-232] is the protocol standard used by UARTs. +* **USBA - USB Type-A** {#usba} + + Traditional USB Host port. + * **VCONN - Connector Voltage** {#vconn} See the [USB-C documentation](./usb-c.md#vconn) for more details. diff --git a/docs/zephyr/zephyr_new_board_checklist.md b/docs/zephyr/zephyr_new_board_checklist.md index f2299a896d..aa9eae4e8c 100644 --- a/docs/zephyr/zephyr_new_board_checklist.md +++ b/docs/zephyr/zephyr_new_board_checklist.md @@ -55,6 +55,7 @@ EC Feature | Ne [Configure EC Chipset (TODO)](./zephyr_template.md) | yes [Configure AP to EC Communication](./zephyr_ap_ec_comm.md) | yes [Configure AP Power Sequencing (TODO)](./zephyr_template.md) | yes +[Configure USB-A](./zephyr_usba.md) | no [Configure USB-C (TODO)](./zephyr_template.md) | yes [Configure Charger (TODO)](./zephyr_template.md) | yes [Configure I2C Buses](./zephyr_i2c.md) | yes diff --git a/docs/zephyr/zephyr_usba.md b/docs/zephyr/zephyr_usba.md new file mode 100644 index 0000000000..ce66125905 --- /dev/null +++ b/docs/zephyr/zephyr_usba.md @@ -0,0 +1,78 @@ +# Zephyr USBA Configuration + +[TOC] + +## Overview + +[USBA] is used to configure the number of USB Type-A ports in the system and +optional control of the power supplied by said ports. + +## Kconfig Options + +`CONFIG_PLATFORM_EC_USBA` enables support for USB-A ports in the EC application. +Refer to [Kconfig.usba] for all sub-options controlling USB-A ports. + +## Devicetree Nodes + +By default, for each USB Type-A port, a GPIO pin is required to control when power +is supplied to the port. The GPIO pins are described in Device Tree nodes. + +Refer to the [named-gpios.yaml] and [cros-ec,usba-port-enable-pins.yaml] child-binding +files for details about gpio properties. + +## Board Specific Code + +none + +## Threads + +When `CONFIG_PLATFORM_EC_USB_PORT_POWER_DUMB=y`, then the EC application automatically +powers up USB-A ports when the AP chipset starts up and powers off the USB-A ports +when the AP chipset shuts down. + +## Testing and Debugging + +Use the gpioset console command to manually enable and disable the USB Type-A port power. + +`gpioset` usage: gpioset <0 | 1> + +The `usbchargemode` console command is used to enable and disable charging +from the USB Type-A port. + +* For dumb power ports: `usbchargemode` +* For smart power ports: `usbchargemode` <0 | 1 | 2 | 3> <0 | 1> + +Charging from USB Type-A ports can be controlled from the AP using ectool `usbchargemode`. + +`ectool usbchargemode` [inhibit_charge] + +Refer to the Application Processor to EC communication for more information about using[ ectool]. + +## Example + +The Herobrine board has one USB Type-A port: + +The following configures the project for one port. + +``` +`CONFIG_PLATFORM_EC_USB_PORT_POWER_DUMB=y` +``` + +The following device tree node configures the gpio pin. + +``` +gpio_en_usb_a_5v: en_usb_a_5v { + gpios = <&gpiof 0 GPIO_OUT_LOW>; +}; + +usba-port-enable-list { + compatible = "cros-ec,usba-port-enable-pins"; + enable-pins = <&gpio_en_usb_a_5v>; +}; +``` + +[USBA]: ../ec_terms.md#usba +[Kconfig.usba]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.usba +[named-gpios.yaml]: ../../zephyr/dts/bindings/gpio/named-gpios.yaml +[cros-ec,usba-port-enable-pins.yaml]: ../../zephyr/dts/bindings/gpio/cros-ec,usba-port-enable-pins.yaml +[ectool]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/util/ectool.c;?q=function:ms_help&ss=chromiumos -- cgit v1.2.1