ec_host_cmd.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Google LLC
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_EC_HOST_CMD_H_
#define ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_EC_HOST_CMD_H_
 
#include <stdint.h>
#include <zephyr/kernel.h>
#include <zephyr/mgmt/ec_host_cmd/backend.h>
#include <zephyr/sys/__assert.h>
#include <zephyr/sys/iterable_sections.h>
 
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 /* Force enum to be 16 bits. */
} __packed;
 
enum ec_host_cmd_log_level {
        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 */
};
 
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,
};
 
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);
 
struct ec_host_cmd {
        struct ec_host_cmd_rx_ctx rx_ctx;
        struct ec_host_cmd_tx_buf tx;
        struct ec_host_cmd_backend *backend;
        struct k_sem rx_ready;
        enum ec_host_cmd_status rx_status;
        ec_host_cmd_user_cb_t user_cb;
        void *user_data;
        enum ec_host_cmd_state state;
#ifdef CONFIG_EC_HOST_CMD_DEDICATED_THREAD
        struct k_thread thread;
#endif /* CONFIG_EC_HOST_CMD_DEDICATED_THREAD */
};
 
struct ec_host_cmd_handler_args {
        void *reserved;
        uint16_t command;
        uint8_t version;
        const void *input_buf;
        uint16_t input_buf_size;
        void *output_buf;
        uint16_t output_buf_max;
        uint16_t output_buf_size;
};
 
typedef enum ec_host_cmd_status (*ec_host_cmd_handler_cb)(struct ec_host_cmd_handler_args *args);
struct ec_host_cmd_handler {
        ec_host_cmd_handler_cb handler;
        uint16_t id;
        uint16_t version_mask;
        uint16_t min_rqt_size;
        uint16_t min_rsp_size;
};
 
#define EC_HOST_CMD_HANDLER(_id, _function, _version_mask, _request_type, _response_type)          \
        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),                                            \
        }
 
#define EC_HOST_CMD_HANDLER_UNBOUND(_id, _function, _version_mask)                                 \
        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,                                                                 \
        }
 
struct ec_host_cmd_request_header {
        uint8_t prtcl_ver;
        uint8_t checksum;
        uint16_t cmd_id;
        uint8_t cmd_ver;
        uint8_t reserved;
        uint16_t data_len;
} __packed;
 
struct ec_host_cmd_response_header {
        uint8_t prtcl_ver;
        uint8_t checksum;
        uint16_t result;
        uint16_t data_len;
        uint16_t reserved;
} __packed;
 
int ec_host_cmd_init(struct ec_host_cmd_backend *backend);
 
int ec_host_cmd_send_response(enum ec_host_cmd_status status,
                              const struct ec_host_cmd_handler_args *args);
 
void ec_host_cmd_rx_notify(void);
 
void ec_host_cmd_set_user_cb(ec_host_cmd_user_cb_t cb, void *user_data);
 
const struct ec_host_cmd *ec_host_cmd_get_hc(void);
 
#ifndef CONFIG_EC_HOST_CMD_DEDICATED_THREAD
FUNC_NORETURN void ec_host_cmd_task(void);
#endif
 
#ifdef CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS
bool ec_host_cmd_send_in_progress_ended(void);
 
enum ec_host_cmd_status ec_host_cmd_send_in_progress_status(void);
 
enum ec_host_cmd_status ec_host_cmd_send_in_progress_continue(ec_host_cmd_in_progress_cb_t cb,
                                                              void *user_data);
#endif /* CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS */
 
int ec_host_cmd_add_suppressed(uint16_t cmd_id);
 
#endif /* ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_EC_HOST_CMD_H_ */