EC Host Command Interface. More...

Data Structures
struct	ec_host_cmd_rx_ctx
	Context for host command backend and handler to pass rx data. More...

struct	ec_host_cmd_tx_buf
	Context for host command backend and handler to pass tx data. More...

struct	ec_host_cmd_backend_api

struct	ec_host_cmd

struct	ec_host_cmd_handler_args
	Arguments passed into every installed host command handler. More...

struct	ec_host_cmd_handler
	Structure use for statically registering host command handlers. More...

struct	ec_host_cmd_request_header
	Header for requests from host to embedded controller. More...

struct	ec_host_cmd_response_header
	Header for responses from embedded controller to host. More...

Macros
#define	EC_HOST_CMD_HANDLER(_id, _function, _version_mask, _request_type, _response_type)
	Statically define and register a host command handler.

#define	EC_HOST_CMD_HANDLER_UNBOUND(_id, _function, _version_mask)
	Statically define and register a host command handler without sizes.

Typedefs
typedef int(*	ec_host_cmd_backend_api_init) (const struct ec_host_cmd_backend backend, struct ec_host_cmd_rx_ctx rx_ctx, struct ec_host_cmd_tx_buf *tx)
	Initialize a host command backend.

typedef int(*	ec_host_cmd_backend_api_send) (const struct ec_host_cmd_backend *backend)
	Sends data to the host.

typedef void(*	ec_host_cmd_user_cb_t) (const struct ec_host_cmd_rx_ctx rx_ctx, void user_data)

typedef enum ec_host_cmd_status(*	ec_host_cmd_in_progress_cb_t) (void *user_data)

typedef enum ec_host_cmd_status(*	ec_host_cmd_handler_cb) (struct ec_host_cmd_handler_args *args)

Enumerations
enum	ec_host_cmd_status { EC_HOST_CMD_SUCCESS = 0 , EC_HOST_CMD_INVALID_COMMAND = 1 , EC_HOST_CMD_ERROR = 2 , EC_HOST_CMD_INVALID_PARAM = 3 , EC_HOST_CMD_ACCESS_DENIED = 4 , EC_HOST_CMD_INVALID_RESPONSE = 5 , EC_HOST_CMD_INVALID_VERSION = 6 , EC_HOST_CMD_INVALID_CHECKSUM = 7 , EC_HOST_CMD_IN_PROGRESS = 8 , EC_HOST_CMD_UNAVAILABLE = 9 , EC_HOST_CMD_TIMEOUT = 10 , EC_HOST_CMD_OVERFLOW = 11 , EC_HOST_CMD_INVALID_HEADER = 12 , EC_HOST_CMD_REQUEST_TRUNCATED = 13 , EC_HOST_CMD_RESPONSE_TOO_BIG = 14 , EC_HOST_CMD_BUS_ERROR = 15 , EC_HOST_CMD_BUSY = 16 , EC_HOST_CMD_INVALID_HEADER_VERSION = 17 , EC_HOST_CMD_INVALID_HEADER_CRC = 18 , EC_HOST_CMD_INVALID_DATA_CRC = 19 , EC_HOST_CMD_DUP_UNAVAILABLE = 20 , EC_HOST_CMD_MAX = UINT16_MAX }
	Host command response codes (16-bit). More...

enum	ec_host_cmd_log_level { EC_HOST_CMD_DEBUG_OFF , EC_HOST_CMD_DEBUG_NORMAL , EC_HOST_CMD_DEBUG_EVERY , EC_HOST_CMD_DEBUG_PARAMS , EC_HOST_CMD_DEBUG_MODES }

enum	ec_host_cmd_state { EC_HOST_CMD_STATE_DISABLED = 0 , EC_HOST_CMD_STATE_RECEIVING , EC_HOST_CMD_STATE_PROCESSING , EC_HOST_CMD_STATE_SENDING }

Functions
struct ec_host_cmd_backend *	ec_host_cmd_backend_get_espi (const struct device *dev)
	Get the eSPI Host Command backend pointer.

struct ec_host_cmd_backend *	ec_host_cmd_backend_get_shi_npcx (void)
	Get the SHI NPCX Host Command backend pointer.

struct ec_host_cmd_backend *	ec_host_cmd_backend_get_shi_ite (void)
	Get the SHI ITE Host Command backend pointer.

struct ec_host_cmd_backend *	ec_host_cmd_backend_get_uart (const struct device *dev)
	Get the UART Host Command backend pointer.

