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 * @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 */
96 } hal_eflash_security;
97
98 /** @} */
99
100 /** @} */
101
102 /** @addtogroup HAL_EXFLASH_STRUCTURES Structures
103 * @{
104 */
105
106 /** @defgroup EXFLASH_HANDLE EXFLASH handle
107 * @{
108 */
109
110 /**
111 * @brief exFlash handle Structure definition
112 */
113 typedef struct _exflash_handle
114 {
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
135 } exflash_handle_t;
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 */
156 } hal_exflash_callback_t;
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 */
356 hal_status_t hal_exflash_init(exflash_handle_t *p_exflash);
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 */
370 hal_status_t hal_exflash_deinit(exflash_handle_t *p_exflash);
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 */
382 void hal_exflash_msp_init(exflash_handle_t *p_exflash);
383
384 /**
385 ****************************************************************************************
386 * @brief De-initialize the exFlash MSP.
387 *
388 * @note This function should not be modified. When the callback is needed,
389 * the hal_exflash_msp_deinit can be implemented in the user file.
390 *
391 * @param[in] p_exflash: Pointer to an exFlash handle which contains the configuration information for the specified exFlash module.
392 ****************************************************************************************
393 */
394 void hal_exflash_msp_deinit(exflash_handle_t *p_exflash);
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 */
432 hal_status_t hal_exflash_operation_protection(exflash_handle_t *p_exflash, uint32_t base_priority);
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 */
534 hal_status_t hal_exflash_suspend(exflash_handle_t *p_exflash);
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 */
552 hal_status_t hal_exflash_resume(exflash_handle_t *p_exflash);
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 */
585 hal_status_t hal_exflash_unlock(exflash_handle_t *p_exflash);
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 */
601 hal_status_t hal_exflash_deepsleep(exflash_handle_t *p_exflash);
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 */
617 hal_status_t hal_exflash_wakeup(exflash_handle_t *p_exflash);
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 */
634 hal_status_t hal_exflash_reset(exflash_handle_t *p_exflash);
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 */
726 hal_exflash_state_t hal_exflash_get_state(exflash_handle_t *p_exflash);
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 */
737 uint32_t hal_exflash_get_error(exflash_handle_t *p_exflash);
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 */
753 typedef hal_status_t (*exflash_operation_func)(exflash_handle_t *p_exflash);
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 */
763 hal_status_t hal_exflash_operation(exflash_handle_t *p_exflash, exflash_operation_func p_func_exflash_operation);
764
765 /**
766 ****************************************************************************************
767 * @brief This function reads the status register of a flash.
768 *
769 * @note The status register is a 16-bit register that provides information about the flash operation status.
770 *
771 * @param[in] p_reg_status: Pointer of status register.
772 * @retval ::HAL_OK: Operation is OK.
773 * @retval ::HAL_ERROR: Parameter error or operation not supported.
774 * @retval ::HAL_BUSY: Driver is busy.
775 * @retval ::HAL_TIMEOUT: Timeout occurred.
776 ****************************************************************************************
777 */
778 hal_status_t hal_exflash_read_status_reg(uint16_t* p_reg_status);
779
780 /**
781 ****************************************************************************************
782 * @brief This function writes the status register of a flash.
783 *
784 * @note The status register is a 16-bit register that provides information about the flash operation status.
785 *
786 * @param reg_status: An integer value representing the content to be written to the flash status register.
787 *
788 * @retval ::HAL_OK: Operation is OK.
789 * @retval ::HAL_ERROR: Parameter error or operation not supported.
790 * @retval ::HAL_BUSY: Driver is busy.
791 * @retval ::HAL_TIMEOUT: Timeout occurred.
792 ****************************************************************************************
793 */
794 hal_status_t hal_exflash_write_status_reg(uint16_t reg_status);
795
796 /**
797 ****************************************************************************************
798 * @brief This function serves to read UID of flash
799 *
800 * @param[out] uid: store 16 Byte flash UID
801 *
802 * @retval ::HAL_OK: Operation is OK.
803 * @retval ::HAL_ERROR: Parameter error or operation not supported.
804 * @retval ::HAL_BUSY: Driver is busy.
805 * @retval ::HAL_TIMEOUT: Timeout occurred.
806 ****************************************************************************************
807 */
808 hal_status_t hal_exflash_read_uid(uint8_t *uid);
809 /** @} */
810
811 /** @} */
812
813 #ifdef __cplusplus
814 }
815 #endif
816
817 #endif /* __GR55xx_HAL_EXFLASH_H__ */
818
819 /** @} */
820
821 /** @} */
822
823 /** @} */
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.
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
Peripheral not initialized
Definition: gr55xx_hal_exflash.h:78
_exflash_handle::count
__IO uint32_t count
exFlash count for suspend and resume
Definition: gr55xx_hal_exflash.h:129
hal_exflash_read_uid
hal_status_t hal_exflash_read_uid(uint8_t *uid)
This function serves to read UID of flash.
HAL_EXFLASH_STATE_ERROR
@ HAL_EXFLASH_STATE_ERROR
Peripheral in 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.
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
Repeat times for the exFlash memory access.
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...
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.
_exflash_handle::security
__IO hal_eflash_security security
exFlash data security
Definition: gr55xx_hal_exflash.h:123
HAL_EXFLASH_STATE_BUSY_WRITE
@ HAL_EXFLASH_STATE_BUSY_WRITE
Peripheral in indirect mode with transmission ongoing.
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
Data will be encrypted and decrypted in write-read operations
Definition: gr55xx_hal_exflash.h:95
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: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
exFlash communication 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
exFlash 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
exFlash XQSPI Handle parameters
Definition: gr55xx_hal_exflash.h:115
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_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
exFlash firmware 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_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.
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
exFlash Error code
Definition: gr55xx_hal_exflash.h:131
_hal_exflash_callback::exflash_msp_deinit
void(* exflash_msp_deinit)(exflash_handle_t *p_exflash)
EXFLASH de-init MSP callback
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)
EXFLASH init MSP callback
Definition: gr55xx_hal_exflash.h:154
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: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
Peripheral in indirect mode and 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
Data will not be encrypted and decrypted in write-read operations
Definition: gr55xx_hal_exflash.h:94
_exflash_handle::flash_id
__IO uint32_t flash_id
exFlash 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
Peripheral in indirect mode with erase ongoing
Definition: gr55xx_hal_exflash.h:83
HAL_EXFLASH_STATE_SUSPEND_ERASE
@ HAL_EXFLASH_STATE_SUSPEND_ERASE
Peripheral in suspend mode from erase
Definition: gr55xx_hal_exflash.h:85