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_FLASH_H 11 #define FSL_FTFX_FLASH_H 12 13 #include "fsl_ftfx_controller.h" 14 15 /*! 16 * @addtogroup ftfx_flash_driver 17 * @{ 18 */ 19 /******************************************************************************* 20 * Definitions 21 ******************************************************************************/ 22 #define kStatus_FLASH_Success kStatus_FTFx_Success 23 #define kFLASH_ApiEraseKey kFTFx_ApiEraseKey 24 25 /*! 26 * @name Flash version 27 * @{ 28 */ 29 /*! @brief Flash driver version for SDK*/ 30 #define FSL_FLASH_DRIVER_VERSION (MAKE_VERSION(3U, 1U, 2U)) /*!< Version 3.1.2. */ 31 32 /*! @brief Flash driver version for ROM*/ 33 #define FSL_FLASH_DRIVER_VERSION_ROM (MAKE_VERSION(3U, 0U, 0U)) /*!< Version 3.0.0. */ 34 35 /*@}*/ 36 37 /*! 38 * @brief Enumeration for the three possible flash protection levels. 39 */ 40 typedef enum _flash_protection_state 41 { 42 kFLASH_ProtectionStateUnprotected, /*!< Flash region is not protected.*/ 43 kFLASH_ProtectionStateProtected, /*!< Flash region is protected.*/ 44 kFLASH_ProtectionStateMixed /*!< Flash is mixed with protected and unprotected region.*/ 45 } flash_prot_state_t; 46 47 /*! 48 * @brief PFlash protection status 49 */ 50 typedef union _pflash_protection_status 51 { 52 uint32_t protl; /*!< PROT[31:0] .*/ 53 uint32_t proth; /*!< PROT[63:32].*/ 54 uint8_t protsl; /*!< PROTS[7:0] .*/ 55 uint8_t protsh; /*!< PROTS[15:8] .*/ 56 uint8_t reserved[2]; 57 } pflash_prot_status_t; 58 59 #if defined(FSL_FEATURE_FLASH_HAS_ACCESS_CONTROL) && FSL_FEATURE_FLASH_HAS_ACCESS_CONTROL 60 /*! 61 * @brief Enumeration for the three possible flash execute access levels. 62 */ 63 typedef enum _flash_execute_only_access_state 64 { 65 kFLASH_AccessStateUnLimited, /*!< Flash region is unlimited.*/ 66 kFLASH_AccessStateExecuteOnly, /*!< Flash region is execute only.*/ 67 kFLASH_AccessStateMixed /*!< Flash is mixed with unlimited and execute only region.*/ 68 } flash_xacc_state_t; 69 #endif /* not define FSL_FEATURE_FLASH_HAS_ACCESS_CONTROL */ 70 71 /*! 72 * @brief Enumeration for various flash properties. 73 */ 74 typedef enum _flash_property_tag 75 { 76 kFLASH_PropertyPflash0SectorSize = 0x00U, /*!< Pflash sector size property.*/ 77 kFLASH_PropertyPflash0TotalSize = 0x01U, /*!< Pflash total size property.*/ 78 kFLASH_PropertyPflash0BlockSize = 0x02U, /*!< Pflash block size property.*/ 79 kFLASH_PropertyPflash0BlockCount = 0x03U, /*!< Pflash block count property.*/ 80 kFLASH_PropertyPflash0BlockBaseAddr = 0x04U, /*!< Pflash block base address property.*/ 81 kFLASH_PropertyPflash0FacSupport = 0x05U, /*!< Pflash fac support property.*/ 82 kFLASH_PropertyPflash0AccessSegmentSize = 0x06U, /*!< Pflash access segment size property.*/ 83 kFLASH_PropertyPflash0AccessSegmentCount = 0x07U, /*!< Pflash access segment count property.*/ 84 85 kFLASH_PropertyPflash1SectorSize = 0x10U, /*!< Pflash sector size property.*/ 86 kFLASH_PropertyPflash1TotalSize = 0x11U, /*!< Pflash total size property.*/ 87 kFLASH_PropertyPflash1BlockSize = 0x12U, /*!< Pflash block size property.*/ 88 kFLASH_PropertyPflash1BlockCount = 0x13U, /*!< Pflash block count property.*/ 89 kFLASH_PropertyPflash1BlockBaseAddr = 0x14U, /*!< Pflash block base address property.*/ 90 kFLASH_PropertyPflash1FacSupport = 0x15U, /*!< Pflash fac support property.*/ 91 kFLASH_PropertyPflash1AccessSegmentSize = 0x16U, /*!< Pflash access segment size property.*/ 92 kFLASH_PropertyPflash1AccessSegmentCount = 0x17U, /*!< Pflash access segment count property.*/ 93 94 kFLASH_PropertyFlexRamBlockBaseAddr = 0x20U, /*!< FlexRam block base address property.*/ 95 kFLASH_PropertyFlexRamTotalSize = 0x21U, /*!< FlexRam total size property.*/ 96 } flash_property_tag_t; 97 98 /*! @brief Flash driver state information. 99 * 100 * An instance of this structure is allocated by the user of the flash driver and 101 * passed into each of the driver APIs. 102 */ 103 typedef struct _flash_config 104 { 105 ftfx_config_t ftfxConfig[FTFx_FLASH_COUNT]; 106 } flash_config_t; 107 108 /******************************************************************************* 109 * API 110 ******************************************************************************/ 111 112 #if defined(__cplusplus) 113 extern "C" { 114 #endif 115 116 /*! 117 * @name Initialization 118 * @{ 119 */ 120 121 /*! 122 * @brief Initializes the global flash properties structure members. 123 * 124 * This function checks and initializes the Flash module for the other Flash APIs. 125 * 126 * @param config Pointer to the storage for the driver runtime state. 127 * 128 * @retval #kStatus_FTFx_Success API was executed successfully. 129 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 130 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 131 * @retval #kStatus_FTFx_PartitionStatusUpdateFailure Failed to update the partition status. 132 */ 133 status_t FLASH_Init(flash_config_t *config); 134 135 /*@}*/ 136 137 /*! 138 * @name Erasing 139 * @{ 140 */ 141 142 /*! 143 * @brief Erases the Dflash sectors encompassed by parameters passed into function. 144 * 145 * This function erases the appropriate number of flash sectors based on the 146 * desired start address and length. 147 * 148 * @param config The pointer to the storage for the driver runtime state. 149 * @param start The start address of the desired flash memory to be erased. 150 * The start address does not need to be sector-aligned but must be word-aligned. 151 * @param lengthInBytes The length, given in bytes (not words or long-words) 152 * to be erased. Must be word-aligned. 153 * @param key The value used to validate all flash erase APIs. 154 * 155 * @retval #kStatus_FTFx_Success API was executed successfully; the appropriate number of flash sectors based on the 156 * desired start address and length were erased successfully. 157 * 158 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 159 * @retval #kStatus_FTFx_AlignmentError The parameter is not aligned with the specified baseline. 160 * @retval #kStatus_FTFx_AddressError The address is out of range. 161 * @retval #kStatus_FTFx_EraseKeyError The API erase key is invalid. 162 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 163 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 164 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 165 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 166 */ 167 status_t FLASH_Erase(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key); 168 169 /*! 170 * @brief Erases the Dflash sectors encompassed by parameters passed into function. 171 * 172 * This function erases one flash sector size based on the start address, and it is 173 * executed asynchronously. 174 * 175 * NOTE: This function can only erase one flash sector at a time, and the other commands 176 * can be executed after the previous command has been completed. 177 * 178 * @param config The pointer to the storage for the driver runtime state. 179 * @param start The start address of the desired flash memory to be erased. 180 * The start address does not need to be sector-aligned but must be word-aligned. 181 * @param key The value used to validate all flash erase APIs. 182 * 183 * @retval #kStatus_FTFx_Success API was executed successfully. 184 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 185 * @retval #kStatus_FTFx_AlignmentError The parameter is not aligned with the specified baseline. 186 * @retval #kStatus_FTFx_AddressError The address is out of range. 187 * @retval #kStatus_FTFx_EraseKeyError The API erase key is invalid. 188 */ 189 status_t FLASH_EraseSectorNonBlocking(flash_config_t *config, uint32_t start, uint32_t key); 190 191 /*! 192 * @brief Erases entire flexnvm 193 * 194 * @param config Pointer to the storage for the driver runtime state. 195 * @param key A value used to validate all flash erase APIs. 196 * 197 * @retval #kStatus_FTFx_Success API was executed successfully; the all pflash and flexnvm were erased successfully, 198 * the swap and eeprom have been reset to unconfigured state. 199 * 200 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 201 * @retval #kStatus_FTFx_EraseKeyError API erase key is invalid. 202 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 203 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 204 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 205 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 206 * @retval #kStatus_FTFx_PartitionStatusUpdateFailure Failed to update the partition status. 207 */ 208 status_t FLASH_EraseAll(flash_config_t *config, uint32_t key); 209 210 #if defined(FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD) && FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD 211 /*! 212 * @brief Erases the entire flexnvm, including protected sectors. 213 * 214 * @param config Pointer to the storage for the driver runtime state. 215 * @param key A value used to validate all flash erase APIs. 216 * 217 * @retval #kStatus_FTFx_Success API was executed successfully; 218 * the protected sectors of flash were reset to unprotected status. 219 * 220 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 221 * @retval #kStatus_FTFx_EraseKeyError API erase key is invalid. 222 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 223 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 224 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 225 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 226 * @retval #kStatus_FTFx_PartitionStatusUpdateFailure Failed to update the partition status. 227 */ 228 status_t FLASH_EraseAllUnsecure(flash_config_t *config, uint32_t key); 229 #endif /* FSL_FEATURE_FLASH_HAS_ERASE_ALL_BLOCKS_UNSECURE_CMD */ 230 231 /*@}*/ 232 233 /*! 234 * @name Programming 235 * @{ 236 */ 237 238 /*! 239 * @brief Programs flash with data at locations passed in through parameters. 240 * 241 * This function programs the flash memory with the desired data for a given 242 * flash area as determined by the start address and the length. 243 * 244 * @param config A pointer to the storage for the driver runtime state. 245 * @param start The start address of the desired flash memory to be programmed. Must be 246 * word-aligned. 247 * @param src A pointer to the source buffer of data that is to be programmed 248 * into the flash. 249 * @param lengthInBytes The length, given in bytes (not words or long-words), 250 * to be programmed. Must be word-aligned. 251 * 252 * @retval #kStatus_FTFx_Success API was executed successfully; the desired data were programed successfully 253 * into flash based on desired start address and length. 254 * 255 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 256 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with the specified baseline. 257 * @retval #kStatus_FTFx_AddressError Address is out of range. 258 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 259 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 260 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 261 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 262 */ 263 status_t FLASH_Program(flash_config_t *config, uint32_t start, uint8_t *src, uint32_t lengthInBytes); 264 265 /*! 266 * @brief Program the Program-Once-Field through parameters. 267 * 268 * This function Program the Program-once-feild with given index and length. 269 * 270 * @param config A pointer to the storage for the driver runtime state. 271 * @param index The index indicating the area of program once field to be read. 272 * @param src A pointer to the source buffer of data that is used to store 273 * data to be write. 274 * @param lengthInBytes The length, given in bytes (not words or long-words), 275 * to be programmed. Must be word-aligned. 276 * 277 * @retval #kStatus_FTFx_Success API was executed successfully; The index indicating the area 278 * of program once field was programed successfully. 279 * 280 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 281 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 282 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 283 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 284 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 285 */ 286 status_t FLASH_ProgramOnce(flash_config_t *config, uint32_t index, uint8_t *src, uint32_t lengthInBytes); 287 288 #if defined(FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD) && FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD 289 /*! 290 * @brief Programs flash with data at locations passed in through parameters via the Program Section command. 291 * 292 * This function programs the flash memory with the desired data for a given 293 * flash area as determined by the start address and length. 294 * 295 * @param config A pointer to the storage for the driver runtime state. 296 * @param start The start address of the desired flash memory to be programmed. Must be 297 * word-aligned. 298 * @param src A pointer to the source buffer of data that is to be programmed 299 * into the flash. 300 * @param lengthInBytes The length, given in bytes (not words or long-words), 301 * to be programmed. Must be word-aligned. 302 * 303 * @retval #kStatus_FTFx_Success API was executed successfully; the desired data have been programed successfully into 304 * flash based on start address and length. 305 * 306 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 307 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 308 * @retval #kStatus_FTFx_AddressError Address is out of range. 309 * @retval #kStatus_FTFx_SetFlexramAsRamError Failed to set flexram as RAM. 310 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 311 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 312 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 313 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 314 * @retval #kStatus_FTFx_RecoverFlexramAsEepromError Failed to recover FlexRAM as EEPROM. 315 */ 316 status_t FLASH_ProgramSection(flash_config_t *config, uint32_t start, uint8_t *src, uint32_t lengthInBytes); 317 #endif /* FSL_FEATURE_FLASH_HAS_PROGRAM_SECTION_CMD */ 318 319 /*@}*/ 320 321 /*! 322 * @name Reading 323 * @{ 324 */ 325 326 #if defined(FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD) && FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD 327 /*! 328 * @brief Reads the resource with data at locations passed in through parameters. 329 * 330 * This function reads the flash memory with the desired location for a given 331 * flash area as determined by the start address and length. 332 * 333 * @param config A pointer to the storage for the driver runtime state. 334 * @param start The start address of the desired flash memory to be programmed. Must be 335 * word-aligned. 336 * @param dst A pointer to the destination buffer of data that is used to store 337 * data to be read. 338 * @param lengthInBytes The length, given in bytes (not words or long-words), 339 * to be read. Must be word-aligned. 340 * @param option The resource option which indicates which area should be read back. 341 * 342 * @retval #kStatus_FTFx_Success API was executed successfully; the data have been read successfully from 343 * program flash IFR, data flash IFR space, and the Version ID field. 344 * 345 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 346 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with the specified baseline. 347 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 348 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 349 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 350 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 351 */ 352 status_t FLASH_ReadResource( 353 flash_config_t *config, uint32_t start, uint8_t *dst, uint32_t lengthInBytes, ftfx_read_resource_opt_t option); 354 #endif /* FSL_FEATURE_FLASH_HAS_READ_RESOURCE_CMD */ 355 356 /*! 357 * @brief Reads the Program Once Field through parameters. 358 * 359 * This function reads the read once feild with given index and length. 360 * 361 * @param config A pointer to the storage for the driver runtime state. 362 * @param index The index indicating the area of program once field to be read. 363 * @param dst A pointer to the destination buffer of data that is used to store 364 * data to be read. 365 * @param lengthInBytes The length, given in bytes (not words or long-words), 366 * to be programmed. Must be word-aligned. 367 * 368 * @retval #kStatus_FTFx_Success API was executed successfully; the data have been successfuly 369 * read form Program flash0 IFR map and Program Once field based on index and length. 370 371 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 372 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 373 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 374 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 375 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 376 */ 377 status_t FLASH_ReadOnce(flash_config_t *config, uint32_t index, uint8_t *dst, uint32_t lengthInBytes); 378 379 /*@}*/ 380 381 /*! 382 * @name Verification 383 * @{ 384 */ 385 386 /*! 387 * @brief Verifies an erasure of the desired flash area at a specified margin level. 388 * 389 * This function checks the appropriate number of flash sectors based on 390 * the desired start address and length to check whether the flash is erased 391 * to the specified read margin level. 392 * 393 * @param config A pointer to the storage for the driver runtime state. 394 * @param start The start address of the desired flash memory to be verified. 395 * The start address does not need to be sector-aligned but must be word-aligned. 396 * @param lengthInBytes The length, given in bytes (not words or long-words), 397 * to be verified. Must be word-aligned. 398 * @param margin Read margin choice. 399 * 400 * @retval #kStatus_FTFx_Success API was executed successfully; the specified FLASH region has been erased. 401 * 402 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 403 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 404 * @retval #kStatus_FTFx_AddressError Address is out of range. 405 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 406 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 407 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 408 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 409 */ 410 status_t FLASH_VerifyErase(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, ftfx_margin_value_t margin); 411 412 /*! 413 * @brief Verifies erasure of the entire flash at a specified margin level. 414 * 415 * This function checks whether the flash is erased to the 416 * specified read margin level. 417 * 418 * @param config A pointer to the storage for the driver runtime state. 419 * @param margin Read margin choice. 420 * 421 * @retval #kStatus_FTFx_Success API was executed successfully; all program flash and flexnvm were in erased state. 422 * 423 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 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 the command execution. 428 */ 429 status_t FLASH_VerifyEraseAll(flash_config_t *config, ftfx_margin_value_t margin); 430 431 /*! 432 * @brief Verifies programming of the desired flash area at a specified margin level. 433 * 434 * This function verifies the data programmed in the flash memory using the 435 * Flash Program Check Command and compares it to the expected data for a given 436 * flash area as determined by the start address and length. 437 * 438 * @param config A pointer to the storage for the driver runtime state. 439 * @param start The start address of the desired flash memory to be verified. Must be word-aligned. 440 * @param lengthInBytes The length, given in bytes (not words or long-words), 441 * to be verified. Must be word-aligned. 442 * @param expectedData A pointer to the expected data that is to be 443 * verified against. 444 * @param margin Read margin choice. 445 * @param failedAddress A pointer to the returned failing address. 446 * @param failedData A pointer to the returned failing data. Some derivatives do 447 * not include failed data as part of the FCCOBx registers. In this 448 * case, zeros are returned upon failure. 449 * 450 * @retval #kStatus_FTFx_Success API was executed successfully; the desired data have been successfully programed into 451 * specified FLASH region. 452 * 453 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 454 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 455 * @retval #kStatus_FTFx_AddressError Address is out of range. 456 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 457 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 458 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 459 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 460 */ 461 status_t FLASH_VerifyProgram(flash_config_t *config, 462 uint32_t start, 463 uint32_t lengthInBytes, 464 const uint8_t *expectedData, 465 ftfx_margin_value_t margin, 466 uint32_t *failedAddress, 467 uint32_t *failedData); 468 469 /*@}*/ 470 471 /*! 472 * @name Security 473 * @{ 474 */ 475 476 /*! 477 * @brief Returns the security state via the pointer passed into the function. 478 * 479 * This function retrieves the current flash security status, including the 480 * security enabling state and the backdoor key enabling state. 481 * 482 * @param config A pointer to storage for the driver runtime state. 483 * @param state A pointer to the value returned for the current security status code: 484 * 485 * @retval #kStatus_FTFx_Success API was executed successfully; the security state of flash was stored to state. 486 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 487 */ 488 status_t FLASH_GetSecurityState(flash_config_t *config, ftfx_security_state_t *state); 489 490 /*! 491 * @brief Allows users to bypass security with a backdoor key. 492 * 493 * If the MCU is in secured state, this function unsecures the MCU by 494 * comparing the provided backdoor key with ones in the flash configuration 495 * field. 496 * 497 * @param config A pointer to the storage for the driver runtime state. 498 * @param backdoorKey A pointer to the user buffer containing the backdoor key. 499 * 500 * @retval #kStatus_FTFx_Success API was executed successfully. 501 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 502 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 503 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 504 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 505 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 506 */ 507 status_t FLASH_SecurityBypass(flash_config_t *config, const uint8_t *backdoorKey); 508 509 /*@}*/ 510 511 /*! 512 * @name FlexRAM 513 * @{ 514 */ 515 516 #if defined(FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD) && FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD 517 /*! 518 * @brief Sets the FlexRAM function command. 519 * 520 * @param config A pointer to the storage for the driver runtime state. 521 * @param option The option used to set the work mode of FlexRAM. 522 * 523 * @retval #kStatus_FTFx_Success API was executed successfully; the FlexRAM has been successfully configured as RAM or 524 * EEPROM. 525 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 526 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 527 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 528 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 529 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 530 */ 531 status_t FLASH_SetFlexramFunction(flash_config_t *config, ftfx_flexram_func_opt_t option); 532 #endif /* FSL_FEATURE_FLASH_HAS_SET_FLEXRAM_FUNCTION_CMD */ 533 534 /*@}*/ 535 536 /*! 537 * @name Swap 538 * @{ 539 */ 540 541 #if defined(FSL_FEATURE_FLASH_HAS_PFLASH_BLOCK_SWAP) && FSL_FEATURE_FLASH_HAS_PFLASH_BLOCK_SWAP 542 /*! 543 * @brief Swaps the lower half flash with the higher half flash. 544 * 545 * @param config A pointer to the storage for the driver runtime state. 546 * @param address Address used to configure the flash swap function 547 * @param isSetEnable The possible option used to configure the Flash Swap function or check the flash Swap status. 548 * 549 * @retval #kStatus_FTFx_Success API was executed successfully; the lower half flash and higher half flash have been 550 * swaped. 551 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 552 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 553 * @retval #kStatus_FTFx_SwapIndicatorAddressError Swap indicator address is invalid. 554 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 555 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 556 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 557 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 558 * @retval #kStatus_FTFx_SwapSystemNotInUninitialized Swap system is not in an uninitialized state. 559 */ 560 status_t FLASH_Swap(flash_config_t *config, uint32_t address, bool isSetEnable); 561 #endif /* FSL_FEATURE_FLASH_HAS_PFLASH_BLOCK_SWAP */ 562 563 /*@}*/ 564 565 /*! 566 * @name Protection 567 * @{ 568 */ 569 570 /*! 571 * @brief Returns the protection state of the desired flash area via the pointer passed into the function. 572 * 573 * This function retrieves the current flash protect status for a given 574 * flash area as determined by the start address and length. 575 * 576 * @param config A pointer to the storage for the driver runtime state. 577 * @param start The start address of the desired flash memory to be checked. Must be word-aligned. 578 * @param lengthInBytes The length, given in bytes (not words or long-words) 579 * to be checked. Must be word-aligned. 580 * @param protection_state A pointer to the value returned for the current 581 * protection status code for the desired flash area. 582 * 583 * @retval #kStatus_FTFx_Success API was executed successfully; the protection state of specified FLASH region was 584 * stored to protection_state. 585 * 586 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 587 * @retval #kStatus_FTFx_AlignmentError Parameter is not aligned with specified baseline. 588 * @retval #kStatus_FTFx_AddressError The address is out of range. 589 */ 590 status_t FLASH_IsProtected(flash_config_t *config, 591 uint32_t start, 592 uint32_t lengthInBytes, 593 flash_prot_state_t *protection_state); 594 595 #if defined(FSL_FEATURE_FLASH_HAS_ACCESS_CONTROL) && FSL_FEATURE_FLASH_HAS_ACCESS_CONTROL 596 /*! 597 * @brief Returns the access state of the desired flash area via the pointer passed into the function. 598 * 599 * This function retrieves the current flash access status for a given 600 * flash area as determined by the start address and length. 601 * 602 * @param config A pointer to the storage for the driver runtime state. 603 * @param start The start address of the desired flash memory to be checked. Must be word-aligned. 604 * @param lengthInBytes The length, given in bytes (not words or long-words), 605 * to be checked. Must be word-aligned. 606 * @param access_state A pointer to the value returned for the current 607 * access status code for the desired flash area. 608 * 609 * @retval #kStatus_FTFx_Success API was executed successfully; the executeOnly state of specified FLASH region was 610 * stored to access_state. 611 * 612 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 613 * @retval #kStatus_FTFx_AlignmentError The parameter is not aligned to the specified baseline. 614 * @retval #kStatus_FTFx_AddressError The address is out of range. 615 */ 616 status_t FLASH_IsExecuteOnly(flash_config_t *config, 617 uint32_t start, 618 uint32_t lengthInBytes, 619 flash_xacc_state_t *access_state); 620 #endif /* FSL_FEATURE_FLASH_HAS_ACCESS_CONTROL */ 621 622 /*! 623 * @brief Sets the PFlash Protection to the intended protection status. 624 * 625 * @param config A pointer to storage for the driver runtime state. 626 * @param protectStatus The expected protect status to set to the PFlash protection register. Each bit is 627 * corresponding to protection of 1/32(64) of the total PFlash. The least significant bit is corresponding to the lowest 628 * address area of PFlash. The most significant bit is corresponding to the highest address area of PFlash. There are 629 * two possible cases as shown below: 630 * 0: this area is protected. 631 * 1: this area is unprotected. 632 * 633 * @retval #kStatus_FTFx_Success API was executed successfully; the specified FLASH region is protected. 634 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 635 * @retval #kStatus_FTFx_CommandFailure Run-time error during command execution. 636 */ 637 status_t FLASH_PflashSetProtection(flash_config_t *config, pflash_prot_status_t *protectStatus); 638 639 /*! 640 * @brief Gets the PFlash protection status. 641 * 642 * @param config A pointer to the storage for the driver runtime state. 643 * @param protectStatus Protect status returned by the PFlash IP. Each bit is corresponding to the protection of 644 * 1/32(64) 645 * of the 646 * total PFlash. The least significant bit corresponds to the lowest address area of the PFlash. The most significant 647 * bit corresponds to the highest address area of PFlash. There are two possible cases as shown below: 648 * 0: this area is protected. 649 * 1: this area is unprotected. 650 * 651 * @retval #kStatus_FTFx_Success API was executed successfully; the Protection state was stored to protectStatus; 652 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 653 */ 654 status_t FLASH_PflashGetProtection(flash_config_t *config, pflash_prot_status_t *protectStatus); 655 656 /*@}*/ 657 658 /*! 659 * @name Properties 660 * @{ 661 */ 662 663 /*! 664 * @brief Returns the desired flash property. 665 * 666 * @param config A pointer to the storage for the driver runtime state. 667 * @param whichProperty The desired property from the list of properties in 668 * enum flash_property_tag_t 669 * @param value A pointer to the value returned for the desired flash property. 670 * 671 * @retval #kStatus_FTFx_Success API was executed successfully; the flash property was stored to value. 672 * @retval #kStatus_FTFx_InvalidArgument An invalid argument is provided. 673 * @retval #kStatus_FTFx_UnknownProperty An unknown property tag. 674 */ 675 status_t FLASH_GetProperty(flash_config_t *config, flash_property_tag_t whichProperty, uint32_t *value); 676 677 /*@}*/ 678 679 /*! 680 * @name commantStatus 681 * @{ 682 */ 683 684 /*! 685 * @brief Get previous command status. 686 * 687 * This function is used to obtain the execution status of the previous command. 688 * 689 * @retval #kStatus_FTFx_Success The previous command is executed successfully. 690 * @retval #kStatus_FTFx_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 691 * @retval #kStatus_FTFx_AccessError Invalid instruction codes and out-of bounds addresses. 692 * @retval #kStatus_FTFx_ProtectionViolation The program/erase operation is requested to execute on protected areas. 693 * @retval #kStatus_FTFx_CommandFailure Run-time error during the command execution. 694 */ 695 status_t FLASH_GetCommandState(void); 696 697 /*@}*/ 698 699 #if defined(__cplusplus) 700 } 701 #endif 702 703 /*! @}*/ 704 705 #endif /* FSL_FTFX_FLASH_H */ 706