struct ec_host_cmd_backend *	ec_host_cmd_backend_get_spi (struct gpio_dt_spec *cs)
	Get the SPI Host Command backend pointer.

int	ec_host_cmd_init (struct ec_host_cmd_backend *backend)
	Initialize the host command subsystem.

int	ec_host_cmd_send_response (enum ec_host_cmd_status status, const struct ec_host_cmd_handler_args *args)
	Send the host command response.

void	ec_host_cmd_rx_notify (void)
	Signal a new host command.

void	ec_host_cmd_set_user_cb (ec_host_cmd_user_cb_t cb, void *user_data)
	Install a user callback for receiving a host command.

const struct ec_host_cmd *	ec_host_cmd_get_hc (void)
	Get the main ec host command structure.

FUNC_NORETURN void	ec_host_cmd_task (void)
	The thread function for Host Command subsystem.

int	ec_host_cmd_add_suppressed (uint16_t cmd_id)
	Add a suppressed command.

Detailed Description

EC Host Command Interface.

Since: 2.4

Version: 0.1.0

Macro Definition Documentation

◆ EC_HOST_CMD_HANDLER

#define EC_HOST_CMD_HANDLER	(	_id,
		_function,
		_version_mask,
		_request_type,
		_response_type
	)

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Value:

        const STRUCT_SECTION_ITERABLE(ec_host_cmd_handler, __cmd##_id) = {                         \
                .handler = _function,                                                              \
                .id = _id,                                                                         \
                .version_mask = _version_mask,                                                     \
                .min_rqt_size = sizeof(_request_type),                                             \
                .min_rsp_size = sizeof(_response_type),                                            \
        }

Statically define and register a host command handler.

Helper macro to statically define and register a host command handler that has a compile-time-fixed sizes for its both request and response structures.

Parameters

_id	Id of host command to handle request for.
_function	Name of handler function.
_version_mask	The bitfield of all versions that the _function supports. E.g. BIT(0) corresponds to version 0.
_request_type	The datatype of the request parameters for _function.
_response_type	The datatype of the response parameters for _function.

◆ EC_HOST_CMD_HANDLER_UNBOUND

#define EC_HOST_CMD_HANDLER_UNBOUND	(	_id,
		_function,
		_version_mask
	)

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Value:

        const STRUCT_SECTION_ITERABLE(ec_host_cmd_handler, __cmd##_id) = {                         \
                .handler = _function,                                                              \
                .id = _id,                                                                         \
                .version_mask = _version_mask,                                                     \
                .min_rqt_size = 0,                                                                 \
                .min_rsp_size = 0,                                                                 \
        }

Statically define and register a host command handler without sizes.

Helper macro to statically define and register a host command handler whose request or response structure size is not known as compile time.

Parameters

_id	Id of host command to handle request for.
_function	Name of handler function.
_version_mask	The bitfield of all versions that the _function supports. E.g. BIT(0) corresponds to version 0.

Typedef Documentation

◆ ec_host_cmd_backend_api_init

typedef int(* ec_host_cmd_backend_api_init) (const struct ec_host_cmd_backend *backend, struct ec_host_cmd_rx_ctx *rx_ctx, struct ec_host_cmd_tx_buf *tx)

#include <include/zephyr/mgmt/ec_host_cmd/backend.h>

Initialize a host command backend.

This routine initializes a host command backend. It includes initialization a device used to communication and setting up buffers. This function is called by the ec_host_cmd_init function.

Parameters

[in]	backend	Pointer to the backend structure for the driver instance.
[in,out]	rx_ctx	Pointer to the receive context object. These objects are used to receive data from the driver when the host sends data. The buf member can be assigned by the backend.
[in,out]	tx	Pointer to the transmit buffer object. The buf and len_max members can be assigned by the backend. These objects are used to send data by the backend with the ec_host_cmd_backend_api_send function.

Return values

0	if successful

◆ ec_host_cmd_backend_api_send

typedef int(* ec_host_cmd_backend_api_send) (const struct ec_host_cmd_backend *backend)

#include <include/zephyr/mgmt/ec_host_cmd/backend.h>

Sends data to the host.

Sends data from tx buf that was passed via ec_host_cmd_backend_api_init function.

Parameters

backend Pointer to the backed to send data.

Return values

0	if successful.

◆ ec_host_cmd_handler_cb

typedef enum ec_host_cmd_status(* ec_host_cmd_handler_cb) (struct ec_host_cmd_handler_args *args)

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

◆ ec_host_cmd_in_progress_cb_t

