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