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¶
-
enumerator
-
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.
-
const void *const
-
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.
-
ec_host_cmd_handler_cb
-
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.
-
uint8_t
-
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.
-
uint8_t
-