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