1 /* 2 * Copyright 2017 - 2021 NXP 3 * All rights reserved. 4 * 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef FSL_FLASH_H_ 10 #define FSL_FLASH_H_ 11 12 #if (defined(BL_TARGET_FLASH) || defined(BL_TARGET_ROM) || defined(BL_TARGET_RAM)) 13 #include <assert.h> 14 #include <string.h> 15 #include "fsl_device_registers.h" 16 #include "bootloader_common.h" 17 #else 18 #include "fsl_common.h" 19 #endif 20 21 /******************************************************************************* 22 * Definitions 23 ******************************************************************************/ 24 25 /*! 26 * @addtogroup flash_driver 27 * @{ 28 */ 29 30 /*! 31 * @name Flash version 32 * @{ 33 */ 34 /*! @brief Constructs the version number for drivers. */ 35 #if !defined(MAKE_VERSION) 36 #define MAKE_VERSION(major, minor, bugfix) (((major) << 16) | ((minor) << 8) | (bugfix)) 37 #endif 38 39 /*! @brief Flash driver version for SDK*/ 40 #define FSL_FLASH_DRIVER_VERSION (MAKE_VERSION(2, 1, 2)) /*!< Version 2.1.2. */ 41 42 /*! @brief Flash driver version for ROM*/ 43 enum _flash_driver_version_constants 44 { 45 kFLASH_DriverVersionName = 'F', /*!< Flash driver version name.*/ 46 kFLASH_DriverVersionMajor = 2, /*!< Major flash driver version.*/ 47 kFLASH_DriverVersionMinor = 1, /*!< Minor flash driver version.*/ 48 kFLASH_DriverVersionBugfix = 1 /*!< Bugfix for flash driver version.*/ 49 }; 50 /*! @} */ 51 52 /*! 53 * @name Flash configuration 54 * @{ 55 */ 56 /*! @brief Indicates whether to support EEPROM in the Flash driver */ 57 #if (defined(FSL_FEATURE_FLASH_HAS_EEPROM) && FSL_FEATURE_FLASH_HAS_EEPROM) 58 #define FLASH_SSD_CONFIG_ENABLE_EEPROM_SUPPORT 1 /*!< Enables the EEPROM support. */ 59 #else 60 #define FLASH_SSD_CONFIG_ENABLE_EEPROM_SUPPORT 0 /*!< Disables the EEPROM support. */ 61 #endif 62 63 /*! @brief Indicates whether the EEPROM is enabled in the Flash driver */ 64 #define FLASH_SSD_IS_EEPROM_ENABLED FLASH_SSD_CONFIG_ENABLE_EEPROM_SUPPORT 65 66 /*! @brief Indicates whether to support Secondary flash in the Flash driver */ 67 #if !defined(FLASH_SSD_CONFIG_ENABLE_SECONDARY_FLASH_SUPPORT) 68 #define FLASH_SSD_CONFIG_ENABLE_SECONDARY_FLASH_SUPPORT 1 /*!< Enables the secondary flash support by default. */ 69 #endif 70 71 /*! @brief Indicates whether the secondary flash is supported in the Flash driver */ 72 #if defined(FSL_FEATURE_FLASH_HAS_MULTIPLE_FLASH) || defined(FSL_FEATURE_FLASH_PFLASH_1_START_ADDRESS) 73 #define FLASH_SSD_IS_SECONDARY_FLASH_ENABLED (FLASH_SSD_CONFIG_ENABLE_SECONDARY_FLASH_SUPPORT) 74 #else 75 #define FLASH_SSD_IS_SECONDARY_FLASH_ENABLED (0) 76 #endif 77 78 /*! @brief Flash driver location. */ 79 #if !defined(FLASH_DRIVER_IS_FLASH_RESIDENT) 80 #if (!defined(BL_TARGET_ROM) && !defined(BL_TARGET_RAM)) 81 #define FLASH_DRIVER_IS_FLASH_RESIDENT 1 /*!< Used for the flash resident application. */ 82 #else 83 #define FLASH_DRIVER_IS_FLASH_RESIDENT 0 /*!< Used for the non-flash resident application. */ 84 #endif 85 #endif 86 87 /*! @brief Flash Driver Export option */ 88 #if !defined(FLASH_DRIVER_IS_EXPORTED) 89 #if (defined(BL_TARGET_ROM) || defined(BL_TARGET_FLASH)) 90 #define FLASH_DRIVER_IS_EXPORTED 1 /*!< Used for the ROM bootloader. */ 91 #else 92 #define FLASH_DRIVER_IS_EXPORTED 0 /*!< Used for the MCUXpresso SDK application. */ 93 #endif 94 #endif 95 96 /*! @brief Enable flash stalling controller */ 97 #define FLASH_ENABLE_STALLING_FLASH_CONTROLLER 1 98 /*! @} */ 99 100 /*! 101 * @name Flash status 102 * @{ 103 */ 104 /*! @brief Flash driver status group. */ 105 #if defined(kStatusGroup_FlashDriver) 106 #define kStatusGroupGeneric kStatusGroup_Generic 107 #define kStatusGroupFlashDriver kStatusGroup_FlashDriver 108 #elif defined(kStatusGroup_FLASH) 109 #define kStatusGroupGeneric kStatusGroup_Generic 110 #define kStatusGroupFlashDriver kStatusGroup_FLASH 111 #else 112 #define kStatusGroupGeneric 0 113 #define kStatusGroupFlashDriver 1 114 #endif 115 116 /*! @brief Constructs a status code value from a group and a code number. */ 117 #if !defined(MAKE_STATUS) 118 #define MAKE_STATUS(group, code) ((((group)*100) + (code))) 119 #endif 120 121 /*! 122 * @brief Flash driver status codes. 123 */ 124 enum 125 { 126 kStatus_FLASH_Success = MAKE_STATUS(kStatusGroupGeneric, 0), /*!< API is executed successfully*/ 127 kStatus_FLASH_InvalidArgument = MAKE_STATUS(kStatusGroupGeneric, 4), /*!< Invalid argument*/ 128 kStatus_FLASH_SizeError = MAKE_STATUS(kStatusGroupFlashDriver, 0), /*!< Error size*/ 129 kStatus_FLASH_AlignmentError = 130 MAKE_STATUS(kStatusGroupFlashDriver, 1), /*!< Parameter is not aligned with the specified baseline*/ 131 kStatus_FLASH_AddressError = MAKE_STATUS(kStatusGroupFlashDriver, 2), /*!< Address is out of range */ 132 kStatus_FLASH_AccessError = 133 MAKE_STATUS(kStatusGroupFlashDriver, 3), /*!< Invalid instruction codes and out-of bound addresses */ 134 kStatus_FLASH_ProtectionViolation = MAKE_STATUS( 135 kStatusGroupFlashDriver, 4), /*!< The program/erase operation is requested to execute on protected areas */ 136 kStatus_FLASH_CommandFailure = 137 MAKE_STATUS(kStatusGroupFlashDriver, 5), /*!< Run-time error during command execution. */ 138 kStatus_FLASH_UnknownProperty = MAKE_STATUS(kStatusGroupFlashDriver, 6), /*!< Unknown property.*/ 139 kStatus_FLASH_EraseKeyError = MAKE_STATUS(kStatusGroupFlashDriver, 7), /*!< API erase key is invalid.*/ 140 kStatus_FLASH_RegionExecuteOnly = 141 MAKE_STATUS(kStatusGroupFlashDriver, 8), /*!< The current region is execute-only.*/ 142 kStatus_FLASH_ExecuteInRamFunctionNotReady = 143 MAKE_STATUS(kStatusGroupFlashDriver, 9), /*!< Execute-in-RAM function is not available.*/ 144 kStatus_FLASH_PartitionStatusUpdateFailure = 145 MAKE_STATUS(kStatusGroupFlashDriver, 10), /*!< Failed to update partition status.*/ 146 kStatus_FLASH_SetFlexramAsEepromError = 147 MAKE_STATUS(kStatusGroupFlashDriver, 11), /*!< Failed to set FlexRAM as EEPROM.*/ 148 kStatus_FLASH_RecoverFlexramAsRamError = 149 MAKE_STATUS(kStatusGroupFlashDriver, 12), /*!< Failed to recover FlexRAM as RAM.*/ 150 kStatus_FLASH_SetFlexramAsRamError = MAKE_STATUS(kStatusGroupFlashDriver, 13), /*!< Failed to set FlexRAM as RAM.*/ 151 kStatus_FLASH_RecoverFlexramAsEepromError = 152 MAKE_STATUS(kStatusGroupFlashDriver, 14), /*!< Failed to recover FlexRAM as EEPROM.*/ 153 kStatus_FLASH_CommandNotSupported = MAKE_STATUS(kStatusGroupFlashDriver, 15), /*!< Flash API is not supported.*/ 154 kStatus_FLASH_SwapSystemNotInUninitialized = 155 MAKE_STATUS(kStatusGroupFlashDriver, 16), /*!< Swap system is not in an uninitialzed state.*/ 156 kStatus_FLASH_SwapIndicatorAddressError = 157 MAKE_STATUS(kStatusGroupFlashDriver, 17), /*!< The swap indicator address is invalid.*/ 158 kStatus_FLASH_ReadOnlyProperty = MAKE_STATUS(kStatusGroupFlashDriver, 18), /*!< The flash property is read-only.*/ 159 kStatus_FLASH_InvalidPropertyValue = 160 MAKE_STATUS(kStatusGroupFlashDriver, 19), /*!< The flash property value is out of range.*/ 161 kStatus_FLASH_InvalidSpeculationOption = 162 MAKE_STATUS(kStatusGroupFlashDriver, 20), /*!< The option of flash prefetch speculation is invalid.*/ 163 164 kStatus_FLASH_ClockDivider = MAKE_STATUS(kStatusGroupFlashDriver, 21), /*!<Flash clock prescaler is wrong*/ 165 kStatus_FLASH_EepromDoubleBitFault = 166 MAKE_STATUS(kStatusGroupFlashDriver, 22), /*!< A double bit fault was detected in the stored parity.*/ 167 kStatus_FLASH_EepromSingleBitFault = 168 MAKE_STATUS(kStatusGroupFlashDriver, 23), /*!< A single bit fault was detected in the stored parity.*/ 169 170 }; 171 172 /*! @} */ 173 174 /*! 175 * @name Flash API key 176 * @{ 177 */ 178 /*! @brief Constructs the four character code for the Flash driver API key. */ 179 #if !defined(FOUR_CHAR_CODE) 180 #define FOUR_CHAR_CODE(a, b, c, d) (((d) << 24) | ((c) << 16) | ((b) << 8) | ((a))) 181 #endif 182 183 /*! 184 * @brief Enumeration for Flash driver API keys. 185 * 186 * @note The resulting value is built with a byte order such that the string 187 * being readable in expected order when viewed in a hex editor, if the value 188 * is treated as a 32-bit little endian value. 189 */ 190 enum _flash_driver_api_keys 191 { 192 kFLASH_ApiEraseKey = FOUR_CHAR_CODE('k', 'f', 'e', 'k') /*!< Key value used to validate all flash erase APIs.*/ 193 }; 194 /*! @} */ 195 196 /*! 197 * @brief Enumeration for supported flash user margin levels. 198 */ 199 typedef enum _flash_user_margin_value 200 { 201 kFLASH_ReadMarginValueNormal = 0x0000U, /*!< Use the 'normal' read level for 1s.*/ 202 kFLASH_UserMarginValue1 = 0x0001U, /*!< Apply the 'User' margin to the normal read-1 level.*/ 203 kFLASH_UserMarginValue0 = 0x0002U, /*!< Apply the 'User' margin to the normal read-0 level.*/ 204 } flash_user_margin_value_t; 205 206 /*! 207 * @brief Enumeration for supported factory margin levels. 208 */ 209 typedef enum _flash_factory_margin_value 210 { 211 kFLASH_FactoryMarginValue1 = 0x0003U, /*!< Apply the 'Factory' margin to the normal read-1 level.*/ 212 kFLASH_FactoryMarginValue0 = 0x0004U, /*!< Apply the 'Factory' margin to the normal read-0 level.*/ 213 } flash_factory_margin_value_t; 214 215 /*! 216 * @brief Enumeration for supported flash margin levels. 217 */ 218 typedef enum _flash_margin_value 219 { 220 kFLASH_MarginValueNormal, /*!< Use the 'normal' read level for 1s.*/ 221 kFLASH_MarginValueUser, /*!< Apply the 'User' margin to the normal read-1 level.*/ 222 kFLASH_MarginValueFactory, /*!< Apply the 'Factory' margin to the normal read-1 level.*/ 223 kFLASH_MarginValueInvalid, /*!< Not real margin level, Used to determine the range of valid margin level. */ 224 } flash_margin_value_t; 225 226 /*! 227 * @brief Enumeration for the three possible flash security states. 228 */ 229 typedef enum _flash_security_state 230 { 231 kFLASH_SecurityStateNotSecure, /*!< Flash is not secure.*/ 232 kFLASH_SecurityStateBackdoorEnabled, /*!< Flash backdoor is enabled.*/ 233 kFLASH_SecurityStateBackdoorDisabled /*!< Flash backdoor is disabled.*/ 234 } flash_security_state_t; 235 236 /*! 237 * @brief Enumeration for the three possible flash protection levels. 238 */ 239 typedef enum _flash_protection_state 240 { 241 kFLASH_ProtectionStateUnprotected, /*!< Flash region is not protected.*/ 242 kFLASH_ProtectionStateProtected, /*!< Flash region is protected.*/ 243 kFLASH_ProtectionStateMixed /*!< Flash is mixed with protected and unprotected region.*/ 244 } flash_protection_state_t; 245 246 /*! 247 * @brief Enumeration for various flash properties. 248 */ 249 typedef enum _flash_property_tag 250 { 251 kFLASH_PropertyPflashSectorSize = 0x00U, /*!< Pflash sector size property.*/ 252 kFLASH_PropertyPflashTotalSize = 0x01U, /*!< Pflash total size property.*/ 253 kFLASH_PropertyPflashBlockSize = 0x02U, /*!< Pflash block size property.*/ 254 kFLASH_PropertyPflashBlockCount = 0x03U, /*!< Pflash block count property.*/ 255 kFLASH_PropertyPflashBlockBaseAddr = 0x04U, /*!< Pflash block base address property.*/ 256 kFLASH_PropertyPflashFacSupport = 0x05U, /*!< Pflash fac support property.*/ 257 258 kFLASH_PropertyEepromTotalSize = 0x15U, /*!< EEPROM total size property.*/ 259 kFLASH_PropertyFlashMemoryIndex = 0x20U, /*!< Flash memory index property.*/ 260 kFLASH_PropertyFlashCacheControllerIndex = 0x21U, /*!< Flash cache controller index property.*/ 261 262 kFLASH_PropertyEepromBlockBaseAddr = 0x22U, /*!< EEPROM block base address property.*/ 263 kFLASH_PropertyEepromSectorSize = 0x23U, /*!< EEPROM sector size property.*/ 264 kFLASH_PropertyEepromBlockSize = 0x24U, /*!< EEPROM block size property.*/ 265 kFLASH_PropertyEepromBlockCount = 0x25U, /*!< EEPROM block count property.*/ 266 kFLASH_PropertyFlashClockFrequency = 0x26U, /*!< Flash peripheral clock property.*/ 267 } flash_property_tag_t; 268 269 /*! 270 * @brief Constants for execute-in-RAM flash function. 271 * _flash_execute_in_ram_function_constants 272 */ 273 enum 274 { 275 kFLASH_ExecuteInRamFunctionMaxSizeInWords = 16U, /*!< The maximum size of execute-in-RAM function.*/ 276 kFLASH_ExecuteInRamFunctionTotalNum = 2U /*!< Total number of execute-in-RAM functions.*/ 277 }; 278 279 /*! 280 * @brief PFlash protection status - full 281 */ 282 typedef struct _pflash_protection_status 283 { 284 uint8_t fprotvalue; /*!< FPROT[7:0] .*/ 285 } pflash_protection_status_t; 286 287 /*! 288 * @brief Enumeration for the flash memory index. 289 */ 290 typedef enum _flash_memory_index 291 { 292 kFLASH_MemoryIndexPrimaryFlash = 0x00U, /*!< Current flash memory is primary flash.*/ 293 kFLASH_MemoryIndexSecondaryFlash = 0x01U, /*!< Current flash memory is secondary flash.*/ 294 } flash_memory_index_t; 295 296 /*! 297 * @brief Enumeration for the flash cache controller index. 298 */ 299 typedef enum _flash_cache_controller_index 300 { 301 kFLASH_CacheControllerIndexForCore0 = 0x00U, /*!< Current flash cache controller is for core 0.*/ 302 kFLASH_CacheControllerIndexForCore1 = 0x01U, /*!< Current flash cache controller is for core 1.*/ 303 } flash_cache_controller_index_t; 304 305 /*! @brief A callback type used for the Pflash block*/ 306 typedef void (*flash_callback_t)(void); 307 308 /*! 309 * @brief Enumeration for the two possible options of flash prefetch speculation. 310 */ 311 typedef enum _flash_prefetch_speculation_option 312 { 313 kFLASH_prefetchSpeculationOptionEnable = 0x00U, 314 kFLASH_prefetchSpeculationOptionDisable = 0x01U 315 } flash_prefetch_speculation_option_t; 316 317 /*! 318 * @brief Flash prefetch speculation status. 319 */ 320 typedef struct _flash_prefetch_speculation_status 321 { 322 flash_prefetch_speculation_option_t instructionOption; /*!< Instruction speculation.*/ 323 flash_prefetch_speculation_option_t dataOption; /*!< Data speculation.*/ 324 } flash_prefetch_speculation_status_t; 325 326 /*! 327 * @brief Flash cache clear process code. 328 */ 329 typedef enum _flash_cache_clear_process 330 { 331 kFLASH_CacheClearProcessPre = 0x00U, /*!< Pre flash cache clear process.*/ 332 kFLASH_CacheClearProcessPost = 0x01U, /*!< Post flash cache clear process.*/ 333 } flash_cache_clear_process_t; 334 335 /*! 336 * @brief Active flash protection information for the current operation. 337 */ 338 typedef struct _flash_protection_config 339 { 340 uint32_t lowRegionStart; /*!< Start address of flash protection low region.*/ 341 uint32_t lowRegionEnd; /*!< End address of flash protection low region.*/ 342 uint32_t highRegionStart; /*!< Start address of flash protection high region.*/ 343 uint32_t highRegionEnd; /*!< End address of flash protection high region.*/ 344 } flash_protection_config_t; 345 346 /*! 347 * @brief Active flash information for the current operation. 348 */ 349 typedef struct _flash_operation_config 350 { 351 uint32_t convertedAddress; /*!< A converted address for the current flash type.*/ 352 uint32_t activeSectorSize; /*!< A sector size of the current flash type.*/ 353 uint32_t activeBlockSize; /*!< A block size of the current flash type.*/ 354 uint32_t blockWriteUnitSize; /*!< The write unit size.*/ 355 uint32_t sectorCmdAddressAligment; /*!< An erase sector command address alignment.*/ 356 uint32_t sectionCmdAddressAligment; /*!< A program/verify section command address alignment.*/ 357 358 uint32_t programCmdAddressAligment; /*!< A program flash command address alignment.*/ 359 } flash_operation_config_t; 360 361 /*! 362 * @brief Flash execute-in-RAM command. 363 */ 364 typedef union 365 { 366 uint32_t commadAddr; 367 void (*callFlashCommand)(volatile uint8_t *FTMRx_fstat); 368 } function_run_command_t; 369 370 typedef union 371 { 372 uint32_t bitOperationAddr; 373 void (*callCommonBitOperationCommand)(volatile uint32_t *base, 374 uint32_t bitMask, 375 uint32_t bitShift, 376 uint32_t bitValue); 377 } function_common_bit_operation_t; 378 /*! 379 * @brief Flash execute-in-RAM function information. 380 */ 381 typedef struct _flash_execute_in_ram_function_config 382 { 383 uint32_t activeFunctionCount; /*!< Number of available execute-in-RAM functions.*/ 384 function_run_command_t runCmdFuncAddr; /*!< Execute-in-RAM function: flash_run_command. */ 385 function_common_bit_operation_t CommonBitOperationAddr; /*! Execute-in-RAM function: flash_common_bit_operation. */ 386 } flash_execute_in_ram_function_config_t; 387 388 /*! @brief Flash driver state information. 389 * 390 * An instance of this structure is allocated by the user of the flash driver and 391 * passed into each of the driver APIs. 392 */ 393 typedef struct _flash_config 394 { 395 uint32_t PFlashBlockBase; /*!< A base address of the first PFlash block */ 396 uint32_t PFlashTotalSize; /*!< The size of the combined PFlash block. */ 397 uint8_t PFlashBlockCount; /*!< A number of PFlash blocks. */ 398 uint8_t FlashMemoryIndex; /*!< 0 - primary flash; 1 - secondary flash*/ 399 uint8_t FlashCacheControllerIndex; /*!< 0 - Controller for core 0; 1 - Controller for core 1 */ 400 uint8_t Reserved0; /*!< Reserved field 0 */ 401 uint32_t PFlashSectorSize; /*!< The size in bytes of a sector of PFlash. */ 402 flash_callback_t PFlashCallback; /*!< The callback function for the flash API. */ 403 404 uint32_t *flashExecuteInRamFunctionInfo; /*!< An information structure of the flash execute-in-RAM function. */ 405 406 uint32_t EEpromTotalSize; /*!< For the FlexNVM device, this is the size in bytes of the EEPROM area which was 407 partitioned from FlexRAM */ 408 /*!< For the non-FlexNVM device, this field is unused */ 409 410 uint32_t EEpromBlockBase; /*!< This is the base address of the Eeprom */ 411 /*!< For the non-Eeprom device, this field is unused */ 412 uint8_t EEpromBlockCount; /*!< A number of EEPROM blocks. */ 413 /*!< For the non-Eeprom device, this field is unused */ 414 uint8_t EEpromSectorSize; /*!< The size in bytes of a sector of EEPROM. */ 415 /*!< For the non-Eeprom device, this field is unused */ 416 uint8_t Reserved1[2]; /*!< Reserved field 1 */ 417 uint32_t PFlashClockFreq; /*!< The flash peripheral clock frequency */ 418 uint32_t PFlashMarginLevel; /*!< The margin level*/ 419 flash_execute_in_ram_function_config_t executeInRamFunction; 420 } flash_config_t; 421 422 /******************************************************************************* 423 * API 424 ******************************************************************************/ 425 426 #if defined(__cplusplus) 427 extern "C" { 428 #endif 429 430 /*! 431 * @name Initialization 432 * @{ 433 */ 434 435 /*! 436 * @brief Initializes the global flash properties structure members. 437 * 438 * This function checks and initializes the Flash module for the other Flash APIs. 439 * 440 * @param config Pointer to the storage for the driver runtime state. 441 * 442 * @retval #kStatus_FLASH_Success API was executed successfully. 443 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 444 * @retval #kStatus_FLASH_ClockDivider Flash clock prescaler is wrong. 445 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 446 */ 447 status_t FLASH_Init(flash_config_t *config); 448 449 /*! 450 * @brief Sets the desired flash callback function. 451 * 452 * @param config Pointer to the storage for the driver runtime state. 453 * @param callback A callback function to be stored in the driver. 454 * 455 * @retval #kStatus_FLASH_Success API was executed successfully. 456 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 457 */ 458 status_t FLASH_SetCallback(flash_config_t *config, flash_callback_t callback); 459 460 #if defined(FLASH_DRIVER_IS_FLASH_RESIDENT) && FLASH_DRIVER_IS_FLASH_RESIDENT 461 /*! 462 * @brief Prepares flash execute-in-RAM functions. 463 * 464 * @param config Pointer to the storage for the driver runtime state. 465 * 466 * @retval #kStatus_FLASH_Success API was executed successfully. 467 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 468 */ 469 status_t FLASH_PrepareExecuteInRamFunctions(flash_config_t *config); 470 #endif /* FLASH_DRIVER_IS_FLASH_RESIDENT */ 471 472 /*! @} */ 473 474 /*! 475 * @name Erasing 476 * @{ 477 */ 478 479 /*! 480 * @brief Erases entire flash 481 * 482 * @param config Pointer to the storage for the driver runtime state. 483 * @param key A value used to validate all flash erase APIs. 484 * 485 * @retval #kStatus_FLASH_Success API was executed successfully. 486 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 487 * @retval #kStatus_FLASH_EraseKeyError API erase key is invalid. 488 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 489 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 490 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 491 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 492 * @retval #kStatus_FLASH_EepromSingleBitFault EEPROM single bit fault error code. 493 * @retval #kStatus_FLASH_EepromDoubleBitFault EEPROM double bit fault error code. 494 */ 495 status_t FLASH_EraseAll(flash_config_t *config, uint32_t key); 496 497 /*! 498 * @brief Erases the flash sectors encompassed by parameters passed into function. 499 * 500 * This function erases the appropriate number of flash sectors based on the 501 * desired start address and length. 502 * 503 * @param config The pointer to the storage for the driver runtime state. 504 * @param start The start address of the desired flash memory to be erased. 505 * The start address does not need to be sector-aligned but must be word-aligned. 506 * @param lengthInBytes The length, given in bytes (not words or long-words) 507 * to be erased. Must be word-aligned. 508 * @param key The value used to validate all flash erase APIs. 509 * 510 * @retval #kStatus_FLASH_Success API was executed successfully. 511 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 512 * @retval #kStatus_FLASH_AlignmentError The parameter is not aligned with the specified baseline. 513 * @retval #kStatus_FLASH_AddressError The address is out of range. 514 * @retval #kStatus_FLASH_EraseKeyError The API erase key is invalid. 515 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 516 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 517 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 518 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 519 */ 520 status_t FLASH_Erase(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key); 521 522 #if defined(FLASH_SSD_IS_EEPROM_ENABLED) && FLASH_SSD_IS_EEPROM_ENABLED 523 /*! 524 * @brief Erases the eeprom sectors encompassed by parameters passed into function. 525 * 526 * This function erases the appropriate number of eeprom sectors based on the 527 * desired start address and length. 528 * 529 * @param config The pointer to the storage for the driver runtime state. 530 * @param start The start address of the desired eeprom memory to be erased. 531 * The start address does not need to be sector-aligned but must be word-aligned. 532 * @param lengthInBytes The length, given in bytes (not words or long-words) 533 * to be erased. Must be word-aligned. 534 * @param key The value used to validate all eeprom erase APIs. 535 * 536 * @retval #kStatus_FLASH_Success API was executed successfully. 537 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 538 * @retval #kStatus_FLASH_AlignmentError The parameter is not aligned with the specified baseline. 539 * @retval #kStatus_FLASH_AddressError The address is out of range. 540 * @retval #kStatus_FLASH_EraseKeyError The API erase key is invalid. 541 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 542 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 543 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 544 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 545 */ 546 status_t FLASH_EraseEEprom(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key); 547 #endif /* FLASH_SSD_IS_EEPROM_ENABLED */ 548 549 #if defined(FSL_FEATURE_FLASH_HAS_UNSECURE_FLASH_CMD) && FSL_FEATURE_FLASH_HAS_UNSECURE_FLASH_CMD 550 /*! 551 * @brief Erases the entire flash, including protected sectors. 552 * 553 * @param config Pointer to the storage for the driver runtime state. 554 * @param key A value used to validate all flash erase APIs. 555 * 556 * @retval #kStatus_FLASH_Success API was executed successfully. 557 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 558 * @retval #kStatus_FLASH_EraseKeyError API erase key is invalid. 559 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 560 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 561 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 562 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 563 * @retval #kStatus_FLASH_EepromSingleBitFault EEPROM single bit fault error code. 564 * @retval #kStatus_FLASH_EepromDoubleBitFault EEPROM double bit fault error code. 565 */ 566 status_t FLASH_EraseAllUnsecure(flash_config_t *config, uint32_t key); 567 #endif /* FSL_FEATURE_FLASH_HAS_UNSECURE_FLASH_CMD */ 568 569 /*! @} */ 570 571 /*! 572 * @name Programming 573 * @{ 574 */ 575 576 /*! 577 * @brief Programs flash with data at locations passed in through parameters. 578 * 579 * This function programs the flash memory with the desired data for a given 580 * flash area as determined by the start address and the length. 581 * 582 * @param config A pointer to the storage for the driver runtime state. 583 * @param start The start address of the desired flash memory to be programmed. Must be 584 * word-aligned. 585 * @param src A pointer to the source buffer of data that is to be programmed 586 * into the flash. 587 * @param lengthInBytes The length, given in bytes (not words or long-words), 588 * to be programmed. Must be word-aligned. 589 * 590 * @retval #kStatus_FLASH_Success API was executed successfully. 591 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 592 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with the specified baseline. 593 * @retval #kStatus_FLASH_AddressError Address is out of range. 594 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 595 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 596 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 597 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 598 */ 599 status_t FLASH_Program(flash_config_t *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes); 600 601 /*! 602 * @brief Programs Program Once Field through parameters. 603 * 604 * This function programs the Program Once Field with the desired data for a given 605 * flash area as determined by the index and length. 606 * 607 * @param config A pointer to the storage for the driver runtime state. 608 * @param index The index indicating which area of the Program Once Field to be programmed. 609 * @param src A pointer to the source buffer of data that is to be programmed 610 * into the Program Once Field. 611 * @param lengthInBytes The length, given in bytes (not words or long-words), 612 * to be programmed. Must be word-aligned. 613 * 614 * @retval #kStatus_FLASH_Success API was executed successfully. 615 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 616 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 617 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 618 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 619 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 620 */ 621 status_t FLASH_ProgramOnce(flash_config_t *config, uint32_t index, uint32_t *src, uint32_t lengthInBytes); 622 623 #if defined(FLASH_SSD_IS_EEPROM_ENABLED) && FLASH_SSD_IS_EEPROM_ENABLED 624 /*! 625 * @brief Programs the EEPROM with data at locations passed in through parameters. 626 * 627 * This function programs the emulated EEPROM with the desired data for a given 628 * flash area as determined by the start address and length. 629 * 630 * @param config A pointer to the storage for the driver runtime state. 631 * @param start The start address of the desired flash memory to be programmed. Must be 632 * word-aligned. 633 * @param src A pointer to the source buffer of data that is to be programmed 634 * into the flash. 635 * @param lengthInBytes The length, given in bytes (not words or long-words), 636 * to be programmed. Must be word-aligned. 637 * 638 * @retval #kStatus_FLASH_Success API was executed successfully. 639 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 640 * @retval #kStatus_FLASH_AddressError Address is out of range. 641 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 642 * @retval #kStatus_FLASH_EepromSingleBitFault EEPROM single bit fault error code. 643 * @retval #kStatus_FLASH_EepromDoubleBitFault EEPROM double bit fault error code. 644 */ 645 status_t FLASH_EepromWrite(flash_config_t *config, uint32_t start, uint8_t *src, uint32_t lengthInBytes); 646 #endif /* FLASH_SSD_IS_EEPROM_ENABLED */ 647 648 /*! @} */ 649 650 /*! 651 * @name Reading 652 * @{ 653 */ 654 655 /*! 656 * @brief Reads the Program Once Field through parameters. 657 * 658 * This function reads the read once feild with given index and length. 659 * 660 * @param config A pointer to the storage for the driver runtime state. 661 * @param index The index indicating the area of program once field to be read. 662 * @param dst A pointer to the destination buffer of data that is used to store 663 * data to be read. 664 * @param lengthInBytes The length, given in bytes (not words or long-words), 665 * to be programmed. Must be word-aligned. 666 * 667 * @retval #kStatus_FLASH_Success API was executed successfully. 668 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 669 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 670 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 671 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 672 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 673 */ 674 status_t FLASH_ReadOnce(flash_config_t *config, uint32_t index, uint32_t *dst, uint32_t lengthInBytes); 675 676 /*! @} */ 677 678 /*! 679 * @name Security 680 * @{ 681 */ 682 683 /*! 684 * @brief Returns the security state via the pointer passed into the function. 685 * 686 * This function retrieves the current flash security status, including the 687 * security enabling state and the backdoor key enabling state. 688 * 689 * @param config A pointer to storage for the driver runtime state. 690 * @param state A pointer to the value returned for the current security status code: 691 * 692 * @retval #kStatus_FLASH_Success API was executed successfully. 693 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 694 */ 695 status_t FLASH_GetSecurityState(flash_config_t *config, flash_security_state_t *state); 696 697 /*! 698 * @brief Allows users to bypass security with a backdoor key. 699 * 700 * If the MCU is in secured state, this function unsecures the MCU by 701 * comparing the provided backdoor key with ones in the flash configuration 702 * field. 703 * 704 * @param config A pointer to the storage for the driver runtime state. 705 * @param backdoorKey A pointer to the user buffer containing the backdoor key. 706 * 707 * @retval #kStatus_FLASH_Success API was executed successfully. 708 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 709 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 710 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 711 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 712 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 713 */ 714 status_t FLASH_SecurityBypass(flash_config_t *config, const uint8_t *backdoorKey); 715 716 /*! @} */ 717 718 /*! 719 * @name Verification 720 * @{ 721 */ 722 723 /*! 724 * @brief Verifies erasure of the entire flash at a specified margin level. 725 * 726 * This function checks whether the flash is erased to the 727 * specified read margin level. 728 * 729 * @param config A pointer to the storage for the driver runtime state. 730 * @param margin Read margin choice. 731 * 732 * @retval #kStatus_FLASH_Success API was executed successfully. 733 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 734 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 735 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 736 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 737 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 738 * @retval #kStatus_FLASH_EepromSingleBitFault EEPROM single bit fault error code. 739 * @retval #kStatus_FLASH_EepromDoubleBitFault EEPROM double bit fault error code. 740 */ 741 status_t FLASH_VerifyEraseAll(flash_config_t *config, flash_margin_value_t margin); 742 743 /*! 744 * @brief Verifies an erasure of the desired flash area at a specified margin level. 745 * 746 * This function checks the appropriate number of flash sectors based on 747 * the desired start address and length to check whether the flash is erased 748 * to the specified read margin level. 749 * 750 * @param config A pointer to the storage for the driver runtime state. 751 * @param margin Read margin choice. 752 * @param start The start address of the desired flash memory to be verified. 753 * The start address does not need to be sector-aligned but must be word-aligned. 754 * @param lengthInBytes The length, given in bytes (not words or long-words), 755 * to be verified. Must be word-aligned. 756 * 757 * @retval #kStatus_FLASH_Success API was executed successfully. 758 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 759 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with specified baseline. 760 * @retval #kStatus_FLASH_AddressError Address is out of range. 761 * @retval #kStatus_FLASH_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 762 * @retval #kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses. 763 * @retval #kStatus_FLASH_ProtectionViolation The program/erase operation is requested to execute on protected areas. 764 * @retval #kStatus_FLASH_CommandFailure Run-time error during the command execution. 765 */ 766 status_t FLASH_VerifyErase(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, flash_margin_value_t margin); 767 768 /*! @} */ 769 770 /*! 771 * @name Protection 772 * @{ 773 */ 774 775 /*! 776 * @brief Returns the protection state of the desired flash area via the pointer passed into the function. 777 * 778 * This function retrieves the current flash protect status 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 checked. Must be word-aligned. 783 * @param lengthInBytes The length, given in bytes (not words or long-words) 784 * to be checked. Must be word-aligned. 785 * @param protection_state A pointer to the value returned for the current 786 * protection status code for the desired flash area. 787 * 788 * @retval #kStatus_FLASH_Success API was executed successfully. 789 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 790 * @retval #kStatus_FLASH_AlignmentError Parameter is not aligned with specified baseline. 791 * @retval #kStatus_FLASH_AddressError The address is out of range. 792 */ 793 status_t FLASH_IsProtected(flash_config_t *config, 794 uint32_t start, 795 uint32_t lengthInBytes, 796 flash_protection_state_t *protection_state); 797 798 /*! @} */ 799 800 /*! 801 * @name Properties 802 * @{ 803 */ 804 805 /*! 806 * @brief Returns the desired flash property. 807 * 808 * @param config A pointer to the storage for the driver runtime state. 809 * @param whichProperty The desired property from the list of properties in 810 * enum flash_property_tag_t 811 * @param value A pointer to the value returned for the desired flash property. 812 * 813 * @retval #kStatus_FLASH_Success API was executed successfully. 814 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 815 * @retval #kStatus_FLASH_UnknownProperty An unknown property tag. 816 */ 817 status_t FLASH_GetProperty(flash_config_t *config, flash_property_tag_t whichProperty, uint32_t *value); 818 819 /*! 820 * @brief Sets the desired flash property. 821 * 822 * @param config A pointer to the storage for the driver runtime state. 823 * @param whichProperty The desired property from the list of properties in 824 * enum flash_property_tag_t 825 * @param value A to set for the desired flash property. 826 * 827 * @retval #kStatus_FLASH_Success API was executed successfully. 828 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 829 * @retval #kStatus_FLASH_UnknownProperty An unknown property tag. 830 * @retval #kStatus_FLASH_InvalidPropertyValue An invalid property value. 831 * @retval #kStatus_FLASH_ReadOnlyProperty An read-only property tag. 832 */ 833 status_t FLASH_SetProperty(flash_config_t *config, flash_property_tag_t whichProperty, uint32_t value); 834 835 /*! @} */ 836 837 /*! 838 * @name Flash Protection Utilities 839 * @{ 840 */ 841 842 /*! 843 * @brief Sets the PFlash Protection to the intended protection status. 844 * 845 * @param config A pointer to storage for the driver runtime state. 846 * @param protectStatus The expected protect status to set to the PFlash protection register. 847 * 848 * @retval #kStatus_FLASH_Success API was executed successfully. 849 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 850 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 851 */ 852 status_t FLASH_PflashSetProtection(flash_config_t *config, pflash_protection_status_t *protectStatus); 853 854 /*! 855 * @brief Gets the PFlash protection status. 856 * 857 * @param config A pointer to the storage for the driver runtime state. 858 * @param protectStatus Protect status returned by the PFlash IP. 859 * 860 * @retval #kStatus_FLASH_Success API was executed successfully. 861 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 862 */ 863 status_t FLASH_PflashGetProtection(flash_config_t *config, pflash_protection_status_t *protectStatus); 864 865 #if defined(FLASH_SSD_IS_EEPROM_ENABLED) && FLASH_SSD_IS_EEPROM_ENABLED 866 /*! 867 * @brief Sets the EEPROM protection to the intended protection status. 868 * 869 * @param config A pointer to the storage for the driver runtime state. 870 * @param protectStatus The expected protect status to set to the EEPROM protection register. 871 * 872 * @retval #kStatus_FLASH_Success API was executed successfully. 873 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 874 * @retval #kStatus_FLASH_CommandNotSupported Flash API is not supported. 875 * @retval #kStatus_FLASH_CommandFailure Run-time error during command execution. 876 */ 877 status_t FLASH_EepromSetProtection(flash_config_t *config, uint8_t protectStatus); 878 #endif /* FLASH_SSD_IS_EEPROM_ENABLED */ 879 880 #if defined(FLASH_SSD_IS_EEPROM_ENABLED) && FLASH_SSD_IS_EEPROM_ENABLED 881 /*! 882 * @brief Gets the EEPROM protection status. 883 * 884 * @param config A pointer to the storage for the driver runtime state. 885 * @param protectStatus EEPROM Protect status returned by the EEPROM IP. 886 * 887 * @retval #kStatus_FLASH_Success API was executed successfully. 888 * @retval #kStatus_FLASH_InvalidArgument An invalid argument is provided. 889 * @retval #kStatus_FLASH_CommandNotSupported Flash API is not supported. 890 */ 891 status_t FLASH_EepromGetProtection(flash_config_t *config, uint8_t *protectStatus); 892 #endif /* FLASH_SSD_IS_EEPROM_ENABLED */ 893 894 /*! @} */ 895 896 /*! 897 * @name Flash Speculation Utilities 898 * @{ 899 */ 900 901 /*! 902 * @brief Sets the PFlash prefetch speculation to the intended speculation status. 903 * 904 * @param speculationStatus The expected protect status to set to the PFlash protection register. Each bit is 905 * @retval #kStatus_FLASH_Success API was executed successfully. 906 * @retval #kStatus_FLASH_InvalidSpeculationOption An invalid speculation option argument is provided. 907 */ 908 status_t FLASH_PflashSetPrefetchSpeculation(flash_prefetch_speculation_status_t *speculationStatus); 909 910 /*! 911 * @brief Gets the PFlash prefetch speculation status. 912 * 913 * @param speculationStatus Speculation status returned by the PFlash IP. 914 * @retval #kStatus_FLASH_Success API was executed successfully. 915 */ 916 status_t FLASH_PflashGetPrefetchSpeculation(flash_prefetch_speculation_status_t *speculationStatus); 917 918 /*! @} */ 919 920 #if defined(__cplusplus) 921 } 922 #endif 923 924 /*! @}*/ 925 926 #endif /* FSL_FLASH_H_ */ 927
