EC Host Command Interface. More...

Topics
	Backends
	Interface to EC Host Command backends.
	Simulator
	Interface to EC Host Command Simulator.

Data Structures
struct	ec_host_cmd
	Host command context structure. More...
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 void(*	ec_host_cmd_user_cb_t) (const struct ec_host_cmd_rx_ctx rx_ctx, void user_data)
	User callback function type for host command reception.
typedef enum ec_host_cmd_status(*	ec_host_cmd_in_progress_cb_t) (void *user_data)
	In-progress callback function type.
typedef enum ec_host_cmd_status(*	ec_host_cmd_handler_cb) (struct ec_host_cmd_handler_args *args)
	Host command handler callback function type.

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 }
	Host command log levels. More...
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 }
	Host command state. More...

Functions
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.
bool	ec_host_cmd_send_in_progress_ended (void)
	Check if a Host Command that sent EC_HOST_CMD_IN_PROGRESS status has ended.
enum ec_host_cmd_status	ec_host_cmd_send_in_progress_status (void)
	Get final result of a last Host Command that has sent EC_HOST_CMD_IN_PROGRESS status.
enum ec_host_cmd_status	ec_host_cmd_send_in_progress_continue (ec_host_cmd_in_progress_cb_t cb, void *user_data)
	Continue processing a handler in callback after returning EC_HOST_CMD_IN_PROGRESS.
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 <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 <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_handler_cb

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

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

Host command handler callback function type.

This callback is invoked to process a host command that matches the handler's command ID and version. The handler processes the incoming command data and generates a response.

Parameters

args	Pointer to an ec_host_cmd_handler_args structure containing command data and buffers

Returns: Status code indicating the result of command processing

◆ ec_host_cmd_in_progress_cb_t

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

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

In-progress callback function type.

This callback is executed asynchronously for commands that return EC_HOST_CMD_IN_PROGRESS status. It allows long-running operations to complete in the background.

Parameters

user_data User-provided data passed to the callback

Returns: Final status code for the command

◆ 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 <zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>

User callback function type for host command reception.

This callback is invoked after a host command is received and validated but before command processing begins. It allows user code to perform custom actions based on the received command.

Parameters

rx_ctx	Pointer to the receive context containing command data
user_data	User-defined data pointer passed during callback registration

Enumeration Type Documentation

◆ ec_host_cmd_log_level

enum ec_host_cmd_log_level

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

Host command log levels.

Enumerator
EC_HOST_CMD_DEBUG_OFF	No Host Command debug output.
EC_HOST_CMD_DEBUG_NORMAL	Normal output mode; skips repeated commands.
EC_HOST_CMD_DEBUG_EVERY	Print every command.
EC_HOST_CMD_DEBUG_PARAMS	... and print params for request/response
EC_HOST_CMD_DEBUG_MODES	Number of host command debug modes.

◆ ec_host_cmd_state

enum ec_host_cmd_state

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

Host command state.

Enumerator
EC_HOST_CMD_STATE_DISABLED	Host command subsystem is disabled.
EC_HOST_CMD_STATE_RECEIVING	Receiving command data from host.
EC_HOST_CMD_STATE_PROCESSING	Processing received command.
EC_HOST_CMD_STATE_SENDING	Sending response to host.

◆ ec_host_cmd_status

enum ec_host_cmd_status

#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 <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_get_hc()

const struct ec_host_cmd * ec_host_cmd_get_hc ( void )

#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 <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 <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_in_progress_continue()

enum ec_host_cmd_status ec_host_cmd_send_in_progress_continue	(	ec_host_cmd_in_progress_cb_t	cb,
		void *	user_data )

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

Continue processing a handler in callback after returning EC_HOST_CMD_IN_PROGRESS.

A Host Command handler may return the EC_HOST_CMD_IN_PROGRESS, but needs to continue work. This function should be called before returning EC_HOST_CMD_IN_PROGRESS with a callback that will be executed. The return status of the callback will be stored and can be obtained with the ec_host_cmd_send_in_progress_status function. The ec_host_cmd_send_in_progress_ended function can be used to check if the callback has ended.

Attention: Available only when the following Kconfig option is enabled: CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS.

Parameters

[in]	cb	A callback to be called after returning from a command handler.
[in]	user_data	User data to be passed to the callback.

Return values

EC_HOST_CMD_BUSY if any command is already in progress, EC_HOST_CMD_SUCCESS otherwise

◆ ec_host_cmd_send_in_progress_ended()

bool ec_host_cmd_send_in_progress_ended ( void )

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

Check if a Host Command that sent EC_HOST_CMD_IN_PROGRESS status has ended.

A Host Command that sends EC_HOST_CMD_IN_PROGRESS status doesn't send a final result. The final result can be obtained with the ec_host_cmd_send_in_progress_status function.

Attention: Available only when the following Kconfig option is enabled: CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS.

Return values

true	if the Host Command endded

◆ ec_host_cmd_send_in_progress_status()

enum ec_host_cmd_status ec_host_cmd_send_in_progress_status ( void )

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

Get final result of a last Host Command that has sent EC_HOST_CMD_IN_PROGRESS status.

A Host Command that sends EC_HOST_CMD_IN_PROGRESS status doesn't send a final result. Get the saved status with this function. The status can be obtained only once. Further calls return EC_HOST_CMD_UNAVAILABLE.

Saving status of Host Commands that send response data is not supported.

Attention: Available only when the following Kconfig option is enabled: CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS.

Return values

The	final status or EC_HOST_CMD_UNAVAILABLE if not available.

◆ 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 <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 <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 <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.

Topics

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_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_get_hc()

◆ ec_host_cmd_init()

◆ ec_host_cmd_rx_notify()

◆ ec_host_cmd_send_in_progress_continue()

◆ ec_host_cmd_send_in_progress_ended()

◆ ec_host_cmd_send_in_progress_status()

◆ ec_host_cmd_send_response()

◆ ec_host_cmd_set_user_cb()

◆ ec_host_cmd_task()