Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
|
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. |
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. |
EC Host Command Interface.
#define EC_HOST_CMD_HANDLER | ( | _id, | |
_function, | |||
_version_mask, | |||
_request_type, | |||
_response_type ) |
#include <zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>
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.
_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. |
#define EC_HOST_CMD_HANDLER_UNBOUND | ( | _id, | |
_function, | |||
_version_mask ) |
#include <zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>
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.
_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 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.
args | Pointer to an ec_host_cmd_handler_args structure containing command data and buffers |
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.
user_data | User-provided data passed to the callback |
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.
rx_ctx | Pointer to the receive context containing command data |
user_data | User-defined data pointer passed during callback registration |
#include <zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>
Host command log levels.
enum ec_host_cmd_state |
#include <zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>
Host command state.
enum ec_host_cmd_status |
#include <zephyr/mgmt/ec_host_cmd/ec_host_cmd.h>
Host command response codes (16-bit).
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.
[in] | cmd_id | A command id to be suppressed. |
0 | if successful, -EIO if exceeded max number of suppressed commands. |
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.
A | pointer to the main host command structure |
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.
[in] | backend | Pointer to the backend structure to initialize. |
0 | if successful |
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.
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.
CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS
.[in] | cb | A callback to be called after returning from a command handler. |
[in] | user_data | User data to be passed to the callback. |
EC_HOST_CMD_BUSY | if any command is already in progress, EC_HOST_CMD_SUCCESS otherwise |
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.
CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS
.true | if the Host Command endded |
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.
CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS
.The | final status or EC_HOST_CMD_UNAVAILABLE if not available. |
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.
[in] | status | Host command status to be sent. |
[in] | args | Pointer of a structure passed to the handler. |
0 | if successful. |
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.
[in] | cb | A callback to be installed. |
[in] | user_data | User data to be passed to the callback. |
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.