Flash_driver_api
Collaboration diagram for Flash_driver_api:

## Data Structures

struct | flash_execute_in_ram_function_config_t
| Flash execute-in-ram function information. More...
struct | flash_config_t
| Flash driver state information. More...
union | standard_version_t
| Structure of version property. More...
struct | standard_version_t.__unnamed__
struct | standard_version_t.B
struct | flash_driver_interface_t
| Interface for the flash driver. More...
struct | bootloader_tree_t
| Root of the bootloader API tree. 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, 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, 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, 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, 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,
kFLASH_PropertyEepromTotalSize = 0x15U,
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,
kFLASH_PropertyEepromTotalSize = 0x15U,
kFLASH_PropertyVersion = 0x20U
}

| Enumeration for various flash properties. More...
enum | _flash_execute_in_ram_function_constants { kFLASH_ExecuteInRamFunctionMaxSize = 64U, kFLASH_ExecuteInRamFunctionTotalNum = 2U, 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, kFLASH_ResourceOptionFlashIfr, kFLASH_ResourceOptionVersionId = 0x01U }
| Enumeration for the two possible options of flash read resource command. More...

## Variables

static const flash_driver_interface_t * | s_flashInterface
| Global pointer to the flash driver API table in ROM.

## Flash version

enum | _flash_driver_version_constants { kFLASH_DriverVersionName = 'F', kFLASH_DriverVersionMajor = 2, kFLASH_DriverVersionMinor = 1, kFLASH_DriverVersionBugfix = 0, kFLASH_DriverVersionName = 'F', kFLASH_DriverVersionMajor = 2, kFLASH_DriverVersionMinor = 1, kFLASH_DriverVersionBugfix = 0 }
| FLASH driver version for ROM. More...

## Flash status

enum

_generic_status {
kStatus_Success = MAKE_STATUS(kStatusGroup_Generic, 0),
kStatus_Fail = MAKE_STATUS(kStatusGroup_Generic, 1),
kStatus_ReadOnly = MAKE_STATUS(kStatusGroup_Generic, 2),
kStatus_OutOfRange = MAKE_STATUS(kStatusGroup_Generic, 3),
kStatus_InvalidArgument = MAKE_STATUS(kStatusGroup_Generic, 4),
kStatus_Timeout = MAKE_STATUS(kStatusGroup_Generic, 5),
kStatus_NoTransferInProgress = MAKE_STATUS(kStatusGroup_Generic, 6),
kStatus_Success = MAKE_STATUS(kStatusGroupGeneric, 0),
kStatus_Fail = MAKE_STATUS(kStatusGroupGeneric, 1),
kStatus_ReadOnly = MAKE_STATUS(kStatusGroupGeneric, 2),
kStatus_OutOfRange = MAKE_STATUS(kStatusGroupGeneric, 3),
kStatus_InvalidArgument = MAKE_STATUS(kStatusGroupGeneric, 4)
}

| Generic status return codes.

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,
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...
typedef int32_t | status_t
| Type used for all status and error return values.

## Flash API key

enum | _flash_driver_api_keys { kFLASH_ApiEraseKey = FOUR_CHAR_CODE('k', 'f', 'e', 'k'), kFLASH_ApiEraseKey = FOUR_CHAR_CODE('k', 'f', 'e', 'k') }
| Enumeration for flash driver API keys. 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_EraseAllUnsecure (flash_config_t *config, uint32_t key)
| Erases entire flash, including protected sectors. More...
status_t | FLASH_EraseAllExecuteOnlySegments (flash_config_t *config, uint32_t key)
| Erases all program flash execute-only segments defined by the FXACC registers. 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...
status_t | FLASH_ReadResource (flash_config_t *config, uint32_t start, uint32_t *dst, uint32_t lengthInBytes, flash_read_resource_option_t option)
| Read resource with data at locations passed in through parameters. More...
status_t | FLASH_ReadOnce (flash_config_t *config, uint32_t index, uint32_t *dst, uint32_t lengthInBytes)
| Read Program Once Field 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_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...

## Usage Information

## Data Structure Documentation

struct flash_execute_in_ram_function_config_t

Flash execute-in-ram function information.

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

struct flash_config_t

