1 /** 2 **************************************************************************************** 3 * 4 * @file app_qspi.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of QSPI 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_QSPI QSPI 47 * @brief QSPI APP module driver. 48 * @{ 49 */ 50 51 52 #ifndef _APP_QSPI_H_ 53 #define _APP_QSPI_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_QSPI_MODULE_ENABLED 65 66 /** @addtogroup APP_QSPI_DEFINE Defines 67 * @{ 68 */ 69 70 #define APP_QSPI_PIN_ENABLE 1 /**< QSPI pin enable */ 71 #define APP_QSPI_PIN_DISABLE 0 /**< QSPI pin disable */ 72 73 /** @} */ 74 75 /** @addtogroup APP_QSPI_ENUM Enumerations 76 * @{ 77 */ 78 79 /** 80 * @brief QSPI module Enumerations definition 81 */ 82 typedef enum { 83 APP_QSPI_ID_0, /**< QSPI module 0 */ 84 APP_QSPI_ID_1, /**< QSPI module 1 */ 85 APP_QSPI_ID_MAX /**< Only for check parameter, not used as input parameters. */ 86 } app_qspi_id_t; 87 88 /** 89 * @brief QSPI operating mode Enumerations definition 90 */ 91 typedef enum { 92 APP_QSPI_TYPE_INTERRUPT, /**< Interrupt operation mode */ 93 APP_QSPI_TYPE_POLLING, /**< Polling operation mode */ 94 APP_QSPI_TYPE_DMA, /**< DMA operation mode */ 95 APP_QSPI_TYPE_MAX, /**< Only for check parameter, not used as input parameters. */ 96 } app_qspi_type_t; 97 98 /** 99 * @brief APP QSPI Event Type 100 */ 101 typedef enum { 102 APP_QSPI_EVT_ERROR, /**< Error reported by UART peripheral. */ 103 APP_QSPI_EVT_TX_CPLT, /**< Requested TX transfer completed. */ 104 APP_QSPI_EVT_RX_DATA, /**< Requested RX transfer completed. */ 105 } app_qspi_evt_type_t; 106 /** @} */ 107 108 /** @addtogroup APP_QSPI_STRUCTURES Structures 109 * @{ 110 */ 111 112 /** 113 * @brief QSPI IO configuration Structures 114 */ 115 typedef struct { 116 app_io_type_t type; /**< Specifies the type of QSPI IO. */ 117 app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */ 118 uint32_t pin; /**< Specifies the IO pins to be configured. 119 This parameter can be any value of @ref GR551x_pins. */ 120 app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */ 121 uint8_t enable; /**< Enable or disable the pin. */ 122 } app_qspi_pin_t; 123 124 /** 125 * @brief QSPI configuration Structures 126 */ 127 typedef struct { 128 app_qspi_pin_t cs; /**< Set the configuration of QSPI CS pin. */ 129 app_qspi_pin_t clk; /**< Set the configuration of QSPI CLK pin. */ 130 app_qspi_pin_t io_0; /**< Set the configuration of QSPI IO0 pin. */ 131 app_qspi_pin_t io_1; /**< Set the configuration of QSPI IO1 pin. */ 132 app_qspi_pin_t io_2; /**< Set the configuration of QSPI IO2 pin. */ 133 app_qspi_pin_t io_3; /**< Set the configuration of QSPI IO3 pin. */ 134 } app_qspi_pin_cfg_t; 135 136 /** 137 * @brief QSPI operate mode Enumerations definition 138 */ 139 typedef struct { 140 app_qspi_type_t type; /**< Specifies the operation mode of QSPI. */ 141 dma_channel_t dma_channel; /**< Specifies the dma channel of QSPI. */ 142 } app_qspi_mode_t; 143 144 /** 145 * @brief QSPI parameters structure definition 146 */ 147 typedef struct { 148 app_qspi_id_t id; /**< specified QSPI module ID. */ 149 app_qspi_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified QSPI module. */ 150 app_qspi_mode_t use_mode; /**< QSPI operate mode. */ 151 qspi_init_t init; /**< QSPI communication parameters. */ 152 } app_qspi_params_t; 153 154 /** @} */ 155 156 /** @addtogroup APP_QSPI_TYPEDEFS Typedefs 157 * @{ 158 */ 159 /** 160 * @brief QSPI command structure definition 161 */ 162 typedef qspi_command_t app_qspi_command_t; 163 /** @} */ 164 165 166 /** @addtogroup APP_QSPI_STRUCTURES Structures 167 * @{ 168 */ 169 /** 170 * @brief QSPI event structure definition 171 */ 172 typedef struct { 173 app_qspi_evt_type_t type; /**< Type of event. */ 174 union { 175 uint32_t error_code; /**< QSPI Error code . */ 176 uint16_t size; /**< QSPI transmitted/received counter. */ 177 } data; /**< Event data. */ 178 } app_qspi_evt_t; 179 /** @} */ 180 181 /** @addtogroup APP_QSPI_TYPEDEFS Typedefs 182 * @{ 183 */ 184 /** 185 * @brief QSPI event callback definition 186 */ 187 typedef void (*app_qspi_evt_handler_t)(app_qspi_evt_t *p_evt); 188 /** @} */ 189 190 191 /* Exported functions --------------------------------------------------------*/ 192 /** @addtogroup HAL_APP_QSPI_DRIVER_FUNCTIONS Functions 193 * @{ 194 */ 195 /** 196 **************************************************************************************** 197 * @brief Initialize the APP QSPI DRIVER according to the specified parameters 198 * in the app_qspi_params_t and app_qspi_evt_handler_t. 199 * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode 200 * is set, you can't use interrupt mode. 201 * 202 * @param[in] p_params: Pointer to app_qspi_params_t parameter which contains the 203 * configuration information for the specified QSPI module. 204 * @param[in] evt_handler: QSPI user callback function. 205 * 206 * @return Result of initialization. 207 **************************************************************************************** 208 */ 209 uint16_t app_qspi_init(app_qspi_params_t *p_params, app_qspi_evt_handler_t evt_handler); 210 211 /** 212 **************************************************************************************** 213 * @brief De-initialize the APP QSPI DRIVER peripheral. 214 * 215 * @param[in] id: De-initialize for a specific ID. 216 * 217 * @return Result of De-initialization. 218 **************************************************************************************** 219 */ 220 uint16_t app_qspi_deinit(app_qspi_id_t id); 221 222 /** 223 **************************************************************************************** 224 * @brief Receive an amount of data with the specified instruction, address and dummy cycles in blocking mode. 225 * @note This function is used only in Indirect Read Mode. 226 * @param[in] id: which QSPI module want to receive. 227 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 228 * contains the instruction and address for data transfer. 229 * @param[out] p_data: Pointer to data buffer 230 * @param[in] timeout: Timeout duration 231 * 232 * @return Result of operation. 233 **************************************************************************************** 234 */ 235 uint16_t app_qspi_command_receive_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint8_t *p_data, uint32_t timeout); 236 237 /** 238 **************************************************************************************** 239 * @brief Receive an amount of data with the specified instruction, 240 * address and dummy cycles in non-blocking mode with Interrupt. 241 * @note This function is used only in Indirect Read Mode. 242 * @param[in] id: which QSPI module want to receive. 243 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 244 * contains the instruction and address for data transfer. 245 * @param[out] p_data: Pointer to data buffer 246 * 247 * @return Result of operation. 248 **************************************************************************************** 249 */ 250 uint16_t app_qspi_command_receive_async(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint8_t *p_data); 251 252 /** 253 **************************************************************************************** 254 * @brief Receive an amount of data with the specified instruction, address and dummy cycles in blocking mode. 255 * @note This function is used only in Indirect Read Mode. 256 * @param[in] id: which QSPI module want to transmit. 257 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 258 * contains the instruction and address for data transfer. 259 * @param[out] p_data: Pointer to data buffer 260 * @param[in] timeout: Timeout duration 261 * 262 * @return Result of operation. 263 **************************************************************************************** 264 */ 265 uint16_t app_qspi_command_transmit_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint8_t *p_data, uint32_t timeout); 266 267 /** 268 **************************************************************************************** 269 * @brief Receive an amount of data with the specified instruction, 270 * address and dummy cycles in non-blocking mode with Interrupt. 271 * @note This function is used only in Indirect Read Mode. 272 * @param[in] id: which QSPI module want to transmit. 273 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 274 * contains the instruction and address for data transfer. 275 * @param[out] p_data: Pointer to data buffer 276 * 277 * @return Result of operation. 278 **************************************************************************************** 279 */ 280 uint16_t app_qspi_command_transmit_async(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint8_t *p_data); 281 282 /** 283 **************************************************************************************** 284 * @brief Transmit only instruction in blocking mode. 285 * @note This function is used only in Indirect Write Mode. 286 * @param[in] id: which QSPI module want to transmit command. 287 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 288 * contains the instruction and address for data transfer. 289 * @param[in] timeout: Timeout duration 290 * 291 * @return Result of operation. 292 **************************************************************************************** 293 */ 294 uint16_t app_qspi_command_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint32_t timeout); 295 296 /** 297 **************************************************************************************** 298 * @brief Transmit instruction in non-blocking mode with Interrupt. 299 * @note This function is used only in Indirect Write Mode. 300 * @param[in] id: which QSPI module want to transmit command. 301 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 302 * contains the instruction and address for data transfer. 303 * 304 * @return Result of operation. 305 **************************************************************************************** 306 */ 307 uint16_t app_qspi_command_async(app_qspi_id_t id, app_qspi_command_t *p_cmd); 308 309 /** 310 **************************************************************************************** 311 * @brief Transmit an amount of data in blocking mode with standard SPI. 312 * @note This function is used only in Indirect Write Mode. 313 * @param[in] id: which QSPI module want to transmit. 314 * @param[in] p_data: Pointer to data buffer 315 * @param[in] length: Amount of data to be sent in bytes 316 * @param[in] timeout: Timeout duration 317 * 318 * @return Result of operation. 319 **************************************************************************************** 320 */ 321 uint16_t app_qspi_transmit_sync(app_qspi_id_t id, uint8_t *p_data, uint32_t length, uint32_t timeout); 322 323 /** 324 **************************************************************************************** 325 * @brief Transmit an amount of data in non-blocking mode at standard SPI with Interrupt. 326 * @note This function is used only in Indirect Write Mode. 327 * @param[in] id: which QSPI module want to transmit. 328 * @param[in] p_data: Pointer to data buffer 329 * @param[in] length: Amount of data to be sent in bytes 330 * 331 * @return Result of operation. 332 **************************************************************************************** 333 */ 334 uint16_t app_qspi_transmit_async(app_qspi_id_t id, uint8_t *p_data, uint32_t length); 335 336 /** 337 **************************************************************************************** 338 * @brief Receive an amount of data in blocking mode with standard SPI. 339 * @note This function is used only in Indirect Read Mode. 340 * @param[in] id: which QSPI module want to receive. 341 * @param[out] p_data: Pointer to data buffer 342 * @param[in] length: Amount of data to be received in bytes 343 * @param[in] timeout: Timeout duration 344 * 345 * @return Result of operation. 346 **************************************************************************************** 347 */ 348 uint16_t app_qspi_receive_sync(app_qspi_id_t id, uint8_t *p_data, uint32_t length, uint32_t timeout); 349 350 /** 351 **************************************************************************************** 352 * @brief Receive an amount of data in non-blocking mode at standard SPI with Interrupt. 353 * @note This function is used only in Indirect Read Mode. 354 * @param[in] id: which QSPI module want to receive. 355 * @param[out] p_data: Pointer to data buffer 356 * @param[in] length: Amount of data to be received in bytes 357 * 358 * @return Result of operation. 359 **************************************************************************************** 360 */ 361 uint16_t app_qspi_receive_async(app_qspi_id_t id, uint8_t *p_data, uint32_t length); 362 363 /** 364 **************************************************************************************** 365 * @brief Return the QSPI handle. 366 * 367 * @param[in] id: QSPI Channel ID. 368 * 369 * @return Pointer to the specified ID's QSPI handle. 370 **************************************************************************************** 371 */ 372 qspi_handle_t *app_qspi_get_handle(app_qspi_id_t id); 373 374 #ifdef ENV_RTOS_USE_SEMP 375 376 /** 377 **************************************************************************************** 378 * @brief [RTOS] Receive an amount of data with the specified instruction, address and dummy cycles in blocking mode. 379 * @note This function is used only in Indirect Read Mode. 380 * @param[in] id: which QSPI module want to receive. 381 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 382 * contains the instruction and address for data transfer. 383 * @param[out] p_data: Pointer to data buffer 384 * 385 * @return Result of operation. 386 **************************************************************************************** 387 */ 388 uint16_t app_qspi_command_receive_sem_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint8_t *p_data); 389 390 /** 391 **************************************************************************************** 392 * @brief [RTOS] Receive an amount of data with the specified instruction, address and dummy cycles in blocking mode. 393 * @note This function is used only in Indirect Read Mode. 394 * @param[in] id: which QSPI module want to transmit. 395 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 396 * contains the instruction and address for data transfer. 397 * @param[out] p_data: Pointer to data buffer 398 * 399 * @return Result of operation. 400 **************************************************************************************** 401 */ 402 uint16_t app_qspi_command_transmit_sem_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint8_t *p_data); 403 404 /** 405 **************************************************************************************** 406 * @brief [RTOS] Transmit only instruction in blocking mode. 407 * @note This function is used only in Indirect Write Mode. 408 * @param[in] id: which QSPI module want to transmit command. 409 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 410 * contains the instruction and address for data transfer. 411 * 412 * @return Result of operation. 413 **************************************************************************************** 414 */ 415 uint16_t app_qspi_command_sem_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd); 416 417 /** 418 **************************************************************************************** 419 * @brief [RTOS] Transmit an amount of data in blocking mode with standard SPI. 420 * @note This function is used only in Indirect Write Mode. 421 * @param[in] id: which QSPI module want to transmit. 422 * @param[in] p_data: Pointer to data buffer 423 * @param[in] length: Amount of data to be sent in bytes 424 * 425 * @return Result of operation. 426 **************************************************************************************** 427 */ 428 uint16_t app_qspi_transmit_sem_sync(app_qspi_id_t id, uint8_t *p_data, uint32_t length); 429 430 /** 431 **************************************************************************************** 432 * @brief [RTOS] Receive an amount of data in blocking mode with standard SPI. 433 * @note This function is used only in Indirect Read Mode. 434 * @param[in] id: which QSPI module want to receive. 435 * @param[out] p_data: Pointer to data buffer 436 * @param[in] length: Amount of data to be received in bytes 437 * 438 * @return Result of operation. 439 **************************************************************************************** 440 */ 441 uint16_t app_qspi_receive_sem_sync(app_qspi_id_t id, uint8_t *p_data, uint32_t length); 442 443 #endif 444 445 /** 446 **************************************************************************************** 447 * @brief [High speed] Receive an amount of data with 448 * the specified instruction, address and dummy cycles in blocking mode. 449 * @note This function is used only in Indirect Read Mode. 450 * @param[in] id: which QSPI module want to receive. 451 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 452 * contains the instruction and address for data transfer. 453 * @param[out] p_data: Pointer to data buffer 454 * 455 * @return Result of operation. 456 **************************************************************************************** 457 */ 458 uint16_t app_qspi_command_receive_high_speed_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint8_t *p_data); 459 460 /** 461 **************************************************************************************** 462 * @brief [High speed] Receive an amount of data with 463 * the specified instruction, address and dummy cycles in blocking mode. 464 * @note This function is used only in Indirect Read Mode. 465 * @param[in] id: which QSPI module want to transmit. 466 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 467 * contains the instruction and address for data transfer. 468 * @param[out] p_data: Pointer to data buffer 469 * 470 * @return Result of operation. 471 **************************************************************************************** 472 */ 473 uint16_t app_qspi_command_transmit_high_speed_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd, uint8_t *p_data); 474 475 /** 476 **************************************************************************************** 477 * @brief [High speed] Transmit only instruction in blocking mode. 478 * @note This function is used only in Indirect Write Mode. 479 * @param[in] id: which QSPI module want to transmit command. 480 * @param[in] p_cmd: Pointer to a app_qspi_command_t structure that 481 * contains the instruction and address for data transfer. 482 * 483 * @return Result of operation. 484 **************************************************************************************** 485 */ 486 uint16_t app_qspi_command_high_speed_sync(app_qspi_id_t id, app_qspi_command_t *p_cmd); 487 488 /** 489 **************************************************************************************** 490 * @brief [High speed] Transmit an amount of data in blocking mode with standard SPI. 491 * @note This function is used only in Indirect Write Mode. 492 * @param[in] id: which QSPI module want to transmit. 493 * @param[in] p_data: Pointer to data buffer 494 * @param[in] length: Amount of data to be sent in bytes 495 * 496 * @return Result of operation. 497 **************************************************************************************** 498 */ 499 uint16_t app_qspi_transmit_high_speed_sync(app_qspi_id_t id, uint8_t *p_data, uint32_t length); 500 501 /** 502 **************************************************************************************** 503 * @brief [High speed] Receive an amount of data in blocking mode with standard SPI. 504 * @note This function is used only in Indirect Read Mode. 505 * @param[in] id: which QSPI module want to receive. 506 * @param[out] p_data: Pointer to data buffer 507 * @param[in] length: Amount of data to be received in bytes 508 * 509 * @return Result of operation. 510 **************************************************************************************** 511 */ 512 uint16_t app_qspi_receive_high_speed_sync(app_qspi_id_t id, uint8_t *p_data, uint32_t length); 513 514 /** @} */ 515 516 #endif 517 518 #ifdef __cplusplus 519 } 520 #endif 521 522 #endif 523 524 /** @} */ 525 /** @} */ 526 /** @} */ 527