1 /** 2 **************************************************************************************** 3 * 4 * @file app_spi.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of SPI app library. 7 * 8 **************************************************************************************** 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 specific prior written permission. 23 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 **************************************************************************************** 36 */ 37 38 /** @addtogroup PERIPHERAL Peripheral Driver 39 * @{ 40 */ 41 42 /** @addtogroup APP_DRIVER APP DRIVER 43 * @{ 44 */ 45 46 /** @defgroup APP_SPI SPI 47 * @brief SPI APP module driver. 48 * @{ 49 */ 50 51 52 #ifndef _APP_SPI_H_ 53 #define _APP_SPI_H_ 54 55 #include "gr55xx_hal.h" 56 #include "app_io.h" 57 #include "app_drv_error.h" 58 #include "app_rtos_cfg.h" 59 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 64 #ifdef HAL_SPI_MODULE_ENABLED 65 66 #ifdef _APP_SPI_V2_H_ 67 #error "NOT Support USING app_spi AND app_spi_v2 AT The Same Time !!!" 68 #endif 69 70 /** @addtogroup APP_SPI_DEFINE Defines 71 * @{ 72 */ 73 74 #define APP_SPI_PIN_ENABLE 1 /**< SPI pin enable */ 75 #define APP_SPI_PIN_DISABLE 0 /**< SPI pin disable */ 76 77 /** @} */ 78 79 /** @addtogroup APP_SPI_ENUM Enumerations 80 * @{ 81 */ 82 83 /** 84 * @brief SPI module Enumerations definition 85 */ 86 typedef enum { 87 APP_SPI_ID_SLAVE, /**< SPI slave module. */ 88 APP_SPI_ID_MASTER, /**< SPI master module. */ 89 APP_SPI_ID_MAX, /**< Only for check parameter, not used as input parameters. */ 90 } app_spi_id_t; 91 92 /** 93 * @brief SPI operating mode Enumerations definition 94 */ 95 typedef enum { 96 APP_SPI_TYPE_INTERRUPT, /**< Interrupt operation mode */ 97 APP_SPI_TYPE_POLLING, /**< Polling operation mode */ 98 APP_SPI_TYPE_DMA, /**< DMA operation mode */ 99 APP_SPI_TYPE_MAX, /**< Only for check parameter, not used as input parameters. */ 100 } app_spi_type_t; 101 102 /** 103 * @brief SPI event Enumerations definition 104 */ 105 typedef enum { 106 APP_SPI_EVT_ERROR, /**< Error reported by UART peripheral. */ 107 APP_SPI_EVT_TX_CPLT, /**< Requested TX transfer completed. */ 108 APP_SPI_EVT_RX_DATA, /**< Requested RX transfer completed. */ 109 APP_SPI_EVT_TX_RX, /**< Requested TX/RX transfer completed. */ 110 } app_spi_evt_type_t; 111 /** @} */ 112 113 /** @addtogroup APP_SPI_STRUCTURES Structures 114 * @{ 115 */ 116 /** 117 * @brief SPI IO Structures 118 */ 119 typedef struct { 120 app_io_type_t type; /**< Specifies the type of SPI IO. */ 121 app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */ 122 uint32_t pin; /**< Specifies the IO pins to be configured. 123 This parameter can be any value of @ref GR551x_pins. */ 124 app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */ 125 uint8_t enable; /**< Enable or disable the pin. */ 126 } app_spi_pin_t; 127 128 /** 129 * @brief SPI IO configuration Structures 130 */ 131 typedef struct { 132 app_spi_pin_t cs; /**< Set the configuration of SPI CS pin. */ 133 app_spi_pin_t clk; /**< Set the configuration of SPI CLK pin. */ 134 app_spi_pin_t mosi; /**< Set the configuration of SPI MOSI pin. */ 135 app_spi_pin_t miso; /**< Set the configuration of SPI MISO pin. */ 136 } app_spi_pin_cfg_t; 137 138 /** 139 * @brief SPI operate mode Enumerations definition 140 */ 141 typedef struct { 142 app_spi_type_t type; /**< Specifies the operation mode of SPI. */ 143 dma_channel_t tx_dma_channel; /**< Specifies the dma channel of SPI TX. */ 144 dma_channel_t rx_dma_channel; /**< Specifies the dma channel of SPI RX. */ 145 } app_spi_mode_t; 146 147 /** 148 * @brief SPI parameters structure definition 149 */ 150 typedef struct { 151 app_spi_id_t id; /**< specified SPI module ID. */ 152 app_spi_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified SPI module. */ 153 app_spi_mode_t use_mode; /**< SPI operate mode. */ 154 spi_init_t init; /**< SPI communication parameters. */ 155 } app_spi_params_t; 156 157 /** 158 * @brief SPI event structure definition 159 */ 160 typedef struct { 161 app_spi_evt_type_t type; /**< Type of event. */ 162 union { 163 uint32_t error_code; /**< SPI Error code . */ 164 uint16_t size; /**< SPI transmitted/received counter. */ 165 } data; /**< SPI data. */ 166 } app_spi_evt_t; 167 168 /** 169 * @brief SPI event callback definition 170 */ 171 typedef void (*app_spi_evt_handler_t)(app_spi_evt_t *p_evt); 172 173 /** @} */ 174 175 /* Exported functions --------------------------------------------------------*/ 176 /** @addtogroup APP_SPI_DRIVER_FUNCTIONS Functions 177 * @{ 178 */ 179 /** 180 **************************************************************************************** 181 * @brief Initialize the APP SPI DRIVER according to the specified parameters 182 * in the app_spi_params_t and app_spi_evt_handler_t. 183 * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode 184 * is set, you can't use interrupt mode. 185 * 186 * @param[in] p_params: Pointer to app_spi_params_t parameter which contains the 187 * configuration information for the specified SPI module. 188 * @param[in] evt_handler: SPI user callback function. 189 * 190 * 191 * @return Result of initialization. 192 **************************************************************************************** 193 */ 194 uint16_t app_spi_init(app_spi_params_t *p_params, app_spi_evt_handler_t evt_handler); 195 196 /** 197 **************************************************************************************** 198 * @brief De-initialize the APP SPI DRIVER peripheral. 199 * 200 * @param[in] id: De-initialize for a specific ID. 201 * 202 * @return Result of De-initialization. 203 **************************************************************************************** 204 */ 205 uint16_t app_spi_deinit(app_spi_id_t id); 206 207 /** 208 **************************************************************************************** 209 * @brief Receive in master or slave mode an amount of data in blocking mode. 210 * 211 * @param[in] id: which SPI module want to receive. 212 * @param[in] p_data: Pointer to data buffer 213 * @param[in] size: Amount of data to be sent 214 * @param[in] timeout: Timeout duration 215 * 216 * @return Result of operation. 217 **************************************************************************************** 218 */ 219 uint16_t app_spi_receive_sync(app_spi_id_t id, uint8_t *p_data, uint16_t size, uint32_t timeout); 220 221 /** 222 **************************************************************************************** 223 * @brief Receive in master or slave mode an amount of data in non-blocking mode with Interrupt 224 * 225 * @param[in] id: which SPI module want to receive. 226 * @param[in] p_data: Pointer to data buffer 227 * @param[in] size: Amount of data to be sent 228 * 229 * @return Result of operation. 230 **************************************************************************************** 231 */ 232 uint16_t app_spi_receive_async(app_spi_id_t id, uint8_t *p_data, uint16_t size); 233 234 /** 235 **************************************************************************************** 236 * @brief Transmits in master or slave mode an amount of data in blocking mode. 237 * 238 * @param[in] id: which SPI module want to transmit. 239 * @param[in] p_data: Pointer to data buffer 240 * @param[in] size: Amount of data to be sent 241 * @param[in] timeout: Timeout duration 242 * 243 * @return Result of operation. 244 **************************************************************************************** 245 */ 246 uint16_t app_spi_transmit_sync(app_spi_id_t id, uint8_t *p_data, uint16_t size, uint32_t timeout); 247 248 /** 249 **************************************************************************************** 250 * @brief Transmits in master or slave mode an amount of data in non-blocking mode with Interrupt 251 * 252 * @param[in] id: which SPI module want to transmit. 253 * @param[in] p_data: Pointer to data buffer 254 * @param[in] size: Amount of data to be sent 255 * 256 * @return Result of operation. 257 **************************************************************************************** 258 */ 259 uint16_t app_spi_transmit_async(app_spi_id_t id, uint8_t *p_data, uint16_t size); 260 261 /** 262 **************************************************************************************** 263 * @brief Transmits and receive in master or slave mode an amount of data in blocking mode. 264 * 265 * @param[in] id: which SPI module want to transmit. 266 * @param[in] p_tx_data: Pointer to tx data buffer 267 * @param[in] p_rx_data: Pointer to rx data buffer 268 * @param[in] size: Amount of data to be sent and receive 269 * @param[in] timeout: Timeout duration 270 * 271 * @return Result of operation. 272 **************************************************************************************** 273 */ 274 uint16_t app_spi_transmit_receive_sync(app_spi_id_t id, uint8_t *p_tx_data, 275 uint8_t *p_rx_data, uint32_t size, uint32_t timeout); 276 277 /** 278 **************************************************************************************** 279 * @brief Transmits and receive in master or slave mode an amount of data in non-blocking mode with Interrupt 280 * 281 * @param[in] id: which SPI module want to transmit. 282 * @param[in] p_tx_data: Pointer to tx data buffer 283 * @param[in] p_rx_data: Pointer to rx data buffer 284 * @param[in] size: Amount of data to be sent and receive 285 * 286 * @return Result of operation. 287 **************************************************************************************** 288 */ 289 uint16_t app_spi_transmit_receive_async(app_spi_id_t id, uint8_t *p_tx_data, uint8_t *p_rx_data, uint32_t size); 290 291 /** 292 **************************************************************************************** 293 * @brief Read an amount of data from EEPROM in blocking mode. 294 * 295 * @param[in] id: which SPI module want to transmit. 296 * @param[in] p_tx_data: Pointer to transmission data buffer 297 * @param[out] p_rx_data: Pointer to reception data buffer 298 * @param[in] tx_size: Amount of data to be sent in bytes 299 * @param[in] rx_size: Amount of data to be received in bytes 300 * @param[in] timeout: Timeout duration 301 * 302 * @return Result of operation. 303 **************************************************************************************** 304 */ 305 uint16_t app_spi_read_eeprom_sync(app_spi_id_t id, uint8_t *p_tx_data, uint8_t *p_rx_data, 306 uint32_t tx_size, uint32_t rx_size, uint32_t timeout); 307 308 /** 309 **************************************************************************************** 310 * @brief Read an amount of data from EEPROM in non-blocking mode with Interrupt. 311 * 312 * @param[in] id: which SPI module want to transmit. 313 * @param[in] p_tx_data: Pointer to transmission data buffer 314 * @param[out] p_rx_data: Pointer to reception data buffer 315 * @param[in] tx_size: Amount of data to be sent in bytes 316 * @param[in] rx_size: Amount of data to be received in bytes 317 * 318 * @return Result of operation. 319 **************************************************************************************** 320 */ 321 uint16_t app_spi_read_eeprom_async(app_spi_id_t id, uint8_t *p_tx_data, uint8_t *p_rx_data, 322 uint32_t tx_size, uint32_t rx_size); 323 324 /** 325 **************************************************************************************** 326 * @brief Transmits in master or slave mode an amount of data in non-blocking mode with DMA 327 * 328 * @param[in] id: which SPI module want to transmit. 329 * @param[in] p_cmd_data: Pointer to command data buffer 330 * @param[in] p_tx_data: Pointer to transmission data buffer 331 * @param[in] cmd_size: Amount of command data to be sent in bytes 332 * @param[in] tx_size: Amount of data to be sent in bytes 333 * 334 * @return Result of operation. 335 **************************************************************************************** 336 */ 337 uint16_t app_spi_write_memory_async(app_spi_id_t id, uint8_t *p_cmd_data, uint8_t *p_tx_data, 338 uint32_t cmd_size, uint32_t tx_size); 339 340 /** 341 **************************************************************************************** 342 * @brief Read an amount of data from EEPROM in non-blocking mode with DMA. 343 * 344 * @param[in] id: which SPI module want to transmit. 345 * @param[in] p_cmd_data: Pointer to command data buffer 346 * @param[out] p_rx_data: Pointer to reception data buffer 347 * @param[in] cmd_size: Amount of command data to be sent in bytes 348 * @param[in] rx_size: Amount of data to be received in bytes 349 * 350 * @return Result of operation. 351 **************************************************************************************** 352 */ 353 uint16_t app_spi_read_memory_async(app_spi_id_t id, uint8_t *p_cmd_data, uint8_t *p_rx_data, 354 uint32_t cmd_size, uint32_t rx_size); 355 356 /** 357 **************************************************************************************** 358 * @brief Return the SPI handle. 359 * 360 * @param[in] id: SPI Channel ID. 361 * 362 * @return Pointer to the specified ID's SPI handle. 363 **************************************************************************************** 364 */ 365 spi_handle_t *app_spi_get_handle(app_spi_id_t id); 366 367 368 #ifdef ENV_RTOS_USE_SEMP 369 /** 370 **************************************************************************************** 371 * @brief [RTOS] Receive in master or slave mode an amount of data in blocking mode. 372 * 373 * @param[in] id: which SPI module want to receive. 374 * @param[in] p_data: Pointer to data buffer 375 * @param[in] size: Amount of data to be sent 376 * 377 * @return Result of operation. 378 **************************************************************************************** 379 */ 380 uint16_t app_spi_receive_sem_sync(app_spi_id_t id, uint8_t *p_data, uint16_t size); 381 382 /** 383 **************************************************************************************** 384 * @brief [RTOS] Transmits in master or slave mode an amount of data in blocking mode. 385 * 386 * @param[in] id: which SPI module want to transmit. 387 * @param[in] p_data: Pointer to data buffer 388 * @param[in] size: Amount of data to be sent 389 * 390 * @return Result of operation. 391 **************************************************************************************** 392 */ 393 uint16_t app_spi_transmit_sem_sync(app_spi_id_t id, uint8_t *p_data, uint16_t size); 394 395 /** 396 **************************************************************************************** 397 * @brief [RTOS] Transmits and receive in master or slave mode an amount of data in blocking mode. 398 * 399 * @param[in] id: which SPI module want to transmit. 400 * @param[in] p_tx_data: Pointer to tx data buffer 401 * @param[in] p_rx_data: Pointer to rx data buffer 402 * @param[in] size: Amount of data to be sent and receive 403 * 404 * @return Result of operation. 405 **************************************************************************************** 406 */ 407 uint16_t app_spi_transmit_receive_sem_sync(app_spi_id_t id, uint8_t *p_tx_data, uint8_t *p_rx_data, uint32_t size); 408 #endif 409 410 /** 411 **************************************************************************************** 412 * @brief [High speed] Receive in master or slave mode an amount of data in blocking mode. 413 * 414 * @param[in] id: which SPI module want to receive. 415 * @param[in] p_data: Pointer to data buffer 416 * @param[in] size: Amount of data to be sent 417 * 418 * @return Result of operation. 419 **************************************************************************************** 420 */ 421 uint16_t app_spi_receive_high_speed_sync(app_spi_id_t id, uint8_t *p_data, uint16_t size); 422 423 /** 424 **************************************************************************************** 425 * @brief [High speed] Transmit in master or slave mode an amount of data in blocking mode. 426 * 427 * @param[in] id: which SPI module want to receive. 428 * @param[in] p_data: Pointer to data buffer 429 * @param[in] size: Amount of data to be sent 430 * 431 * @return Result of operation. 432 **************************************************************************************** 433 */ 434 uint16_t app_spi_transmit_high_speed_sync(app_spi_id_t id, uint8_t *p_data, uint16_t size); 435 436 /** @} */ 437 438 #endif 439 440 #ifdef __cplusplus 441 } 442 #endif 443 444 #endif 445 446 /** @} */ 447 /** @} */ 448 /** @} */ 449