Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
EC Host Command Interface

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_cmdec_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:
.handler = _function, \
.id = _id, \
.version_mask = _version_mask, \
.min_rqt_size = sizeof(_request_type), \
.min_rsp_size = sizeof(_response_type), \
}
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition iterable_sections.h:216
Structure use for statically registering host command handlers.
Definition ec_host_cmd.h:187

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
_idId of host command to handle request for.
_functionName of handler function.
_version_maskThe bitfield of all versions that the _function supports. E.g. BIT(0) corresponds to version 0.
_request_typeThe datatype of the request parameters for _function.
_response_typeThe 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:
.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
_idId of host command to handle request for.
_functionName of handler function.
_version_maskThe 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
argsPointer 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_dataUser-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_ctxPointer to the receive context containing command data
user_dataUser-defined data pointer passed during callback registration

Enumeration Type Documentation

◆ 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

#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

#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_idA command id to be suppressed.
Return values
0if 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
Apointer 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]backendPointer to the backend structure to initialize.
Return values
0if 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]cbA callback to be called after returning from a command handler.
[in]user_dataUser data to be passed to the callback.
Return values
EC_HOST_CMD_BUSYif 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
trueif 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
Thefinal 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]statusHost command status to be sent.
[in]argsPointer of a structure passed to the handler.
Return values
0if 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]cbA callback to be installed.
[in]user_dataUser 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.