zephyr: add documentation about host commands

barnas-michal · Chromeos LUCI · commit 53a2adff4d69 · 2022-03-22T18:40:46.000Z
This commit adds information about available Kconfigs and device tree definitions used to enable and configure host interface support. BRANCH=main BUG=b:208438167 TEST=generate preview Change-Id: I049dbd5efd5edc32492b191b8f1cc7911ad2b2bd Signed-off-by: Michał Barnaś <mb@semihalf.com> Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3401640 Reviewed-by: Keith Short <keithshort@chromium.org>
diff --git a/docs/ap-ec-comm.md b/docs/ap-ec-comm.md
@@ -25,6 +25,21 @@ the following sections.
 providing a CLI. They call one of the transport-specific `ec_command`
 implementations in the `util/comm-*.c` files to send and receive from the EC.
 
+#### Stress test
+
+The `ectool stress` command sends a large amount of host commands continuously
+to the EC. This verifies that the EC can respond to all commands received
+without timeouts or communication errors.
+
+It will log the time elapsed for every iteration of sending 10000 host commands
+with the time that it took to send them.
+
+Example output of stress test is:
+`Update: attempt 10000 round 1 | took 205 seconds`
+
+Killing the process will result in displaying the total runtime and failures
+that happened during it.
+
 ### EC kernel driver
 
 In most cases, `ectool` communicates via the [`cros-ec` Kernel driver], rather
