Line data Source code
1 1 : /*
2 : * Copyright (c) 2020 Google LLC.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Public APIs for Host Command backends that respond to host commands
10 : * @ingroup ec_host_cmd_backend
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_BACKEND_H_
14 : #define ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_BACKEND_H_
15 :
16 : /**
17 : * @brief Interface to EC Host Command backends
18 : * @defgroup ec_host_cmd_backend Backends
19 : * @ingroup ec_host_cmd_interface
20 : * @{
21 : */
22 :
23 : #include <zephyr/sys/__assert.h>
24 : #include <zephyr/device.h>
25 : #include <zephyr/drivers/gpio.h>
26 : #include <zephyr/kernel.h>
27 : #include <zephyr/types.h>
28 :
29 : #ifdef __cplusplus
30 : extern "C" {
31 : #endif
32 :
33 : /**
34 : * @brief EC Host Command Backend
35 : */
36 1 : struct ec_host_cmd_backend {
37 : /** API provided by the backend. */
38 1 : const struct ec_host_cmd_backend_api *api;
39 : /** Context for the backend. */
40 1 : void *ctx;
41 : };
42 :
43 : /**
44 : * @brief Context for host command backend and handler to pass rx data.
45 : */
46 1 : struct ec_host_cmd_rx_ctx {
47 : /**
48 : * Buffer to hold received data. The buffer is provided by the handler if
49 : * CONFIG_EC_HOST_CMD_HANDLER_RX_BUFFER_SIZE > 0. Otherwise, the backend should provide
50 : * the buffer on its own and overwrites @a buf pointer and @a len_max
51 : * in the init function.
52 : */
53 1 : uint8_t *buf;
54 : /** Number of bytes written to @a buf by backend. */
55 1 : size_t len;
56 : /** Maximum number of bytes to receive with one request packet. */
57 1 : size_t len_max;
58 : };
59 :
60 : /**
61 : * @brief Context for host command backend and handler to pass tx data
62 : */
63 1 : struct ec_host_cmd_tx_buf {
64 : /**
65 : * Data to write to the host. The buffer is provided by the handler if
66 : * CONFIG_EC_HOST_CMD_HANDLER_TX_BUFFER_SIZE > 0. Otherwise, the backend should provide
67 : * the buffer on its own and overwrites @a buf pointer and @a len_max
68 : * in the init function.
69 : */
70 1 : void *buf;
71 : /** Number of bytes to write from @a buf. */
72 1 : size_t len;
73 : /** Maximum number of bytes to send with one response packet. */
74 1 : size_t len_max;
75 : };
76 :
77 : /**
78 : * @brief Initialize a host command backend
79 : *
80 : * This routine initializes a host command backend. It includes initialization
81 : * a device used to communication and setting up buffers.
82 : * This function is called by the ec_host_cmd_init function.
83 : *
84 : * @param[in] backend Pointer to the backend structure for the driver instance.
85 : * @param[in,out] rx_ctx Pointer to the receive context object. These objects are used to receive
86 : * data from the driver when the host sends data. The buf member can be
87 : * assigned by the backend.
88 : * @param[in,out] tx Pointer to the transmit buffer object. The buf and len_max members can be
89 : * assigned by the backend. These objects are used to send data by the
90 : * backend with the ec_host_cmd_backend_api_send function.
91 : *
92 : * @retval 0 if successful
93 : */
94 1 : typedef int (*ec_host_cmd_backend_api_init)(const struct ec_host_cmd_backend *backend,
95 : struct ec_host_cmd_rx_ctx *rx_ctx,
96 : struct ec_host_cmd_tx_buf *tx);
97 :
98 : /**
99 : * @brief Sends data to the host
100 : *
101 : * Sends data from tx buf that was passed via ec_host_cmd_backend_api_init
102 : * function.
103 : *
104 : * @param backend Pointer to the backed to send data.
105 : *
106 : * @retval 0 if successful.
107 : */
108 1 : typedef int (*ec_host_cmd_backend_api_send)(const struct ec_host_cmd_backend *backend);
109 :
110 0 : struct ec_host_cmd_backend_api {
111 0 : ec_host_cmd_backend_api_init init;
112 0 : ec_host_cmd_backend_api_send send;
113 : };
114 :
115 : /**
116 : * @brief Get the eSPI Host Command backend pointer
117 : *
118 : * Get the eSPI pointer backend and pass a pointer to eSPI device instance that will be used for
119 : * the Host Command communication.
120 : *
121 : * @param dev Pointer to eSPI device instance.
122 : *
123 : * @retval The eSPI backend pointer.
124 : */
125 1 : struct ec_host_cmd_backend *ec_host_cmd_backend_get_espi(const struct device *dev);
126 :
127 : /**
128 : * @brief Get the SHI NPCX Host Command backend pointer
129 : *
130 : * @retval the SHI NPCX backend pointer
131 : */
132 1 : struct ec_host_cmd_backend *ec_host_cmd_backend_get_shi_npcx(void);
133 :
134 : /**
135 : * @brief Get the SHI ITE Host Command backend pointer
136 : *
137 : * @retval the SHI ITE backend pointer
138 : */
139 1 : struct ec_host_cmd_backend *ec_host_cmd_backend_get_shi_ite(void);
140 :
141 : /**
142 : * @brief Get the UART Host Command backend pointer
143 : *
144 : * Get the UART pointer backend and pass a pointer to UART device instance that will be used for
145 : * the Host Command communication.
146 : *
147 : * @param dev Pointer to UART device instance.
148 : *
149 : * @retval The UART backend pointer.
150 : */
151 1 : struct ec_host_cmd_backend *ec_host_cmd_backend_get_uart(const struct device *dev);
152 :
153 : /**
154 : * @brief Get the SPI Host Command backend pointer
155 : *
156 : * Get the SPI pointer backend and pass a chip select pin that will be used for the Host Command
157 : * communication.
158 : *
159 : * @param cs Chip select pin..
160 : *
161 : * @retval The SPI backend pointer.
162 : */
163 1 : struct ec_host_cmd_backend *ec_host_cmd_backend_get_spi(struct gpio_dt_spec *cs);
164 :
165 : /**
166 : * @brief Signal event over USB
167 : *
168 : * Signal event using USB interrupt endpoint. It informs host that there is a pending event that has
169 : * to be handled. The function performs remote wake-up if needed.
170 : */
171 1 : void ec_host_cmd_backend_usb_trigger_event(void);
172 :
173 : /**
174 : * @}
175 : */
176 :
177 : #ifdef __cplusplus
178 : }
179 : #endif
180 :
181 : #endif /* ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_EC_HOST_CMD_BACKEND_H_ */
|
