| Kinetis SDK v.2.0 API Reference Manual Rev. 0 Freescale Semiconductor, Inc.

- Main Page
- Related Pages
- API Reference

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Typedefs | Enumerations
C90TFS Flash Driver

## Overview

The flash provides the C90TFS Flash driver of Kinetis devices with the C90TFS Flash module inside. The flash provides general APIs to handle specific operations on C90TFS/FTFx Flash module. The user can use those APIs directly in the application. In addition, it provides internal functions called by the driver. Although these functions are not meant to be called from the user's application directly, the APIs can still be used.

## Data Structures
struct | flash_execute_in_ram_function_config_t
| Flash execute-in-ram function information. More...
struct | flash_swap_state_config_t
| Flash Swap information. More...
struct | flash_swap_ifr_field_config_t
| Flash Swap IFR fileds. More...
struct | flash_operation_config_t
| Active flash information for current operation. More...
struct | flash_config_t
| Flash driver state information. More...

## Typedefs
typedef void(* | flash_callback_t )(void)
| callback type used for pflash block

## Enumerations
enum | flash_margin_value_t { kFLASH_marginValueNormal, kFLASH_marginValueUser, kFLASH_marginValueFactory, kFLASH_marginValueInvalid }
| Enumeration for supported flash margin levels. More...
enum | flash_security_state_t { kFLASH_securityStateNotSecure, kFLASH_securityStateBackdoorEnabled, kFLASH_securityStateBackdoorDisabled }
| Enumeration for the three possible flash security states. More...
enum | flash_protection_state_t { kFLASH_protectionStateUnprotected, kFLASH_protectionStateProtected, kFLASH_protectionStateMixed }
| Enumeration for the three possible flash protection levels. More...
enum | flash_execute_only_access_state_t { kFLASH_accessStateUnLimited, kFLASH_accessStateExecuteOnly, kFLASH_accessStateMixed }
| Enumeration for the three possible flash execute access levels. More...
enum | flash_property_tag_t { kFLASH_propertyPflashSectorSize = 0x00U, kFLASH_propertyPflashTotalSize = 0x01U, kFLASH_propertyPflashBlockSize = 0x02U, kFLASH_propertyPflashBlockCount = 0x03U, kFLASH_propertyPflashBlockBaseAddr = 0x04U, kFLASH_propertyPflashFacSupport = 0x05U, kFLASH_propertyPflashAccessSegmentSize = 0x06U, kFLASH_propertyPflashAccessSegmentCount = 0x07U, kFLASH_propertyFlexRamBlockBaseAddr = 0x08U, kFLASH_propertyFlexRamTotalSize = 0x09U, kFLASH_propertyDflashSectorSize = 0x10U, kFLASH_propertyDflashTotalSize = 0x11U, kFLASH_propertyDflashBlockSize = 0x12U, kFLASH_propertyDflashBlockCount = 0x13U, kFLASH_propertyDflashBlockBaseAddr = 0x14U }
| Enumeration for various flash properties. More...
enum | _flash_execute_in_ram_function_constants { kFLASH_executeInRamFunctionMaxSize = 64U, kFLASH_executeInRamFunctionTotalNum = 2U }
| Constants for execute-in-ram flash function. More...
enum | flash_read_resource_option_t { kFLASH_resourceOptionFlashIfr, kFLASH_resourceOptionVersionId = 0x01U }
| Enumeration for the two possible options of flash read resource command. More...
enum | _flash_read_resource_range { kFLASH_resourceRangePflashIfrSizeInBytes = 256U, kFLASH_resourceRangeVersionIdSizeInBytes = 8U, kFLASH_resourceRangeVersionIdStart = 0x00U, kFLASH_resourceRangeVersionIdEnd = 0x07U, kFLASH_resourceRangePflashSwapIfrStart = 0x40000U, kFLASH_resourceRangePflashSwapIfrEnd = 0x403FFU, kFLASH_resourceRangeDflashIfrStart = 0x800000U, kFLASH_resourceRangeDflashIfrEnd = 0x8003FFU }
| Enumeration for the range of special-purpose flash resource. More...
enum | flash_flexram_function_option_t { kFLASH_flexramFunctionOptionAvailableAsRam = 0xFFU, kFLASH_flexramFunctionOptionAvailableForEeprom = 0x00U }
| Enumeration for the two possilbe options of set flexram function command. More...
enum | flash_swap_function_option_t { kFLASH_swapFunctionOptionEnable = 0x00U, kFLASH_swapFunctionOptionDisable = 0x01U }
| Enumeration for the possible options of Swap function. More...
enum | flash_swap_control_option_t { kFLASH_swapControlOptionIntializeSystem = 0x01U, kFLASH_swapControlOptionSetInUpdateState = 0x02U, kFLASH_swapControlOptionSetInCompleteState = 0x04U, kFLASH_swapControlOptionReportStatus = 0x08U, kFLASH_swapControlOptionDisableSystem = 0x10U }
| Enumeration for the possible options of Swap Control commands. More...
enum | flash_swap_state_t { kFLASH_swapStateUninitialized = 0x00U, kFLASH_swapStateReady = 0x01U, kFLASH_swapStateUpdate = 0x02U, kFLASH_swapStateUpdateErased = 0x03U, kFLASH_swapStateComplete = 0x04U, kFLASH_swapStateDisabled = 0x05U }
| Enumeration for the possible flash swap status. More...
enum | flash_swap_block_status_t { kFLASH_swapBlockStatusLowerHalfProgramBlocksAtZero, kFLASH_swapBlockStatusUpperHalfProgramBlocksAtZero }
| Enumeration for the possible flash swap block status More...
enum | flash_partition_flexram_load_option_t { kFLASH_partitionFlexramLoadOptionLoadedWithValidEepromData, kFLASH_partitionFlexramLoadOptionNotLoaded = 0x01U }
| Enumeration for FlexRAM load during reset option. More...

