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

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_backendec_host_cmd_backend_get_espi (const struct device *dev)
 Get the eSPI Host Command backend pointer.
 
struct ec_host_cmd_backendec_host_cmd_backend_get_shi_npcx (void)
 Get the SHI NPCX Host Command backend pointer.
 
struct ec_host_cmd_backendec_host_cmd_backend_get_shi_ite (void)
 Get the SHI ITE Host Command backend pointer.
 
struct ec_host_cmd_backendec_host_cmd_backend_get_uart (const struct device *dev)
 Get the UART Host Command backend pointer.
 
struct ec_host_cmd_backendec_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_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.
 
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:
.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:145

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 <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_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]backendPointer to the backend structure for the driver instance.
[in,out]rx_ctxPointer 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]txPointer 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
0if 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
backendPointer to the backed to send data.
Return values
0if successful.

◆ ec_host_cmd_handler_cb

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

◆ ec_host_cmd_in_progress_cb_t

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

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

Enumeration Type Documentation

◆ 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

#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

#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_idA command id to be suppressed.
Return values
0if 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
devPointer to eSPI device instance.
Return values
TheeSPI 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
theSHI 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
theSHI 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
csChip select pin..
Return values
TheSPI 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
devPointer to UART device instance.
Return values
TheUART 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
Apointer 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]backendPointer to the backend structure to initialize.
Return values
0if 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]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 <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 <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.