typedef enum ec_host_cmd_status(* ec_host_cmd_in_progress_cb_t) (void *user_data)

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

◆ ec_host_cmd_user_cb_t

typedef void(* ec_host_cmd_user_cb_t) (const struct ec_host_cmd_rx_ctx *rx_ctx, void *user_data)

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Enumeration Type Documentation

◆ ec_host_cmd_log_level

enum ec_host_cmd_log_level

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Enumerator
EC_HOST_CMD_DEBUG_OFF
EC_HOST_CMD_DEBUG_NORMAL
EC_HOST_CMD_DEBUG_EVERY
EC_HOST_CMD_DEBUG_PARAMS
EC_HOST_CMD_DEBUG_MODES

◆ ec_host_cmd_state

enum ec_host_cmd_state

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Enumerator
EC_HOST_CMD_STATE_DISABLED
EC_HOST_CMD_STATE_RECEIVING
EC_HOST_CMD_STATE_PROCESSING
EC_HOST_CMD_STATE_SENDING

◆ ec_host_cmd_status

enum ec_host_cmd_status

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Host command response codes (16-bit).

Enumerator
EC_HOST_CMD_SUCCESS	Host command was successful.
EC_HOST_CMD_INVALID_COMMAND	The specified command id is not recognized or supported.
EC_HOST_CMD_ERROR	Generic Error.
EC_HOST_CMD_INVALID_PARAM	One of more of the input request parameters is invalid.
EC_HOST_CMD_ACCESS_DENIED	Host command is not permitted.
EC_HOST_CMD_INVALID_RESPONSE	Response was invalid (e.g. not version 3 of header).
EC_HOST_CMD_INVALID_VERSION	Host command id version unsupported.
EC_HOST_CMD_INVALID_CHECKSUM	Checksum did not match.
EC_HOST_CMD_IN_PROGRESS	A host command is currently being processed.
EC_HOST_CMD_UNAVAILABLE	Requested information is currently unavailable.
EC_HOST_CMD_TIMEOUT	Timeout during processing.
EC_HOST_CMD_OVERFLOW	Data or table overflow.
EC_HOST_CMD_INVALID_HEADER	Header is invalid or unsupported (e.g. not version 3 of header).
EC_HOST_CMD_REQUEST_TRUNCATED	Did not receive all expected request data.
EC_HOST_CMD_RESPONSE_TOO_BIG	Response was too big to send within one response packet.
EC_HOST_CMD_BUS_ERROR	Error on underlying communication bus.
EC_HOST_CMD_BUSY	System busy. Should retry later.
EC_HOST_CMD_INVALID_HEADER_VERSION	Header version invalid.
EC_HOST_CMD_INVALID_HEADER_CRC	Header CRC invalid.
EC_HOST_CMD_INVALID_DATA_CRC	Data CRC invalid.
EC_HOST_CMD_DUP_UNAVAILABLE	Can't resend response.
EC_HOST_CMD_MAX

Function Documentation

◆ ec_host_cmd_add_suppressed()

int ec_host_cmd_add_suppressed ( uint16_t cmd_id )

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Add a suppressed command.

Suppressed commands are not logged. Add a command to be suppressed.

Parameters

[in] cmd_id A command id to be suppressed.

Return values

0	if successful, -EIO if exceeded max number of suppressed commands.

◆ ec_host_cmd_backend_get_espi()

struct ec_host_cmd_backend * ec_host_cmd_backend_get_espi ( const struct device * dev )

#include <include/zephyr/mgmt/ec_host_cmd/backend.h>

Get the eSPI Host Command backend pointer.

Get the eSPI pointer backend and pass a pointer to eSPI device instance that will be used for the Host Command communication.

Parameters

dev	Pointer to eSPI device instance.

Return values

The	eSPI backend pointer.

◆ ec_host_cmd_backend_get_shi_ite()

struct ec_host_cmd_backend * ec_host_cmd_backend_get_shi_ite ( void )

#include <include/zephyr/mgmt/ec_host_cmd/backend.h>

Get the SHI ITE Host Command backend pointer.

Return values

the	SHI ITE backend pointer

◆ ec_host_cmd_backend_get_shi_npcx()

struct ec_host_cmd_backend * ec_host_cmd_backend_get_shi_npcx ( void )

#include <include/zephyr/mgmt/ec_host_cmd/backend.h>

Get the SHI NPCX Host Command backend pointer.

Return values

the	SHI NPCX backend pointer

◆ ec_host_cmd_backend_get_spi()