## Flash version
enum | _flash_driver_version_constants { kFLASH_driverVersionName = 'F', kFLASH_driverVersionMajor = 2, kFLASH_driverVersionMinor = 1, kFLASH_driverVersionBugfix = 0 }
| FLASH driver version for ROM. More...
#define | MAKE_VERSION(major, minor, bugfix) (((major) << 16) | ((minor) << 8) | (bugfix))
| Construct the version number for drivers. More...
#define | FSL_FLASH_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))
| FLASH driver version for SDK. More...

## Flash configuration
#define | FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT 1
| Whether to support FlexNVM in flash driver. More...
#define | FLASH_SSD_IS_FLEXNVM_ENABLED (FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT && FSL_FEATURE_FLASH_HAS_FLEX_NVM)
| Whether the FlexNVM is enabled in flash driver.
#define | FLASH_DRIVER_IS_FLASH_RESIDENT 1
| Flash driver location. More...
#define | FLASH_DRIVER_IS_EXPORTED 0
| Flash Driver Export option. More...

## Flash status
enum | _flash_status { kStatus_FLASH_Success = MAKE_STATUS(kStatusGroupGeneric, 0), kStatus_FLASH_InvalidArgument = MAKE_STATUS(kStatusGroupGeneric, 4), kStatus_FLASH_SizeError = MAKE_STATUS(kStatusGroupFlashDriver, 0), kStatus_FLASH_AlignmentError, kStatus_FLASH_AddressError = MAKE_STATUS(kStatusGroupFlashDriver, 2), kStatus_FLASH_AccessError, kStatus_FLASH_ProtectionViolation, kStatus_FLASH_CommandFailure, kStatus_FLASH_UnknownProperty = MAKE_STATUS(kStatusGroupFlashDriver, 6), kStatus_FLASH_EraseKeyError = MAKE_STATUS(kStatusGroupFlashDriver, 7), kStatus_FLASH_RegionExecuteOnly = MAKE_STATUS(kStatusGroupFlashDriver, 8), kStatus_FLASH_ExecuteInRamFunctionNotReady, kStatus_FLASH_PartitionStatusUpdateFailure, kStatus_FLASH_SetFlexramAsEepromError, kStatus_FLASH_RecoverFlexramAsRamError, kStatus_FLASH_SetFlexramAsRamError = MAKE_STATUS(kStatusGroupFlashDriver, 13), kStatus_FLASH_RecoverFlexramAsEepromError, kStatus_FLASH_CommandNotSupported = MAKE_STATUS(kStatusGroupFlashDriver, 15), kStatus_FLASH_SwapSystemNotInUninitialized, kStatus_FLASH_SwapIndicatorAddressError }
| Flash driver status codes. More...
#define | kStatusGroupGeneric 0
| Flash driver status group. More...
#define | kStatusGroupFlashDriver 1
#define | MAKE_STATUS(group, code) ((((group)*100) + (code)))
| Construct a status code value from a group and code number. More...

## Flash API key
enum | _flash_driver_api_keys { kFLASH_apiEraseKey = FOUR_CHAR_CODE('k', 'f', 'e', 'k') }
| Enumeration for flash driver API keys. More...
#define | FOUR_CHAR_CODE(a, b, c, d) (((d) << 24) | ((c) << 16) | ((b) << 8) | ((a)))
| Construct the four char code for flash driver API key. More...

## Initialization
status_t | FLASH_Init (flash_config_t *config)
| Initializes global flash properties structure members. More...
status_t | FLASH_SetCallback (flash_config_t *config, flash_callback_t callback)
| Set the desired flash callback function. More...
status_t | FLASH_PrepareExecuteInRamFunctions (flash_config_t *config)
| Prepare flash execute-in-ram functions. More...