Flash driver state information.

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 | 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
uint32_t * | flashExecuteInRamFunctionInfo | Info struct of flash execute-in-ram function.
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 | PFlashAccessSegmentCount | Number of PFlash access segments.
uint32_t | PFlashAccessSegmentSize | Size in bytes of a access segment of PFlash.
uint32_t | PFlashBlockBase | Base address of the first PFlash block
uint32_t | PFlashBlockCount | Number of PFlash blocks.
flash_callback_t | PFlashCallback | Callback function for flash API.
uint32_t | PFlashSectorSize | Size in bytes of a sector of PFlash.
uint32_t | PFlashTotalSize | Size of all combined PFlash block.

union standard_version_t

Structure of version property.

### Public Member Functions

| StandardVersion ()
| StandardVersion (uint32_t version)

### Data Fields

struct {
uint8_t | bugfix
| bugfix version [7:0]
uint8_t | minor
| minor version [15:8]
uint8_t | major
| major version [23:16]
char | name
| name [31:24]
}; |
uint32_t | version
| combined version numbers
struct {
uint32_t | bugfix: 8
| bugfix version [7:0]
uint32_t | minor: 8
| minor version [15:8]
uint32_t | major: 8
| major version [23:16]
uint32_t | name: 8
| name [31:24]
} | B
struct {
uint32_t | bugfix: 8
| bugfix version [7:0]
uint32_t | minor: 8
| minor version [15:8]
uint32_t | major: 8
| major version [23:16]
uint32_t | name: 8
| name [31:24]
} | B

struct standard_version_t.__unnamed__

Data Fields
uint8_t | bugfix | bugfix version [7:0]
uint8_t | major | major version [23:16]
uint8_t | minor | minor version [15:8]
char | name | name [31:24]

struct standard_version_t.B

Data Fields
uint32_t | bugfix: 8 | bugfix version [7:0]
uint32_t | major: 8 | major version [23:16]
uint32_t | minor: 8 | minor version [15:8]
uint32_t | name: 8 | name [31:24]

struct flash_driver_interface_t

Interface for the flash driver.

Collaboration diagram for flash_driver_interface_t:
[legend]

### Data Fields

standard_version_t | version
| flash driver API version number.
status_t(* | flash_init )(flash_config_t *config)
status_t(* | flash_erase_all )(flash_config_t *config, uint32_t key)
status_t(* | flash_erase_all_unsecure )(flash_config_t *config, uint32_t key)
status_t(* | flash_erase )(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key)
status_t(* | flash_program )(flash_config_t *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes)
status_t(* | flash_get_security_state )(flash_config_t *config, flash_security_state_t *state)
status_t(* | flash_security_bypass )(flash_config_t *config, const uint8_t *backdoorKey)
status_t(* | flash_verify_erase_all )(flash_config_t *config, flash_margin_value_t margin)
status_t(* | flash_verify_erase )(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, flash_margin_value_t margin)
status_t(* | flash_verify_program )(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)
status_t(* | flash_get_property )(flash_config_t *config, flash_property_tag_t whichProperty, uint32_t *value)
status_t(* | flash_register_callback )(flash_config_t *config, flash_callback_t callback)
status_t(* | flash_program_once )(flash_config_t *config, uint32_t index, uint32_t *src, uint32_t lengthInBytes)
status_t(* | flash_read_once )(flash_config_t *config, uint32_t index, uint32_t *dst, uint32_t lengthInBytes)
status_t(* | flash_read_resource )(flash_config_t *config, uint32_t start, uint32_t *dst, uint32_t lengthInBytes, flash_read_resource_option_t option)
status_t(* | flash_prepare_execute_in_ram_functions )(flash_config_t *config)
status_t(* | flash_is_execute_only )(flash_config_t *config, uint32_t start, uint32_t lengthInBytes, flash_execute_only_access_state_t *access_state)
status_t(* | flash_erase_all_execute_only_segments )(flash_config_t *config, uint32_t key)
status_t(* | flash_verify_erase_all_execute_only_segments )(flash_config_t *config, flash_margin_value_t margin)
status_t(* | flash_set_flexram_function )(flash_config_t *config, flash_flexram_function_option_t option)
status_t(* | flash_program_section )(flash_config_t *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes)

struct bootloader_tree_t

Root of the bootloader API tree.

An instance of this struct resides in read-only memory in the bootloader. It provides a user application access to APIs exported by the bootloader.

Note
  The order of existing fields must not be changed.

Collaboration diagram for bootloader_tree_t:
[legend]

### Data Fields

void(* | runBootloader )(void *arg)
| Function to start the bootloader executing.
standard_version_t | version
| Bootloader version number.
const char * | copyright
| Copyright string.
const bootloader_context_t * | runtimeContext
| Pointer to the bootloader's runtime context.
const flash_driver_interface_t * | flashDriver
| Flash driver API.
const aes_driver_interface_t * | aesDriver
| AES driver API.
standard_version_t | bootloader_version
| Bootloader version number.
const uint32_t * | reserved
| Do NOT use.

