Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
ec_host_cmd.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Google LLC
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7#ifndef ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_EC_HOST_CMD_H_
8#define ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_EC_HOST_CMD_H_
9
18
19#include <stdint.h>
20#include <zephyr/kernel.h>
22#include <zephyr/sys/__assert.h>
24
74
85
95
106typedef void (*ec_host_cmd_user_cb_t)(const struct ec_host_cmd_rx_ctx *rx_ctx, void *user_data);
107
118typedef enum ec_host_cmd_status (*ec_host_cmd_in_progress_cb_t)(void *user_data);
119
141#ifdef CONFIG_EC_HOST_CMD_DEDICATED_THREAD
142 struct k_thread thread;
143#endif /* CONFIG_EC_HOST_CMD_DEDICATED_THREAD */
144};
145
170
183
209
224#define EC_HOST_CMD_HANDLER(_id, _function, _version_mask, _request_type, _response_type) \
225 const STRUCT_SECTION_ITERABLE(ec_host_cmd_handler, __cmd##_id) = { \
226 .handler = _function, \
227 .id = _id, \
228 .version_mask = _version_mask, \
229 .min_rqt_size = sizeof(_request_type), \
230 .min_rsp_size = sizeof(_response_type), \
231 }
232
244#define EC_HOST_CMD_HANDLER_UNBOUND(_id, _function, _version_mask) \
245 const STRUCT_SECTION_ITERABLE(ec_host_cmd_handler, __cmd##_id) = { \
246 .handler = _function, \
247 .id = _id, \
248 .version_mask = _version_mask, \
249 .min_rqt_size = 0, \
250 .min_rsp_size = 0, \
251 }
252
283
306
324
337 const struct ec_host_cmd_handler_args *args);
338
346
356
366const struct ec_host_cmd *ec_host_cmd_get_hc(void);
367
368#ifndef CONFIG_EC_HOST_CMD_DEDICATED_THREAD
376FUNC_NORETURN void ec_host_cmd_task(void);
377#endif
378
379#if defined(CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS) || defined(__DOXYGEN__)
391
406
424 void *user_data);
425#endif /* CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS */
426
437
441
442#endif /* ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_EC_HOST_CMD_H_ */
Public APIs for Host Command backends that respond to host commands.
enum ec_host_cmd_status(* ec_host_cmd_handler_cb)(struct ec_host_cmd_handler_args *args)
Host command handler callback function type.
Definition ec_host_cmd.h:182
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.
ec_host_cmd_log_level
Host command log levels.
Definition ec_host_cmd.h:78
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.
bool ec_host_cmd_send_in_progress_ended(void)
Check if a Host Command that sent EC_HOST_CMD_IN_PROGRESS status has ended.
ec_host_cmd_status
Host command response codes (16-bit).
Definition ec_host_cmd.h:28
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.
int ec_host_cmd_add_suppressed(uint16_t cmd_id)
Add a suppressed command.
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.
Definition ec_host_cmd.h:106
FUNC_NORETURN void ec_host_cmd_task(void)
The thread function for Host Command subsystem.
int ec_host_cmd_init(struct ec_host_cmd_backend *backend)
Initialize the host command subsystem.
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.
ec_host_cmd_state
Host command state.
Definition ec_host_cmd.h:89
enum ec_host_cmd_status(* ec_host_cmd_in_progress_cb_t)(void *user_data)
In-progress callback function type.
Definition ec_host_cmd.h:118
void ec_host_cmd_rx_notify(void)
Signal a new host command.
const struct ec_host_cmd * ec_host_cmd_get_hc(void)
Get the main ec host command structure.
@ EC_HOST_CMD_DEBUG_EVERY
Print every command.
Definition ec_host_cmd.h:81
@ EC_HOST_CMD_DEBUG_PARAMS
... and print params for request/response
Definition ec_host_cmd.h:82
@ EC_HOST_CMD_DEBUG_OFF
No Host Command debug output.
Definition ec_host_cmd.h:79
@ EC_HOST_CMD_DEBUG_MODES
Number of host command debug modes.
Definition ec_host_cmd.h:83
@ EC_HOST_CMD_DEBUG_NORMAL
Normal output mode; skips repeated commands.
Definition ec_host_cmd.h:80
@ EC_HOST_CMD_BUSY
System busy.
Definition ec_host_cmd.h:62
@ EC_HOST_CMD_REQUEST_TRUNCATED
Did not receive all expected request data.
Definition ec_host_cmd.h:56
@ EC_HOST_CMD_INVALID_DATA_CRC
Data CRC invalid.
Definition ec_host_cmd.h:68
@ EC_HOST_CMD_DUP_UNAVAILABLE
Can't resend response.
Definition ec_host_cmd.h:70
@ EC_HOST_CMD_ERROR
Generic Error.
Definition ec_host_cmd.h:34
@ EC_HOST_CMD_INVALID_HEADER
Header is invalid or unsupported (e.g.
Definition ec_host_cmd.h:54
@ EC_HOST_CMD_INVALID_HEADER_VERSION
Header version invalid.
Definition ec_host_cmd.h:64
@ EC_HOST_CMD_IN_PROGRESS
A host command is currently being processed.
Definition ec_host_cmd.h:46
@ EC_HOST_CMD_SUCCESS
Host command was successful.
Definition ec_host_cmd.h:30
@ EC_HOST_CMD_INVALID_VERSION
Host command id version unsupported.
Definition ec_host_cmd.h:42
@ EC_HOST_CMD_INVALID_CHECKSUM
Checksum did not match.
Definition ec_host_cmd.h:44
@ EC_HOST_CMD_UNAVAILABLE
Requested information is currently unavailable.
Definition ec_host_cmd.h:48
@ EC_HOST_CMD_INVALID_HEADER_CRC
Header CRC invalid.
Definition ec_host_cmd.h:66
@ EC_HOST_CMD_MAX
Definition ec_host_cmd.h:72
@ EC_HOST_CMD_INVALID_COMMAND
The specified command id is not recognized or supported.
Definition ec_host_cmd.h:32
@ EC_HOST_CMD_ACCESS_DENIED
Host command is not permitted.
Definition ec_host_cmd.h:38
@ EC_HOST_CMD_TIMEOUT
Timeout during processing.
Definition ec_host_cmd.h:50
@ EC_HOST_CMD_BUS_ERROR
Error on underlying communication bus.
Definition ec_host_cmd.h:60
@ EC_HOST_CMD_INVALID_PARAM
One of more of the input request parameters is invalid.
Definition ec_host_cmd.h:36
@ EC_HOST_CMD_OVERFLOW
Data or table overflow.
Definition ec_host_cmd.h:52
@ EC_HOST_CMD_RESPONSE_TOO_BIG
Response was too big to send within one response packet.
Definition ec_host_cmd.h:58
@ EC_HOST_CMD_INVALID_RESPONSE
Response was invalid (e.g.
Definition ec_host_cmd.h:40
@ EC_HOST_CMD_STATE_RECEIVING
Receiving command data from host.
Definition ec_host_cmd.h:91
@ EC_HOST_CMD_STATE_PROCESSING
Processing received command.
Definition ec_host_cmd.h:92
@ EC_HOST_CMD_STATE_DISABLED
Host command subsystem is disabled.
Definition ec_host_cmd.h:90
@ EC_HOST_CMD_STATE_SENDING
Sending response to host.
Definition ec_host_cmd.h:93
Public kernel APIs.
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
#define UINT16_MAX
Definition stdint.h:28
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
EC Host Command Backend.
Definition backend.h:36
Arguments passed into every installed host command handler.
Definition ec_host_cmd.h:149
uint16_t command
Command identifier.
Definition ec_host_cmd.h:153
uint16_t output_buf_size
Number of bytes of output_buf to send to the host.
Definition ec_host_cmd.h:168
void * output_buf
The data written to this buffer will be send to the host.
Definition ec_host_cmd.h:164
const void * input_buf
The incoming data that can be cast to the handlers request type.
Definition ec_host_cmd.h:160
uint16_t input_buf_size
The number of valid bytes that can be read from input_buf.
Definition ec_host_cmd.h:162
void * reserved
Reserved for compatibility.
Definition ec_host_cmd.h:151
uint16_t output_buf_max
Maximum number of bytes that can be written to the output_buf.
Definition ec_host_cmd.h:166
uint8_t version
The version of the host command that is being requested.
Definition ec_host_cmd.h:158
Structure use for statically registering host command handlers.
Definition ec_host_cmd.h:187
uint16_t version_mask
The bitfield of all versions that the handler supports, where each bit value represents that the hand...
Definition ec_host_cmd.h:197
uint16_t min_rsp_size
The minimum output_buf_size enforced by the framework before passing to the handler.
Definition ec_host_cmd.h:207
ec_host_cmd_handler_cb handler
Callback routine to process commands that match id.
Definition ec_host_cmd.h:189
uint16_t id
The numerical command id used as the lookup for commands.
Definition ec_host_cmd.h:191
uint16_t min_rqt_size
The minimum input_buf_size enforced by the framework before passing to the handler.
Definition ec_host_cmd.h:202
Header for requests from host to embedded controller.
Definition ec_host_cmd.h:260
uint16_t cmd_id
Id of command that is being sent.
Definition ec_host_cmd.h:272
uint8_t cmd_ver
Version of the specific cmd_id being requested.
Definition ec_host_cmd.h:277
uint8_t prtcl_ver
Should be 3.
Definition ec_host_cmd.h:265
uint8_t checksum
Checksum of response and data; sum of all bytes including checksum.
Definition ec_host_cmd.h:270
uint8_t reserved
Unused byte in current protocol version; set to 0.
Definition ec_host_cmd.h:279
uint16_t data_len
Length of data which follows this header.
Definition ec_host_cmd.h:281
Header for responses from embedded controller to host.
Definition ec_host_cmd.h:291
uint8_t prtcl_ver
Should be 3.
Definition ec_host_cmd.h:293
uint16_t reserved
Unused bytes in current protocol version; set to 0.
Definition ec_host_cmd.h:304
uint16_t result
A ec_host_cmd_status response code for specific command.
Definition ec_host_cmd.h:300
uint8_t checksum
Checksum of response and data; sum of all bytes including checksum.
Definition ec_host_cmd.h:298
uint16_t data_len
Length of data which follows this header.
Definition ec_host_cmd.h:302
Context for host command backend and handler to pass rx data.
Definition backend.h:46
Context for host command backend and handler to pass tx data.
Definition backend.h:63
Host command context structure.
Definition ec_host_cmd.h:123
enum ec_host_cmd_status rx_status
Status of the rx data checked in the ec_host_cmd_send_received function.
Definition ec_host_cmd.h:133
struct ec_host_cmd_rx_ctx rx_ctx
Definition ec_host_cmd.h:124
enum ec_host_cmd_state state
Definition ec_host_cmd.h:140
struct k_sem rx_ready
The backend gives rx_ready (by calling the ec_host_cmd_send_receive function), when data in rx_ctx ar...
Definition ec_host_cmd.h:131
void * user_data
Definition ec_host_cmd.h:139
struct ec_host_cmd_backend * backend
Definition ec_host_cmd.h:126
ec_host_cmd_user_cb_t user_cb
User callback after receiving a command.
Definition ec_host_cmd.h:138
struct ec_host_cmd_tx_buf tx
Definition ec_host_cmd.h:125
Semaphore structure.
Definition kernel.h:3275
Thread Structure.
Definition thread.h:262