## Erasing
status_t | FLASH_EraseAll (flash_config_t *config, uint32_t key)
| Erases entire flash. More...
status_t | FLASH_Erase (flash_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key)
| Erases flash sectors encompassed by parameters passed into function. More...
status_t | FLASH_EraseAllExecuteOnlySegments (flash_config_t *config, uint32_t key)
| Erases entire flash, including protected sectors. More...

## Programming
status_t | FLASH_Program (flash_config_t *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes)
| Programs flash with data at locations passed in through parameters. More...
status_t | FLASH_ProgramOnce (flash_config_t *config, uint32_t index, uint32_t *src, uint32_t lengthInBytes)
| Programs Program Once Field through parameters. More...

## Reading
  Programs flash with data at locations passed in through parameters via Program Section command This function programs the flash memory with desired data for a given flash area as determined by the start address and length. Parameters
  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be programmed. Must be word-aligned.
  src | Pointer to the source buffer of data that is to be programmed into the flash.
  lengthInBytes | The length, given in bytes (not words or long-words) to be programmed. Must be word-aligned.
  Return values
  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
  kStatus_FLASH_AddressError | Address is out of range.
  kStatus_FLASH_SetFlexramAsRamError | Failed to set flexram as ram
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.
  kStatus_FLASH_RecoverFlexramAsEepromError | Failed to recover flexram as eeprom
  Programs EEPROM with data at locations passed in through parameters This function programs the Emulated EEPROM with desired data for a given flash area as determined by the start address and length. Parameters
  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be programmed. Must be word-aligned.
  src | Pointer to the source buffer of data that is to be programmed into the flash.
  lengthInBytes | The length, given in bytes (not words or long-words) to be programmed. Must be word-aligned.
  Return values
  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AddressError | Address is out of range.
  kStatus_FLASH_SetFlexramAsEepromError | Failed to set flexram as eeprom.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_RecoverFlexramAsRamError | Failed to recover flexram as ram
status_t | FLASH_ReadOnce (flash_config_t *config, uint32_t index, uint32_t *dst, uint32_t lengthInBytes)
| Read resource with data at locations passed in through parameters. More...

## Security
status_t | FLASH_GetSecurityState (flash_config_t *config, flash_security_state_t *state)
| Returns the security state via the pointer passed into the function. More...
status_t | FLASH_SecurityBypass (flash_config_t *config, const uint8_t *backdoorKey)
| Allows user to bypass security with a backdoor key. More...

## Verification
status_t | FLASH_VerifyEraseAll (flash_config_t *config, flash_margin_value_t margin)
| Verifies erasure of entire flash at specified margin level. More...
status_t | FLASH_VerifyErase (flash_config_t *config, uint32_t start, uint32_t lengthInBytes, flash_margin_value_t margin)
| Verifies erasure of desired flash area at specified margin level. More...
status_t | FLASH_VerifyProgram (flash_config_t *config, uint32_t start, uint32_t lengthInBytes, const uint32_t *expectedData, flash_margin_value_t margin, uint32_t *failedAddress, uint32_t *failedData)
| Verifies programming of desired flash area at specified margin level. More...
status_t | FLASH_VerifyEraseAllExecuteOnlySegments (flash_config_t *config, flash_margin_value_t margin)
| Verifies if the program flash executeonly segments have been erased to the specified read margin level. More...

## Protection
status_t | FLASH_IsProtected (flash_config_t *config, uint32_t start, uint32_t lengthInBytes, flash_protection_state_t *protection_state)
| Returns the protection state of desired flash area via the pointer passed into the function. More...
status_t | FLASH_IsExecuteOnly (flash_config_t *config, uint32_t start, uint32_t lengthInBytes, flash_execute_only_access_state_t *access_state)
| Returns the access state of desired flash area via the pointer passed into the function. More...

## Properties
status_t | FLASH_GetProperty (flash_config_t *config, flash_property_tag_t whichProperty, uint32_t *value)
| Returns the desired flash property. More...

## Flash Protection Utilities
  Prepares the FlexNVM block for use as data flash, EEPROM backup, or a combination of both and initializes the FlexRAM. Parameters
  config | Pointer to storage for the driver runtime state.
  option | The option used to set FlexRAM load behavior during reset.
  eepromDataSizeCode | Determines the amount of FlexRAM used in each of the available EEPROM subsystems.
  flexnvmPartitionCode | Specifies how to split the FlexNVM block between data flash memory and EEPROM backup memory supporting EEPROM functions.
  Return values
  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.
status_t | FLASH_PflashSetProtection (flash_config_t *config, uint32_t protectStatus)
| Set PFLASH Protection to the intended protection status. More...
status_t | FLASH_PflashGetProtection (flash_config_t *config, uint32_t *protectStatus)
| Get PFLASH Protection Status. More...

