| .. _ec_host_cmd_backend_api: |
| |
| EC Host Command |
| ############### |
| |
| Overview |
| ******** |
| The host command protocol defines the interface for a host, or application processor, to |
| communicate with a target embedded controller (EC). The EC Host command subsystem implements the |
| target side of the protocol, generating responses to commands sent by the host. The host command |
| protocol interface supports multiple versions, but this subsystem implementation only support |
| protocol version 3. |
| |
| Architecture |
| ************ |
| The Host Command subsystem contains a few components: |
| |
| * Backend |
| * General handler |
| * Command handler |
| |
| The backend is a layer between a peripheral driver and the general handler. It is responsible for |
| sending and receiving commands via chosen peripheral. |
| |
| The general handler validates data from the backend e.g. check sizes, checksum, etc. If the command |
| is valid and the user has provided a handler for a received command id, the command handler is |
| called. |
| |
| .. image:: ec_host_cmd.png |
| :align: center |
| |
| SHI (Serial Host Interface) is different to this because it is used olny for communication with a |
| host. SHI does not have API itself, thus the backend and peripheral driver layers are combined into |
| one backend layer. |
| |
| .. image:: ec_host_cmd_shi.png |
| :align: center |
| |
| The supported backend and peripheral drivers: |
| |
| * Simulator |
| * SHI - ITE and NPCX |
| * eSPI - any eSPI slave driver that support :kconfig:option:`CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD` and |
| :kconfig:option:`CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE` |
| * UART - any UART driver that supports the asynchronous API |
| |
| Initialization |
| ************** |
| |
| If the application configures one of the following backend chosen nodes and |
| :kconfig:option:`CONFIG_EC_HOST_CMD_INITIALIZE_AT_BOOT` is set, then the corresponding backend |
| initializes the host command subsystem by calling :c:func:`ec_host_cmd_init`: |
| |
| * ``zephyr,host-cmd-espi-backend`` |
| * ``zephyr,host-cmd-shi-backend`` |
| * ``zephyr,host-cmd-uart-backend`` |
| |
| If no backend chosen node is configured, the application must call the :c:func:`ec_host_cmd_init` |
| function directly. This way of initialization is useful if a backend is chosen in runtime |
| based on e.g. GPIO state. |
| |
| Buffers |
| ******* |
| |
| The host command communication requires buffers for rx and tx. The buffers are be provided by the |
| general handler if :kconfig:option:`CONFIG_EC_HOST_CMD_HANDLER_RX_BUFFER_SIZE` > 0 for rx buffer and |
| :kconfig:option:`CONFIG_EC_HOST_CMD_HANDLER_TX_BUFFER_SIZE` > 0 for the tx buffer. The shared |
| buffers are useful for applications that use multiple backends. Defining separate buffers by every |
| backend would increase the memory usage. However, some buffers can be defined by a peripheral driver |
| e.g. eSPI. These ones should be reused as much as possible. |
| |
| API Reference |
| ************* |
| |
| .. doxygengroup:: ec_host_cmd_interface |