1 /** 2 **************************************************************************************** 3 * 4 * @file gr55xx_hal_exflash.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of EXFLASH HAL 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 HAL_DRIVER HAL Driver 43 * @{ 44 */ 45 46 /** @defgroup HAL_EXFLASH EXFLASH 47 * @brief exFlash HAL module driver. 48 * @{ 49 */ 50 51 /* Define to prevent recursive inclusion -------------------------------------*/ 52 #ifndef __GR55xx_HAL_EXFLASH_H__ 53 #define __GR55xx_HAL_EXFLASH_H__ 54 55 /* Includes ------------------------------------------------------------------*/ 56 #include "gr55xx_ll_xqspi.h" 57 #include "gr55xx_hal_xqspi.h" 58 #include "gr55xx_hal_def.h" 59 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 64 /* Exported types ------------------------------------------------------------*/ 65 /** @addtogroup HAL_EXFLASH_ENUMERATIONS Enumerations 66 * @{ 67 */ 68 69 /** @defgroup HAL_EXFLASH_STATE HAL EXFLASH State 70 * @{ 71 */ 72 73 /** 74 * @brief HAL exFlash State Enumerations definition 75 */ 76 typedef enum { 77 HAL_EXFLASH_STATE_RESET = 0x00, /**< Peripheral not initialized */ 78 HAL_EXFLASH_STATE_READY = 0x01, /**< Peripheral initialized and ready for use */ 79 HAL_EXFLASH_STATE_BUSY = 0x02, /**< Peripheral in indirect mode and busy */ 80 HAL_EXFLASH_STATE_BUSY_READ = 0x12, /**< Peripheral in indirect mode with reception ongoing */ 81 HAL_EXFLASH_STATE_BUSY_WRITE = 0x22, /**< Peripheral in indirect mode with transmission ongoing */ 82 HAL_EXFLASH_STATE_BUSY_ERASE = 0x42, /**< Peripheral in indirect mode with erase ongoing */ 83 HAL_EXFLASH_STATE_SUSPEND_WRITE = 0x21, /**< Peripheral in suspend mode from transmission */ 84 HAL_EXFLASH_STATE_SUSPEND_ERASE = 0x41, /**< Peripheral in suspend mode from erase */ 85 HAL_EXFLASH_STATE_ERROR = 0x04 /**< Peripheral in error */ 86 } hal_exflash_state_t; 87 88 /** 89 * @brief HAL exFlash Security Enumerations definition 90 */ 91 typedef enum { 92 HAL_EXFLASH_UNENCRYPTED = 0x00, /**< Data will not be encrypted and decrypted 93 in write-read operations */ 94 HAL_EXFLASH_ENCRYPTED = 0x01, /**< Data will be encrypted and decrypted 95 in write-read operations */ 96 } hal_eflash_security; 97 98 /** @} */ 99 100 /** @} */ 101 102 /** @addtogroup HAL_EXFLASH_STRUCTURES Structures 103 * @{ 104 */ 105 106 /** @defgroup EXFLASH_HANDLE EXFLASH handle 107 * @{ 108 */ 109 110 /** 111 * @brief exFlash handle Structure definition 112 */ 113 typedef struct _exflash_handle { 114 xqspi_handle_t *p_xqspi; /**< exFlash XQSPI Handle parameters */ 115 116 __IO uint32_t fw_mode; /**< exFlash firmware mode */ 117 118 __IO hal_lock_t lock; /**< Locking object */ 119 120 __IO hal_exflash_state_t state; /**< exFlash communication state */ 121 122 __IO hal_eflash_security security; /**< exFlash data security */ 123 124 __IO uint32_t flash_id; /**< exFlash ID */ 125 126 __IO uint32_t flash_size; /**< exFlash Size */ 127 128 __IO uint32_t count; /**< exFlash count for suspend and resume */ 129 130 __IO uint32_t error_code; /**< exFlash Error code */ 131 132 uint32_t retry; /**< Repeat times for the exFlash memory access */ 133 } exflash_handle_t; 134 /** @} */ 135 136 /** @} */ 137 138 /** @addtogroup HAL_EXFLASH_CALLBACK_STRUCTURES Callback Structures 139 * @{ 140 */ 141 142 /** @defgroup HAL_EXFLASH_Callback Callback 143 * @{ 144 */ 145 146 /** 147 * @brief HAL_EXFLASH Callback function definition 148 */ 149 150 typedef struct _hal_exflash_callback { 151 void (*exflash_msp_init)(exflash_handle_t *p_exflash); /**< EXFLASH init MSP callback */ 152 void (*exflash_msp_deinit)(exflash_handle_t *p_exflash); /**< EXFLASH de-init MSP callback */ 153 } hal_exflash_callback_t; 154 155 /** @} */ 156 157 /** @} */ 158 159 /** 160 * @defgroup HAL_EXFLASH_MACRO Defines 161 * @{ 162 */ 163 164 /* Exported constants --------------------------------------------------------*/ 165 /** @defgroup EXFLASH_EXPORTED_CONSTANTS EXFLASH Exported Constants 166 * @{ 167 */ 168 169 /** @defgroup EXFLASH_ERROR_CODE EXFLASH Error Code 170 * @{ 171 */ 172 #define HAL_EXFLASH_ERROR_NONE ((uint32_t)0x00000000) /**< No error */ 173 #define HAL_EXFLASH_ERROR_TIMEOUT ((uint32_t)0x00000001) /**< Timeout error */ 174 #define HAL_EXFLASH_ERROR_TRANSFER ((uint32_t)0x00000002) /**< Transfer error */ 175 #define HAL_EXFLASH_ERROR_ID ((uint32_t)0x00000003) /**< Flash ID error */ 176 #define HAL_EXFLASH_ERROR_QUAD ((uint32_t)0x00000004) /**< Quad mode error */ 177 #define HAL_EXFLASH_ERROR_INVALID_PARAM ((uint32_t)0x00000008) /**< Invalid parameters error */ 178 /** @} */ 179 180 /** @defgroup EXFLASH_ERASE_TYPE EXFLASH Erase Type 181 * @{ 182 */ 183 #define EXFLASH_ERASE_SECTOR 0 /**< Sector erase */ 184 #define EXFLASH_ERASE_CHIP 1 /**< Chip erase */ 185 /** @} */ 186 187 /** @defgroup EXFLASH_SIZE_INFO EXFLASH Size Information 188 * @{ 189 */ 190 #define EXFLASH_SIZE_PAGE_BYTES ((uint32_t)256) /**< Page size in Bytes */ 191 #define EXFLASH_SIZE_SECTOR_BYTES ((uint32_t)4096) /**< Sector size in Bytes */ 192 #define EXFLASH_SIZE_CHIP_BYTES ((uint32_t)0x800000) /**< Chip size in Bytes */ 193 #define EXFLASH_START_ADDR FLASH_BASE /**< Flash start address */ 194 #define EXFLASH_SIZE (0x00800000UL) /**< Flash size */ 195 #define EXFLASH_END_ADDR (EXFLASH_START_ADDR + EXFLASH_SIZE) /**< Flash end address */ 196 #define EXFLASH_ALIAS_OFFSET (0x02000000UL) /**< Alias address offset */ 197 #define EXFLASH_ALIAS_ADDR (EXFLASH_START_ADDR + EXFLASH_ALIAS_OFFSET) /**< Alias start address */ 198 /** @} */ 199 200 /** @defgroup EXFLASH_LOCK_AREA_TYPE EXFLASH Lock Area Type 201 * @{ 202 */ 203 #define EXFLASH_LOCK_AREA_NONE 0 /**< Offset NONE */ 204 #define EXFLASH_LOCK_AREA_UPPER_1_8 1 /**< Offset 0x070000 - 0x07FFFF */ 205 #define EXFLASH_LOCK_AREA_UPPER_1_4 2 /**< Offset 0x060000 - 0x07FFFF */ 206 #define EXFLASH_LOCK_AREA_UPPER_1_2 3 /**< Offset 0x040000 - 0x07FFFF */ 207 #define EXFLASH_LOCK_AREA_LOWER_1_8 9 /**< Offset 0x000000 - 0x00FFFF */ 208 #define EXFLASH_LOCK_AREA_LOWER_1_4 10 /**< Offset 0x000000 - 0x01FFFF */ 209 #define EXFLASH_LOCK_AREA_LOWER_1_2 11 /**< Offset 0x000000 - 0x03FFFF */ 210 #define EXFLASH_LOCK_AREA_ALL 12 /**< Offset 0x000000 - 0x07FFFF */ 211 #define EXFLASH_LOCK_AREA_TOP_4K 17 /**< Offset 0x07F000 - 0x07FFFF */ 212 #define EXFLASH_LOCK_AREA_TOP_8K 18 /**< Offset 0x07E000 - 0x07FFFF */ 213 #define EXFLASH_LOCK_AREA_TOP_16K 19 /**< Offset 0x07C000 - 0x07FFFF */ 214 #define EXFLASH_LOCK_AREA_TOP_32K 20 /**< Offset 0x078000 - 0x07FFFF */ 215 #define EXFLASH_LOCK_AREA_BOTTOM_4K 25 /**< Offset 0x000000 - 0x000FFF */ 216 #define EXFLASH_LOCK_AREA_BOTTOM_8K 26 /**< Offset 0x000000 - 0x001FFF */ 217 #define EXFLASH_LOCK_AREA_BOTTOM_16K 27 /**< Offset 0x000000 - 0x003FFF */ 218 #define EXFLASH_LOCK_AREA_BOTTOM_32K 28 /**< Offset 0x000000 - 0x007FFF */ 219 #define EXFLASH_LOCK_AREA_LOWER_7_8 33 /**< Offset 0x070000 - 0x07FFFF */ 220 #define EXFLASH_LOCK_AREA_LOWER_3_4 34 /**< Offset 0x060000 - 0x07FFFF */ 221 #define EXFLASH_LOCK_AREA_UPPER_7_8 41 /**< Offset 0x000000 - 0x00FFFF */ 222 #define EXFLASH_LOCK_AREA_UPPER_3_4 42 /**< Offset 0x000000 - 0x01FFFF */ 223 #define EXFLASH_LOCK_AREA_LOWER_127_128 49 /**< Offset 0x000000 - 0x07EFFF */ 224 #define EXFLASH_LOCK_AREA_LOWER_63_64 50 /**< Offset 0x000000 - 0x07DFFF */ 225 #define EXFLASH_LOCK_AREA_LOWER_31_32 51 /**< Offset 0x000000 - 0x07BFFF */ 226 #define EXFLASH_LOCK_AREA_LOWER_15_16 52 /**< Offset 0x000000 - 0x077FFF */ 227 #define EXFLASH_LOCK_AREA_UPPER_127_128 57 /**< Offset 0x001000 - 0x07FFFF */ 228 #define EXFLASH_LOCK_AREA_UPPER_63_64 58 /**< Offset 0x002000 - 0x07FFFF */ 229 #define EXFLASH_LOCK_AREA_UPPER_31_32 59 /**< Offset 0x004000 - 0x07FFFF */ 230 #define EXFLASH_LOCK_AREA_UPPER_15_16 60 /**< Offset 0x008000 - 0x07FFFF */ 231 /** @} */ 232 233 /** @defgroup EXFLASH_RETRY_DEFINITION EXFLASH Repeat Times definition 234 * @{ 235 */ 236 #define HAL_EXFLASH_RETRY_DEFAULT_VALUE ((uint32_t)400000) /**< 400000 times */ 237 /** @} */ 238 239 /** @} */ 240 241 /* Exported macro ------------------------------------------------------------*/ 242 /** @defgroup EXFLASH_EXPORTED_MACROS EXFLASH Exported Macros 243 * @{ 244 */ 245 246 /** @brief Reset exFlash handle states. 247 * @param __HANDLE__ exFlash handle. 248 * @retval None 249 */ 250 #define __HAL_EXFLASH_RESET_HANDLE_STATE(__HANDLE__) ((__HANDLE__)->state = HAL_EXFLASH_STATE_RESET) 251 252 /** @brief Enable the specified exFlash power. 253 * @retval None 254 */ 255 #define __HAL_EXFLASH_POWER_ON() ll_xqspi_enable_exflash_power() 256 257 /** @brief Disable the specified exFlash power. 258 * @retval None 259 */ 260 #define __HAL_EXFLASH_POWER_OFF() ll_xqspi_disable_exflash_power() 261 262 /** @} */ 263 264 /* Private macros ------------------------------------------------------------*/ 265 /** @defgroup EXFLASH_PRIVATE_MACRO EXFLASH Private Macros 266 * @{ 267 */ 268 269 /** 270 * @brief Check if exFlash erase type is valid. 271 * @param __TYPE__ exFlash erase type. 272 * @retval SET (__TYPE__ is valid) or RESET (__TYPE__ is invalid) 273 */ 274 #define IS_EXFLASH_ERASE_TYPE(__TYPE__) (((__TYPE__) == EXFLASH_ERASE_SECTOR) || \ 275 ((__TYPE__) == EXFLASH_ERASE_CHIP)) 276 277 /** 278 * @brief Check if exFlash lock area type is valid. 279 * @param __AREA__ exFlash lock area type. 280 * @retval SET (__AREA__ is valid) or RESET (__AREA__ is invalid) 281 */ 282 #define IS_EXFLASH_LOCK_AREA(__AREA__) (((__AREA__) == EXFLASH_LOCK_AREA_NONE) || \ 283 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_1_8) || \ 284 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_1_4) || \ 285 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_1_2) || \ 286 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_1_8) || \ 287 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_1_4) || \ 288 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_1_2) || \ 289 ((__AREA__) == EXFLASH_LOCK_AREA_ALL) || \ 290 ((__AREA__) == EXFLASH_LOCK_AREA_TOP_4K) || \ 291 ((__AREA__) == EXFLASH_LOCK_AREA_TOP_8K) || \ 292 ((__AREA__) == EXFLASH_LOCK_AREA_TOP_16K) || \ 293 ((__AREA__) == EXFLASH_LOCK_AREA_TOP_32K) || \ 294 ((__AREA__) == EXFLASH_LOCK_AREA_BOTTOM_4K) || \ 295 ((__AREA__) == EXFLASH_LOCK_AREA_BOTTOM_8K) || \ 296 ((__AREA__) == EXFLASH_LOCK_AREA_BOTTOM_16K) || \ 297 ((__AREA__) == EXFLASH_LOCK_AREA_BOTTOM_32K) || \ 298 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_7_8) || \ 299 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_3_4) || \ 300 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_7_8) || \ 301 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_3_4) || \ 302 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_127_128) || \ 303 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_63_64) || \ 304 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_31_32) || \ 305 ((__AREA__) == EXFLASH_LOCK_AREA_LOWER_15_16) || \ 306 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_127_128) || \ 307 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_63_64) || \ 308 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_31_32) || \ 309 ((__AREA__) == EXFLASH_LOCK_AREA_UPPER_15_16)) 310 /** @} */ 311 312 /** @} */ 313 314 315 /* Exported functions --------------------------------------------------------*/ 316 /** @addtogroup HAL_EXFLASH_DRIVER_FUNCTIONS Functions 317 * @{ 318 */ 319 320 /** @defgroup EXFLASH_Exported_Functions_Group1 Initialization and de-initialization functions 321 * @brief Initialization and de-initialization functions 322 * 323 @verbatim 324 =============================================================================== 325 ##### Initialization and de-initialization functions ##### 326 =============================================================================== 327 [..] This subsection provides a set of functions allowing to initialize and 328 de-initialize the exFlash peripheral. 329 330 (+) User must implement hal_exflash_msp_init() function in which he configures 331 all related peripherals resources (GPIO, DMA, IT and NVIC ). 332 333 (+) Call the function hal_exflash_deinit() to restore the default configuration 334 of the selected exFlash peripheral. 335 336 @endverbatim 337 * @{ 338 */ 339 340 /** 341 **************************************************************************************** 342 * @brief Initialize the exFlash according to the specified parameters 343 * in the exflash_init_t and initialize the associated handle. 344 * 345 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 346 * information for the specified exFlash module. 347 * 348 * @retval ::HAL_OK: Operation is OK. 349 * @retval ::HAL_ERROR: Parameter error or operation not supported. 350 * @retval ::HAL_BUSY: Driver is busy. 351 * @retval ::HAL_TIMEOUT: Timeout occurred. 352 **************************************************************************************** 353 */ 354 hal_status_t hal_exflash_init(exflash_handle_t *p_exflash); 355 356 /** 357 **************************************************************************************** 358 * @brief De-initialize the exFlash peripheral. 359 * 360 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 361 * information for the specified exFlash module. 362 * 363 * @retval ::HAL_OK: Operation is OK. 364 * @retval ::HAL_ERROR: Parameter error or operation not supported. 365 * @retval ::HAL_BUSY: Driver is busy. 366 * @retval ::HAL_TIMEOUT: Timeout occurred. 367 **************************************************************************************** 368 */ 369 hal_status_t hal_exflash_deinit(exflash_handle_t *p_exflash); 370 371 /** 372 **************************************************************************************** 373 * @brief Initialize the exFlash MSP. 374 * 375 * @note This function should not be modified. When the callback is needed, 376 * the hal_exflash_msp_deinit can be implemented in the user file. 377 * 378 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 379 * information for the specified exFlash module. 380 **************************************************************************************** 381 */ 382 void hal_exflash_msp_init(exflash_handle_t *p_exflash); 383 384 /** 385 **************************************************************************************** 386 * @brief De-initialize the exFlash MSP. 387 * 388 * @note This function should not be modified. When the callback is needed, 389 * the hal_exflash_msp_deinit can be implemented in the user file. 390 * 391 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 392 * information for the specified exFlash module. 393 **************************************************************************************** 394 */ 395 void hal_exflash_msp_deinit(exflash_handle_t *p_exflash); 396 397 /** @} */ 398 399 /** @defgroup EXFLASH_EXPORTED_FUNCTIONS_GROUP2 IO operation functions 400 * @brief Data transfers functions 401 * 402 @verbatim 403 ============================================================================== 404 ##### IO operation functions ##### 405 =============================================================================== 406 [..] 407 This subsection provides a set of functions allowing to manage the exFlash 408 data transfers. 409 410 [..] The exFlash supports XIP and QSPI mode: 411 412 (#) There are only one modes of transfer: 413 (++) Blocking mode: The communication is performed in polling mode. 414 The HAL status of all data processing is returned by the same function 415 after finishing transfer. 416 417 @endverbatim 418 * @{ 419 */ 420 /** 421 **************************************************************************************** 422 * @brief During Flash erase/write operation, Disable external interrupts with a priority less than 423 * or equal to base_priority in the system. 424 * 425 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 426 * information for the specified exFlash module. 427 * @param[in] base_priority: Base Priority value to set. 428 * 429 * @retval ::HAL_OK: Operation is OK. 430 * @retval ::HAL_ERROR: Parameter error or operation not supported. 431 * @retval ::HAL_BUSY: Driver is busy. 432 * @retval ::HAL_TIMEOUT: Timeout occurred. 433 **************************************************************************************** 434 */ 435 hal_status_t hal_exflash_operation_protection(exflash_handle_t *p_exflash, uint32_t base_priority); 436 437 /** 438 **************************************************************************************** 439 * @brief Write an amount of data with specified instruction and address to flash. 440 * 441 * @note This function is used only in Indirect Write Mode. In secure mode, address alignment requires 4 bytes. 442 * 443 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 444 * information for the specified exFlash module. 445 * @param[in] addr: Address to write data in flash, start at @ref EXFLASH_START_ADDR. 446 * @param[in] p_data: Pointer to data buffer 447 * @param[in] size: Size of buffer bytes 448 * 449 * @retval ::HAL_OK: Operation is OK. 450 * @retval ::HAL_ERROR: Parameter error or operation not supported. 451 * @retval ::HAL_BUSY: Driver is busy. 452 * @retval ::HAL_TIMEOUT: Timeout occurred. 453 **************************************************************************************** 454 */ 455 hal_status_t hal_exflash_write(exflash_handle_t *p_exflash, uint32_t addr, uint8_t *p_data, uint32_t size); 456 457 /** 458 **************************************************************************************** 459 * @brief Read an amount of data with specified instruction and address from flash. 460 * 461 * @note This function is used only in non-encrypted Indirect Read Mode. 462 * 463 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 464 * information for the specified exFlash module. 465 * @param[in] addr: Address to read data in flash, start at @ref EXFLASH_START_ADDR. 466 * @param[out] p_data: Pointer to data buffer 467 * @param[in] size: Size of buffer bytes 468 * 469 * @retval ::HAL_OK: Operation is OK. 470 * @retval ::HAL_ERROR: Parameter error or operation not supported. 471 * @retval ::HAL_BUSY: Driver is busy. 472 * @retval ::HAL_TIMEOUT: Timeout occurred. 473 **************************************************************************************** 474 */ 475 hal_status_t hal_exflash_read(exflash_handle_t *p_exflash, uint32_t addr, uint8_t *p_data, uint32_t size); 476 477 #if defined(GR5515_D) 478 479 /** 480 **************************************************************************************** 481 * @brief [High speed]Read an amount of data with specified instruction and address from flash. 482 * 483 * @note This function is used only in non-encrypted Indirect Read Mode. 484 * Data content needs to be processed in 4-byte reverse order. 485 * And all parameters need to be aligned with 4 bytes. 486 * 487 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 488 * information for the specified exFlash module. 489 * @param[in] addr: Address to read data in flash, start at @ref EXFLASH_START_ADDR.(Aligned with 4 bytes) 490 * @param[out] p_data: Pointer to data buffer.(Pointer aligned with 4 bytes) 491 * @param[in] size: Size of buffer bytes.number of bytes to read.(A multiple of 4) 492 * 493 * @retval ::HAL_OK: Operation is OK. 494 * @retval ::HAL_ERROR: Parameter error or operation not supported. 495 * @retval ::HAL_BUSY: Driver is busy. 496 * @retval ::HAL_TIMEOUT: Timeout occurred. 497 **************************************************************************************** 498 */ 499 hal_status_t hal_exflash_read_align_word(exflash_handle_t *p_exflash, uint32_t addr, uint8_t *p_data, uint32_t size); 500 501 #endif 502 503 /** 504 **************************************************************************************** 505 * @brief Erase flash region. 506 * 507 * @note All sectors that have address in range of [addr, addr+len] will be erased. If addr is not sector aligned, 508 * preceding data on the sector that addr belongs to will also be erased. If (addr + size) is not sector 509 * aligned, the whole sector will also be erased. If erase_type is @ref EXFLASH_ERASE_CHIP , all data in flash 510 * will be erased ignored addr and size. 511 * 512 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 513 * information for the specified exFlash module. 514 * @param[in] erase_type: Erase flash with page/sector/chip. 515 * @arg @ref EXFLASH_ERASE_SECTOR 516 * @arg @ref EXFLASH_ERASE_CHIP 517 * @param[in] addr: Address to erased data in flash, start at @ref EXFLASH_START_ADDR. 518 * @param[in] size: Size of erased bytes. 519 * 520 * @retval ::HAL_OK: Operation is OK. 521 * @retval ::HAL_ERROR: Parameter error or operation not supported. 522 * @retval ::HAL_BUSY: Driver is busy. 523 * @retval ::HAL_TIMEOUT: Timeout occurred. 524 **************************************************************************************** 525 */ 526 hal_status_t hal_exflash_erase(exflash_handle_t *p_exflash, uint32_t erase_type, uint32_t addr, uint32_t size); 527 528 /** 529 **************************************************************************************** 530 * @brief Suspend flash pragram/erase. 531 * 532 * @note The Suspend instruction interrupts a Page Program, Sector Erase, or Block Erase operation to allow access 533 * to the memory array. After the program or erase operation has entered the suspended state, the memory 534 * array can be read except for the page being programmed or the sector or block being erased. This function 535 * is only used in XIP mode. 536 * 537 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 538 * information for the specified exFlash module. 539 * 540 * @retval ::HAL_OK: Operation is OK. 541 * @retval ::HAL_ERROR: Parameter error or operation not supported. 542 * @retval ::HAL_BUSY: Driver is busy. 543 * @retval ::HAL_TIMEOUT: Timeout occurred. 544 **************************************************************************************** 545 */ 546 hal_status_t hal_exflash_suspend(exflash_handle_t *p_exflash); 547 548 /** 549 **************************************************************************************** 550 * @brief Resume flash pragram/erase. 551 * 552 * @note The Resume instruction resumes a suspended Page Program, Sector Erase, or Block Erase operation. 553 * Before issuing the Resume instruction to restart a suspended erase operation, make sure that there is no 554 * Page Program operation in progress. This function is only used in XIP mode. 555 * 556 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 557 * information for the specified exFlash module. 558 * 559 * @retval ::HAL_OK: Operation is OK. 560 * @retval ::HAL_ERROR: Parameter error or operation not supported. 561 * @retval ::HAL_BUSY: Driver is busy. 562 * @retval ::HAL_TIMEOUT: Timeout occurred. 563 **************************************************************************************** 564 */ 565 hal_status_t hal_exflash_resume(exflash_handle_t *p_exflash); 566 567 /** 568 **************************************************************************************** 569 * @brief Lock area of flash to be software protected against Write and Erase operation. 570 * 571 * @note Locked area only to be read. 572 * 573 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 574 * information for the specified exFlash module. 575 * @param[in] lock_type Area need to lock 576 * 577 * @retval ::HAL_OK: Operation is OK. 578 * @retval ::HAL_ERROR: Parameter error or operation not supported. 579 * @retval ::HAL_BUSY: Driver is busy. 580 * @retval ::HAL_TIMEOUT: Timeout occurred. 581 **************************************************************************************** 582 */ 583 hal_status_t hal_exflash_lock(exflash_handle_t *p_exflash, uint32_t lock_type); 584 585 /** 586 **************************************************************************************** 587 * @brief Unlock write/erase protected in flash. 588 * 589 * @note This function will unlock all chip. 590 * 591 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 592 * information for the specified exFlash module. 593 * 594 * @retval ::HAL_OK: Operation is OK. 595 * @retval ::HAL_ERROR: Parameter error or operation not supported. 596 * @retval ::HAL_BUSY: Driver is busy. 597 * @retval ::HAL_TIMEOUT: Timeout occurred. 598 **************************************************************************************** 599 */ 600 hal_status_t hal_exflash_unlock(exflash_handle_t *p_exflash); 601 602 /** 603 **************************************************************************************** 604 * @brief the exFlash will go to the Deep Power-Down Mode. 605 * 606 * @note This function is used only in Indirect Write Mode. 607 * 608 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 609 * information for the specified exFlash module. 610 * 611 * @retval ::HAL_OK: Operation is OK. 612 * @retval ::HAL_ERROR: Parameter error or operation not supported. 613 * @retval ::HAL_BUSY: Driver is busy. 614 * @retval ::HAL_TIMEOUT: Timeout occurred. 615 **************************************************************************************** 616 */ 617 hal_status_t hal_exflash_deepsleep(exflash_handle_t *p_exflash); 618 619 /** 620 **************************************************************************************** 621 * @brief exFlash will be released from Deep Power-Down Mode. 622 * 623 * @note This function is used only in Indirect Write Mode. 624 * 625 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 626 * information for the specified exFlash module. 627 * 628 * @retval ::HAL_OK: Operation is OK. 629 * @retval ::HAL_ERROR: Parameter error or operation not supported. 630 * @retval ::HAL_BUSY: Driver is busy. 631 * @retval ::HAL_TIMEOUT: Timeout occurred. 632 **************************************************************************************** 633 */ 634 hal_status_t hal_exflash_wakeup(exflash_handle_t *p_exflash); 635 636 /** 637 **************************************************************************************** 638 * @brief Reset exFlash. exFlash will return to its default power-on state and lose all 639 * the current volatile settings. 640 * 641 * @note This function is used only in Indirect Write Mode. 642 * 643 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 644 * information for the specified exFlash module. 645 * 646 * @retval ::HAL_OK: Operation is OK. 647 * @retval ::HAL_ERROR: Parameter error or operation not supported. 648 * @retval ::HAL_BUSY: Driver is busy. 649 * @retval ::HAL_TIMEOUT: Timeout occurred. 650 **************************************************************************************** 651 */ 652 hal_status_t hal_exflash_reset(exflash_handle_t *p_exflash); 653 654 #if defined(GR5515_D) && defined(ENCRYPT_ENABLE) 655 656 /** 657 **************************************************************************************** 658 * @brief Specify the offset address and encrypted KEY address read by XIP. 659 * 660 * @param[in] p_exflash Pointer to an exFlash handle which contains the configuration 661 * information for the specified exFlash module. 662 * @param[in] read_offset The value must be 0x0 and EXFLASH_ALIAS_OFFSET. 663 * @param[in] key_addr The value must be FWCODEKEY_BASE_ADDR(0xA00170E0) and AESKEY_BASE_ADDR(0xA0017060). 664 **************************************************************************************** 665 */ 666 hal_status_t hal_exflash_encrypt_mode(exflash_handle_t *p_exflash, uint32_t read_offset, uint32_t key_addr); 667 668 /** 669 **************************************************************************************** 670 * @brief Expand write an amount of data with specified instruction and address to flash. 671 * 672 * @note This function is used only in Indirect Write Mode. In secure mode, address alignment requires 4 bytes. 673 * Can specify write data to data area or code area. Need to call first hal_exflash_encrypt_mode 674 * 675 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 676 * information for the specified exFlash module. 677 * @param[in] addr: Address to write data in flash, start at @ref EXFLASH_START_ADDR. 678 * @param[in] p_data: Pointer to data buffer 679 * @param[in] size: Size of buffer bytes 680 * 681 * @retval ::HAL_OK: Operation is OK. 682 * @retval ::HAL_ERROR: Parameter error or operation not supported. 683 * @retval ::HAL_BUSY: Driver is busy. 684 * @retval ::HAL_TIMEOUT: Timeout occurred. 685 **************************************************************************************** 686 */ 687 hal_status_t hal_exflash_write_expand(exflash_handle_t *p_exflash, uint32_t addr, uint8_t *p_data, uint32_t size); 688 689 /** 690 **************************************************************************************** 691 * @brief Expand read an amount of data with specified instruction and address from flash. 692 * 693 * @note This function is used only in non-encrypted Indirect Read Mode. 694 * Can specify read data from data area or code area. Need to call first hal_exflash_encrypt_mode 695 * 696 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 697 * information for the specified exFlash module. 698 * @param[in] addr: Address to read data in flash, start at @ref EXFLASH_START_ADDR. 699 * @param[out] p_data: Pointer to data buffer 700 * @param[in] size: Size of buffer bytes 701 * 702 * @retval ::HAL_OK: Operation is OK. 703 * @retval ::HAL_ERROR: Parameter error or operation not supported. 704 * @retval ::HAL_BUSY: Driver is busy. 705 * @retval ::HAL_TIMEOUT: Timeout occurred. 706 **************************************************************************************** 707 */ 708 hal_status_t hal_exflash_read_expand(exflash_handle_t *p_exflash, uint32_t addr, uint8_t *p_data, uint32_t size); 709 710 #endif 711 712 /** @} */ 713 714 /** @defgroup EXFLASH_Exported_Functions_Group3 Peripheral State and Errors functions 715 * @brief exFlash control functions 716 * 717 @verbatim 718 =============================================================================== 719 ##### Peripheral State and Errors functions ##### 720 =============================================================================== 721 [..] 722 This subsection provides a set of functions allowing to control the exFlash. 723 (+) hal_exflash_get_state()API can be helpful to check in run-time the state of the exFlash peripheral. 724 (+) hal_exflash_get_error() check in run-time Errors occurring during communication. 725 (+) hal_exflash_set_timeout() set the timeout during internal process. 726 @endverbatim 727 * @{ 728 */ 729 730 /** 731 **************************************************************************************** 732 * @brief Return the exFlash handle state. 733 * 734 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 735 * information for the specified exFlash module. 736 * 737 * @retval ::HAL_EXFLASH_STATE_RESET: Peripheral not initialized. 738 * @retval ::HAL_EXFLASH_STATE_READY: Peripheral initialized and ready for use. 739 * @retval ::HAL_EXFLASH_STATE_BUSY: Peripheral in indirect mode and busy. 740 * @retval ::HAL_EXFLASH_STATE_BUSY_WRITE: Peripheral in indirect mode with transmission ongoing. 741 * @retval ::HAL_EXFLASH_STATE_BUSY_READ: Peripheral in indirect mode with reception ongoing. 742 * @retval ::HAL_EXFLASH_STATE_BUSY_ERASE: Peripheral in indirect mode with erase ongoing. 743 * @retval ::HAL_EXFLASH_STATE_ERROR: Peripheral in error. 744 **************************************************************************************** 745 */ 746 hal_exflash_state_t hal_exflash_get_state(exflash_handle_t *p_exflash); 747 748 /** 749 **************************************************************************************** 750 * @brief Return the exFlash error code. 751 * 752 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration 753 * information for the specified exFlash module. 754 * 755 * @return exFlash error code in bitmap format 756 **************************************************************************************** 757 */ 758 uint32_t hal_exflash_get_error(exflash_handle_t *p_exflash); 759 760 /** 761 **************************************************************************************** 762 * @brief Set the exFlash internal process timeout value. 763 * 764 * @param[in] p_exflash Pointer to an exFlash handle which contains the configuration 765 * information for the specified exFlash module. 766 * @param[in] retry Internal process repeat times value. 767 **************************************************************************************** 768 */ 769 void hal_exflash_set_retry(exflash_handle_t *p_exflash, uint32_t retry); 770 771 772 /** 773 * @brief HAL exFlash operation function 774 */ 775 typedef hal_status_t (*exflash_operation_func)(exflash_handle_t *p_exflash); 776 777 /** 778 **************************************************************************************** 779 * @brief Call user XIP Flash operation functon. 780 * 781 * @param[in] p_exflash Pointer to an exFlash handle which contains the configuration 782 * information for the specified exFlash module. 783 * @param[in] exflash_operation_func HAL exFlash operation function. 784 **************************************************************************************** 785 */ 786 hal_status_t hal_exflash_operation(exflash_handle_t *p_exflash, exflash_operation_func p_func_exflash_operation); 787 /** @} */ 788 789 /** @} */ 790 791 #ifdef __cplusplus 792 } 793 #endif 794 795 #endif /* __GR55xx_HAL_EXFLASH_H__ */ 796 797 /** @} */ 798 799 /** @} */ 800 801 /** @} */ 802