## Data Structure Documentation

struct flash_execute_in_ram_function_config_t

### Data Fields
uint32_t | activeFunctionCount
| Number of available execute-in-ram functions. More...
uint8_t * | flashRunCommand
| execute-in-ram function: flash_run_command. More...
uint8_t * | flashCacheClearCommand
| execute-in-ram function: flash_cache_clear_command. More...

#### Field Documentation

uint32_t flash_execute_in_ram_function_config_t::activeFunctionCount

uint8_t* flash_execute_in_ram_function_config_t::flashRunCommand

uint8_t* flash_execute_in_ram_function_config_t::flashCacheClearCommand

struct flash_swap_state_config_t

### Data Fields
flash_swap_state_t | flashSwapState
| Current swap system status. More...
flash_swap_block_status_t | currentSwapBlockStatus
| Current swap block status. More...
flash_swap_block_status_t | nextSwapBlockStatus
| Next swap block status. More...

#### Field Documentation

flash_swap_state_t flash_swap_state_config_t::flashSwapState

flash_swap_block_status_t flash_swap_state_config_t::currentSwapBlockStatus

flash_swap_block_status_t flash_swap_state_config_t::nextSwapBlockStatus

struct flash_swap_ifr_field_config_t

### Data Fields
uint16_t | swapIndicatorAddress
| Swap indicator address field. More...
uint16_t | swapEnableWord
| Swap enable word field. More...
uint8_t | reserved0 [6]
| Reserved field. More...
uint16_t | swapDisableWord
| Swap disable word field. More...
uint8_t | reserved1 [4]
| Reserved field. More...

#### Field Documentation

uint16_t flash_swap_ifr_field_config_t::swapIndicatorAddress

uint16_t flash_swap_ifr_field_config_t::swapEnableWord

uint8_t flash_swap_ifr_field_config_t::reserved0[6]

uint16_t flash_swap_ifr_field_config_t::swapDisableWord

uint8_t flash_swap_ifr_field_config_t::reserved1[4]

struct flash_operation_config_t

### Data Fields
uint32_t | convertedAddress
| Converted address for current flash type. More...
uint32_t | activeSectorSize
| Sector size of current flash type. More...
uint32_t | activeBlockSize
| Block size of current flash type. More...
uint32_t | blockWriteUnitSize
| write unit size. More...
uint32_t | sectorCmdAddressAligment
| Erase sector command address alignment. More...
uint32_t | sectionCmdAddressAligment
| Program/Verify section command address alignment. More...
uint32_t | resourceCmdAddressAligment
| Read resource command address alignment. More...
uint32_t | checkCmdAddressAligment
| Program check command address alignment. More...

#### Field Documentation

uint32_t flash_operation_config_t::convertedAddress

uint32_t flash_operation_config_t::activeSectorSize

uint32_t flash_operation_config_t::activeBlockSize

uint32_t flash_operation_config_t::blockWriteUnitSize

uint32_t flash_operation_config_t::sectorCmdAddressAligment

uint32_t flash_operation_config_t::sectionCmdAddressAligment

uint32_t flash_operation_config_t::resourceCmdAddressAligment

uint32_t flash_operation_config_t::checkCmdAddressAligment

struct flash_config_t

An instance of this structure is allocated by the user of the flash driver and passed into each of the driver APIs.

### Data Fields
uint32_t | PFlashBlockBase
| Base address of the first PFlash block.
uint32_t | PFlashTotalSize
| Size of all combined PFlash block. More...
uint32_t | PFlashBlockCount
| Number of PFlash blocks. More...
uint32_t | PFlashSectorSize
| Size in bytes of a sector of PFlash. More...
flash_callback_t | PFlashCallback
| Callback function for flash API. More...
uint32_t | PFlashAccessSegmentSize
| Size in bytes of a access segment of PFlash. More...
uint32_t | PFlashAccessSegmentCount
| Number of PFlash access segments. More...
uint32_t * | flashExecuteInRamFunctionInfo
| Info struct of flash execute-in-ram function. More...
uint32_t | FlexRAMBlockBase
| For FlexNVM device, this is the base address of FlexRAM For non-FlexNVM device, this is the base address of acceleration RAM memory.
uint32_t | FlexRAMTotalSize
| For FlexNVM device, this is the size of FlexRAM For non-FlexNVM device, this is the size of acceleration RAM memory.
uint32_t | DFlashBlockBase
| For FlexNVM device, this is the base address of D-Flash memory (FlexNVM memory); For non-FlexNVM device, this field is unused.
uint32_t | DFlashTotalSize
| For FlexNVM device, this is total size of the FlexNVM memory; For non-FlexNVM device, this field is unused.
uint32_t | EEpromTotalSize
| For FlexNVM device, this is the size in byte of EEPROM area which was partitioned from FlexRAM; For non-FlexNVM device, this field is unused.

