1 // Copyright (C) 2022 Beken Corporation 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #include <driver/spi_types.h> 18 #include <common/bk_include.h> 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /** 25 * @brief Init the SPI driver 26 * 27 * This API init the resoure common: 28 * - Init SPI driver control memory 29 * 30 * @attention 1. This API should be called before any other SPI APIs. 31 * 32 * @return 33 * - BK_OK: succeed 34 * - others: other errors. 35 */ 36 bk_err_t bk_spi_driver_init(void); 37 38 /** 39 * @brief Deinit the SPI driver 40 * 41 * This API free all resource related to SPI and disable SPI. 42 * 43 * @return 44 * - BK_OK: succeed 45 * - others: other errors. 46 */ 47 bk_err_t bk_spi_driver_deinit(void); 48 49 /** 50 * @brief Init the SPI id 51 * 52 * This API init the SPI id: 53 * - Power up the SPI id 54 * - Configure the SPI id clock 55 * - Map the SPI id to dedicated GPIO port 56 * - Set the SPI parameters 57 * - Start the SPI id 58 * 59 * @param id SPI id 60 * @param config SPI parameter settings 61 * 62 * @return 63 * - BK_OK: succeed 64 * - BK_ERR_NULL_PARAM: SPI config paramter is NULL 65 * - BK_ERR_SPI_NOT_INIT: SPI driver not init 66 * - BK_ERR_SPI_INVALID_ID: SPI id is invalid 67 * - others: other errors. 68 */ 69 bk_err_t bk_spi_init(spi_id_t id, const spi_config_t *config); 70 71 /** 72 * @brief Deinit the SPI id 73 * 74 * This API deinit the SPI id: 75 * - Stop the SPI id 76 * - Disable the SPI id interrupt 77 * - Power down the SPI id 78 * 79 * @param id SPI id 80 * 81 * @return 82 * - BK_OK: succeed 83 * - others: other errors. 84 */ 85 bk_err_t bk_spi_deinit(spi_id_t id); 86 87 /** 88 * @brief Set the SPI mode 89 * 90 * @param id SPI id 91 * @param mode SPI mode 92 * 93 * @return 94 * - BK_OK: succeed 95 * - others: other errors. 96 */ 97 bk_err_t bk_spi_set_mode(spi_id_t id, spi_mode_t mode); 98 99 /** 100 * @brief Set the SPI bit width 101 * 102 * @param id SPI id 103 * @param bit_width SPI bit width 104 * 105 * @return 106 * - BK_OK: succeed 107 * - others: other errors. 108 */ 109 bk_err_t bk_spi_set_bit_width(spi_id_t id, spi_bit_width_t bit_width); 110 111 /** 112 * @brief Set the SPI wire mode 113 * 114 * @param id SPI id 115 * @param wire_mode SPI wire mode 116 * 117 * @return 118 * - BK_OK: succeed 119 * - others: other errors. 120 */ 121 bk_err_t bk_spi_set_wire_mode(spi_id_t id, spi_wire_mode_t wire_mode); 122 123 /** 124 * @brief Set the SPI baud rate 125 * 126 * @param id SPI id 127 * @param baud_rate SPI baud rate 128 * 129 * @return 130 * - BK_OK: succeed 131 * - others: other errors. 132 */ 133 bk_err_t bk_spi_set_baud_rate(spi_id_t id, uint32_t baud_rate); 134 135 /** 136 * @brief Set the SPI bit order 137 * 138 * @param id SPI id 139 * @param bit_order SPI bit order 140 * 141 * @return 142 * - BK_OK: succeed 143 * - others: other errors. 144 */ 145 bk_err_t bk_spi_set_bit_order(spi_id_t id, spi_bit_order_t bit_order); 146 147 /** 148 * @brief Register the RX interrupt service routine for SPI id 149 * 150 * @param id spi id 151 * @param isr SPI RX callback 152 * @param param SPI RX callback parameter 153 * 154 * @return 155 * - BK_OK: succeed 156 * - others: other errors. 157 */ 158 bk_err_t bk_spi_register_rx_isr(spi_id_t id, spi_isr_t isr, void *param); 159 160 /** 161 * @brief Register the TX finish interrupt service routine for SPI id 162 * 163 * @param id SPi id 164 * @param isr SPI TX finish callback 165 * @param param SPi TX callback parameter 166 * 167 * @return 168 * - BK_OK: succeed 169 * - others: other errors. 170 */ 171 bk_err_t bk_spi_register_tx_finish_isr(spi_id_t id, spi_isr_t isr, void *param); 172 173 /** 174 * @brief Send data to the SPI port from a given buffer and length 175 * 176 * @param id spi id 177 * @param data data buffer address 178 * @param size data length to send 179 * 180 * @return 181 * - BK_OK: succeed 182 * - BK_ERR_SPI_NOT_INIT: SPI driver not init 183 * - BK_ERR_SPI_INVALID_ID: SPI id number is invalid 184 * - BK_ERR_SPI_ID_NOT_INIT: SPI id not init 185 * - others: other errors. 186 */ 187 bk_err_t bk_spi_write_bytes(spi_id_t id, const void *data, uint32_t size); 188 189 /** 190 * @brief SPI read bytes from SPI buffer 191 * 192 * @param id SPI id 193 * @param data pointer to the buffer 194 * @param size data length to read 195 * 196 * @return 197 * - BK_OK: succeed 198 * - BK_ERR_SPI_NOT_INIT: SPI driver not init 199 * - BK_ERR_SPI_INVALID_ID: SPI id number is invalid 200 * - BK_ERR_SPI_ID_NOT_INIT: SPI id not init 201 * - others: other errors. 202 */ 203 bk_err_t bk_spi_read_bytes(spi_id_t id, void *data, uint32_t size); 204 205 /** 206 * @brief SPI write and read bytes 207 * 208 * @param id SPI id 209 * @param tx_data write data buffer address 210 * @param tx_size data length to read 211 * @param rx_data pointer to the receive buffer 212 * @param rx_size data length to read 213 * @param timeout_ms timeout ms, if set BEKEN_WAIT_FOREVER, read will wait forever 214 * 215 * @return 216 * - BK_OK: succeed 217 * - BK_ERR_SPI_NOT_INIT: SPI driver not init 218 * - BK_ERR_SPI_INVALID_ID: SPI id number is invalid 219 * - BK_ERR_SPI_ID_NOT_INIT: SPI id not init 220 * - others: other errors. 221 */ 222 bk_err_t bk_spi_transmit(spi_id_t id, const void *tx_data, uint32_t tx_size, void *rx_data, uint32_t rx_size); 223 224 225 /** 226 * @brief Register the RX finish interrupt service routine for SPI id 227 * 228 * @param id spi id 229 * @param isr SPI RX callback 230 * @param param SPI RX callback parameter 231 * 232 * @return 233 * - BK_OK: succeed 234 * - others: other errors. 235 */ 236 bk_err_t bk_spi_register_rx_finish_isr(spi_id_t id, spi_isr_t isr, void *param); 237 238 /** 239 * @brief Unregister the RX interrupt service routine for SPI id 240 * 241 * @param id spi id 242 * 243 * @return 244 * - BK_OK: succeed 245 * - others: other errors. 246 */ 247 bk_err_t bk_spi_unregister_rx_isr(spi_id_t id); 248 249 /** 250 * @brief Unregister the RX finish interrupt service routine for SPI id 251 * 252 * @param id spi id 253 * 254 * @return 255 * - BK_OK: succeed 256 * - others: other errors. 257 */ 258 bk_err_t bk_spi_unregister_rx_finish_isr(spi_id_t id); 259 260 /** 261 * @brief Unregister the TX finish interrupt service routine for SPI id 262 * 263 * @param id spi id 264 * 265 * @return 266 * - BK_OK: succeed 267 * - others: other errors. 268 */ 269 bk_err_t bk_spi_unregister_tx_finish_isr(spi_id_t id); 270 271 272 /** 273 * @brief Send data to the SPI port from a given buffer and length in async mode 274 * 275 * @param id spi id 276 * @param data data buffer address 277 * @param size data length to send 278 * 279 * @return 280 * - BK_OK: succeed 281 * - BK_ERR_SPI_NOT_INIT: SPI driver not init 282 * - BK_ERR_SPI_INVALID_ID: SPI id number is invalid 283 * - BK_ERR_SPI_ID_NOT_INIT: SPI id not init 284 * - others: other errors. 285 */ 286 bk_err_t bk_spi_write_bytes_async(spi_id_t id, const void *data, uint32_t size); 287 288 /** 289 * @brief SPI read bytes from SPI buffer in async mode 290 * 291 * @param id SPI id 292 * @param data pointer to the buffer 293 * @param size data length to read 294 * 295 * @return 296 * - BK_OK: succeed 297 * - BK_ERR_SPI_NOT_INIT: SPI driver not init 298 * - BK_ERR_SPI_INVALID_ID: SPI id number is invalid 299 * - BK_ERR_SPI_ID_NOT_INIT: SPI id not init 300 * - others: other errors. 301 */ 302 bk_err_t bk_spi_read_bytes_async(spi_id_t id, void *data, uint32_t size); 303 304 305 306 307 #if CONFIG_SPI_DMA 308 309 /** 310 * @brief Send data to the SPI port by dma from a given buffer and length 311 * 312 * @param id spi id 313 * @param data data buffer address 314 * @param size data length to send 315 * 316 * @return 317 * - BK_OK: succeed 318 * - others: other errors. 319 */ 320 bk_err_t bk_spi_dma_write_bytes(spi_id_t id, const void *data, uint32_t size); 321 322 /** 323 * @brief SPI read bytes by dma from SPI buffer 324 * 325 * @param id SPI id 326 * @param data pointer to the buffer 327 * @param size data length to read 328 * @param timeout_ms timeout ms, if set BEKEN_WAIT_FOREVER, read will wait forever 329 * 330 * @return 331 * - BK_ERR_SPI_NOT_INIT: SPI driver not init 332 * - BK_ERR_SPI_INVALID_ID: SPI id number is invalid 333 * - BK_ERR_SPI_ID_NOT_INIT: SPI id not init 334 * - others: other errors. 335 */ 336 bk_err_t bk_spi_dma_read_bytes(spi_id_t id, void *data, uint32_t size); 337 338 /** 339 * @brief SPI write and read bytes byte dma 340 * 341 * @param id SPI id 342 * @param tx_data write data buffer address 343 * @param tx_size data length to read 344 * @param rx_data pointer to the receive buffer 345 * @param rx_size data length to read 346 * @param timeout_ms timeout ms, if set BEKEN_WAIT_FOREVER, read will wait forever 347 * 348 * @return 349 * - BK_ERR_SPI_NOT_INIT: SPI driver not init 350 * - BK_ERR_SPI_INVALID_ID: SPI id number is invalid 351 * - BK_ERR_SPI_ID_NOT_INIT: SPI id not init 352 * - others: other errors. 353 */ 354 bk_err_t bk_spi_dma_transmit(spi_id_t id, const void *tx_data, uint32_t tx_size, void *rx_data, uint32_t rx_size); 355 356 #endif 357 358 #ifdef __cplusplus 359 } 360 #endif 361 362