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