1 /* 2 * Copyright 2013-2016 Freescale Semiconductor, Inc. 3 * Copyright 2016-2020 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 * 8 */ 9 10 #ifndef FSL_FTFX_CONTROLLER_H 11 #define FSL_FTFX_CONTROLLER_H 12 13 #include "fsl_ftfx_features.h" 14 #include "fsl_ftfx_utilities.h" 15 16 /*! 17 * @addtogroup ftfx_controller 18 * @{ 19 */ 20 /******************************************************************************* 21 * Definitions 22 ******************************************************************************/ 23 24 /*! 25 * @name FTFx status 26 * @{ 27 */ 28 /*! @brief FTFx driver status group. */ 29 #if defined(kStatusGroup_FlashDriver) 30 #define kStatusGroupGeneric kStatusGroup_Generic 31 #define kStatusGroupFtfxDriver kStatusGroup_FlashDriver 32 #elif defined(kStatusGroup_FLASH) 33 #define kStatusGroupGeneric kStatusGroup_Generic 34 #define kStatusGroupFtfxDriver kStatusGroup_FLASH 35 #else 36 #define kStatusGroupGeneric 0 37 #define kStatusGroupFtfxDriver 1 38 #endif 39 40 /*! 41 * @brief FTFx driver status codes. 42 */ 43 enum 44 { 45 kStatus_FTFx_Success = MAKE_STATUS(kStatusGroupGeneric, 0), /*!< API is executed successfully*/ 46 kStatus_FTFx_InvalidArgument = MAKE_STATUS(kStatusGroupGeneric, 4), /*!< Invalid argument*/ 47 kStatus_FTFx_SizeError = MAKE_STATUS(kStatusGroupFtfxDriver, 0), /*!< Error size*/ 48 kStatus_FTFx_AlignmentError = 49 MAKE_STATUS(kStatusGroupFtfxDriver, 1), /*!< Parameter is not aligned with the specified baseline*/ 50 kStatus_FTFx_AddressError = MAKE_STATUS(kStatusGroupFtfxDriver, 2), /*!< Address is out of range */ 51 kStatus_FTFx_AccessError = 52 MAKE_STATUS(kStatusGroupFtfxDriver, 3), /*!< Invalid instruction codes and out-of bound addresses */ 53 kStatus_FTFx_ProtectionViolation = MAKE_STATUS( 54 kStatusGroupFtfxDriver, 4), /*!< The program/erase operation is requested to execute on protected areas */ 55 kStatus_FTFx_CommandFailure = 56 MAKE_STATUS(kStatusGroupFtfxDriver, 5), /*!< Run-time error during command execution. */ 57 kStatus_FTFx_UnknownProperty = MAKE_STATUS(kStatusGroupFtfxDriver, 6), /*!< Unknown property.*/ 58 kStatus_FTFx_EraseKeyError = MAKE_STATUS(kStatusGroupFtfxDriver, 7), /*!< API erase key is invalid.*/ 59 kStatus_FTFx_RegionExecuteOnly = MAKE_STATUS(kStatusGroupFtfxDriver, 8), /*!< The current region is execute-only.*/ 60 kStatus_FTFx_ExecuteInRamFunctionNotReady = 61 MAKE_STATUS(kStatusGroupFtfxDriver, 9), /*!< Execute-in-RAM function is not available.*/ 62 kStatus_FTFx_PartitionStatusUpdateFailure = 63 MAKE_STATUS(kStatusGroupFtfxDriver, 10), /*!< Failed to update partition status.*/ 64 kStatus_FTFx_SetFlexramAsEepromError = 65 MAKE_STATUS(kStatusGroupFtfxDriver, 11), /*!< Failed to set FlexRAM as EEPROM.*/ 66 kStatus_FTFx_RecoverFlexramAsRamError = 67 MAKE_STATUS(kStatusGroupFtfxDriver, 12), /*!< Failed to recover FlexRAM as RAM.*/ 68 kStatus_FTFx_SetFlexramAsRamError = MAKE_STATUS(kStatusGroupFtfxDriver, 13), /*!< Failed to set FlexRAM as RAM.*/ 69 kStatus_FTFx_RecoverFlexramAsEepromError = 70 MAKE_STATUS(kStatusGroupFtfxDriver, 14), /*!< Failed to recover FlexRAM as EEPROM.*/ 71 kStatus_FTFx_CommandNotSupported = MAKE_STATUS(kStatusGroupFtfxDriver, 15), /*!< Flash API is not supported.*/ 72 kStatus_FTFx_SwapSystemNotInUninitialized = 73 MAKE_STATUS(kStatusGroupFtfxDriver, 16), /*!< Swap system is not in an uninitialzed state.*/ 74 kStatus_FTFx_SwapIndicatorAddressError = 75 MAKE_STATUS(kStatusGroupFtfxDriver, 17), /*!< The swap indicator address is invalid.*/ 76 kStatus_FTFx_ReadOnlyProperty = MAKE_STATUS(kStatusGroupFtfxDriver, 18), /*!< The flash property is read-only.*/ 77 kStatus_FTFx_InvalidPropertyValue = 78 MAKE_STATUS(kStatusGroupFtfxDriver, 19), /*!< The flash property value is out of range.*/ 79 kStatus_FTFx_InvalidSpeculationOption = 80 MAKE_STATUS(kStatusGroupFtfxDriver, 20), /*!< The option of flash prefetch speculation is invalid.*/ 81 kStatus_FTFx_CommandOperationInProgress = 82 MAKE_STATUS(kStatusGroupFtfxDriver, 21), /*!< The option of flash command is processing.*/ 83 }; 84 /*@}*/ 85 86 /*! 87 * @name FTFx API key 88 * @{ 89 */ 90 /*! 91 * @brief Enumeration for FTFx driver API keys. 92 * 93 * @note The resulting value is built with a byte order such that the string 94 * being readable in expected order when viewed in a hex editor, if the value 95 * is treated as a 32-bit little endian value. 96 */ 97 enum _ftfx_driver_api_keys 98 { 99 kFTFx_ApiEraseKey = FOUR_CHAR_CODE('k', 'f', 'e', 'k') /*!< Key value used to validate all FTFx erase APIs.*/ 100 }; 101 /*@}*/ 102 103 /*! 104 * @brief Enumeration for the FlexRAM load during reset option. 105 */ 106 typedef enum _ftfx_partition_flexram_load_option 107 { 108 kFTFx_PartitionFlexramLoadOptLoadedWithValidEepromData = 109 0x00U, /*!< FlexRAM is loaded with valid EEPROM data during reset sequence.*/ 110 kFTFx_PartitionFlexramLoadOptNotLoaded = 0x01U /*!< FlexRAM is not loaded during reset sequence.*/ 111 } ftfx_partition_flexram_load_opt_t; 112 113 /*! 114 * @brief Enumeration for the two possible options of flash read resource command. 115 */ 116 typedef enum _ftfx_read_resource_opt 117 { 118 kFTFx_ResourceOptionFlashIfr = 119 0x00U, /*!< Select code for Program flash 0 IFR, Program flash swap 0 IFR, Data flash 0 IFR */ 120 kFTFx_ResourceOptionVersionId = 0x01U /*!< Select code for the version ID*/ 121 } ftfx_read_resource_opt_t; 122 123 /*! 124 * @brief Enumeration for supported FTFx margin levels. 125 */ 126 typedef enum _ftfx_margin_value 127 { 128 kFTFx_MarginValueNormal, /*!< Use the 'normal' read level for 1s.*/ 129 kFTFx_MarginValueUser, /*!< Apply the 'User' margin to the normal read-1 level.*/ 130 kFTFx_MarginValueFactory, /*!< Apply the 'Factory' margin to the normal read-1 level.*/ 131 kFTFx_MarginValueInvalid /*!< Not real margin level, Used to determine the range of valid margin level. */ 132 } ftfx_margin_value_t; 133 134 /*! 135 * @brief Enumeration for the three possible FTFx security states. 136 */ 137 typedef enum _ftfx_security_state 138 { 139 kFTFx_SecurityStateNotSecure = (int)0xc33cc33cu, /*!< Flash is not secure.*/ 140 kFTFx_SecurityStateBackdoorEnabled = (int)0x5aa55aa5u, /*!< Flash backdoor is enabled.*/ 141 kFTFx_SecurityStateBackdoorDisabled = (int)0x5ac33ca5u /*!< Flash backdoor is disabled.*/ 142 } ftfx_security_state_t; 143 144 /*! 145 * @brief Enumeration for the two possilbe options of set FlexRAM function command. 146 */ 147 typedef enum _ftfx_flexram_function_option 148 { 149 kFTFx_FlexramFuncOptAvailableAsRam = 0xFFU, /*!< An option used to make FlexRAM available as RAM */ 150 kFTFx_FlexramFuncOptAvailableForEeprom = 0x00U /*!< An option used to make FlexRAM available for EEPROM */ 151 } ftfx_flexram_func_opt_t; 152 153 /*! 154 * @brief Enumeration for acceleration ram property. 155 */ 156 enum _flash_acceleration_ram_property 157 { 158 kFLASH_AccelerationRamSize = 0x400U 159 }; 160 161 #if defined(FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD) && FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD 162 /*! 163 * @brief Enumeration for the possible options of Swap control commands 164 */ 165 typedef enum _ftfx_swap_control_option 166 { 167 kFTFx_SwapControlOptionIntializeSystem = 0x01U, /*!< An option used to initialize the Swap system */ 168 kFTFx_SwapControlOptionSetInUpdateState = 0x02U, /*!< An option used to set the Swap in an update state */ 169 kFTFx_SwapControlOptionSetInCompleteState = 0x04U, /*!< An option used to set the Swap in a complete state */ 170 kFTFx_SwapControlOptionReportStatus = 0x08U, /*!< An option used to report the Swap status */ 171 kFTFx_SwapControlOptionDisableSystem = 0x10U /*!< An option used to disable the Swap status */ 172 } ftfx_swap_control_opt_t; 173 #endif /* FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD */ 174 175 /*! 176 * @brief Enumeration for the possible flash Swap status. 177 */ 178 typedef enum _ftfx_swap_state 179 { 180 kFTFx_SwapStateUninitialized = 0x00U, /*!< Flash Swap system is in an uninitialized state.*/ 181 kFTFx_SwapStateReady = 0x01U, /*!< Flash Swap system is in a ready state.*/ 182 kFTFx_SwapStateUpdate = 0x02U, /*!< Flash Swap system is in an update state.*/ 183 kFTFx_SwapStateUpdateErased = 0x03U, /*!< Flash Swap system is in an updateErased state.*/ 184 kFTFx_SwapStateComplete = 0x04U, /*!< Flash Swap system is in a complete state.*/ 185 kFTFx_SwapStateDisabled = 0x05U /*!< Flash Swap system is in a disabled state.*/ 186 } ftfx_swap_state_t; 187 188 #if defined(FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD) && FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD 189 /*! 190 * @brief Enumeration for the possible flash Swap block status 191 */ 192 typedef enum _ftfx_swap_block_status 193 { 194 kFTFx_SwapBlockStatusLowerHalfProgramBlocksAtZero = 195 0x00U, /*!< Swap block status is that lower half program block at zero.*/ 196 kFTFx_SwapBlockStatusUpperHalfProgramBlocksAtZero = 197 0x01U, /*!< Swap block status is that upper half program block at zero.*/ 198 } ftfx_swap_block_status_t; 199 200 /*! 201 * @brief Flash Swap information 202 */ 203 typedef struct _ftfx_swap_state_config 204 { 205 ftfx_swap_state_t flashSwapState; /*!<The current Swap system status.*/ 206 ftfx_swap_block_status_t currentSwapBlockStatus; /*!< The current Swap block status.*/ 207 ftfx_swap_block_status_t nextSwapBlockStatus; /*!< The next Swap block status.*/ 208 } ftfx_swap_state_config_t; 209 #endif /* FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD */ 210 211 /*! 212 * @brief Enumeration for FTFx memory type. 213 */ 214 enum _ftfx_memory_type 215 { 216 kFTFx_MemTypePflash = 0x00U, 217 kFTFx_MemTypeFlexnvm = 0x01U 218 }; 219 220 /*! 221 * @brief ftfx special memory access information. 222 */ 223 typedef struct _ftfx_special_mem 224 { 225 uint32_t base; /*!< Base address of flash special memory.*/ 226 uint32_t size; /*!< size of flash special memory.*/ 227 uint32_t count; /*!< flash special memory count.*/ 228 } ftfx_spec_mem_t; 229 230 #if defined(__CC_ARM) 231 #pragma anon_unions 232 #endif 233 /*! 234 * @brief Flash memory descriptor. 235 */ 236 typedef struct _ftfx_mem_descriptor 237 { 238 struct 239 { 240 uint8_t type; /*!< Type of flash block.*/ 241 uint8_t index; /*!< Index of flash block.*/ 242 uint8_t reserved[2]; 243 }; 244 struct 245 { 246 uint32_t isIndBlock : 1; 247 uint32_t hasIndPfsizeReg : 1; 248 uint32_t hasProtControl : 1; 249 uint32_t hasIndProtReg : 1; 250 uint32_t hasXaccControl : 1; 251 uint32_t hasIndXaccReg : 1; 252 uint32_t : 18; 253 uint32_t ProtRegBits : 8; 254 } feature; 255 uint32_t blockBase; /*!< A base address of the flash block */ 256 #if defined(FSL_FEATURE_FLASH_HAS_FLEX_NVM_ALIAS) && FSL_FEATURE_FLASH_HAS_FLEX_NVM_ALIAS 257 uint32_t aliasBlockBase; /*!< A base address of the alias flash block */ 258 #endif 259 uint32_t totalSize; /*!< The size of the flash block. */ 260 uint32_t sectorSize; /*!< The size in bytes of a sector of flash. */ 261 uint32_t blockCount; /*!< A number of flash blocks. */ 262 ftfx_spec_mem_t accessSegmentMem; 263 ftfx_spec_mem_t protectRegionMem; 264 } ftfx_mem_desc_t; 265 266 /*! 267 * @brief Active FTFx information for the current operation. 268 */ 269 typedef struct _ftfx_ops_config 270 { 271 uint32_t convertedAddress; /*!< A converted address for the current flash type.*/ 272 struct 273 { 274 uint8_t sectorCmd; 275 uint8_t sectionCmd; 276 uint8_t resourceCmd; 277 uint8_t checkCmd; 278 uint8_t swapCtrlCmd; 279 uint8_t blockWriteUnitSize; 280 uint8_t reserved[2]; 281 } addrAligment; 282 } ftfx_ops_config_t; 283 284 /*! 285 * @brief Flash IFR memory descriptor. 286 */ 287 typedef struct _ftfx_ifr_descriptor 288 { 289 struct 290 { 291 uint32_t has4ByteIdxSupport : 1; 292 uint32_t has8ByteIdxSupport : 1; 293 uint32_t : 30; 294 } feature; 295 struct 296 { 297 uint8_t versionIdStart; /*!< Version ID start address */ 298 uint8_t versionIdSize; 299 uint16_t ifrMemSize; 300 uint32_t pflashIfrStart; /*!< Program Flash 0 IFR start address */ 301 uint32_t dflashIfrStart; /*!< Data Flash 0 IFR start address */ 302 uint32_t pflashSwapIfrStart; /*!< Program Flash Swap IFR start address*/ 303 } resRange; 304 struct 305 { 306 uint16_t mix8byteIdxStart; 307 uint16_t mix8byteIdxEnd; 308 } idxInfo; 309 } ftfx_ifr_desc_t; 310 311 typedef union 312 { 313 uint32_t commadAddr; 314 void (*callFlashCommand)(FTFx_REG8_ACCESS_TYPE FTMRx_fstat); 315 } function_ptr_t; 316 317 /*! @brief Flash driver state information. 318 * 319 * An instance of this structure is allocated by the user of the flash driver and 320 * passed into each of the driver APIs. 321 */ 322 typedef struct _ftfx_config 323 { 324 ftfx_mem_desc_t flashDesc; 325 ftfx_ops_config_t opsConfig; 326 uint32_t flexramBlockBase; /*!< The base address of the FlexRAM/acceleration RAM */ 327 uint32_t flexramTotalSize; /*!< The size of the FlexRAM/acceleration RAM */ 328 uint16_t eepromTotalSize; /*!< The size of EEPROM area which was partitioned from FlexRAM */ 329 uint16_t reserved; 330 function_ptr_t runCmdFuncAddr; /*!< An buffer point to the flash execute-in-RAM function. */ 331 ftfx_ifr_desc_t ifrDesc; 332 } ftfx_config_t; 333 334 /******************************************************************************* 335 * API 336 ******************************************************************************/ 337 338 #if defined(__cplusplus) 339 extern "C" { 340 #endif 341 342 /*! 343 * @name Initialization 344 * @{ 345 */ 346 347 /*! 348 * @brief Initializes the global flash properties structure members. 349 * 350 * This function checks and initializes the Flash module for the other Flash APIs. 351 * 352 * @param config Pointer to the storage for the driver runtime state. 353 * 354 */ 355 void FTFx_API_Init(ftfx_config_t *config); 356 357 #if defined(FSL_FEATURE_FLASH_HAS_FLEX_NVM) && FSL_FEATURE_FLASH_HAS_FLEX_NVM 358 /*! 359 * @brief Updates FlexNVM memory partition status according to data flash 0 IFR. 360 * 361 * This function updates FlexNVM memory partition status. 362 * 363 * @param config Pointer to the storage for the driver runtime state. 364 * 365 * @retval #kStatus_FTFx_Success API was executed successfully. 366 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 367 * @retval #kStatus_FTFx_PartitionStatusUpdateFailure Failed to update the partition status. 368 */ 369 status_t FTFx_API_UpdateFlexnvmPartitionStatus(ftfx_config_t *config); 370 #endif /* FSL_FEATURE_FLASH_HAS_FLEX_NVM */ 371 372 /*@}*/ 373 374 /*! 375 * @name Erasing 376 * @{ 377 */ 378 379 /*! 380 * @brief Erases the flash sectors encompassed by parameters passed into function. 381 * 382 * This function erases the appropriate number of flash sectors based on the 383 * desired start address and length. 384 * 385 * @param config The pointer to the storage for the driver runtime state. 386 * @param start The start address of the desired flash memory to be erased. 387 * The start address does not need to be sector-aligned but must be word-aligned. 388 * @param lengthInBytes The length, given in bytes (not words or long-words) 389 * to be erased. Must be word-aligned. 390 * @param key The value used to validate all flash erase APIs. 391 * 392 * @retval #kStatus_FTFx_Success API was executed successfully. 393 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 394 * @retval #kStatus_FTFx_AlignmentError The parameter is not aligned with the specified baseline. 395 * @retval #kStatus_FTFx_AddressError The address is out of range. 396 * @retval #kStatus_FTFx_EraseKeyError The API erase key is invalid. 397 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 398 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 399 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 400 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 401 */ 402 status_t FTFx_CMD_Erase(ftfx_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key); 403 404 /*! 405 * @brief Erases the flash sectors encompassed by parameters passed into function. 406 * 407 * This function erases one flash sector size based on the start address. 408 * 409 * @param config The pointer to the storage for the driver runtime state. 410 * @param start The start address of the desired flash memory to be erased. 411 * The start address does not need to be sector-aligned but must be word-aligned. 412 * @param key The value used to validate all flash erase APIs. 413 * 414 * @retval #kStatus_FTFx_Success API was executed successfully. 415 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 416 * @retval #kStatus_FTFx_AlignmentError The parameter is not aligned with the specified baseline. 417 * @retval #kStatus_FTFx_AddressError The address is out of range. 418 * @retval #kStatus_FTFx_EraseKeyError The API erase key is invalid. 419 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 420 */ 421 status_t FTFx_CMD_EraseSectorNonBlocking(ftfx_config_t *config, uint32_t start, uint32_t key); 422 423 /*! 424 * @brief Erases entire flash 425 * 426 * @param config Pointer to the storage for the driver runtime state. 427 * @param key A value used to validate all flash erase APIs. 428 * 429 * @retval #kStatus_FTFx_Success API was executed successfully. 430 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 431 * @retval #kStatus_FTFx_EraseKeyError API erase key is invalid. 432 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 433 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 434 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 435 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 436 * @retval #kStatus_FTFx_PartitionStatusUpdateFailure Failed to update the partition status. 437 */ 438 status_t FTFx_CMD_EraseAll(ftfx_config_t *config, uint32_t key); 439 440 #if defined(FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD) && FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD 441 /*! 442 * @brief Erases the entire flash, including protected sectors. 443 * 444 * @param config Pointer to the storage for the driver runtime state. 445 * @param key A value used to validate all flash erase APIs. 446 * 447 * @retval #kStatus_FTFx_Success API was executed successfully. 448 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 449 * @retval #kStatus_FTFx_EraseKeyError API erase key is invalid. 450 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 451 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 452 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 453 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 454 * @retval #kStatus_FTFx_PartitionStatusUpdateFailure Failed to update the partition status. 455 */ 456 status_t FTFx_CMD_EraseAllUnsecure(ftfx_config_t *config, uint32_t key); 457 #endif /* FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD */ 458 459 /*! 460 * @brief Erases all program flash execute-only segments defined by the FXACC registers. 461 * 462 * @param config Pointer to the storage for the driver runtime state. 463 * @param key A value used to validate all flash erase APIs. 464 * 465 * @retval #kStatus_FTFx_Success API was executed successfully. 466 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 467 * @retval #kStatus_FTFx_EraseKeyError API erase key is invalid. 468 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 469 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 470 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 471 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 472 */ 473 status_t FTFx_CMD_EraseAllExecuteOnlySegments(ftfx_config_t *config, uint32_t key); 474 475 /*@}*/ 476 477 /*! 478 * @name Programming 479 * @{ 480 */ 481 482 /*! 483 * @brief Programs flash with data at locations passed in through parameters. 484 * 485 * This function programs the flash memory with the desired data for a given 486 * flash area as determined by the start address and the length. 487 * 488 * @param config A pointer to the storage for the driver runtime state. 489 * @param start The start address of the desired flash memory to be programmed. Must be 490 * word-aligned. 491 * @param src A pointer to the source buffer of data that is to be programmed 492 * into the flash. 493 * @param lengthInBytes The length, given in bytes (not words or long-words), 494 * to be programmed. Must be word-aligned. 495 * 496 * @retval #kStatus_FTFx_Success API was executed successfully. 497 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 498 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with the specified baseline. 499 * @retval #kStatus_FTFx_AddressError Address is out of range. 500 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 501 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 502 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 503 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 504 */ 505 status_t FTFx_CMD_Program(ftfx_config_t *config, uint32_t start, const uint8_t *src, uint32_t lengthInBytes); 506 507 /*! 508 * @brief Programs Program Once Field through parameters. 509 * 510 * This function programs the Program Once Field with the desired data for a given 511 * flash area as determined by the index and length. 512 * 513 * @param config A pointer to the storage for the driver runtime state. 514 * @param index The index indicating which area of the Program Once Field to be programmed. 515 * @param src A pointer to the source buffer of data that is to be programmed 516 * into the Program Once Field. 517 * @param lengthInBytes The length, given in bytes (not words or long-words), 518 * to be programmed. Must be word-aligned. 519 * 520 * @retval #kStatus_FTFx_Success API was executed successfully. 521 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 522 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 523 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 524 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 525 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 526 */ 527 status_t FTFx_CMD_ProgramOnce(ftfx_config_t *config, uint32_t index, const uint8_t *src, uint32_t lengthInBytes); 528 529 #if defined(FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD) && FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD 530 /*! 531 * @brief Programs flash with data at locations passed in through parameters via the Program Section command. 532 * 533 * This function programs the flash memory with the desired data for a given 534 * flash area as determined by the start address and length. 535 * 536 * @param config A pointer to the storage for the driver runtime state. 537 * @param start The start address of the desired flash memory to be programmed. Must be 538 * word-aligned. 539 * @param src A pointer to the source buffer of data that is to be programmed 540 * into the flash. 541 * @param lengthInBytes The length, given in bytes (not words or long-words), 542 * to be programmed. Must be word-aligned. 543 * 544 * @retval #kStatus_FTFx_Success API was executed successfully. 545 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 546 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 547 * @retval #kStatus_FTFx_AddressError Address is out of range. 548 * @retval #kStatus_FTFx_SetFlexramAsRamError Failed to set flexram as RAM. 549 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 550 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 551 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 552 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 553 * @retval #kStatus_FTFx_RecoverFlexramAsEepromError Failed to recover FlexRAM as EEPROM. 554 */ 555 status_t FTFx_CMD_ProgramSection(ftfx_config_t *config, uint32_t start, const uint8_t *src, uint32_t lengthInBytes); 556 #endif /* FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD */ 557 558 #if defined(FSL_FEATURE_FLASH_HAS_PROGRAM_PARTITION_CMD) && FSL_FEATURE_FLASH_HAS_PROGRAM_PARTITION_CMD 559 /*! 560 * @brief Prepares the FlexNVM block for use as data flash, EEPROM backup, or a combination of both and initializes the 561 * FlexRAM. 562 * 563 * @param config Pointer to storage for the driver runtime state. 564 * @param option The option used to set FlexRAM load behavior during reset. 565 * @param eepromDataSizeCode Determines the amount of FlexRAM used in each of the available EEPROM subsystems. 566 * @param flexnvmPartitionCode Specifies how to split the FlexNVM block between data flash memory and EEPROM backup 567 * memory supporting EEPROM functions. 568 * 569 * @retval #kStatus_FTFx_Success API was executed successfully. 570 * @retval #kStatus_FTFx_InvalidArgument Invalid argument is provided. 571 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 572 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 573 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 574 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 575 */ 576 status_t FTFx_CMD_ProgramPartition(ftfx_config_t *config, 577 ftfx_partition_flexram_load_opt_t option, 578 uint32_t eepromDataSizeCode, 579 uint32_t flexnvmPartitionCode); 580 #endif /* FSL_FEATURE_FLASH_HAS_PROGRAM_PARTITION_CMD */ 581 582 /*@}*/ 583 584 /*! 585 * @name Reading 586 * @{ 587 */ 588 589 /*! 590 * @brief Reads the Program Once Field through parameters. 591 * 592 * This function reads the read once feild with given index and length. 593 * 594 * @param config A pointer to the storage for the driver runtime state. 595 * @param index The index indicating the area of program once field to be read. 596 * @param dst A pointer to the destination buffer of data that is used to store 597 * data to be read. 598 * @param lengthInBytes The length, given in bytes (not words or long-words), 599 * to be programmed. Must be word-aligned. 600 * 601 * @retval #kStatus_FTFx_Success API was executed successfully. 602 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 603 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 604 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 605 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 606 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 607 */ 608 status_t FTFx_CMD_ReadOnce(ftfx_config_t *config, uint32_t index, uint8_t *dst, uint32_t lengthInBytes); 609 610 #if defined(FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD) && FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD 611 /*! 612 * @brief Reads the resource with data at locations passed in through parameters. 613 * 614 * This function reads the flash memory with the desired location for a given 615 * flash area as determined by the start address and length. 616 * 617 * @param config A pointer to the storage for the driver runtime state. 618 * @param start The start address of the desired flash memory to be programmed. Must be 619 * word-aligned. 620 * @param dst A pointer to the destination buffer of data that is used to store 621 * data to be read. 622 * @param lengthInBytes The length, given in bytes (not words or long-words), 623 * to be read. Must be word-aligned. 624 * @param option The resource option which indicates which area should be read back. 625 * 626 * @retval #kStatus_FTFx_Success API was executed successfully. 627 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 628 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with the specified baseline. 629 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 630 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 631 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 632 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 633 */ 634 status_t FTFx_CMD_ReadResource( 635 ftfx_config_t *config, uint32_t start, uint8_t *dst, uint32_t lengthInBytes, ftfx_read_resource_opt_t option); 636 #endif /* FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD */ 637 638 /*@}*/ 639 640 /*! 641 * @name Verification 642 * @{ 643 */ 644 645 /*! 646 * @brief Verifies an erasure of the desired flash area at a specified margin level. 647 * 648 * This function checks the appropriate number of flash sectors based on 649 * the desired start address and length to check whether the flash is erased 650 * to the specified read margin level. 651 * 652 * @param config A pointer to the storage for the driver runtime state. 653 * @param start The start address of the desired flash memory to be verified. 654 * The start address does not need to be sector-aligned but must be word-aligned. 655 * @param lengthInBytes The length, given in bytes (not words or long-words), 656 * to be verified. Must be word-aligned. 657 * @param margin Read margin choice. 658 * 659 * @retval #kStatus_FTFx_Success API was executed successfully. 660 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 661 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 662 * @retval #kStatus_FTFx_AddressError Address is out of range. 663 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 664 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 665 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 666 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 667 */ 668 status_t FTFx_CMD_VerifyErase(ftfx_config_t *config, 669 uint32_t start, 670 uint32_t lengthInBytes, 671 ftfx_margin_value_t margin); 672 673 /*! 674 * @brief Verifies erasure of the entire flash at a specified margin level. 675 * 676 * This function checks whether the flash is erased to the 677 * specified read margin level. 678 * 679 * @param config A pointer to the storage for the driver runtime state. 680 * @param margin Read margin choice. 681 * 682 * @retval #kStatus_FTFx_Success API was executed successfully. 683 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 684 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 685 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 686 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 687 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 688 */ 689 status_t FTFx_CMD_VerifyEraseAll(ftfx_config_t *config, ftfx_margin_value_t margin); 690 691 /*! 692 * @brief Verifies whether the program flash execute-only segments have been erased to 693 * the specified read margin level. 694 * 695 * @param config A pointer to the storage for the driver runtime state. 696 * @param margin Read margin choice. 697 * 698 * @retval #kStatus_FTFx_Success API was executed successfully. 699 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 700 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 701 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 702 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 703 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 704 */ 705 status_t FTFx_CMD_VerifyEraseAllExecuteOnlySegments(ftfx_config_t *config, ftfx_margin_value_t margin); 706 707 /*! 708 * @brief Verifies programming of the desired flash area at a specified margin level. 709 * 710 * This function verifies the data programed in the flash memory using the 711 * Flash Program Check Command and compares it to the expected data for a given 712 * flash area as determined by the start address and length. 713 * 714 * @param config A pointer to the storage for the driver runtime state. 715 * @param start The start address of the desired flash memory to be verified. Must be word-aligned. 716 * @param lengthInBytes The length, given in bytes (not words or long-words), 717 * to be verified. Must be word-aligned. 718 * @param expectedData A pointer to the expected data that is to be 719 * verified against. 720 * @param margin Read margin choice. 721 * @param failedAddress A pointer to the returned failing address. 722 * @param failedData A pointer to the returned failing data. Some derivatives do 723 * not include failed data as part of the FCCOBx registers. In this 724 * case, zeros are returned upon failure. 725 * 726 * @retval #kStatus_FTFx_Success API was executed successfully. 727 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 728 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 729 * @retval #kStatus_FTFx_AddressError Address is out of range. 730 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 731 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 732 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 733 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 734 */ 735 status_t FTFx_CMD_VerifyProgram(ftfx_config_t *config, 736 uint32_t start, 737 uint32_t lengthInBytes, 738 const uint8_t *expectedData, 739 ftfx_margin_value_t margin, 740 uint32_t *failedAddress, 741 uint32_t *failedData); 742 743 /*@}*/ 744 745 /*! 746 * @name Security 747 * @{ 748 */ 749 750 /*! 751 * @brief Returns the security state via the pointer passed into the function. 752 * 753 * This function retrieves the current flash security status, including the 754 * security enabling state and the backdoor key enabling state. 755 * 756 * @param config A pointer to storage for the driver runtime state. 757 * @param state A pointer to the value returned for the current security status code: 758 * 759 * @retval #kStatus_FTFx_Success API was executed successfully. 760 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 761 */ 762 status_t FTFx_REG_GetSecurityState(ftfx_config_t *config, ftfx_security_state_t *state); 763 764 /*! 765 * @brief Allows users to bypass security with a backdoor key. 766 * 767 * If the MCU is in secured state, this function unsecures the MCU by 768 * comparing the provided backdoor key with ones in the flash configuration 769 * field. 770 * 771 * @param config A pointer to the storage for the driver runtime state. 772 * @param backdoorKey A pointer to the user buffer containing the backdoor key. 773 * 774 * @retval #kStatus_FTFx_Success API was executed successfully. 775 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 776 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 777 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 778 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 779 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 780 */ 781 status_t FTFx_CMD_SecurityBypass(ftfx_config_t *config, const uint8_t *backdoorKey); 782 783 /*@}*/ 784 785 /*! 786 * @name FlexRAM 787 * @{ 788 */ 789 790 #if defined(FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD) && FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD 791 /*! 792 * @brief Sets the FlexRAM function command. 793 * 794 * @param config A pointer to the storage for the driver runtime state. 795 * @param option The option used to set the work mode of FlexRAM. 796 * 797 * @retval #kStatus_FTFx_Success API was executed successfully. 798 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 799 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 800 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 801 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 802 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 803 */ 804 status_t FTFx_CMD_SetFlexramFunction(ftfx_config_t *config, ftfx_flexram_func_opt_t option); 805 #endif /* FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD */ 806 807 /*@}*/ 808 809 /*! 810 * @name Swap 811 * @{ 812 */ 813 814 #if defined(FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD) && FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD 815 /*! 816 * @brief Configures the Swap function or checks the swap state of the Flash module. 817 * 818 * @param config A pointer to the storage for the driver runtime state. 819 * @param address Address used to configure the flash Swap function. 820 * @param option The possible option used to configure Flash Swap function or check the flash Swap status 821 * @param returnInfo A pointer to the data which is used to return the information of flash Swap. 822 * 823 * @retval #kStatus_FTFx_Success API was executed successfully. 824 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 825 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 826 * @retval #kStatus_FTFx_SwapIndicatorAddressError Swap indicator address is invalid. 827 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 828 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 829 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 830 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 831 */ 832 status_t FTFx_CMD_SwapControl(ftfx_config_t *config, 833 uint32_t address, 834 ftfx_swap_control_opt_t option, 835 ftfx_swap_state_config_t *returnInfo); 836 #endif /* FSL_FEATURE_FLASH_HAS_SWAP_CONTROL_CMD */ 837 838 /*@}*/ 839 840 #if defined(__cplusplus) 841 } 842 #endif 843 844 /*! @}*/ 845 846 #endif /* FSL_FTFX_CONTROLLER_H */ 847