struct ec_host_cmd_backend * ec_host_cmd_backend_get_spi ( struct gpio_dt_spec * cs )

#include <include/zephyr/mgmt/ec_host_cmd/backend.h>

Get the SPI Host Command backend pointer.

Get the SPI pointer backend and pass a chip select pin that will be used for the Host Command communication.

Parameters

cs	Chip select pin..

Return values

The	SPI backend pointer.

◆ ec_host_cmd_backend_get_uart()

struct ec_host_cmd_backend * ec_host_cmd_backend_get_uart ( const struct device * dev )

#include <include/zephyr/mgmt/ec_host_cmd/backend.h>

Get the UART Host Command backend pointer.

Get the UART pointer backend and pass a pointer to UART device instance that will be used for the Host Command communication.

Parameters

dev	Pointer to UART device instance.

Return values

The	UART backend pointer.

◆ ec_host_cmd_get_hc()

const struct ec_host_cmd * ec_host_cmd_get_hc ( void )

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Get the main ec host command structure.

This routine returns a pointer to the main host command structure. It allows the application code to get inside information for any reason e.g. the host command thread id.

Return values

A	pointer to the main host command structure

◆ ec_host_cmd_init()

int ec_host_cmd_init ( struct ec_host_cmd_backend * backend )

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Initialize the host command subsystem.

This routine initializes the host command subsystem. It includes initialization of a backend and the handler. When the application configures the zephyr,host-cmd-espi-backend/zephyr,host-cmd-shi-backend/ zephyr,host-cmd-uart-backend chosen node and CONFIG_EC_HOST_CMD_INITIALIZE_AT_BOOT is set, the chosen backend automatically calls this routine at CONFIG_EC_HOST_CMD_INIT_PRIORITY . Applications that require a run-time selection of the backend must set CONFIG_EC_HOST_CMD_INITIALIZE_AT_BOOT to n and must explicitly call this routine.

Parameters

[in] backend Pointer to the backend structure to initialize.

Return values

0	if successful

◆ ec_host_cmd_rx_notify()

void ec_host_cmd_rx_notify ( void )

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Signal a new host command.

Signal that a new host command has been received. The function should be called by a backend after copying data to the rx buffer and setting the length.

◆ ec_host_cmd_send_response()

int ec_host_cmd_send_response	(	enum ec_host_cmd_status	status,
		const struct ec_host_cmd_handler_args *	args
	)

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Send the host command response.

This routine sends the host command response. It should be used to send IN_PROGRESS status or if the host command handler doesn't return e.g. reboot command.

Parameters

[in]	status	Host command status to be sent.
[in]	args	Pointer of a structure passed to the handler.

Return values

0	if successful.

◆ ec_host_cmd_set_user_cb()

void ec_host_cmd_set_user_cb	(	ec_host_cmd_user_cb_t	cb,
		void *	user_data
	)

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

Install a user callback for receiving a host command.

It allows installing a custom procedure needed by a user after receiving a command.

Parameters

[in]	cb	A callback to be installed.
[in]	user_data	User data to be passed to the callback.

◆ ec_host_cmd_task()

FUNC_NORETURN void ec_host_cmd_task ( void )

#include <include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

The thread function for Host Command subsystem.

This routine calls the Host Command thread entry function. If CONFIG_EC_HOST_CMD_DEDICATED_THREAD is not defined, a new thread is not created, and this function has to be called by application code. It doesn't return.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ EC_HOST_CMD_HANDLER

◆ EC_HOST_CMD_HANDLER_UNBOUND

Typedef Documentation

◆ ec_host_cmd_backend_api_init

◆ ec_host_cmd_backend_api_send

◆ ec_host_cmd_handler_cb

◆ ec_host_cmd_in_progress_cb_t

◆ ec_host_cmd_user_cb_t

Enumeration Type Documentation

◆ ec_host_cmd_log_level

◆ ec_host_cmd_state

◆ ec_host_cmd_status

Function Documentation

◆ ec_host_cmd_add_suppressed()

◆ ec_host_cmd_backend_get_espi()

◆ ec_host_cmd_backend_get_shi_ite()

◆ ec_host_cmd_backend_get_shi_npcx()

◆ ec_host_cmd_backend_get_spi()

◆ ec_host_cmd_backend_get_uart()

◆ ec_host_cmd_get_hc()

◆ ec_host_cmd_init()

◆ ec_host_cmd_rx_notify()

◆ ec_host_cmd_send_response()

◆ ec_host_cmd_set_user_cb()

◆ ec_host_cmd_task()