571f8591b9
Correcting typos in various documentation files Signed-off-by: Andreas Deininger <andreas@deininger.net>
87 lines
3.2 KiB
ReStructuredText
87 lines
3.2 KiB
ReStructuredText
.. _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 only 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.
|
|
|
|
Logging
|
|
*******
|
|
|
|
The host command has an embedded logging system of the ongoing communication. The are a few logging
|
|
levels:
|
|
|
|
* `LOG_INF` is used to log a command id of a new command and not success responses. Repeats of the
|
|
same command are not logged
|
|
* `LOG_DBG` logs every command, even repeats
|
|
* `LOG_DBG` + :kconfig:option:`CONFIG_EC_HOST_CMD_LOG_DBG_BUFFERS` logs every command and responses
|
|
with the data buffers
|
|
|
|
API Reference
|
|
*************
|
|
|
|
.. doxygengroup:: ec_host_cmd_interface
|