Part 1
요약·해설
일반 backend와 SHI·SPI 통합 구조, DTS compatible, chosen node 초기화, shared buffer와 log level을 설명합니다.
Version 3
SHI · eSPI · UART · SPI
Backend → Handler
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
48C63D87A11DB09D82812EFD3AAB14243E6DB927ED5A3139B06FD8BFA6D94A3C
.. _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:: ../../../../services/device_mgmt/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:: ../../../../services/device_mgmt/ec_host_cmd_shi.png
:align: center
Another case is SPI. Unfortunately, the current SPI API can't be used to handle the host commands
communication. The main issues are unknown command size sent by the host (the SPI transaction
sends/receives specific number of bytes) and need to constant sending status byte (the SPI module
is enabled and disabled per transaction). It forces implementing the SPI driver within a backend,
as it is done for SHI. That means a SPI backend has to be implemented per chip family. However, it
can be changed in the future once the SPI API is extended to host command needs. Please check `the
discussion <https://github.com/zephyrproject-rtos/zephyr/issues/56091>`_.
That approach requires configuring the SPI dts node in a special way. The main compatible string of
a SPI node has changed to use the Host Command version of a SPI driver. The rest of the properties
should be configured as usual. Example of the SPI node for STM32:
.. code-block:: devicetree
&spi1 {
/* Change the compatible string to use the Host Command version of the
* STM32 SPI driver
*/
compatible = "st,stm32-spi-host-cmd";
status = "okay";
dmas = <&dma2 3 3 0x38440 0x03>,
<&dma2 0 3 0x38480 0x03>;
dma-names = "tx", "rx";
/* This field is used to point at our CS pin */
cs-gpios = <&gpioa 4 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
};
The STM32 SPI host command backend driver supports the :dtcompatible:`st,stm32h7-spi` and
:dtcompatible:`st,stm32-spi-fifo` variant implementations. To enable these variants, append the
corresponding compatible string. For example, to enable FIFO support and support for the STM32H7
SoCs, modify the compatible string as shown.
.. code-block:: devicetree
&spi1 {
compatible = "st,stm32h7-spi", "st,stm32-spi-fifo", "st,stm32-spi-host-cmd";
...
};
The chip that runs Zephyr is a SPI slave and the `cs-gpios` property is used to point our CS pin.
For the SPI, it is required to set the backend chosen node ``zephyr,host-cmd-spi-backend``.
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
* SPI - STM32
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``
* ``zephyr,host-cmd-spi-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
Part 3
한국어 전문 번역
개요
Host command protocol은 host 또는 application processor가 target embedded controller(EC)와 통신하는 interface를 정의합니다. EC Host Command subsystem은 protocol의 target 측을 구현해 host가 보낸 command에 response를 생성합니다. Protocol interface는 여러 version을 지원하지만 이 subsystem 구현은 protocol version 3만 지원합니다.
Architecture
Host Command subsystem은 세 component로 구성됩니다.
- Backend
- General handler
- Command handler
Backend는 peripheral driver와 general handler 사이의 layer이며 선택한 peripheral로 command를 송수신합니다.
General handler는 backend가 보낸 data의 size와 checksum 등을 검증합니다. Command가 valid하고 user가 수신한 command ID용 handler를 제공했다면 command handler를 호출합니다.

SHI(Serial Host Interface)는 host 통신 전용이라는 점에서 다릅니다. SHI 자체 API가 없으므로 backend와 peripheral driver layer를 하나의 backend layer로 합칩니다.

SPI도 별도 case입니다. 현재 SPI API는 host command 통신을 처리할 수 없습니다. Host가 보내는 command size를 미리 알 수 없지만 SPI transaction은 정해진 byte 수를 송수신하고, SPI module은 transaction마다 enable·disable되므로 status byte를 계속 보내기도 어렵습니다. 따라서 SHI처럼 backend 안에 SPI driver를 구현해야 하며 chip family마다 SPI backend가 필요합니다. SPI API가 host command 요구 사항을 지원하도록 확장되면 바뀔 수 있습니다. 관련 discussion을 참고합니다.
이 방식에서는 SPI DTS node를 특별하게 설정해야 합니다. SPI node의 주 compatible string을 Host Command version SPI driver로 바꾸고 나머지 property는 평소처럼 설정합니다. STM32 SPI node 예는 다음과 같습니다.
&spi1 {
/* Change the compatible string to use the Host Command version of the
* STM32 SPI driver
*/
compatible = "st,stm32-spi-host-cmd";
status = "okay";
dmas = <&dma2 3 3 0x38440 0x03>,
<&dma2 0 3 0x38480 0x03>;
dma-names = "tx", "rx";
/* This field is used to point at our CS pin */
cs-gpios = <&gpioa 4 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
};
STM32 SPI Host Command backend driver는 st,stm32h7-spi와 st,stm32-spi-fifo variant 구현을 지원합니다. Variant를 enable하려면 대응 compatible string을 추가합니다. 다음 예는 FIFO와 STM32H7 SoC support를 함께 enable합니다.
&spi1 {
compatible = "st,stm32h7-spi", "st,stm32-spi-fifo", "st,stm32-spi-host-cmd";
...
};
Zephyr를 실행하는 chip은 SPI slave이며 cs-gpios property가 이 chip의 CS pin을 가리킵니다. SPI에서는 backend chosen node zephyr,host-cmd-spi-backend도 설정해야 합니다.
지원하는 backend와 peripheral driver는 다음과 같습니다.
- Simulator
- SHI: ITE와 NPCX
- eSPI:
CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD와CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE를 지원하는 eSPI slave driver - UART: asynchronous API를 지원하는 UART driver
- SPI: STM32
초기화
Application이 다음 backend chosen node 중 하나를 설정하고 CONFIG_EC_HOST_CMD_INITIALIZE_AT_BOOT을 enable하면 해당 backend가 ec_host_cmd_init을 호출해 Host Command subsystem을 초기화합니다.
zephyr,host-cmd-espi-backendzephyr,host-cmd-shi-backendzephyr,host-cmd-uart-backendzephyr,host-cmd-spi-backend
Backend chosen node가 없다면 application이 ec_host_cmd_init을 직접 호출해야 합니다. GPIO state 등에 따라 runtime에 backend를 고를 때 유용한 초기화 방식입니다.
Buffer
Host command 통신에는 RX와 TX buffer가 필요합니다. CONFIG_EC_HOST_CMD_HANDLER_RX_BUFFER_SIZE가 0보다 크면 general handler가 RX buffer를 제공하고, CONFIG_EC_HOST_CMD_HANDLER_TX_BUFFER_SIZE가 0보다 크면 TX buffer를 제공합니다.
Shared buffer는 여러 backend를 사용하는 application에 유용합니다. Backend마다 separate buffer를 두면 memory usage가 늘어납니다. 다만 eSPI처럼 peripheral driver가 자체 buffer를 제공할 수 있으며, 이런 buffer는 가능한 한 재사용해야 합니다.
Logging
Host Command에는 진행 중인 통신을 기록하는 logging system이 내장되어 있습니다.
LOG_INF: 새 command의 ID와 성공하지 않은 response를 기록합니다. 같은 command의 반복은 기록하지 않습니다.LOG_DBG: 반복을 포함해 모든 command를 기록합니다.LOG_DBG와CONFIG_EC_HOST_CMD_LOG_DBG_BUFFERS: 모든 command와 response를 data buffer와 함께 기록합니다.
API Reference
원문의 Doxygen group ec_host_cmd_interface에 Host Command API가 수록됩니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.