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