1# Application Processor to EC communication 2 3[TOC] 4 5## Overview 6 7The Application Processor (sometimes called the host) communicates with the EC 8by issuing *host commands*, which are identified by a command ID and version 9number, and then reading a response. When a host command is issued through 10`ectool`, two or three software components are involved: 11 12* `ectool`, the user-space binary, 13* normally the `cros-ec` Kernel driver, and 14* the code on the EC itself. This can be thought of as two parts: 15 * a chip-specific driver for the appropriate transport, and 16 * the generic host command handling code (mostly in the [host command task]). 17 18We'll go into detail of each of these, as well as the traffic on the wire, in 19the following sections. 20 21### `ectool` 22 23`ectool` contains wrapper functions for the host commands exposed by the EC, 24providing a CLI. They call one of the transport-specific `ec_command` 25implementations in the `util/comm-*.c` files to send and receive from the EC. 26 27### EC kernel driver 28 29In most cases, `ectool` communicates via the [`cros-ec` Kernel driver], rather 30than directly from userspace. It sends raw commands to the Kernel driver, which 31sends them on to the EC, bypassing a lot of the other Kernel driver 32functionality. 33 34There are other CrOS EC-related Kernel drivers, which use host commands to act 35as adapters to existing Linux APIs. For example, sensors from the EC are mapped 36to the Linux [Industrial I/O] system. 37 38### On the wire 39 40Now we come to the protocol itself. All transactions take this general form: 41 42* Host writes the request packet, consisting of: 43 * a transport-specific header; 44 * a `struct ec_host_request` containing the command ID, data length, and a 45 checksum; and 46 * zero or more bytes of parameters for the command, the format of which 47 depends on the command. 48* Host reads the response to its request, consisting of: 49 * a transport-specific header; 50 * a `struct ec_host_response` containing the result code, data length, and a 51 checksum; and 52 * zero or more bytes of response from the command, again with a 53 command-specific format. 54 55### On the EC 56 57The host packet is received on the EC by some chip-specific code which checks 58its transport-specific header, then passes it on to the common host command code, 59starting at `host_packet_receive`. The common code validates the packet and 60then sends it on to the handler function (annotated with the 61`DECLARE_HOST_COMMAND` macro), which runs in the `HOSTCMD` task. The handler can 62set a response by modifying its arguments struct, which is sent back to the host 63via the chip-specific code. 64 65While this is happening, the EC needs to indicate to the host that it is busy 66processing and not yet ready to give a response. How it does this depends on the 67transport method used (see [Transport-specific details] below). 68 69## Versions 70 71There are two different concepts of "version" involved in host commands: version 72of the overarching protocol, and versions of individual commands. 73 74### Protocol versions 75 76There have been three protocol versions so far, and this document describes 77version 3. Version 1 was superseded by 2 before it shipped, so no devices use 78it anymore. Version 2 is generally deprecated, but you might still encounter it 79occasionally. 80 81Which version is in use can be determined using the `EC_CMD_GET_PROTOCOL_INFO` 82command. This was only introduced in version 3, however, so if errors, 83`EC_CMD_HELLO` should be sent in version 2. If the hello command succeeds, the 84EC speaks version 2. 85 86### Command versions 87 88Individual commands also have versions, independent of the protocol version 89they're being called with. Different versions of a command may have different 90parameter or response formats. `EC_CMD_GET_CMD_VERSIONS` returns the versions of 91the given command supported by the EC. These version numbers start at 0. 92 93## Transport-specific details 94 95Although the command and response formats are the same across all transports, 96some details of how they are transmitted differ, which may be of interest when 97implementing the EC side of the protocol on a new chip. 98 99### I<sup>2</sup>C 100 101I<sup>2</sup>C is very flexible with its timing, so when the EC receives a 102packet from the host, it should stretch the clock, holding it low until it is 103ready for the host to read the response. 104 105If the host tries to read more bytes than were in the response, the EC should 106respond with an obvious filler byte (such as 0xEC). For example, if a command 107that normally returns 50 bytes errors, its response will only be 8 bytes (the 108size of the response struct). The host will probably try to read 50 bytes 109anyway, so the EC should send the 8 bytes of the struct followed by 42 copies of 110the filler byte. 111 112### SPI 113 114The SPI bus is similar to I<sup>2</sup>C, but with two major exceptions. First, 115there's a minimum speed on the SPI bus. If peripheral devices don't respond 116quickly enough, the controller will assume they're broken and give up. Second, 117every transaction is bidirectional. When bits are being clocked from controller 118to peripheral on the MOSI line, the controller will simultaneously read bits in 119the other direction on the MISO line. 120 121Hardware devices can usually handle this, and often some hardware-based flow 122control used to "stretch" the transaction by a bit or byte if the peripheral 123device needs a little extra time to respond to the controller's demands. 124 125When exchanging messages with the EC on the SPI bus, the EC's host commands are 126communicated using our own software flow-control scheme, because most of the 127embedded controllers either aren't fast enough or don't have any support for 128hardware flow-control. 129 130It works like this: When the AP sends a byte to the EC, if the EC doesn't have a 131response queued up in advance, a default "placeholder" byte is returned. The EC 132preconfigures that default response byte to indicate its status (ready, busy, 133waiting for more input, etc.). Once the AP has sent a complete command message, 134it continues clocking bytes to the EC (which the EC ignores) and just looks at 135the response byte that comes back. Once the EC has parsed the AP's command and 136is ready to reply, it sends a "start of frame" byte, followed by the actual 137response. The AP continues to read and ignore bytes from the EC until it sees 138the start of frame byte, and then it knows that the EC's response is starting 139with the next byte. 140 141Once the response packet has been read, any additional reads should return 142`EC_SPI_PAST_END`. 143 144### LPC or eSPI 145 146The EC should set `EC_LPC_STATUS_PROCESSING` in its command status register 147after receiving a host packet and before it has a response ready. 148 149 150[`cros-ec` Kernel driver]: https://chromium.googlesource.com/chromiumos/third_party/kernel/+/refs/heads/chromeos-4.19/drivers/mfd/cros_ec_dev.c 151[Industrial I/O]: https://www.kernel.org/doc/html/v4.14/driver-api/iio/index.html 152[host command task]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/main/common/host_command.c 153[Transport-specific details]: #Transport_specific-details 154