#### Field Documentation

uint32_t flash_config_t::PFlashTotalSize

uint32_t flash_config_t::PFlashBlockCount

uint32_t flash_config_t::PFlashSectorSize

flash_callback_t flash_config_t::PFlashCallback

uint32_t flash_config_t::PFlashAccessSegmentSize

uint32_t flash_config_t::PFlashAccessSegmentCount

uint32_t* flash_config_t::flashExecuteInRamFunctionInfo

## Macro Definition Documentation

#define MAKE_VERSION | ( |  | major,
|  |  | minor,
|  |  | bugfix
| ) |  | (((major) << 16) | ((minor) << 8) | (bugfix))

#define FSL_FLASH_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))

Version 2.1.0.

#define FLASH_SSD_CONFIG_ENABLE_FLEXNVM_SUPPORT 1

Enable FlexNVM support by default.

#define FLASH_DRIVER_IS_FLASH_RESIDENT 1

Used for flash resident application.

#define FLASH_DRIVER_IS_EXPORTED 0

Used for SDK application.

#define kStatusGroupGeneric 0

#define MAKE_STATUS | ( |  | group,
|  |  | code
| ) |  | ((((group)*100) + (code)))

#define FOUR_CHAR_CODE | ( |  | a,
|  |  | b,
|  |  | c,
|  |  | d
| ) |  | (((d) << 24) | ((c) << 16) | ((b) << 8) | ((a)))

## Enumeration Type Documentation

enum _flash_driver_version_constants

Enumerator
kFLASH_driverVersionName | Flash driver version name.
kFLASH_driverVersionMajor | Major flash driver version.
kFLASH_driverVersionMinor | Minor flash driver version.
kFLASH_driverVersionBugfix | Bugfix for flash driver version.

enum _flash_status

Enumerator
kStatus_FLASH_Success | Api is executed successfully.
kStatus_FLASH_InvalidArgument | Invalid argument.
kStatus_FLASH_SizeError | Error size.
kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
kStatus_FLASH_AddressError | Address is out of range.
kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
kStatus_FLASH_CommandFailure | Run-time error during command execution.
kStatus_FLASH_UnknownProperty | Unknown property.
kStatus_FLASH_EraseKeyError | Api erase key is invalid.
kStatus_FLASH_RegionExecuteOnly | Current region is execute only.
kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
kStatus_FLASH_PartitionStatusUpdateFailure | Failed to update partition status.
kStatus_FLASH_SetFlexramAsEepromError | Failed to set flexram as eeprom.
kStatus_FLASH_RecoverFlexramAsRamError | Failed to recover flexram as ram.
kStatus_FLASH_SetFlexramAsRamError | Failed to set flexram as ram.
kStatus_FLASH_RecoverFlexramAsEepromError | Failed to recover flexram as eeprom.
kStatus_FLASH_CommandNotSupported | Flash api is not supported.
kStatus_FLASH_SwapSystemNotInUninitialized | Swap system is not in uninitialzed state.
kStatus_FLASH_SwapIndicatorAddressError | Swap indicator address is invalid.

enum _flash_driver_api_keys

Note
  The resulting value is built with a byte order such that the string being readable in expected order when viewed in a hex editor, if the value is treated as a 32-bit little endian value.

Enumerator
kFLASH_apiEraseKey | Key value used to validate all flash erase APIs.

enum flash_margin_value_t

Enumerator
kFLASH_marginValueNormal | Use the 'normal' read level for 1s.
kFLASH_marginValueUser | Apply the 'User' margin to the normal read-1 level.
kFLASH_marginValueFactory | Apply the 'Factory' margin to the normal read-1 level.
kFLASH_marginValueInvalid | Not real margin level, Used to determine the range of valid margin level.

enum flash_security_state_t

Enumerator
kFLASH_securityStateNotSecure | Flash is not secure.
kFLASH_securityStateBackdoorEnabled | Flash backdoor is enabled.
kFLASH_securityStateBackdoorDisabled | Flash backdoor is disabled.

enum flash_protection_state_t

Enumerator
kFLASH_protectionStateUnprotected | Flash region is not protected.
kFLASH_protectionStateProtected | Flash region is protected.
kFLASH_protectionStateMixed | Flash is mixed with protected and unprotected region.

enum flash_execute_only_access_state_t

Enumerator
kFLASH_accessStateUnLimited | Flash region is unLimited.
kFLASH_accessStateExecuteOnly | Flash region is execute only.
kFLASH_accessStateMixed | Flash is mixed with unLimited and execute only region.

enum flash_property_tag_t

