This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

EC Host Command¶

Overview¶

API Reference¶

group ec_host_cmd_periph_interface

EC Host Command Interface.

Defines

EC_HOST_CMD_HANDLER(_function, _id, _version_mask, _request_type, _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

_function – Name of handler function.
_id – Id of host command to handle request for.
_version_mask – The bitfield of all versions that the _function supports. E.g. BIT(0) corresponse 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(_function, _id, _version_mask)¶

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

_function – Name of handler function.
_id – Id of host command to handle request for.
_version_mask – The bitfield of all versions that the _function supports. E.g. BIT(0) corresponse to version 0.

Typedefs

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

Enums

enum ec_host_cmd_status¶

Values:

enumerator EC_HOST_CMD_SUCCESS = 0¶: Host command was successful.

enumerator EC_HOST_CMD_INVALID_COMMAND = 1¶: The specified command id is not recognized or supported.

enumerator EC_HOST_CMD_ERROR = 2¶: Generic Error.

enumerator EC_HOST_CMD_INVALID_PARAM = 3¶: One of more of the input request parameters is invalid.

enumerator EC_HOST_CMD_ACCESS_DENIED = 4¶: Host command is not permitted.

enumerator EC_HOST_CMD_INVALID_RESPONSE = 5¶: Response was invalid (e.g. not version 3 of header).

enumerator EC_HOST_CMD_INVALID_VERSION = 6¶: Host command id version unsupported.

enumerator EC_HOST_CMD_INVALID_CHECKSUM = 7¶: Checksum did not match

enumerator EC_HOST_CMD_IN_PROGRESS = 8¶: A host command is currently being processed.

enumerator EC_HOST_CMD_UNAVAILABLE = 9¶: Requested information is currently unavailable.

enumerator EC_HOST_CMD_TIMEOUT = 10¶: Timeout during processing.

enumerator EC_HOST_CMD_OVERFLOW = 11¶: Data or table overflow.

enumerator EC_HOST_CMD_INVALID_HEADER = 12¶: Header is invalid or unsupported (e.g. not version 3 of header).

enumerator EC_HOST_CMD_REQUEST_TRUNCATED = 13¶: Did not receive all expected request data.

enumerator EC_HOST_CMD_RESPONSE_TOO_BIG = 14¶: Response was too big to send within one response packet.

enumerator EC_HOST_CMD_BUS_ERROR = 15¶: Error on underlying communication bus.

enumerator EC_HOST_CMD_BUSY = 16¶: System busy. Should retry later.

enumerator EC_HOST_CMD_MAX = UINT16_MAX¶

struct ec_host_cmd_handler_args¶

#include <ec_host_cmd.h>

Arguments passed into every installed host command handler.

Public Members

const void *const input_buf¶: The incoming data that can be cast to the handlers request type.

const uint16_t input_buf_size¶: The number of valid bytes that can be read from input_buf.

void *const output_buf¶: The data written to this buffer will be send to the host.

uint16_t output_buf_size¶: [in/out] Upon entry, this is the maximum number of bytes that can be written to the output_buf. Upon exit, this should be the number of bytes of output_buf to send to the host.

const uint8_t version¶: The version of the host command that is being requested. This will be a value that has been static registered as valid for the handler.

struct ec_host_cmd_handler¶

#include <ec_host_cmd.h>

Structure use for statically registering host command handlers.

Public Members

ec_host_cmd_handler_cb handler¶: Callback routine to process commands that match id.

uint16_t id¶: The numberical command id used as the lookup for commands.

uint16_t version_mask¶: The bitfield of all versions that the handler supports, where each bit value represents that the handler supports that version. E.g. BIT(0) corresponse to version 0.

uint16_t min_rqt_size¶: The minimum input_buf_size enforced by the framework before passing to the handler.

uint16_t min_rsp_size¶: The minimum output_buf_size enforced by the framework before passing to the handler.

struct ec_host_cmd_request_header¶

#include <ec_host_cmd.h>

Header for requests from host to embedded controller.

Represent the over-the-wire header in LE format for host command requests. This represent version 3 of the host command header. The requests are always sent from host to embedded controller.

Public Members

uint8_t prtcl_ver¶: Should be 3. The EC will return EC_HOST_CMD_INVALID_HEADER if it receives a header with a version it doesn’t know how to parse.

uint8_t checksum¶: Checksum of response and data; sum of all bytes including checksum. Should total to 0.

uint16_t cmd_id¶: Id of command that is being sent.

uint8_t cmd_ver¶: Version of the specific cmd_id being requested. Valid versions start at 0.

uint8_t reserved¶: Unused byte in current protocol version; set to 0.

uint16_t data_len¶: Length of data which follows this header.

struct ec_host_cmd_response_header¶

#include <ec_host_cmd.h>

Header for responses from embedded controller to host.

Represent the over-the-wire header in LE format for host command responses. This represent version 3 of the host command header. Responses are always sent from embedded controller to host.

Public Members

uint8_t prtcl_ver¶: Should be 3.

uint8_t checksum¶: Checksum of response and data; sum of all bytes including checksum. Should total to 0.

uint16_t result¶: A ec_host_cmd_status response code for specific command.

uint16_t data_len¶: Length of data which follows this header.

uint16_t reserved¶: Unused bytes in current protocol version; set to 0.