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