Enumerator
kFLASH_propertyPflashSectorSize | Pflash sector size property.
kFLASH_propertyPflashTotalSize | Pflash total size property.
kFLASH_propertyPflashBlockSize | Pflash block size property.
kFLASH_propertyPflashBlockCount | Pflash block count property.
kFLASH_propertyPflashBlockBaseAddr | Pflash block base address property.
kFLASH_propertyPflashFacSupport | Pflash fac support property.
kFLASH_propertyPflashAccessSegmentSize | Pflash access segment size property.
kFLASH_propertyPflashAccessSegmentCount | Pflash access segment count property.
kFLASH_propertyFlexRamBlockBaseAddr | FlexRam block base address property.
kFLASH_propertyFlexRamTotalSize | FlexRam total size property.
kFLASH_propertyDflashSectorSize | Dflash sector size property.
kFLASH_propertyDflashTotalSize | Dflash total size property.
kFLASH_propertyDflashBlockSize | Dflash block count property.
kFLASH_propertyDflashBlockCount | Dflash block base address property.
kFLASH_propertyDflashBlockBaseAddr | Eeprom total size property.

enum _flash_execute_in_ram_function_constants

Enumerator
kFLASH_executeInRamFunctionMaxSize | Max size of execute-in-ram function.
kFLASH_executeInRamFunctionTotalNum | Total number of execute-in-ram functions.

enum flash_read_resource_option_t

Enumerator
kFLASH_resourceOptionFlashIfr | Select code for Program flash 0 IFR, Program flash swap 0 IFR, Data flash 0 IFR.
kFLASH_resourceOptionVersionId | Select code for Version ID.

enum _flash_read_resource_range

Enumerator
kFLASH_resourceRangePflashIfrSizeInBytes | Pflash IFR size in byte.
kFLASH_resourceRangeVersionIdSizeInBytes | Version ID IFR size in byte.
kFLASH_resourceRangeVersionIdStart | Version ID IFR start address.
kFLASH_resourceRangeVersionIdEnd | Version ID IFR end address.
kFLASH_resourceRangePflashSwapIfrStart | Pflash swap IFR start address.
kFLASH_resourceRangePflashSwapIfrEnd | Pflash swap IFR end address.
kFLASH_resourceRangeDflashIfrStart | Dflash IFR start address.
kFLASH_resourceRangeDflashIfrEnd | Dflash IFR end address.

enum flash_flexram_function_option_t

Enumerator
kFLASH_flexramFunctionOptionAvailableAsRam | Option used to make FlexRAM available as RAM.
kFLASH_flexramFunctionOptionAvailableForEeprom | Option used to make FlexRAM available for EEPROM.

enum flash_swap_function_option_t

Enumerator
kFLASH_swapFunctionOptionEnable | Option used to enable Swap function.
kFLASH_swapFunctionOptionDisable | Option used to Disable Swap function.

enum flash_swap_control_option_t

Enumerator
kFLASH_swapControlOptionIntializeSystem | Option used to Intialize Swap System.
kFLASH_swapControlOptionSetInUpdateState | Option used to Set Swap in Update State.
kFLASH_swapControlOptionSetInCompleteState | Option used to Set Swap in Complete State.
kFLASH_swapControlOptionReportStatus | Option used to Report Swap Status.
kFLASH_swapControlOptionDisableSystem | Option used to Disable Swap Status.

enum flash_swap_state_t

Enumerator
kFLASH_swapStateUninitialized | Flash swap system is in uninitialized state.
kFLASH_swapStateReady | Flash swap system is in ready state.
kFLASH_swapStateUpdate | Flash swap system is in update state.
kFLASH_swapStateUpdateErased | Flash swap system is in updateErased state.
kFLASH_swapStateComplete | Flash swap system is in complete state.
kFLASH_swapStateDisabled | Flash swap system is in disabled state.

enum flash_swap_block_status_t

Enumerator
kFLASH_swapBlockStatusLowerHalfProgramBlocksAtZero | Swap block status is that lower half program block at zero.
kFLASH_swapBlockStatusUpperHalfProgramBlocksAtZero | Swap block status is that upper half program block at zero.

enum flash_partition_flexram_load_option_t

Enumerator
kFLASH_partitionFlexramLoadOptionLoadedWithValidEepromData | FlexRAM is loaded with valid EEPROM data during reset sequence.
kFLASH_partitionFlexramLoadOptionNotLoaded | FlexRAM is not loaded during reset sequence.

## Function Documentation

status_t FLASH_Init | ( | flash_config_t * | config | ) |

This function checks and initializes Flash module for the other Flash APIs.

Parameters

  config | Pointer to storage for the driver runtime state.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_PartitionStatusUpdateFailure | Failed to update partition status.

status_t FLASH_SetCallback | ( | flash_config_t * | config,
|  | flash_callback_t | callback
| ) |  |

Parameters

  config | Pointer to storage for the driver runtime state.
  callback | callback function to be stored in driver

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.

status_t FLASH_PrepareExecuteInRamFunctions | ( | flash_config_t * | config | ) |

