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 : */ 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 0 : struct ec_host_cmd_backend { 26 : /** API provided by the backed. */ 27 1 : const struct ec_host_cmd_backend_api *api; 28 : /** Context for the backed. */ 29 1 : 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 1 : 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 1 : uint8_t *buf; 50 : /** Number of bytes written to @a buf by backend. */ 51 1 : size_t len; 52 : /** Maximum number of bytes to receive with one request packet. */ 53 1 : size_t len_max; 54 : }; 55 : 56 : /** 57 : * @brief Context for host command backend and handler to pass tx data 58 : */ 59 1 : 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 1 : void *buf; 67 : /** Number of bytes to write from @a buf. */ 68 1 : size_t len; 69 : /** Maximum number of bytes to send with one response packet. */ 70 1 : 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 1 : 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 1 : typedef int (*ec_host_cmd_backend_api_send)(const struct ec_host_cmd_backend *backend); 105 : 106 0 : struct ec_host_cmd_backend_api { 107 0 : ec_host_cmd_backend_api_init init; 108 0 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
