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