1 /* 2 * Copyright (c) 2013-2016, Freescale Semiconductor, Inc. 3 * Copyright 2016-2017 NXP 4 * All rights reserved. 5 * 6 * 7 * SPDX-License-Identifier: BSD-3-Clause 8 */ 9 10 #ifndef _FSL_FLASH_H_ 11 #define _FSL_FLASH_H_ 12 13 #if (defined(BL_TARGET_FLASH) || defined(BL_TARGET_ROM) || defined(BL_TARGET_RAM)) 14 #include <assert.h> 15 #include <string.h> 16 #include "fsl_device_registers.h" 17 #include "bootloader_common.h" 18 #else 19 #include "fsl_common.h" 20 #endif 21 22 /******************************************************************************* 23 * Definitions 24 ******************************************************************************/ 25 26 /*! 27 * @addtogroup flash_driver 28 * @{ 29 */ 30 31 /*! 32 * @name Flash version 33 * @{ 34 */ 35 /*! @brief Constructs the version number for drivers. */ 36 #if !defined(MAKE_VERSION) 37 #define MAKE_VERSION(major, minor, bugfix) (((major) << 16) | ((minor) << 8) | (bugfix)) 38 #endif 39 40 /*! @brief Flash driver version for SDK*/ 41 #define FSL_FLASH_DRIVER_VERSION (MAKE_VERSION(2, 4, 1)) /*!< Version 2.4.1. */ 42 43 /*! @brief Flash driver version for ROM*/ 44 enum _flash_driver_version_constants 45 { 46 kFLASH_DriverVersionName = 'F', /*!< Flash driver version name.*/ 47 kFLASH_DriverVersionMajor = 2, /*!< Major flash driver version.*/ 48 kFLASH_DriverVersionMinor = 4, /*!< Minor flash driver version.*/ 49 kFLASH_DriverVersionBugfix = 1 /*!< Bugfix for flash driver version.*/ 50 }; 51 /*@}*/ 52 53 /*! 54 * @name Flash configuration 55 * @{ 56 */ 57 /*! @brief Indicates whether to support FlexNVM in the Flash driver */ 58 #if !defined(FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT) 59 #define FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT 1 /*!< Enables the FlexNVM support by default. */ 60 #endif 61 62 /*! @brief Indicates whether the FlexNVM is enabled in the Flash driver */ 63 #define FLASH_SSD_IS_FLEXNVM_ENABLED (FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT && FSL_FEATURE_FLASH_HAS_FLEX_NVM) 64 65 /*! @brief Indicates whether to support Secondary flash in the Flash driver */ 66 #if !defined(FLASH_SSD_CONFIG_ENABLE_SECONDARY_FLASH_SUPPORT) 67 #define FLASH_SSD_CONFIG_ENABLE_SECONDARY_FLASH_SUPPORT 1 /*!< Enables the secondary flash support by default. */ 68 #endif 69 70 /*! @brief Indicates whether the secondary flash is supported in the Flash driver */ 71 #if defined(FSL_FEATURE_FLASH_HAS_MULTIPLE_FLASH) || defined(FSL_FEATURE_FLASH_PFLASH_1_START_ADDRESS) 72 #define FLASH_SSD_IS_SECONDARY_FLASH_ENABLED (FLASH_SSD_CONFIG_ENABLE_SECONDARY_FLASH_SUPPORT) 73 #else 74 #define FLASH_SSD_IS_SECONDARY_FLASH_ENABLED (0) 75 #endif 76 77 /*! @brief Flash driver location. */ 78 #if !defined(FLASH_DRIVER_IS_FLASH_RESIDENT) 79 #if (!defined(BL_TARGET_ROM) && !defined(BL_TARGET_RAM)) 80 #define FLASH_DRIVER_IS_FLASH_RESIDENT 1 /*!< Used for the flash resident application. */ 81 #else 82 #define FLASH_DRIVER_IS_FLASH_RESIDENT 0 /*!< Used for the non-flash resident application. */ 83 #endif 84 #endif 85 86 /*! @brief Flash Driver Export option */ 87 #if !defined(FLASH_DRIVER_IS_EXPORTED) 88 #if (defined(BL_TARGET_ROM) || defined(BL_TARGET_FLASH)) 89 #define FLASH_DRIVER_IS_EXPORTED 1 /*!< Used for the ROM bootloader. */ 90 #else 91 #define FLASH_DRIVER_IS_EXPORTED 0 /*!< Used for the MCUXpresso SDK application. */ 92 #endif 93 #endif 94 /*@}*/ 95 96 /*! 97 * @name Flash status 98 * @{ 99 */ 100 /*! @brief Flash driver status group. */ 101 #if defined(kStatusGroup_FlashDriver) 102 #define kStatusGroupGeneric kStatusGroup_Generic 103 #define kStatusGroupFlashDriver kStatusGroup_FlashDriver 104 #elif defined(kStatusGroup_FLASH) 105 #define kStatusGroupGeneric kStatusGroup_Generic 106 #define kStatusGroupFlashDriver kStatusGroup_FLASH 107 #else 108 #define kStatusGroupGeneric 0 109 #define kStatusGroupFlashDriver 1 110 #endif 111 112 /*! @brief Constructs a status code value from a group and a code number. */ 113 #if !defined(MAKE_STATUS) 114 #define MAKE_STATUS(group, code) ((((group)*100) + (code))) 115 #endif 116 117 /*! 118 * @brief Flash driver status codes. 119 */ 120 enum _flash_status 121 { 122 kStatus_FLASH_Success = MAKE_STATUS(kStatusGroupGeneric, 0), /*!< API is executed successfully*/ 123 kStatus_FLASH_InvalidArgument = MAKE_STATUS(kStatusGroupGeneric, 4), /*!< Invalid argument*/ 124 kStatus_FLASH_SizeError = MAKE_STATUS(kStatusGroupFlashDriver, 0), /*!< Error size*/ 125 kStatus_FLASH_AlignmentError = 126 MAKE_STATUS(kStatusGroupFlashDriver, 1), /*!< Parameter is not aligned with the specified baseline*/ 127 kStatus_FLASH_AddressError = MAKE_STATUS(kStatusGroupFlashDriver, 2), /*!< Address is out of range */ 128 kStatus_FLASH_AccessError = 129 MAKE_STATUS(kStatusGroupFlashDriver, 3), /*!< Invalid instruction codes and out-of bound addresses */ 130 kStatus_FLASH_ProtectionViolation = MAKE_STATUS( 131 kStatusGroupFlashDriver, 4), /*!< The program/erase operation is requested to execute on protected areas */ 132 kStatus_FLASH_CommandFailure = 133 MAKE_STATUS(kStatusGroupFlashDriver, 5), /*!< Run-time error during command execution. */ 134 kStatus_FLASH_UnknownProperty = MAKE_STATUS(kStatusGroupFlashDriver, 6), /*!< Unknown property.*/ 135 kStatus_FLASH_EraseKeyError = MAKE_STATUS(kStatusGroupFlashDriver, 7), /*!< API erase key is invalid.*/ 136 kStatus_FLASH_RegionExecuteOnly = 137 MAKE_STATUS(kStatusGroupFlashDriver, 8), /*!< The current region is execute-only.*/ 138 kStatus_FLASH_ExecuteInRamFunctionNotReady = 139 MAKE_STATUS(kStatusGroupFlashDriver, 9), /*!< Execute-in-RAM function is not available.*/ 140 kStatus_FLASH_PartitionStatusUpdateFailure = 141 MAKE_STATUS(kStatusGroupFlashDriver, 10), /*!< Failed to update partition status.*/ 142 kStatus_FLASH_SetFlexramAsEepromError = 143 MAKE_STATUS(kStatusGroupFlashDriver, 11), /*!< Failed to set FlexRAM as EEPROM.*/ 144 kStatus_FLASH_RecoverFlexramAsRamError = 145 MAKE_STATUS(kStatusGroupFlashDriver, 12), /*!< Failed to recover FlexRAM as RAM.*/ 146 kStatus_FLASH_SetFlexramAsRamError = MAKE_STATUS(kStatusGroupFlashDriver, 13), /*!< Failed to set FlexRAM as RAM.*/ 147 kStatus_FLASH_RecoverFlexramAsEepromError = 148 MAKE_STATUS(kStatusGroupFlashDriver, 14), /*!< Failed to recover FlexRAM as EEPROM.*/ 149 kStatus_FLASH_CommandNotSupported = MAKE_STATUS(kStatusGroupFlashDriver, 15), /*!< Flash API is not supported.*/ 150 kStatus_FLASH_SwapSystemNotInUninitialized = 151 MAKE_STATUS(kStatusGroupFlashDriver, 16), /*!< Swap system is not in an uninitialzed state.*/ 152 kStatus_FLASH_SwapIndicatorAddressError = 153 MAKE_STATUS(kStatusGroupFlashDriver, 17), /*!< The swap indicator address is invalid.*/ 154 kStatus_FLASH_ReadOnlyProperty = MAKE_STATUS(kStatusGroupFlashDriver, 18), /*!< The flash property is read-only.*/ 155 kStatus_FLASH_InvalidPropertyValue = 156 MAKE_STATUS(kStatusGroupFlashDriver, 19), /*!< The flash property value is out of range.*/ 157 kStatus_FLASH_InvalidSpeculationOption = 158 MAKE_STATUS(kStatusGroupFlashDriver, 20), /*!< The option of flash prefetch speculation is invalid.*/ 159 }; 160 /*@}*/ 161 162 /*! 163 * @name Flash API key 164 * @{ 165 */ 166 /*! @brief Constructs the four character code for the Flash driver API key. */ 167 #if !defined(FOUR_CHAR_CODE) 168 #define FOUR_CHAR_CODE(a, b, c, d) (((d) << 24) | ((c) << 16) | ((b) << 8) | ((a))) 169 #endif 170 171 /*! 172 * @brief Enumeration for Flash driver API keys. 173 * 174 * @note The resulting value is built with a byte order such that the string 175 * being readable in expected order when viewed in a hex editor, if the value 176 * is treated as a 32-bit little endian value. 177 */ 178 enum _flash_driver_api_keys 179 { 180 kFLASH_ApiEraseKey = FOUR_CHAR_CODE('k', 'f', 'e', 'k') /*!< Key value used to validate all flash erase APIs.*/ 181 }; 182 /*@}*/ 183 184 /*! 185 * @brief Enumeration for supported flash margin levels. 186 */ 187 typedef enum _flash_margin_value 188 { 189 kFLASH_MarginValueNormal, /*!< Use the 'normal' read level for 1s.*/ 190 kFLASH_MarginValueUser, /*!< Apply the 'User' margin to the normal read-1 level.*/ 191 kFLASH_MarginValueFactory, /*!< Apply the 'Factory' margin to the normal read-1 level.*/ 192 kFLASH_MarginValueInvalid /*!< Not real margin level, Used to determine the range of valid margin level. */ 193 } flash_margin_value_t; 194 195 /*! 196 * @brief Enumeration for the three possible flash security states. 197 */ 198 typedef enum _flash_security_state 199 { 200 kFLASH_SecurityStateNotSecure = 0xc33cc33cU, /*!< Flash is not secure.*/ 201 kFLASH_SecurityStateBackdoorEnabled = 0x5aa55aa5U, /*!< Flash backdoor is enabled.*/ 202 kFLASH_SecurityStateBackdoorDisabled = 0x5ac33ca5U /*!< Flash backdoor is disabled.*/ 203 } flash_security_state_t; 204 205 /*! 206 * @brief Enumeration for the three possible flash protection levels. 207 */ 208 typedef enum _flash_protection_state 209 { 210 kFLASH_ProtectionStateUnprotected, /*!< Flash region is not protected.*/ 211 kFLASH_ProtectionStateProtected, /*!< Flash region is protected.*/ 212 kFLASH_ProtectionStateMixed /*!< Flash is mixed with protected and unprotected region.*/ 213 } flash_protection_state_t; 214 215 /*! 216 * @brief Enumeration for the three possible flash execute access levels. 217 */ 218 typedef enum _flash_execute_only_access_state 219 { 220 kFLASH_AccessStateUnLimited, /*!< Flash region is unlimited.*/ 221 kFLASH_AccessStateExecuteOnly, /*!< Flash region is execute only.*/ 222 kFLASH_AccessStateMixed /*!< Flash is mixed with unlimited and execute only region.*/ 223 } flash_execute_only_access_state_t; 224 225 /*! 226 * @brief Enumeration for various flash properties. 227 */ 228 typedef enum _flash_property_tag 229 { 230 kFLASH_PropertyPflashSectorSize = 0x00U, /*!< Pflash sector size property.*/ 231 kFLASH_PropertyPflashTotalSize = 0x01U, /*!< Pflash total size property.*/ 232 kFLASH_PropertyPflashBlockSize = 0x02U, /*!< Pflash block size property.*/ 233 kFLASH_PropertyPflashBlockCount = 0x03U, /*!< Pflash block count property.*/ 234 kFLASH_PropertyPflashBlockBaseAddr = 0x04U, /*!< Pflash block base address property.*/ 235 kFLASH_PropertyPflashFacSupport = 0x05U, /*!< Pflash fac support property.*/ 236 kFLASH_PropertyPflashAccessSegmentSize = 0x06U, /*!< Pflash access segment size property.*/ 237 kFLASH_PropertyPflashAccessSegmentCount = 0x07U, /*!< Pflash access segment count property.*/ 238 kFLASH_PropertyFlexRamBlockBaseAddr = 0x08U, /*!< FlexRam block base address property.*/ 239 kFLASH_PropertyFlexRamTotalSize = 0x09U, /*!< FlexRam total size property.*/ 240 kFLASH_PropertyDflashSectorSize = 0x10U, /*!< Dflash sector size property.*/ 241 kFLASH_PropertyDflashTotalSize = 0x11U, /*!< Dflash total size property.*/ 242 kFLASH_PropertyDflashBlockSize = 0x12U, /*!< Dflash block size property.*/ 243 kFLASH_PropertyDflashBlockCount = 0x13U, /*!< Dflash block count property.*/ 244 kFLASH_PropertyDflashBlockBaseAddr = 0x14U, /*!< Dflash block base address property.*/ 245 kFLASH_PropertyEepromTotalSize = 0x15U, /*!< EEPROM total size property.*/ 246 kFLASH_PropertyFlashMemoryIndex = 0x20U /*!< Flash memory index property.*/ 247 } flash_property_tag_t; 248 249 /*! 250 * @brief Constants for execute-in-RAM flash function. 251 */ 252 enum _flash_execute_in_ram_function_constants 253 { 254 kFLASH_ExecuteInRamFunctionMaxSizeInWords = 16U, /*!< The maximum size of execute-in-RAM function.*/ 255 kFLASH_ExecuteInRamFunctionTotalNum = 2U /*!< Total number of execute-in-RAM functions.*/ 256 }; 257 258 /*! 259 * @brief Flash execute-in-RAM function information. 260 */ 261 typedef struct _flash_execute_in_ram_function_config 262 { 263 uint32_t activeFunctionCount; /*!< Number of available execute-in-RAM functions.*/ 264 uint32_t *flashRunCommand; /*!< Execute-in-RAM function: flash_run_command.*/ 265 uint32_t *flashCommonBitOperation; /*!< Execute-in-RAM function: flash_common_bit_operation.*/ 266 } flash_execute_in_ram_function_config_t; 267 268 /*! 269 * @brief Enumeration for the two possible options of flash read resource command. 270 */ 271 typedef enum _flash_read_resource_option 272 { 273 kFLASH_ResourceOptionFlashIfr = 274 0x00U, /*!< Select code for Program flash 0 IFR, Program flash swap 0 IFR, Data flash 0 IFR */ 275 kFLASH_ResourceOptionVersionId = 0x01U /*!< Select code for the version ID*/ 276 } flash_read_resource_option_t; 277 278 /*! 279 * @brief Enumeration for the range of special-purpose flash resource 280 */ 281 enum _flash_read_resource_range 282 { 283 #if (FSL_FEATURE_FLASH_IS_FTFE == 1) 284 kFLASH_ResourceRangePflashIfrSizeInBytes = 1024U, /*!< Pflash IFR size in byte.*/ 285 kFLASH_ResourceRangeVersionIdSizeInBytes = 8U, /*!< Version ID IFR size in byte.*/ 286 kFLASH_ResourceRangeVersionIdStart = 0x08U, /*!< Version ID IFR start address.*/ 287 kFLASH_ResourceRangeVersionIdEnd = 0x0FU, /*!< Version ID IFR end address.*/ 288 kFLASH_ResourceRangePflashSwapIfrStart = 0x40000U, /*!< Pflash swap IFR start address.*/ 289 kFLASH_ResourceRangePflashSwapIfrEnd = 290 (kFLASH_ResourceRangePflashSwapIfrStart + 0x3FFU), /*!< Pflash swap IFR end address.*/ 291 #else /* FSL_FEATURE_FLASH_IS_FTFL == 1 or FSL_FEATURE_FLASH_IS_FTFA = =1 */ 292 kFLASH_ResourceRangePflashIfrSizeInBytes = 256U, /*!< Pflash IFR size in byte.*/ 293 kFLASH_ResourceRangeVersionIdSizeInBytes = 8U, /*!< Version ID IFR size in byte.*/ 294 kFLASH_ResourceRangeVersionIdStart = 0x00U, /*!< Version ID IFR start address.*/ 295 kFLASH_ResourceRangeVersionIdEnd = 0x07U, /*!< Version ID IFR end address.*/ 296 #if 0x20000U == (FSL_FEATURE_FLASH_PFLASH_BLOCK_COUNT * FSL_FEATURE_FLASH_PFLASH_BLOCK_SIZE) 297 kFLASH_ResourceRangePflashSwapIfrStart = 0x8000U, /*!< Pflash swap IFR start address.*/ 298 #elif 0x40000U == (FSL_FEATURE_FLASH_PFLASH_BLOCK_COUNT * FSL_FEATURE_FLASH_PFLASH_BLOCK_SIZE) 299 kFLASH_ResourceRangePflashSwapIfrStart = 0x10000U, /*!< Pflash swap IFR start address.*/ 300 #elif 0x80000U == (FSL_FEATURE_FLASH_PFLASH_BLOCK_COUNT * FSL_FEATURE_FLASH_PFLASH_BLOCK_SIZE) 301 kFLASH_ResourceRangePflashSwapIfrStart = 0x20000U, /*!< Pflash swap IFR start address.*/ 302 #else 303 kFLASH_ResourceRangePflashSwapIfrStart = 0, 304 #endif 305 kFLASH_ResourceRangePflashSwapIfrEnd = 306 (kFLASH_ResourceRangePflashSwapIfrStart + 0xFFU), /*!< Pflash swap IFR end address.*/ 307 #endif 308 kFLASH_ResourceRangeDflashIfrStart = 0x800000U, /*!< Dflash IFR start address.*/ 309 kFLASH_ResourceRangeDflashIfrEnd = 0x8003FFU, /*!< Dflash IFR end address.*/ 310 }; 311 312 /*! 313 * @brief Enumeration for the index of read/program once record 314 */ 315 enum _k3_flash_read_once_index 316 { 317 kFLASH_RecordIndexSwapAddr = 0xA1U, /*!< Index of Swap indicator address.*/ 318 kFLASH_RecordIndexSwapEnable = 0xA2U, /*!< Index of Swap system enable.*/ 319 kFLASH_RecordIndexSwapDisable = 0xA3U, /*!< Index of Swap system disable.*/ 320 }; 321 322 /*! 323 * @brief Enumeration for the two possilbe options of set FlexRAM function command. 324 */ 325 typedef enum _flash_flexram_function_option 326 { 327 kFLASH_FlexramFunctionOptionAvailableAsRam = 0xFFU, /*!< An option used to make FlexRAM available as RAM */ 328 kFLASH_FlexramFunctionOptionAvailableForEeprom = 0x00U /*!< An option used to make FlexRAM available for EEPROM */ 329 } flash_flexram_function_option_t; 330 331 /*! 332 * @brief Enumeration for acceleration RAM property. 333 */ 334 enum _flash_acceleration_ram_property 335 { 336 kFLASH_AccelerationRamSize = 0x400U 337 }; 338 339 /*! 340 * @brief Enumeration for the possible options of Swap function 341 */ 342 typedef enum _flash_swap_function_option 343 { 344 kFLASH_SwapFunctionOptionEnable = 0x00U, /*!< An option used to enable the Swap function */ 345 kFLASH_SwapFunctionOptionDisable = 0x01U /*!< An option used to disable the Swap function */ 346 } flash_swap_function_option_t; 347 348 /*! 349 * @brief Enumeration for the possible options of Swap control commands 350 */ 351 typedef enum _flash_swap_control_option 352 { 353 kFLASH_SwapControlOptionIntializeSystem = 0x01U, /*!< An option used to initialize the Swap system */ 354 kFLASH_SwapControlOptionSetInUpdateState = 0x02U, /*!< An option used to set the Swap in an update state */ 355 kFLASH_SwapControlOptionSetInCompleteState = 0x04U, /*!< An option used to set the Swap in a complete state */ 356 kFLASH_SwapControlOptionReportStatus = 0x08U, /*!< An option used to report the Swap status */ 357 kFLASH_SwapControlOptionDisableSystem = 0x10U /*!< An option used to disable the Swap status */ 358 } flash_swap_control_option_t; 359 360 /*! 361 * @brief Enumeration for the possible flash Swap status. 362 */ 363 typedef enum _flash_swap_state 364 { 365 kFLASH_SwapStateUninitialized = 0x00U, /*!< Flash Swap system is in an uninitialized state.*/ 366 kFLASH_SwapStateReady = 0x01U, /*!< Flash Swap system is in a ready state.*/ 367 kFLASH_SwapStateUpdate = 0x02U, /*!< Flash Swap system is in an update state.*/ 368 kFLASH_SwapStateUpdateErased = 0x03U, /*!< Flash Swap system is in an updateErased state.*/ 369 kFLASH_SwapStateComplete = 0x04U, /*!< Flash Swap system is in a complete state.*/ 370 kFLASH_SwapStateDisabled = 0x05U /*!< Flash Swap system is in a disabled state.*/ 371 } flash_swap_state_t; 372 373 /*! 374 * @breif Enumeration for the possible flash Swap block status 375 */ 376 typedef enum _flash_swap_block_status 377 { 378 kFLASH_SwapBlockStatusLowerHalfProgramBlocksAtZero = 379 0x00U, /*!< Swap block status is that lower half program block at zero.*/ 380 kFLASH_SwapBlockStatusUpperHalfProgramBlocksAtZero = 381 0x01U, /*!< Swap block status is that upper half program block at zero.*/ 382 } flash_swap_block_status_t; 383 384 /*! 385 * @brief Flash Swap information 386 */ 387 typedef struct _flash_swap_state_config 388 { 389 flash_swap_state_t flashSwapState; /*!<The current Swap system status.*/ 390 flash_swap_block_status_t currentSwapBlockStatus; /*!< The current Swap block status.*/ 391 flash_swap_block_status_t nextSwapBlockStatus; /*!< The next Swap block status.*/ 392 } flash_swap_state_config_t; 393 394 /*! 395 * @brief Flash Swap IFR fields 396 */ 397 typedef struct _flash_swap_ifr_field_config 398 { 399 uint16_t swapIndicatorAddress; /*!< A Swap indicator address field.*/ 400 uint16_t swapEnableWord; /*!< A Swap enable word field.*/ 401 uint8_t reserved0[4]; /*!< A reserved field.*/ 402 #if (FSL_FEATURE_FLASH_IS_FTFE == 1) 403 uint8_t reserved1[2]; /*!< A reserved field.*/ 404 uint16_t swapDisableWord; /*!< A Swap disable word field.*/ 405 uint8_t reserved2[4]; /*!< A reserved field.*/ 406 #endif 407 } flash_swap_ifr_field_config_t; 408 409 /*! 410 * @brief Flash Swap IFR field data 411 */ 412 typedef union _flash_swap_ifr_field_data 413 { 414 uint32_t flashSwapIfrData[2]; /*!< A flash Swap IFR field data .*/ 415 flash_swap_ifr_field_config_t flashSwapIfrField; /*!< A flash Swap IFR field structure.*/ 416 } flash_swap_ifr_field_data_t; 417 418 /*! 419 * @brief PFlash protection status - low 32bit 420 */ 421 typedef union _pflash_protection_status_low 422 { 423 uint32_t protl32b; /*!< PROT[31:0] .*/ 424 struct 425 { 426 uint8_t protsl; /*!< PROTS[7:0] .*/ 427 uint8_t protsh; /*!< PROTS[15:8] .*/ 428 uint8_t reserved[2]; 429 } prots16b; 430 } pflash_protection_status_low_t; 431 432 /*! 433 * @brief PFlash protection status - full 434 */ 435 typedef struct _pflash_protection_status 436 { 437 pflash_protection_status_low_t valueLow32b; /*!< PROT[31:0] or PROTS[15:0].*/ 438 #if ((FSL_FEATURE_FLASH_IS_FTFA == 1) && (defined(FTFA_FPROTH0_PROT_MASK))) || \ 439 ((FSL_FEATURE_FLASH_IS_FTFE == 1) && (defined(FTFE_FPROTH0_PROT_MASK))) || \ 440 ((FSL_FEATURE_FLASH_IS_FTFL == 1) && (defined(FTFL_FPROTH0_PROT_MASK))) 441 struct 442 { 443 uint32_t proth32b; 444 } valueHigh32b; /*!< PROT[63:32].*/ 445 #endif 446 } pflash_protection_status_t; 447 448 /*! 449 * @brief Enumeration for the FlexRAM load during reset option. 450 */ 451 typedef enum _flash_partition_flexram_load_option 452 { 453 kFLASH_PartitionFlexramLoadOptionLoadedWithValidEepromData = 454 0x00U, /*!< FlexRAM is loaded with valid EEPROM data during reset sequence.*/ 455 kFLASH_PartitionFlexramLoadOptionNotLoaded = 0x01U /*!< FlexRAM is not loaded during reset sequence.*/ 456 } flash_partition_flexram_load_option_t; 457 458 /*! 459 * @brief Enumeration for the flash memory index. 460 */ 461 typedef enum _flash_memory_index 462 { 463 kFLASH_MemoryIndexPrimaryFlash = 0x00U, /*!< Current flash memory is primary flash.*/ 464 kFLASH_MemoryIndexSecondaryFlash = 0x01U, /*!< Current flash memory is secondary flash.*/ 465 } flash_memory_index_t; 466 467 /*! 468 * @brief Enumeration for the flash cache controller index. 469 */ 470 typedef enum _flash_cache_controller_index 471 { 472 kFLASH_CacheControllerIndexForCore0 = 0x00U, /*!< Current flash cache controller is for core 0.*/ 473 kFLASH_CacheControllerIndexForCore1 = 0x01U, /*!< Current flash cache controller is for core 1.*/ 474 } flash_cache_controller_index_t; 475 476 /*! 477 * @brief Enumeration for the two possible options of flash prefetch speculation. 478 */ 479 typedef enum _flash_prefetch_speculation_option 480 { 481 kFLASH_prefetchSpeculationOptionEnable = 0x00U, 482 kFLASH_prefetchSpeculationOptionDisable = 0x01U 483 } flash_prefetch_speculation_option_t; 484 485 /*! 486 * @brief Flash prefetch speculation status. 487 */ 488 typedef struct _flash_prefetch_speculation_status 489 { 490 flash_prefetch_speculation_option_t instructionOption; /*!< Instruction speculation.*/ 491 flash_prefetch_speculation_option_t dataOption; /*!< Data speculation.*/ 492 } flash_prefetch_speculation_status_t; 493 494 /*! 495 * @brief Flash cache clear process code. 496 */ 497 typedef enum _flash_cache_clear_process 498 { 499 kFLASH_CacheClearProcessPre = 0x00U, /*!< Pre flash cache clear process.*/ 500 kFLASH_CacheClearProcessPost = 0x01U, /*!< Post flash cache clear process.*/ 501 } flash_cache_clear_process_t; 502 503 /*! 504 * @brief Active flash protection information for the current operation. 505 */ 506 typedef struct _flash_protection_config 507 { 508 uint32_t regionBase; /*!< Base address of flash protection region.*/ 509 uint32_t regionSize; /*!< size of flash protection region.*/ 510 uint32_t regionCount; /*!< flash protection region count.*/ 511 } flash_protection_config_t; 512 513 /*! 514 * @brief Active flash Execute-Only access information for the current operation. 515 */ 516 typedef struct _flash_access_config 517 { 518 uint32_t SegmentBase; /*!< Base address of flash Execute-Only segment.*/ 519 uint32_t SegmentSize; /*!< size of flash Execute-Only segment.*/ 520 uint32_t SegmentCount; /*!< flash Execute-Only segment count.*/ 521 } flash_access_config_t; 522 523 /*! 524 * @brief Active flash information for the current operation. 525 */ 526 typedef struct _flash_operation_config 527 { 528 uint32_t convertedAddress; /*!< A converted address for the current flash type.*/ 529 uint32_t activeSectorSize; /*!< A sector size of the current flash type.*/ 530 uint32_t activeBlockSize; /*!< A block size of the current flash type.*/ 531 uint32_t blockWriteUnitSize; /*!< The write unit size.*/ 532 uint32_t sectorCmdAddressAligment; /*!< An erase sector command address alignment.*/ 533 uint32_t sectionCmdAddressAligment; /*!< A program/verify section command address alignment.*/ 534 uint32_t resourceCmdAddressAligment; /*!< A read resource command address alignment.*/ 535 uint32_t checkCmdAddressAligment; /*!< A program check command address alignment.*/ 536 } flash_operation_config_t; 537 538 /*! @brief Flash driver state information. 539 * 540 * An instance of this structure is allocated by the user of the flash driver and 541 * passed into each of the driver APIs. 542 */ 543 typedef struct _flash_config 544 { 545 uint32_t PFlashBlockBase; /*!< A base address of the first PFlash block */ 546 uint32_t PFlashTotalSize; /*!< The size of the combined PFlash block. */ 547 uint8_t PFlashBlockCount; /*!< A number of PFlash blocks. */ 548 uint8_t FlashMemoryIndex; /*!< 0 - primary flash; 1 - secondary flash*/ 549 uint8_t Reserved0[2]; /*!< Reserved field 0 */ 550 uint32_t PFlashSectorSize; /*!< The size in bytes of a sector of PFlash. */ 551 uint32_t Reserved1; /*!< Reserved field 1 */ 552 uint32_t PFlashAccessSegmentSize; /*!< A size in bytes of an access segment of PFlash. */ 553 uint32_t PFlashAccessSegmentCount; /*!< A number of PFlash access segments. */ 554 uint32_t *flashExecuteInRamFunctionInfo; /*!< An information structure of the flash execute-in-RAM function. */ 555 uint32_t FlexRAMBlockBase; /*!< For the FlexNVM device, this is the base address of the FlexRAM */ 556 /*!< For the non-FlexNVM device, this is the base address of the acceleration RAM memory */ 557 uint32_t FlexRAMTotalSize; /*!< For the FlexNVM device, this is the size of the FlexRAM */ 558 /*!< For the non-FlexNVM device, this is the size of the acceleration RAM memory */ 559 uint32_t 560 DFlashBlockBase; /*!< For the FlexNVM device, this is the base address of the D-Flash memory (FlexNVM memory) */ 561 /*!< For the non-FlexNVM device, this field is unused */ 562 uint32_t DFlashTotalSize; /*!< For the FlexNVM device, this is the total size of the FlexNVM memory; */ 563 /*!< For the non-FlexNVM device, this field is unused */ 564 uint32_t EEpromTotalSize; /*!< For the FlexNVM device, this is the size in bytes of the EEPROM area which was 565 partitioned from FlexRAM */ 566 /*!< For the non-FlexNVM device, this field is unused */ 567 } flash_config_t; 568 569 /******************************************************************************* 570 * API 571 ******************************************************************************/ 572 573 #if defined(__cplusplus) 574 extern "C" { 575 #endif 576 577 /*! 578 * @name Initialization 579 * @{ 580 */ 581 582 /*! 583 * @brief Initializes the global flash properties structure members. 584 * 585 * This function checks and initializes the Flash module for the other Flash APIs. 586 * 587 * @param config Pointer to the storage for the driver runtime state. 588 * 589 * @retval #kStatus_FLASH_Success API was executed successfully. 590 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 591 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 592 * @retval #kStatus_FLASH_PartitionStatusUpdateFailure Failed to update the partition status. 593 */ 594 status_t FLASH_Init(flash_config_t *config); 595 596 /*! 597 * @brief Prepares flash execute-in-RAM functions. 598 * 599 * @param config Pointer to the storage for the driver runtime state. 600 * 601 * @retval #kStatus_FLASH_Success API was executed successfully. 602 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 603 */ 604 #if FLASH_DRIVER_IS_FLASH_RESIDENT 605 status_t FLASH_PrepareExecuteInRamFunctions(flash_config_t *config); 606 #endif 607 608 /*@}*/ 609 610 /*! 611 * @name Erasing 612 * @{ 613 */ 614 615 /*! 616 * @brief Erases entire flash 617 * 618 * @param config Pointer to the storage for the driver runtime state. 619 * @param key A value used to validate all flash erase APIs. 620 * 621 * @retval #kStatus_FLASH_Success API was executed successfully. 622 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 623 * @retval #kStatus_FLASH_EraseKeyError API erase key is invalid. 624 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 625 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 626 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 627 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 628 * @retval #kStatus_FLASH_PartitionStatusUpdateFailure Failed to update the partition status. 629 */ 630 status_t FLASH_EraseAll(flash_config_t *config, uint32_t key); 631 632 /*! 633 * @brief Erases the flash sectors encompassed by parameters passed into function. 634 * 635 * This function erases the appropriate number of flash sectors based on the 636 * desired start address and length. 637 * 638 * @param config The pointer to the storage for the driver runtime state. 639 * @param start The start address of the desired flash memory to be erased. 640 * The start address does not need to be sector-aligned but must be word-aligned. 641 * @param lengthInBytes The length, given in bytes (not words or long-words) 642 * to be erased. Must be word-aligned. 643 * @param key The value used to validate all flash erase APIs. 644 * 645 * @retval #kStatus_FLASH_Success API was executed successfully. 646 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 647 * @retval #kStatus_FLASH_AlignmentError The parameter is not aligned with the specified baseline. 648 * @retval #kStatus_FLASH_AddressError The address is out of range. 649 * @retval #kStatus_FLASH_EraseKeyError The API erase key is invalid. 650 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 651 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 652 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 653 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 654 */ 655 status_t FLASH_Erase(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key); 656 657 /*! 658 * @brief Erases the entire flash, including protected sectors. 659 * 660 * @param config Pointer to the storage for the driver runtime state. 661 * @param key A value used to validate all flash erase APIs. 662 * 663 * @retval #kStatus_FLASH_Success API was executed successfully. 664 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 665 * @retval #kStatus_FLASH_EraseKeyError API erase key is invalid. 666 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 667 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 668 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 669 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 670 * @retval #kStatus_FLASH_PartitionStatusUpdateFailure Failed to update the partition status. 671 */ 672 #if defined(FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD) && FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD 673 status_t FLASH_EraseAllUnsecure(flash_config_t *config, uint32_t key); 674 #endif 675 676 /*! 677 * @brief Erases all program flash execute-only segments defined by the FXACC registers. 678 * 679 * @param config Pointer to the storage for the driver runtime state. 680 * @param key A value used to validate all flash erase APIs. 681 * 682 * @retval #kStatus_FLASH_Success API was executed successfully. 683 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 684 * @retval #kStatus_FLASH_EraseKeyError API erase key is invalid. 685 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 686 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 687 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 688 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 689 */ 690 status_t FLASH_EraseAllExecuteOnlySegments(flash_config_t *config, uint32_t key); 691 692 /*@}*/ 693 694 /*! 695 * @name Programming 696 * @{ 697 */ 698 699 /*! 700 * @brief Programs flash with data at locations passed in through parameters. 701 * 702 * This function programs the flash memory with the desired data for a given 703 * flash area as determined by the start address and the length. 704 * 705 * @param config A pointer to the storage for the driver runtime state. 706 * @param start The start address of the desired flash memory to be programmed. Must be 707 * word-aligned. 708 * @param src A pointer to the source buffer of data that is to be programmed 709 * into the flash. 710 * @param lengthInBytes The length, given in bytes (not words or long-words), 711 * to be programmed. Must be word-aligned. 712 * 713 * @retval #kStatus_FLASH_Success API was executed successfully. 714 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 715 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with the specified baseline. 716 * @retval #kStatus_FLASH_AddressError Address is out of range. 717 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 718 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 719 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 720 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 721 */ 722 status_t FLASH_Program(flash_config_t *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes); 723 724 /*! 725 * @brief Programs Program Once Field through parameters. 726 * 727 * This function programs the Program Once Field with the desired data for a given 728 * flash area as determined by the index and length. 729 * 730 * @param config A pointer to the storage for the driver runtime state. 731 * @param index The index indicating which area of the Program Once Field to be programmed. 732 * @param src A pointer to the source buffer of data that is to be programmed 733 * into the Program Once Field. 734 * @param lengthInBytes The length, given in bytes (not words or long-words), 735 * to be programmed. Must be word-aligned. 736 * 737 * @retval #kStatus_FLASH_Success API was executed successfully. 738 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 739 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 740 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 741 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 742 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 743 */ 744 status_t FLASH_ProgramOnce(flash_config_t *config, uint32_t index, uint32_t *src, uint32_t lengthInBytes); 745 746 /*! 747 * @brief Programs flash with data at locations passed in through parameters via the Program Section command. 748 * 749 * This function programs the flash memory with the desired data for a given 750 * flash area as determined by the start address and length. 751 * 752 * @param config A pointer to the storage for the driver runtime state. 753 * @param start The start address of the desired flash memory to be programmed. Must be 754 * word-aligned. 755 * @param src A pointer to the source buffer of data that is to be programmed 756 * into the flash. 757 * @param lengthInBytes The length, given in bytes (not words or long-words), 758 * to be programmed. Must be word-aligned. 759 * 760 * @retval #kStatus_FLASH_Success API was executed successfully. 761 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 762 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with specified baseline. 763 * @retval #kStatus_FLASH_AddressError Address is out of range. 764 * @retval #kStatus_FLASH_SetFlexramAsRamError Failed to set flexram as RAM. 765 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 766 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 767 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 768 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 769 * @retval #kStatus_FLASH_RecoverFlexramAsEepromError Failed to recover FlexRAM as EEPROM. 770 */ 771 #if defined(FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD) && FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD 772 status_t FLASH_ProgramSection(flash_config_t *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes); 773 #endif 774 775 /*! 776 * @brief Programs the EEPROM with data at locations passed in through parameters. 777 * 778 * This function programs the emulated EEPROM with the desired data for a given 779 * flash area as determined by the start address and length. 780 * 781 * @param config A pointer to the storage for the driver runtime state. 782 * @param start The start address of the desired flash memory to be programmed. Must be 783 * word-aligned. 784 * @param src A pointer to the source buffer of data that is to be programmed 785 * into the flash. 786 * @param lengthInBytes The length, given in bytes (not words or long-words), 787 * to be programmed. Must be word-aligned. 788 * 789 * @retval #kStatus_FLASH_Success API was executed successfully. 790 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 791 * @retval #kStatus_FLASH_AddressError Address is out of range. 792 * @retval #kStatus_FLASH_SetFlexramAsEepromError Failed to set flexram as eeprom. 793 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 794 * @retval #kStatus_FLASH_RecoverFlexramAsRamError Failed to recover the FlexRAM as RAM. 795 */ 796 #if FLASH_SSD_IS_FLEXNVM_ENABLED 797 status_t FLASH_EepromWrite(flash_config_t *config, uint32_t start, uint8_t *src, uint32_t lengthInBytes); 798 #endif 799 800 /*@}*/ 801 802 /*! 803 * @name Reading 804 * @{ 805 */ 806 807 /*! 808 * @brief Reads the resource with data at locations passed in through parameters. 809 * 810 * This function reads the flash memory with the desired location for a given 811 * flash area as determined by the start address and length. 812 * 813 * @param config A pointer to the storage for the driver runtime state. 814 * @param start The start address of the desired flash memory to be programmed. Must be 815 * word-aligned. 816 * @param dst A pointer to the destination buffer of data that is used to store 817 * data to be read. 818 * @param lengthInBytes The length, given in bytes (not words or long-words), 819 * to be read. Must be word-aligned. 820 * @param option The resource option which indicates which area should be read back. 821 * 822 * @retval #kStatus_FLASH_Success API was executed successfully. 823 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 824 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with the specified baseline. 825 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 826 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 827 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 828 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 829 */ 830 #if defined(FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD) && FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD 831 status_t FLASH_ReadResource( 832 flash_config_t *config, uint32_t start, uint32_t *dst, uint32_t lengthInBytes, flash_read_resource_option_t option); 833 #endif 834 835 /*! 836 * @brief Reads the Program Once Field through parameters. 837 * 838 * This function reads the read once feild with given index and length. 839 * 840 * @param config A pointer to the storage for the driver runtime state. 841 * @param index The index indicating the area of program once field to be read. 842 * @param dst A pointer to the destination buffer of data that is used to store 843 * data to be read. 844 * @param lengthInBytes The length, given in bytes (not words or long-words), 845 * to be programmed. Must be word-aligned. 846 * 847 * @retval #kStatus_FLASH_Success API was executed successfully. 848 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 849 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 850 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 851 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 852 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 853 */ 854 status_t FLASH_ReadOnce(flash_config_t *config, uint32_t index, uint32_t *dst, uint32_t lengthInBytes); 855 856 /*@}*/ 857 858 /*! 859 * @name Security 860 * @{ 861 */ 862 863 /*! 864 * @brief Returns the security state via the pointer passed into the function. 865 * 866 * This function retrieves the current flash security status, including the 867 * security enabling state and the backdoor key enabling state. 868 * 869 * @param config A pointer to storage for the driver runtime state. 870 * @param state A pointer to the value returned for the current security status code: 871 * 872 * @retval #kStatus_FLASH_Success API was executed successfully. 873 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 874 */ 875 status_t FLASH_GetSecurityState(flash_config_t *config, flash_security_state_t *state); 876 877 /*! 878 * @brief Allows users to bypass security with a backdoor key. 879 * 880 * If the MCU is in secured state, this function unsecures the MCU by 881 * comparing the provided backdoor key with ones in the flash configuration 882 * field. 883 * 884 * @param config A pointer to the storage for the driver runtime state. 885 * @param backdoorKey A pointer to the user buffer containing the backdoor key. 886 * 887 * @retval #kStatus_FLASH_Success API was executed successfully. 888 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 889 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 890 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 891 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 892 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 893 */ 894 status_t FLASH_SecurityBypass(flash_config_t *config, const uint8_t *backdoorKey); 895 896 /*@}*/ 897 898 /*! 899 * @name Verification 900 * @{ 901 */ 902 903 /*! 904 * @brief Verifies erasure of the entire flash at a specified margin level. 905 * 906 * This function checks whether the flash is erased to the 907 * specified read margin level. 908 * 909 * @param config A pointer to the storage for the driver runtime state. 910 * @param margin Read margin choice. 911 * 912 * @retval #kStatus_FLASH_Success API was executed successfully. 913 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 914 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 915 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 916 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 917 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 918 */ 919 status_t FLASH_VerifyEraseAll(flash_config_t *config, flash_margin_value_t margin); 920 921 /*! 922 * @brief Verifies an erasure of the desired flash area at a specified margin level. 923 * 924 * This function checks the appropriate number of flash sectors based on 925 * the desired start address and length to check whether the flash is erased 926 * to the specified read margin level. 927 * 928 * @param config A pointer to the storage for the driver runtime state. 929 * @param start The start address of the desired flash memory to be verified. 930 * The start address does not need to be sector-aligned but must be word-aligned. 931 * @param lengthInBytes The length, given in bytes (not words or long-words), 932 * to be verified. Must be word-aligned. 933 * @param margin Read margin choice. 934 * 935 * @retval #kStatus_FLASH_Success API was executed successfully. 936 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 937 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with specified baseline. 938 * @retval #kStatus_FLASH_AddressError Address is out of range. 939 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 940 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 941 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 942 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 943 */ 944 status_t FLASH_VerifyErase(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, flash_margin_value_t margin); 945 946 /*! 947 * @brief Verifies programming of the desired flash area at a specified margin level. 948 * 949 * This function verifies the data programed in the flash memory using the 950 * Flash Program Check Command and compares it to the expected data for a given 951 * flash area as determined by the start address and length. 952 * 953 * @param config A pointer to the storage for the driver runtime state. 954 * @param start The start address of the desired flash memory to be verified. Must be word-aligned. 955 * @param lengthInBytes The length, given in bytes (not words or long-words), 956 * to be verified. Must be word-aligned. 957 * @param expectedData A pointer to the expected data that is to be 958 * verified against. 959 * @param margin Read margin choice. 960 * @param failedAddress A pointer to the returned failing address. 961 * @param failedData A pointer to the returned failing data. Some derivatives do 962 * not include failed data as part of the FCCOBx registers. In this 963 * case, zeros are returned upon failure. 964 * 965 * @retval #kStatus_FLASH_Success API was executed successfully. 966 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 967 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with specified baseline. 968 * @retval #kStatus_FLASH_AddressError Address is out of range. 969 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 970 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 971 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 972 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 973 */ 974 status_t FLASH_VerifyProgram(flash_config_t *config, 975 uint32_t start, 976 uint32_t lengthInBytes, 977 const uint32_t *expectedData, 978 flash_margin_value_t margin, 979 uint32_t *failedAddress, 980 uint32_t *failedData); 981 982 /*! 983 * @brief Verifies whether the program flash execute-only segments have been erased to 984 * the specified read margin level. 985 * 986 * @param config A pointer to the storage for the driver runtime state. 987 * @param margin Read margin choice. 988 * 989 * @retval #kStatus_FLASH_Success API was executed successfully. 990 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 991 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 992 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 993 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 994 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 995 */ 996 status_t FLASH_VerifyEraseAllExecuteOnlySegments(flash_config_t *config, flash_margin_value_t margin); 997 998 /*@}*/ 999 1000 /*! 1001 * @name Protection 1002 * @{ 1003 */ 1004 1005 /*! 1006 * @brief Returns the protection state of the desired flash area via the pointer passed into the function. 1007 * 1008 * This function retrieves the current flash protect status for a given 1009 * flash area as determined by the start address and length. 1010 * 1011 * @param config A pointer to the storage for the driver runtime state. 1012 * @param start The start address of the desired flash memory to be checked. Must be word-aligned. 1013 * @param lengthInBytes The length, given in bytes (not words or long-words) 1014 * to be checked. Must be word-aligned. 1015 * @param protection_state A pointer to the value returned for the current 1016 * protection status code for the desired flash area. 1017 * 1018 * @retval #kStatus_FLASH_Success API was executed successfully. 1019 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1020 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with specified baseline. 1021 * @retval #kStatus_FLASH_AddressError The address is out of range. 1022 */ 1023 status_t FLASH_IsProtected(flash_config_t *config, 1024 uint32_t start, 1025 uint32_t lengthInBytes, 1026 flash_protection_state_t *protection_state); 1027 1028 /*! 1029 * @brief Returns the access state of the desired flash area via the pointer passed into the function. 1030 * 1031 * This function retrieves the current flash access status for a given 1032 * flash area as determined by the start address and length. 1033 * 1034 * @param config A pointer to the storage for the driver runtime state. 1035 * @param start The start address of the desired flash memory to be checked. Must be word-aligned. 1036 * @param lengthInBytes The length, given in bytes (not words or long-words), 1037 * to be checked. Must be word-aligned. 1038 * @param access_state A pointer to the value returned for the current 1039 * access status code for the desired flash area. 1040 * 1041 * @retval #kStatus_FLASH_Success API was executed successfully. 1042 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1043 * @retval #kStatus_FLASH_AlignmentError The parameter is not aligned to the specified baseline. 1044 * @retval #kStatus_FLASH_AddressError The address is out of range. 1045 */ 1046 status_t FLASH_IsExecuteOnly(flash_config_t *config, 1047 uint32_t start, 1048 uint32_t lengthInBytes, 1049 flash_execute_only_access_state_t *access_state); 1050 1051 /*@}*/ 1052 1053 /*! 1054 * @name Properties 1055 * @{ 1056 */ 1057 1058 /*! 1059 * @brief Returns the desired flash property. 1060 * 1061 * @param config A pointer to the storage for the driver runtime state. 1062 * @param whichProperty The desired property from the list of properties in 1063 * enum flash_property_tag_t 1064 * @param value A pointer to the value returned for the desired flash property. 1065 * 1066 * @retval #kStatus_FLASH_Success API was executed successfully. 1067 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1068 * @retval #kStatus_FLASH_UnknownProperty An unknown property tag. 1069 */ 1070 status_t FLASH_GetProperty(flash_config_t *config, flash_property_tag_t whichProperty, uint32_t *value); 1071 1072 /*! 1073 * @brief Sets the desired flash property. 1074 * 1075 * @param config A pointer to the storage for the driver runtime state. 1076 * @param whichProperty The desired property from the list of properties in 1077 * enum flash_property_tag_t 1078 * @param value A to set for the desired flash property. 1079 * 1080 * @retval #kStatus_FLASH_Success API was executed successfully. 1081 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1082 * @retval #kStatus_FLASH_UnknownProperty An unknown property tag. 1083 * @retval #kStatus_FLASH_InvalidPropertyValue An invalid property value. 1084 * @retval #kStatus_FLASH_ReadOnlyProperty An read-only property tag. 1085 */ 1086 status_t FLASH_SetProperty(flash_config_t *config, flash_property_tag_t whichProperty, uint32_t value); 1087 1088 /*@}*/ 1089 1090 /*! 1091 * @name FlexRAM 1092 * @{ 1093 */ 1094 1095 /*! 1096 * @brief Sets the FlexRAM function command. 1097 * 1098 * @param config A pointer to the storage for the driver runtime state. 1099 * @param option The option used to set the work mode of FlexRAM. 1100 * 1101 * @retval #kStatus_FLASH_Success API was executed successfully. 1102 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1103 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 1104 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 1105 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 1106 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 1107 */ 1108 #if defined(FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD) && FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD 1109 status_t FLASH_SetFlexramFunction(flash_config_t *config, flash_flexram_function_option_t option); 1110 #endif 1111 1112 /*@}*/ 1113 1114 /*! 1115 * @name Swap 1116 * @{ 1117 */ 1118 1119 /*! 1120 * @brief Configures the Swap function or checks the the swap state of the Flash module. 1121 * 1122 * @param config A pointer to the storage for the driver runtime state. 1123 * @param address Address used to configure the flash Swap function. 1124 * @param option The possible option used to configure Flash Swap function or check the flash Swap status 1125 * @param returnInfo A pointer to the data which is used to return the information of flash Swap. 1126 * 1127 * @retval #kStatus_FLASH_Success API was executed successfully. 1128 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1129 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with specified baseline. 1130 * @retval #kStatus_FLASH_SwapIndicatorAddressError Swap indicator address is invalid. 1131 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 1132 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 1133 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 1134 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 1135 */ 1136 #if defined(FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD) && FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD 1137 status_t FLASH_SwapControl(flash_config_t *config, 1138 uint32_t address, 1139 flash_swap_control_option_t option, 1140 flash_swap_state_config_t *returnInfo); 1141 #endif 1142 1143 /*! 1144 * @brief Swaps the lower half flash with the higher half flash. 1145 * 1146 * @param config A pointer to the storage for the driver runtime state. 1147 * @param address Address used to configure the flash swap function 1148 * @param option The possible option used to configure the Flash Swap function or check the flash Swap status. 1149 * 1150 * @retval #kStatus_FLASH_Success API was executed successfully. 1151 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1152 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with specified baseline. 1153 * @retval #kStatus_FLASH_SwapIndicatorAddressError Swap indicator address is invalid. 1154 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 1155 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 1156 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 1157 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 1158 * @retval #kStatus_FLASH_SwapSystemNotInUninitialized Swap system is not in an uninitialzed state. 1159 */ 1160 #if defined(FSL_FEATURE_FLASH_HAS_PFLASH_BLOCK_SWAP) && FSL_FEATURE_FLASH_HAS_PFLASH_BLOCK_SWAP 1161 status_t FLASH_Swap(flash_config_t *config, uint32_t address, flash_swap_function_option_t option); 1162 #endif 1163 1164 /*! 1165 * @name FlexNVM 1166 * @{ 1167 */ 1168 1169 /*! 1170 * @brief Prepares the FlexNVM block for use as data flash, EEPROM backup, or a combination of both and initializes the 1171 * FlexRAM. 1172 * 1173 * @param config Pointer to storage for the driver runtime state. 1174 * @param option The option used to set FlexRAM load behavior during reset. 1175 * @param eepromDataSizeCode Determines the amount of FlexRAM used in each of the available EEPROM subsystems. 1176 * @param flexnvmPartitionCode Specifies how to split the FlexNVM block between data flash memory and EEPROM backup 1177 * memory supporting EEPROM functions. 1178 * 1179 * @retval #kStatus_FLASH_Success API was executed successfully. 1180 * @retval #kStatus_FLASH_InvalidArgument Invalid argument is provided. 1181 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 1182 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 1183 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 1184 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 1185 */ 1186 #if defined(FSL_FEATURE_FLASH_HAS_PROGRAM_PARTITION_CMD) && FSL_FEATURE_FLASH_HAS_PROGRAM_PARTITION_CMD 1187 status_t FLASH_ProgramPartition(flash_config_t *config, 1188 flash_partition_flexram_load_option_t option, 1189 uint32_t eepromDataSizeCode, 1190 uint32_t flexnvmPartitionCode); 1191 #endif 1192 1193 /*@}*/ 1194 1195 /*! 1196 * @name Flash Protection Utilities 1197 * @{ 1198 */ 1199 1200 /*! 1201 * @brief Sets the PFlash Protection to the intended protection status. 1202 * 1203 * @param config A pointer to storage for the driver runtime state. 1204 * @param protectStatus The expected protect status to set to the PFlash protection register. Each bit is 1205 * corresponding to protection of 1/32(64) of the total PFlash. The least significant bit is corresponding to the lowest 1206 * address area of PFlash. The most significant bit is corresponding to the highest address area of PFlash. There are 1207 * two possible cases as shown below: 1208 * 0: this area is protected. 1209 * 1: this area is unprotected. 1210 * 1211 * @retval #kStatus_FLASH_Success API was executed successfully. 1212 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1213 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 1214 */ 1215 status_t FLASH_PflashSetProtection(flash_config_t *config, pflash_protection_status_t *protectStatus); 1216 1217 /*! 1218 * @brief Gets the PFlash protection status. 1219 * 1220 * @param config A pointer to the storage for the driver runtime state. 1221 * @param protectStatus Protect status returned by the PFlash IP. Each bit is corresponding to the protection of 1222 * 1/32(64) 1223 * of the 1224 * total PFlash. The least significant bit corresponds to the lowest address area of the PFlash. The most significant 1225 * bit corresponds to the highest address area of PFlash. There are two possible cases as shown below: 1226 * 0: this area is protected. 1227 * 1: this area is unprotected. 1228 * 1229 * @retval #kStatus_FLASH_Success API was executed successfully. 1230 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1231 */ 1232 status_t FLASH_PflashGetProtection(flash_config_t *config, pflash_protection_status_t *protectStatus); 1233 1234 /*! 1235 * @brief Sets the DFlash protection to the intended protection status. 1236 * 1237 * @param config A pointer to the storage for the driver runtime state. 1238 * @param protectStatus The expected protect status to set to the DFlash protection register. Each bit 1239 * corresponds to the protection of the 1/8 of the total DFlash. The least significant bit corresponds to the lowest 1240 * address area of the DFlash. The most significant bit corresponds to the highest address area of the DFlash. There 1241 * are 1242 * two possible cases as shown below: 1243 * 0: this area is protected. 1244 * 1: this area is unprotected. 1245 * 1246 * @retval #kStatus_FLASH_Success API was executed successfully. 1247 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1248 * @retval #kStatus_FLASH_CommandNotSupported Flash API is not supported. 1249 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 1250 */ 1251 #if FLASH_SSD_IS_FLEXNVM_ENABLED 1252 status_t FLASH_DflashSetProtection(flash_config_t *config, uint8_t protectStatus); 1253 #endif 1254 1255 /*! 1256 * @brief Gets the DFlash protection status. 1257 * 1258 * @param config A pointer to the storage for the driver runtime state. 1259 * @param protectStatus DFlash Protect status returned by the PFlash IP. Each bit corresponds to the protection of the 1260 * 1/8 of 1261 * the total DFlash. The least significant bit corresponds to the lowest address area of the DFlash. The most 1262 * significant bit corresponds to the highest address area of the DFlash, and so on. There are two possible cases as 1263 * below: 1264 * 0: this area is protected. 1265 * 1: this area is unprotected. 1266 * 1267 * @retval #kStatus_FLASH_Success API was executed successfully. 1268 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1269 * @retval #kStatus_FLASH_CommandNotSupported Flash API is not supported. 1270 */ 1271 #if FLASH_SSD_IS_FLEXNVM_ENABLED 1272 status_t FLASH_DflashGetProtection(flash_config_t *config, uint8_t *protectStatus); 1273 #endif 1274 1275 /*! 1276 * @brief Sets the EEPROM protection to the intended protection status. 1277 * 1278 * @param config A pointer to the storage for the driver runtime state. 1279 * @param protectStatus The expected protect status to set to the EEPROM protection register. Each bit 1280 * corresponds to the protection of the 1/8 of the total EEPROM. The least significant bit corresponds to the lowest 1281 * address area of the EEPROM. The most significant bit corresponds to the highest address area of EEPROM, and so on. 1282 * There are two possible cases as shown below: 1283 * 0: this area is protected. 1284 * 1: this area is unprotected. 1285 * 1286 * @retval #kStatus_FLASH_Success API was executed successfully. 1287 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1288 * @retval #kStatus_FLASH_CommandNotSupported Flash API is not supported. 1289 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 1290 */ 1291 #if FLASH_SSD_IS_FLEXNVM_ENABLED 1292 status_t FLASH_EepromSetProtection(flash_config_t *config, uint8_t protectStatus); 1293 #endif 1294 1295 /*! 1296 * @brief Gets the DFlash protection status. 1297 * 1298 * @param config A pointer to the storage for the driver runtime state. 1299 * @param protectStatus DFlash Protect status returned by the PFlash IP. Each bit corresponds to the protection of the 1300 * 1/8 of 1301 * the total EEPROM. The least significant bit corresponds to the lowest address area of the EEPROM. The most 1302 * significant bit corresponds to the highest address area of the EEPROM. There are two possible cases as below: 1303 * 0: this area is protected. 1304 * 1: this area is unprotected. 1305 * 1306 * @retval #kStatus_FLASH_Success API was executed successfully. 1307 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 1308 * @retval #kStatus_FLASH_CommandNotSupported Flash API is not supported. 1309 */ 1310 #if FLASH_SSD_IS_FLEXNVM_ENABLED 1311 status_t FLASH_EepromGetProtection(flash_config_t *config, uint8_t *protectStatus); 1312 #endif 1313 1314 /*@}*/ 1315 1316 /*@}*/ 1317 1318 /*! 1319 * @name Flash Speculation Utilities 1320 * @{ 1321 */ 1322 1323 /*! 1324 * @brief Sets the PFlash prefetch speculation to the intended speculation status. 1325 * 1326 * @param speculationStatus The expected protect status to set to the PFlash protection register. Each bit is 1327 * @retval #kStatus_FLASH_Success API was executed successfully. 1328 * @retval #kStatus_FLASH_InvalidSpeculationOption An invalid speculation option argument is provided. 1329 */ 1330 status_t FLASH_PflashSetPrefetchSpeculation(flash_prefetch_speculation_status_t *speculationStatus); 1331 1332 /*! 1333 * @brief Gets the PFlash prefetch speculation status. 1334 * 1335 * @param speculationStatus Speculation status returned by the PFlash IP. 1336 * @retval #kStatus_FLASH_Success API was executed successfully. 1337 */ 1338 status_t FLASH_PflashGetPrefetchSpeculation(flash_prefetch_speculation_status_t *speculationStatus); 1339 1340 /*@}*/ 1341 1342 #if defined(__cplusplus) 1343 } 1344 #endif 1345 1346 /*! @}*/ 1347 1348 #endif /* _FSL_FLASH_H_ */ 1349