Parameters

  config | Pointer to storage for the driver runtime state.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.

status_t FLASH_EraseAll | ( | flash_config_t * | config,
|  | uint32_t | key
| ) |  |

Parameters

  config | Pointer to storage for the driver runtime state.
  key | value used to validate all flash erase APIs.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_EraseKeyError | Api erase key is invalid.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.
  kStatus_FLASH_PartitionStatusUpdateFailure | Failed to update partition status

status_t FLASH_Erase | ( | flash_config_t * | config,
|  | uint32_t | start,
|  | uint32_t | lengthInBytes,
|  | uint32_t | key
| ) |  |

This function erases the appropriate number of flash sectors based on the desired start address and length.

Parameters

  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be erased. The start address does not need to be sector aligned but must be word-aligned.
  lengthInBytes | The length, given in bytes (not words or long-words) to be erased. Must be word aligned.
  key | value used to validate all flash erase APIs.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
  kStatus_FLASH_AddressError | Address is out of range.
  kStatus_FLASH_EraseKeyError | Api erase key is invalid.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_EraseAllExecuteOnlySegments | ( | flash_config_t * | config,
|  | uint32_t | key
| ) |  |

Parameters

  config | Pointer to storage for the driver runtime state.
  key | value used to validate all flash erase APIs.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_EraseKeyError | Api erase key is invalid.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.
  kStatus_FLASH_PartitionStatusUpdateFailure | Failed to update partition status

Erases all program flash execute-only segments defined by the FXACC registers.

Parameters

  config | Pointer to storage for the driver runtime state.
  key | value used to validate all flash erase APIs.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_EraseKeyError | Api erase key is invalid.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_Program | ( | flash_config_t * | config,
|  | uint32_t | start,
|  | uint32_t * | src,
|  | uint32_t | lengthInBytes
| ) |  |

This function programs the flash memory with desired data for a given flash area as determined by the start address and length.

Parameters

  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be programmed. Must be word-aligned.
  src | Pointer to the source buffer of data that is to be programmed into the flash.
  lengthInBytes | The length, given in bytes (not words or long-words) to be programmed. Must be word-aligned.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
  kStatus_FLASH_AddressError | Address is out of range.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_ProgramOnce | ( | flash_config_t * | config,
|  | uint32_t | index,
|  | uint32_t * | src,
|  | uint32_t | lengthInBytes
| ) |  |

This function programs the Program Once Field with desired data for a given flash area as determined by the index and length.

Parameters

  config | Pointer to storage for the driver runtime state.
  index | The index indicating which area of Program Once Field to be programmed.
  src | Pointer to the source buffer of data that is to be programmed into the Program Once Field.
  lengthInBytes | The length, given in bytes (not words or long-words) to be programmed. Must be word-aligned.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_ReadOnce | ( | flash_config_t * | config,
|  | uint32_t | index,
|  | uint32_t * | dst,
|  | uint32_t | lengthInBytes
| ) |  |

This function reads the flash memory with desired location for a given flash area as determined by the start address and length.

Parameters

  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be programmed. Must be word-aligned.
  dst | Pointer to the destination buffer of data that is used to store data to be read.
  lengthInBytes | The length, given in bytes (not words or long-words) to be read. Must be word-aligned.
  option | The resource option which indicates which area should be read back.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

Read Program Once Field through parameters

This function reads the read once feild with given index and length

Parameters

  config | Pointer to storage for the driver runtime state.
  index | The index indicating the area of program once field to be read.
  dst | Pointer to the destination buffer of data that is used to store data to be read.
  lengthInBytes | The length, given in bytes (not words or long-words) to be programmed. Must be word-aligned.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_GetSecurityState | ( | flash_config_t * | config,
|  | flash_security_state_t * | state
| ) |  |

This function retrieves the current Flash security status, including the security enabling state and the backdoor key enabling state.

Parameters

  config | Pointer to storage for the driver runtime state.
  state | Pointer to the value returned for the current security status code:

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.

status_t FLASH_SecurityBypass | ( | flash_config_t * | config,
|  | const uint8_t * | backdoorKey
| ) |  |

If the MCU is in secured state, this function will unsecure the MCU by comparing the provided backdoor key with ones in the Flash Configuration Field.

Parameters

  config | Pointer to storage for the driver runtime state.
  backdoorKey | Pointer to the user buffer containing the backdoor key.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_VerifyEraseAll | ( | flash_config_t * | config,
|  | flash_margin_value_t | margin
| ) |  |

This function will check to see if the flash have been erased to the specified read margin level.

Parameters

  config | Pointer to storage for the driver runtime state.
  margin | Read margin choice

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_VerifyErase | ( | flash_config_t * | config,
|  | uint32_t | start,
|  | uint32_t | lengthInBytes,
|  | flash_margin_value_t | margin
| ) |  |

This function will check the appropriate number of flash sectors based on the desired start address and length to see if the flash have been erased to the specified read margin level.

Parameters

  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be verified. The start address does not need to be sector aligned but must be word-aligned.
  lengthInBytes | The length, given in bytes (not words or long-words) to be verified. Must be word-aligned.
  margin | Read margin choice

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
  kStatus_FLASH_AddressError | Address is out of range.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_VerifyProgram | ( | flash_config_t * | config,
|  | uint32_t | start,
|  | uint32_t | lengthInBytes,
|  | const uint32_t * | expectedData,
|  | flash_margin_value_t | margin,
|  | uint32_t * | failedAddress,
|  | uint32_t * | failedData
| ) |  |

This function verifies the data programed in the flash memory using the Flash Program Check Command and compares it with expected data for a given flash area as determined by the start address and length.

Parameters

  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be verified. Must be word-aligned.
  lengthInBytes | The length, given in bytes (not words or long-words) to be verified. Must be word-aligned.
  expectedData | Pointer to the expected data that is to be verified against.
  margin | Read margin choice
  failedAddress | Pointer to returned failing address.
  failedData | Pointer to returned failing data. Some derivitives do not included failed data as part of the FCCOBx registers. In this case, zeros are returned upon failure.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
  kStatus_FLASH_AddressError | Address is out of range.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_VerifyEraseAllExecuteOnlySegments | ( | flash_config_t * | config,
|  | flash_margin_value_t | margin
| ) |  |

Parameters

  config | Pointer to storage for the driver runtime state.
  margin | Read margin choice

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_ExecuteInRamFunctionNotReady | Execute-in-ram function is not available.
  kStatus_FLASH_AccessError | Invalid instruction codes and out-of bounds addresses.
  kStatus_FLASH_ProtectionViolation | The program/erase operation is requested to execute on protected areas.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_IsProtected | ( | flash_config_t * | config,
|  | uint32_t | start,
|  | uint32_t | lengthInBytes,
|  | flash_protection_state_t * | protection_state
| ) |  |

This function retrieves the current Flash protect status for a given flash area as determined by the start address and length.

Parameters

  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be checked. Must be word-aligned.
  lengthInBytes | The length, given in bytes (not words or long-words) to be checked. Must be word-aligned.
  protection_state | Pointer to the value returned for the current protection status code for the desired flash area.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
  kStatus_FLASH_AddressError | Address is out of range.

status_t FLASH_IsExecuteOnly | ( | flash_config_t * | config,
|  | uint32_t | start,
|  | uint32_t | lengthInBytes,
|  | flash_execute_only_access_state_t * | access_state
| ) |  |

This function retrieves the current Flash access status for a given flash area as determined by the start address and length.

Parameters

  config | Pointer to storage for the driver runtime state.
  start | The start address of the desired flash memory to be checked. Must be word-aligned.
  lengthInBytes | The length, given in bytes (not words or long-words) to be checked. Must be word-aligned.
  access_state | Pointer to the value returned for the current access status code for the desired flash area.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_AlignmentError | Parameter is not aligned with specified baseline.
  kStatus_FLASH_AddressError | Address is out of range.

status_t FLASH_GetProperty | ( | flash_config_t * | config,
|  | flash_property_tag_t | whichProperty,
|  | uint32_t * | value
| ) |  |

Parameters

  config | Pointer to storage for the driver runtime state.
  whichProperty | The desired property from the list of properties in enum flash_property_tag_t
  value | Pointer to the value returned for the desired flash property

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_UnknownProperty | unknown property tag

status_t FLASH_PflashSetProtection | ( | flash_config_t * | config,
|  | uint32_t | protectStatus
| ) |  |

Parameters

  config | Pointer to storage for the driver runtime state.
  protectStatus | The expected protect status user wants to set to PFlash protection register. Each bit is corresponding to protection of 1/32 of the total PFlash. The least significant bit is corresponding to the lowest address area of P-Flash. The most significant bit is corresponding to the highest address area of PFlash. There are two possible cases as shown below: 0: this area is protected. 1: this area is unprotected.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.
  kStatus_FLASH_CommandFailure | Run-time error during command execution.

status_t FLASH_PflashGetProtection | ( | flash_config_t * | config,
|  | uint32_t * | protectStatus
| ) |  |

Parameters

  config | Pointer to storage for the driver runtime state.
  protectStatus | Protect status returned by PFlash IP. Each bit is corresponding to protection of 1/32 of the total PFlash. The least significant bit is corresponding to the lowest address area of PFlash. The most significant bit is corresponding to the highest address area of PFlash. Thee are two possible cases as below: 0: this area is protected. 1: this area is unprotected.

Return values

  kStatus_FLASH_Success | Api was executed successfully.
  kStatus_FLASH_InvalidArgument | Invalid argument is provided.