## Enumeration Type Documentation

enum _flash_driver_api_keys

Enumeration for 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.
kFLASH_ApiEraseKey | Key value used to validate all flash erase APIs.

enum _flash_driver_version_constants

FLASH driver version for ROM.

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.
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_execute_in_ram_function_constants

Constants for execute-in-ram flash function.

Enumerator
kFLASH_ExecuteInRamFunctionMaxSize | Max size of execute-in-ram function.
kFLASH_ExecuteInRamFunctionTotalNum | Total number of execute-in-ram functions.
kFLASH_ExecuteInRamFunctionMaxSize | Max size of execute-in-ram function.
kFLASH_ExecuteInRamFunctionTotalNum | Total number of execute-in-ram functions.

enum _flash_status

Flash driver status codes.

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.
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_execute_only_access_state_t

Enumeration for the three possible flash execute access levels.

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.
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_margin_value_t

Enumeration for supported flash margin levels.

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.
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_property_tag_t

Enumeration for various flash properties.

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.
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 size property.
kFLASH_PropertyDflashBlockCount | Dflash block count property.
kFLASH_PropertyDflashBlockBaseAddr | Dflash block base property.
kFLASH_PropertyEepromTotalSize | Eeprom total size property.
kFLASH_PropertyVersion | Flash driver version property.

enum flash_protection_state_t

Enumeration for the three possible flash protection levels.

Enumerator
kFLASH_ProtectionStateUnprotected | Flash region is not protected.
kFLASH_ProtectionStateProtected | Flash region is protected.
kFLASH_ProtectionStateMixed | Flash is mixed with protected and unprotected region.
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_read_resource_option_t

Enumeration for the two possible options of flash read resource command.

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
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_security_state_t

Enumeration for the three possible flash security states.

Enumerator
kFLASH_SecurityStateNotSecure | Flash is not secure.
kFLASH_SecurityStateBackdoorEnabled | Flash backdoor is enabled.
kFLASH_SecurityStateBackdoorDisabled | Flash backdoor is disabled.
kFLASH_SecurityStateNotSecure | Flash is not secure.
kFLASH_SecurityStateBackdoorEnabled | Flash backdoor is enabled.
kFLASH_SecurityStateBackdoorDisabled | Flash backdoor is disabled.

## Function Documentation

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.

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_EraseAll | ( | flash_config_t * | config,
|  | uint32_t | key
| ) |  |

Erases entire flash.

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_EraseAllExecuteOnlySegments | ( | flash_config_t * | config,
|  | uint32_t | key
| ) |  |

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_EraseAllUnsecure | ( | flash_config_t * | config,
|  | uint32_t | key
| ) |  |

Erases entire flash, including protected sectors.

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_GetProperty | ( | flash_config_t * | config,
|  | flash_property_tag_t | whichProperty,
|  | uint32_t * | value
| ) |  |

Returns the desired flash property.

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_GetSecurityState | ( | flash_config_t * | config,
|  | flash_security_state_t * | state
| ) |  |

Returns the security state via the pointer passed into the function.

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_Init | ( | flash_config_t * | config | ) |

Initializes global flash properties structure members.

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_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.

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_PrepareExecuteInRamFunctions | ( | flash_config_t * | config | ) |

Prepare flash execute-in-ram functions.

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_Program | ( | flash_config_t * | config,
|  | uint32_t | start,
|  | uint32_t * | src,
|  | uint32_t | lengthInBytes
| ) |  |

Programs flash with data at locations passed in through parameters.

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
| ) |  |

Programs Program Once Field through parameters.

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
| ) |  |

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_ReadResource | ( | flash_config_t * | config,
|  | uint32_t | start,
|  | uint32_t * | dst,
|  | uint32_t | lengthInBytes,
|  | flash_read_resource_option_t | option
| ) |  |

Read resource with data at locations passed in through parameters.

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.

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

Allows user to bypass security with a backdoor key.

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_SetCallback | ( | flash_config_t * | config,
|  | flash_callback_t | callback
| ) |  |

Set the desired flash callback function.

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_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.

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_VerifyEraseAll | ( | flash_config_t * | config,
|  | flash_margin_value_t | margin
| ) |  |

Verifies erasure of entire flash at specified margin level.

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_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.

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_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.

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.