Zephyr API Documentation  3.6.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
19#include <stdint.h>
20#include <zephyr/kernel.h>
22#include <zephyr/sys/__assert.h>
24
71
72 EC_HOST_CMD_MAX = UINT16_MAX /* Force enum to be 16 bits. */
73} __packed;
74
76 EC_HOST_CMD_DEBUG_OFF, /* No Host Command debug output */
77 EC_HOST_CMD_DEBUG_NORMAL, /* Normal output mode; skips repeated commands */
78 EC_HOST_CMD_DEBUG_EVERY, /* Print every command */
79 EC_HOST_CMD_DEBUG_PARAMS, /* ... and print params for request/response */
80 EC_HOST_CMD_DEBUG_MODES /* Number of host command debug modes */
81};
82
88};
89
90typedef void (*ec_host_cmd_user_cb_t)(const struct ec_host_cmd_rx_ctx *rx_ctx, void *user_data);
91typedef enum ec_host_cmd_status (*ec_host_cmd_in_progress_cb_t)(void *user_data);
92
101 struct k_sem rx_ready;
111#ifdef CONFIG_EC_HOST_CMD_DEDICATED_THREAD
112 struct k_thread thread;
113#endif /* CONFIG_EC_HOST_CMD_DEDICATED_THREAD */
114};
115
121 void *reserved;
130 const void *input_buf;
139};
140
166};
167
182#define EC_HOST_CMD_HANDLER(_id, _function, _version_mask, _request_type, _response_type) \
183 const STRUCT_SECTION_ITERABLE(ec_host_cmd_handler, __cmd##_id) = { \
184 .handler = _function, \
185 .id = _id, \
186 .version_mask = _version_mask, \
187 .min_rqt_size = sizeof(_request_type), \
188 .min_rsp_size = sizeof(_response_type), \
189 }
190
202#define EC_HOST_CMD_HANDLER_UNBOUND(_id, _function, _version_mask) \
203 const STRUCT_SECTION_ITERABLE(ec_host_cmd_handler, __cmd##_id) = { \
204 .handler = _function, \
205 .id = _id, \
206 .version_mask = _version_mask, \
207 .min_rqt_size = 0, \
208 .min_rsp_size = 0, \
209 }
210
240} __packed;
241
263} __packed;
264
282
295 const struct ec_host_cmd_handler_args *args);
296
304
314
324const struct ec_host_cmd *ec_host_cmd_get_hc(void);
325
326#ifndef CONFIG_EC_HOST_CMD_DEDICATED_THREAD
334FUNC_NORETURN void ec_host_cmd_task(void);
335#endif
336
337#ifdef CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS
346bool ec_host_cmd_send_in_progress_ended(void);
347
359enum ec_host_cmd_status ec_host_cmd_send_in_progress_status(void);
360
375enum ec_host_cmd_status ec_host_cmd_send_in_progress_continue(ec_host_cmd_in_progress_cb_t cb,
376 void *user_data);
377#endif /* CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS */
378
389
394#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)
Definition: ec_host_cmd.h:141
ec_host_cmd_log_level
Definition: ec_host_cmd.h:75
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.
ec_host_cmd_status
Host command response codes (16-bit).
Definition: ec_host_cmd.h:28
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)
Definition: ec_host_cmd.h:90
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
Definition: ec_host_cmd.h:83
enum ec_host_cmd_status(* ec_host_cmd_in_progress_cb_t)(void *user_data)
Definition: ec_host_cmd.h:91
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
Definition: ec_host_cmd.h:78
@ EC_HOST_CMD_DEBUG_PARAMS
Definition: ec_host_cmd.h:79
@ EC_HOST_CMD_DEBUG_OFF
Definition: ec_host_cmd.h:76
@ EC_HOST_CMD_DEBUG_MODES
Definition: ec_host_cmd.h:80
@ EC_HOST_CMD_DEBUG_NORMAL
Definition: ec_host_cmd.h:77
@ 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
Definition: ec_host_cmd.h:85
@ EC_HOST_CMD_STATE_PROCESSING
Definition: ec_host_cmd.h:86
@ EC_HOST_CMD_STATE_DISABLED
Definition: ec_host_cmd.h:84
@ EC_HOST_CMD_STATE_SENDING
Definition: ec_host_cmd.h:87
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
Definition: backend.h:25
Arguments passed into every installed host command handler.
Definition: ec_host_cmd.h:119
uint16_t command
Command identifier.
Definition: ec_host_cmd.h:123
uint16_t output_buf_size
Number of bytes of output_buf to send to the host.
Definition: ec_host_cmd.h:138
void * output_buf
The data written to this buffer will be send to the host.
Definition: ec_host_cmd.h:134
const void * input_buf
The incoming data that can be cast to the handlers request type.
Definition: ec_host_cmd.h:130
uint16_t input_buf_size
The number of valid bytes that can be read from input_buf.
Definition: ec_host_cmd.h:132
void * reserved
Reserved for compatibility.
Definition: ec_host_cmd.h:121
uint16_t output_buf_max
Maximum number of bytes that can be written to the output_buf.
Definition: ec_host_cmd.h:136
uint8_t version
The version of the host command that is being requested.
Definition: ec_host_cmd.h:128
Structure use for statically registering host command handlers.
Definition: ec_host_cmd.h:145
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:155
uint16_t min_rsp_size
The minimum output_buf_size enforced by the framework before passing to the handler.
Definition: ec_host_cmd.h:165
ec_host_cmd_handler_cb handler
Callback routine to process commands that match id.
Definition: ec_host_cmd.h:147
uint16_t id
The numerical command id used as the lookup for commands.
Definition: ec_host_cmd.h:149
uint16_t min_rqt_size
The minimum input_buf_size enforced by the framework before passing to the handler.
Definition: ec_host_cmd.h:160
Header for requests from host to embedded controller.
Definition: ec_host_cmd.h:218
uint16_t cmd_id
Id of command that is being sent.
Definition: ec_host_cmd.h:230
uint8_t cmd_ver
Version of the specific cmd_id being requested.
Definition: ec_host_cmd.h:235
uint8_t prtcl_ver
Should be 3.
Definition: ec_host_cmd.h:223
uint8_t checksum
Checksum of response and data; sum of all bytes including checksum.
Definition: ec_host_cmd.h:228
uint8_t reserved
Unused byte in current protocol version; set to 0.
Definition: ec_host_cmd.h:237
uint16_t data_len
Length of data which follows this header.
Definition: ec_host_cmd.h:239
Header for responses from embedded controller to host.
Definition: ec_host_cmd.h:249
uint8_t prtcl_ver
Should be 3.
Definition: ec_host_cmd.h:251
uint16_t reserved
Unused bytes in current protocol version; set to 0.
Definition: ec_host_cmd.h:262
uint16_t result
A ec_host_cmd_status response code for specific command.
Definition: ec_host_cmd.h:258
uint8_t checksum
Checksum of response and data; sum of all bytes including checksum.
Definition: ec_host_cmd.h:256
uint16_t data_len
Length of data which follows this header.
Definition: ec_host_cmd.h:260
Context for host command backend and handler to pass rx data.
Definition: backend.h:42
Context for host command backend and handler to pass tx data.
Definition: backend.h:59
Definition: ec_host_cmd.h:93
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:103
struct ec_host_cmd_rx_ctx rx_ctx
Definition: ec_host_cmd.h:94
enum ec_host_cmd_state state
Definition: ec_host_cmd.h:110
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:101
void * user_data
Definition: ec_host_cmd.h:109
struct ec_host_cmd_backend * backend
Definition: ec_host_cmd.h:96
ec_host_cmd_user_cb_t user_cb
User callback after receiving a command.
Definition: ec_host_cmd.h:108
struct ec_host_cmd_tx_buf tx
Definition: ec_host_cmd.h:95
Thread Structure.
Definition: thread.h:259