diff --git a/docs/zephyr/zephyr_ap_ec_comm.md b/docs/zephyr/zephyr_ap_ec_comm.md
@@ -0,0 +1,296 @@
+# Application Processor to EC communication
+
+[TOC]
+
+## Overview
+
+Host commands allow communication between AP and EC.
+
+This communication is used to inform the ChromeOS running on AP about events
+like opening or closing lid, connecting or disconnecting charger,
+thermal status, keyboard events.
+
+## Kconfig options
+
+Kconfig Option                           | Default     | Documentation
+:--------------------------------------- | :---------: | :------------
+`CONFIG_PLATFORM_EC_HOSTCMD`             | y if AP     | [EC host commands]
+
+### Transport layer
+
+The `CONFIG_PLATFORM_EC_HOST_INTERFACE_TYPE` choice selects the interface type
+used to transport the AP/EC messages.
+
+Kconfig to select interface              | Default     | Documentation
+:--------------------------------------- | :---------: | :------------
+`CONFIG_PLATFORM_EC_HOST_INTERFACE_ESPI` | y if AP_X86 | [eSPI interface]
+`CONFIG_PLATFORM_EC_HOST_INTERFACE_HECI` | n           | [HECI interface]
+`CONFIG_PLATFORM_EC_HOST_INTERFACE_LPC`  | n           | [LPC interface]
+`CONFIG_PLATFORM_EC_HOST_INTERFACE_SHI`  | y if AP_ARM | [SHI interface]
+
+#### SHI
+
+[SHI] is acronym for SPI Host Interface. It's default interface for computers
+with ARM AP.
+It doesn't have any special Kconfigs.
+
+#### eSPI - Virtual wires
+
+[eSPI] is acronym for Enhanced Serial Peripheral Interface.
+It allows to define signals as virtual ones instead of using normal GPIOs.
+
+See the [Kconfig.espi] file for all sub-options related to the eSPI interface.
+
+#### HECI
+
+HECI is acronym for Host Embedded Controller Interface.
+It doesn't have any special Kconfigs.
+
+#### LPC
+
+[LPC] is acronym for Low Pin Count bus.
+It doesn't have any special Kconfigs.
+
+### Generic configuration
+
+The following options are generic and defines features available through
+host interface.
+
+Kconfig sub-options                          | Default     | Documentation
+:------------------------------------------- | :---------: | :------------
+`CONFIG_PLATFORM_EC_HOSTCMD_CONSOLE`         | y           | [Host command console]
+`CONFIG_PLATFORM_EC_HOSTCMD_CONSOLE_BUF_SIZE`| 4096        | [Host command console buffer size]
+`CONFIG_PLATFORM_EC_HOST_COMMAND_STATUS`     | y if PLATFORM_EC_HOST_INTERFACE_SHI | [Host command - status]
+
+### MKBP - Matrix Keyboard Protocol
+
+MKBP was originally used to send keyboard events to AP OS.
+Later, more functionalities were added and more types of events can be sent
+using this protocol. It can transfer information about keystrokes, sensors,
+switches, fingerprints and more.
+
+Kconfig sub-options                          | Default     | Documentation
+:------------------------------------------- | :---------: | :------------
+`CONFIG_PLATFORM_EC_MKBP_INPUT_DEVICES`      | n           | [MKBP input devices]
+`CONFIG_PLATFORM_EC_MKBP_EVENT`              | n           | [MKBP event]
+
+The following options must be enabled to use respective masks specified in
+device tree. See [Device Tree nodes](#device-tree-nodes) paragraph for details.
+
+Kconfig sub-options                             | Default     | Documentation
+:---------------------------------------------- | :---------: | :------------
+`CONFIG_PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK`     | n           | [MKBP event wake-up mask]
+`CONFIG_PLATFORM_EC_MKBP_HOST_EVENT_WAKEUP_MASK`| n           | [MKBP host event wake-up mask]
+
+The following options select the delivery method of MKBP messages.
+
+Kconfig sub-options                              | Default     | Documentation
+:----------------------------------------------- | :---------: | :------------
+`CONFIG_PLATFORM_EC_MKBP_USE_GPIO`               | y           | [MKBP gpio]
+`CONFIG_PLATFORM_EC_MKBP_USE_HOST_EVENT`         | n           | [MKBP host event]
+`CONFIG_PLATFORM_EC_MKBP_USE_GPIO_AND_HOST_EVENT`| n           | [MKBP gpio and host event]
+`CONFIG_PLATFORM_EC_MKBP_USE_CUSTOM`             | n           | [MKBP custom]
+
+### Debug
+
+The `CONFIG_PLATFORM_EC_HOSTCMD_DEBUG_MODE` choice selects the verbosity
+level of messages on the EC console.
+
+Kconfig debug verbosity | Default | Documentation
+:---------------------- | :-----: | :------------
+`CONFIG_HCDEBUG_OFF`    | n       | [Debug off]
+`CONFIG_HCDEBUG_NORMAL` | y       | [Debug normal]
+`CONFIG_HCDEBUG_EVERY`  | n       | [Debug every]
+`CONFIG_HCDEBUG_PARAMS` | n       | [Debug params]
+
+## Device Tree nodes
+
+### eSPI
+
+Zephyr has built-in support for eSPI and EC takes advantage of this.
+Boards supported by Zephyr should have definitions of eSPI interfaces in their
+device trees.
+To select the eSPI interface to be used for sending the host commands it must
+be set as chosen node with name `cros-ec,espi`.
+The referenced node has to be enabled, which means that its `status` must
+be set as `okay`.
+
+```
+/ {
+	chosen {
+		cros-ec,espi = &espi0;
+	}
+}
+
+&espi0 {
+	status = "okay";
+};
+```
+
+### SHI
+
+The SoC specific Kconfig for SHI driver is automatically enabled based on
+selected host interface and SoC family. Each SoC driver has specific
+compatibility string which is used to get node with configuration from the
+device tree.
+For example, the nuvoton npcx chip uses compatibility string
+`nuvoton,npcx-cros-shi`.
+
+The node's required properties are defined in yaml files: [SHI bindings]
+
+```
+/ {
+	shi: shi@4000f000 {
+		compatible = "nuvoton,npcx-cros-shi";
+		reg = <0x4000f000 0x120>;
+		interrupts = <18 1>;
+		clocks = <&pcc NPCX_CLOCK_BUS_APB3 NPCX_PWDWN_CTL5 1>;
+		pinctrl-0 = <&altc_shi_sl>;
+		shi-cs-wui =<&wui_io53>;
+		label = "SHI";
+	};
+}
+```
+
+### MKBP Wake-up Masks
+
+The EC can wake up the AP from sleep modes based on multiple event types.
+A wake-up mask specifies which specific event types are able to wake the AP.
+
+For x86 based Chromebooks, the wake-up mask is controlled by the AP firmware
+directly using host commands `EC_CMD_HOST_EVENT_SET_SMI_MASK`,
+`EC_CMD_HOST_EVENT_SET_SCI_MASK` and `EC_CMD_HOST_EVENT_SET_WAKE_MASK`.
+
+For ARM based Chromebooks, the wake-up mask is defined as device tree nodes,
+one for MKBP events and one for generic host events.
+They have respective Kconfig options, which must be enabled to take the masks
+into account.
+
+Both masks have to be compatible with binding file: [MKBP event mask yaml]
+
+Possible enums to use in these nodes are specified in file: [MKBP event mask enums]
+
+```
+/ {
+	ec-mkbp-host-event-wakeup-mask {
+		compatible = "ec-wake-mask-event";
+		wakeup-mask = <(HOST_EVENT_LID_OPEN |
+				HOST_EVENT_POWER_BUTTON |
+				HOST_EVENT_AC_CONNECTED |
+				HOST_EVENT_AC_DISCONNECTED |
+				HOST_EVENT_HANG_DETECT |
+				HOST_EVENT_RTC |
+				HOST_EVENT_MODE_CHANGE |
+				HOST_EVENT_DEVICE)>;
+	};
+
+	ec-mkbp-event-wakeup-mask {
+		compatible = "ec-wake-mask-event";
+		wakeup-mask = <(MKBP_EVENT_KEY_MATRIX |
+				MKBP_EVENT_HOST_EVENT |
+				MKBP_EVENT_SENSOR_FIFO)>;
+	};
+}
+```
+
+## Board Specific Code
+
+No board specific code is required.
+
+## Threads
+
+The host_command_task() thread processes all requests from the AP, regardless
+of the host interface type enabled.
+
+Enabling the `CONFIG_PLATFORM_EC_HOSTCMD` automatically selects
+`CONFIG_HAS_TASK_HOSTCMD` which is responsible for creating the thread.
+
+## Testing and Debugging
+
+Testing and debugging the host commands on DUT are described in
+[CrOS EC documentation]. It is recommended to run the stress test to check
+if communication is working properly with a huge amount of data sent.
+Running the stress test is described in the previously mentioned documentation,
+in the chapter [stress test].
+
+### From EC console
+
+If debug level is higher than `CONFIG_HCDEBUG_OFF`, then HC messages can
+be seen on EC console.
+
+If there's no output lines starting from HC, that may be due to hostcmd channel
+being masked.
+To check what channels are masked, execute `chan` command in EC console.
+```
+uart:~$ chan
+ # Mask     E Channel
+...
+ 7 00000080 * hostcmd
+```
+The asterisk next to channel name means that it is enabled. Otherwise, execute
+command `chan 128` to enable hostcmd channel while disabling others.
+
+If the hostcmd channel is disabled by default, it may be enabled by removing
+its name from `ec-console` node.
+
+```
+ec-console {
+	compatible = "ec-console";
+
+	disabled = "hostcmd";
+};
+```
+
+Removing the `hostcmd` and leaving the empty quotes will result in hostcmd
+messages visible on EC console since boot-up.
+
+## Examples
+
+[Lazor MKBP wake-up](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/trogdor/lazor/gpio.dts?q=ec-mkbp-host-event-wakeup-mask)
+
+[Lazor MKBP Kconfig](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/trogdor/lazor/prj.conf?q=CONFIG_PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK)
+
+[NPCX eSPI selection](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/include/cros/nuvoton/npcx.dtsi?q=cros-ec,espi)
+
+[NPCX SHI definition](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/include/cros/nuvoton/npcx.dtsi?q=shi)
+
+<!--
+Links to the documentation
+-->
+[SHI]:../ec_terms.md#shi
+[eSPI]:../ec_terms.md#espi
+[LPC]:../ec_terms.md#lpc
+[EC host commands]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22menuconfig%20PLATFORM_EC_HOSTCMD%22
+[eSPI interface]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.host_interface?q=%22config%20PLATFORM_EC_HOST_INTERFACE_ESPI%22
+[HECI interface]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.host_interface?q=%22config%20PLATFORM_EC_HOST_INTERFACE_HECI%22
+[LPC interface]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.host_interface?q=%22config%20PLATFORM_EC_HOST_INTERFACE_LPC%22
+[SHI interface]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.host_interface?q=%22config%20PLATFORM_EC_HOST_INTERFACE_SHI%22
+
+[Kconfig.espi]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.espi
+
+[Host command console]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.console?q=%22menuconfig%20PLATFORM_EC_HOSTCMD_CONSOLE%22
+[Host command console buffer size]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.console?q=%22config%20PLATFORM_EC_HOSTCMD_CONSOLE_BUF_SIZE%22
+[Host command - status]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_HOST_COMMAND_STATUS%22
+
+[MKBP input devices]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_INPUT_DEVICES%22
+[MKBP event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_EVENT%22
+
+[MKBP event wake-up mask]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK%22
+[MKBP host event wake-up mask]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_HOST_EVENT_WAKEUP_MASK%22
+
+[MKBP gpio]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_GPIO%22
+[MKBP host event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_HOST_EVENT%22
+[MKBP gpio and host event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_GPIO_AND_HOST_EVENT%22
+[MKBP custom]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_CUSTOM%22
+
+[Debug off]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20HCDEBUG_OFF%22
+[Debug normal]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20HCDEBUG_NORMAL%22
+[Debug every]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20HCDEBUG_EVERY%22
+[Debug params]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20HCDEBUG_PARAMS%22
+
+[SHI bindings]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/cros_shi/
+[MKBP event mask yaml]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/cros_mkbp_event/ec-mkbp-event.yaml
+[MKBP event mask enums]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/include/dt-bindings/wake_mask_event_defines.h
+
+[CrOS EC documentation]:../ap-ec-comm.md#ectool
+[stress test]:../ap-ec-comm.md#stress-test
diff --git a/docs/zephyr/zephyr_new_board_checklist.md b/docs/zephyr/zephyr_new_board_checklist.md
@@ -52,7 +52,7 @@ feature.
 EC Feature                                                                  | Needed for Power On
 :-------------------------------------------------------------------------- | :-----------------:
 [Configure EC Chipset (TODO)](./zephyr_template.md)                         | yes
-[Configure AP to EC Communication (TOD0)](./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-C (TODO)](./zephyr_template.md)                              | yes
 [Configure Charger (TODO)](./zephyr_template.md)                            | yes
diff --git a/docs/zephyr/zephyr_poc_device_bringup.md b/docs/zephyr/zephyr_poc_device_bringup.md
@@ -38,6 +38,8 @@ As long as you get this compiling that should be enough to move to the
 next step.  Further testing of the host command layer will require
 power sequencing up and going.
 
+For further explanation, check [AP-EC communication](zephyr_ap_ec_comm.md) document.
+
 ## Enabling some simple GPIO-based buttons and switches
 
 Next, you can:
