The MCUXpresso SDK provides a driver for the In Application Programming (IAP).
It provides a set of functions to call the on-chip in application programming interface. User code executing from on-chip RAM can call these function to read information like part id, read and write flash, read and write ffr.
In Application Programming operation
FLASH_Init() Initializes the global flash properties structure members
FLASH_Erase() Erases the flash sectors encompassed by parameters passed into function
FLASH_Program() Programs flash with data at locations passed in through parameters
FLASH_VerifyErase() Verifies an erasure of the desired flash area hase been erased
FLASH_VerifyProgram() Verifies programming of the desired flash area hase been programed
FLASH_GetProperty() Returns the desired flash property.
FFR_Init() Generic APIs for FFR
FFR_Deinit() Generic APIs for FFR
FFR_CustomerPagesInit() APIs to access CFPA pages
FFR_InfieldPageWrite() APIs to access CFPA pages
FFR_GetCustomerInfieldData() APIs to access CMPA pages
FFR_GetCustomerData() Read data stored in 'Customer Factory CFG Page'
FFR_KeystoreWrite() Read data stored in 'Customer Factory CFG Page'
FFR_KeystoreGetAC() Read data stored in 'Customer Factory CFG Page'
FFR_KeystoreGetKC() Read data stored in 'Customer Factory CFG Page'
FFR_GetUUID() Read data stored in 'NXP Manufacuring Programmed CFG Page'
FFR_GetManufactureData() Read data stored in 'NXP Manufacuring Programmed CFG Page'
kb_init() Initialize ROM API for a given operation
kb_deinit() Cleans up the ROM API context
kb_execute() Perform the operation configured during init
skboot_authenticate() Authenticate entry function with ARENA allocator init
HASH_IRQHandler() Interface for image authentication API
kb_init() Initialize ROM API for a given operation
kb_deinit() Cleans up the ROM API context
kb_execute() Perform the operation configured during init
skboot_authenticate() Authenticate entry function with ARENA allocator init
HASH_IRQHandler() Interface for image authentication API
Typical use case
IAP Basic Operations
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/iap1
|
| enum | _flash_property_tag {
kFLASH_PropertyPflashSectorSize = 0x00U,
kFLASH_PropertyPflashTotalSize = 0x01U,
kFLASH_PropertyPflashBlockSize = 0x02U,
kFLASH_PropertyPflashBlockCount = 0x03U,
kFLASH_PropertyPflashBlockBaseAddr = 0x04U,
kFLASH_PropertyPflashPageSize = 0x30U,
kFLASH_PropertyPflashSystemFreq = 0x31U,
kFLASH_PropertyFfrSectorSize = 0x40U,
kFLASH_PropertyFfrTotalSize = 0x41U,
kFLASH_PropertyFfrBlockBaseAddr = 0x42U,
kFLASH_PropertyFfrPageSize = 0x43U
} |
| | Enumeration for various flash properties. More...
|
| |
| enum | _flash_max_erase_page_value { kFLASH_MaxPagesToErase = 100U
} |
| | Enumeration for flash max pages to erase. More...
|
| |
| enum | _flash_alignment_property {
kFLASH_AlignementUnitVerifyErase = 4,
kFLASH_AlignementUnitProgram = 512,
kFLASH_AlignementUnitSingleWordRead = 16
} |
| | Enumeration for flash alignment property. More...
|
| |
| enum | _flash_read_ecc_option { , kFLASH_ReadWithEccOff = 1
} |
| | Enumeration for flash read ecc option. More...
|
| |
| enum | _flash_read_margin_option {
kFLASH_ReadMarginNormal = 0,
kFLASH_ReadMarginVsProgram = 1,
kFLASH_ReadMarginVsErase = 2,
kFLASH_ReadMarginIllegalBitCombination = 3
} |
| | Enumeration for flash read margin option. More...
|
| |
| enum | _flash_read_dmacc_option {
kFLASH_ReadDmaccDisabled = 0,
kFLASH_ReadDmaccEnabled = 1
} |
| | Enumeration for flash read dmacc option. More...
|
| |
| enum | _flash_ramp_control_option {
kFLASH_RampControlDivisionFactorReserved = 0,
kFLASH_RampControlDivisionFactor256 = 1,
kFLASH_RampControlDivisionFactor128 = 2,
kFLASH_RampControlDivisionFactor64 = 3
} |
| | Enumeration for flash ramp control option. More...
|
| |
|
| 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,
kStatus_FLASH_ExecuteInRamFunctionNotReady,
kStatus_FLASH_CommandNotSupported = MAKE_STATUS(kStatusGroupFlashDriver, 11),
kStatus_FLASH_ReadOnlyProperty = MAKE_STATUS(kStatusGroupFlashDriver, 12),
kStatus_FLASH_InvalidPropertyValue,
kStatus_FLASH_InvalidSpeculationOption,
kStatus_FLASH_EccError,
kStatus_FLASH_CompareError,
kStatus_FLASH_RegulationLoss = MAKE_STATUS(kStatusGroupFlashDriver, 0x12),
kStatus_FLASH_InvalidWaitStateCycles,
kStatus_FLASH_OutOfDateCfpaPage,
kStatus_FLASH_BlankIfrPageData = MAKE_STATUS(kStatusGroupFlashDriver, 0x21),
kStatus_FLASH_EncryptedRegionsEraseNotDoneAtOnce,
kStatus_FLASH_ProgramVerificationNotAllowed,
kStatus_FLASH_HashCheckError,
kStatus_FLASH_SealedFfrRegion = MAKE_STATUS(kStatusGroupFlashDriver, 0x25),
kStatus_FLASH_FfrRegionWriteBroken,
kStatus_FLASH_NmpaAccessNotAllowed,
kStatus_FLASH_CmpaCfgDirectEraseNotAllowed,
kStatus_FLASH_FfrBankIsLocked = MAKE_STATUS(kStatusGroupFlashDriver, 0x29),
kStatus_FLASH_EraseFrequencyError,
kStatus_FLASH_ProgramFrequencyError
} |
| | Constructs a status code value from a group and a code number. More...
|
| |
| #define | kStatusGroupGeneric 0 |
| | Flash driver status group. More...
|
| |
|
#define | kStatusGroupFlashDriver 1 |
| |
| struct _flash_mode_config |
An instance of this structure is allocated by the user of the flash driver and passed into each of the driver APIs.
| uint32_t _flash_config::PFlashTotalSize |
| uint32_t _flash_config::PFlashBlockCount |
| uint32_t _flash_config::PFlashPageSize |
| uint32_t _flash_config::PFlashSectorSize |
Flash driver version for SDK Version 2.1.5.
| #define FSL_FEATURE_FLASH_IP_IS_C040HD_ATFC (1) |
| #define kStatusGroupGeneric 0 |
| #define FOUR_CHAR_CODE |
( |
|
a, |
|
|
|
b, |
|
|
|
c, |
|
|
|
d |
|
) |
| (((d) << 24) | ((c) << 16) | ((b) << 8) | ((a))) |
An instance of this structure is allocated by the user of the flash driver and passed into each of the driver APIs.
| 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.
|
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 the specified baseline.
|
| kStatus_FLASH_AddressError |
Address is out of range.
|
| kStatus_FLASH_AccessError |
Invalid instruction codes and out-of bound 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 |
The current region is execute-only.
|
| kStatus_FLASH_ExecuteInRamFunctionNotReady |
Execute-in-RAM function is not available.
|
| kStatus_FLASH_CommandNotSupported |
Flash API is not supported.
|
| kStatus_FLASH_ReadOnlyProperty |
The flash property is read-only.
|
| kStatus_FLASH_InvalidPropertyValue |
The flash property value is out of range.
|
| kStatus_FLASH_InvalidSpeculationOption |
The option of flash prefetch speculation is invalid.
|
| kStatus_FLASH_EccError |
A correctable or uncorrectable error during command execution.
|
| kStatus_FLASH_CompareError |
Destination and source memory contents do not match.
|
| kStatus_FLASH_RegulationLoss |
A loss of regulation during read.
|
| kStatus_FLASH_InvalidWaitStateCycles |
The wait state cycle set to r/w mode is invalid.
|
| kStatus_FLASH_OutOfDateCfpaPage |
CFPA page version is out of date.
|
| kStatus_FLASH_BlankIfrPageData |
Blank page cannnot be read.
|
| kStatus_FLASH_EncryptedRegionsEraseNotDoneAtOnce |
Encrypted flash subregions are not erased at once.
|
| kStatus_FLASH_ProgramVerificationNotAllowed |
Program verification is not allowed when the encryption is enabled.
|
| kStatus_FLASH_HashCheckError |
Hash check of page data is failed.
|
| kStatus_FLASH_SealedFfrRegion |
The FFR region is sealed.
|
| kStatus_FLASH_FfrRegionWriteBroken |
The FFR Spec region is not allowed to be written discontinuously.
|
| kStatus_FLASH_NmpaAccessNotAllowed |
The NMPA region is not allowed to be read/written/erased.
|
| kStatus_FLASH_CmpaCfgDirectEraseNotAllowed |
The CMPA Cfg region is not allowed to be erased directly.
|
| kStatus_FLASH_FfrBankIsLocked |
The FFR bank region is locked.
|
| kStatus_FLASH_EraseFrequencyError |
Core frequency is over 100MHZ.
|
| kStatus_FLASH_ProgramFrequencyError |
Core frequency is over 100MHZ.
|
- 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.
|
| 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_PropertyPflashPageSize |
Pflash page size property.
|
| kFLASH_PropertyPflashSystemFreq |
System Frequency System Frequency.
|
| kFLASH_PropertyFfrSectorSize |
FFR sector size property.
|
| kFLASH_PropertyFfrTotalSize |
FFR total size property.
|
| kFLASH_PropertyFfrBlockBaseAddr |
FFR block base address property.
|
| kFLASH_PropertyFfrPageSize |
FFR page size property.
|
| Enumerator |
|---|
| kFLASH_MaxPagesToErase |
The max value in pages to erase.
|
| Enumerator |
|---|
| kFLASH_AlignementUnitVerifyErase |
The alignment unit in bytes used for verify erase operation.
|
| kFLASH_AlignementUnitProgram |
The alignment unit in bytes used for program operation.
|
| kFLASH_AlignementUnitSingleWordRead |
The alignment unit in bytes used for verify program operation.
The alignment unit in bytes used for SingleWordRead command.
|
| Enumerator |
|---|
| kFLASH_ReadWithEccOff |
ECC is on.
|
| Enumerator |
|---|
| kFLASH_ReadMarginNormal |
Normal read.
|
| kFLASH_ReadMarginVsProgram |
Margin vs.
program
|
| kFLASH_ReadMarginVsErase |
Margin vs.
erase
|
| kFLASH_ReadMarginIllegalBitCombination |
Illegal bit combination.
|
| Enumerator |
|---|
| kFLASH_ReadDmaccDisabled |
Memory word.
|
| kFLASH_ReadDmaccEnabled |
DMACC word.
|
| Enumerator |
|---|
| kFLASH_RampControlDivisionFactorReserved |
Reserved.
|
| kFLASH_RampControlDivisionFactor256 |
clk48mhz / 256 = 187.5KHz
|
| kFLASH_RampControlDivisionFactor128 |
clk48mhz / 128 = 375KHz
|
| kFLASH_RampControlDivisionFactor64 |
clk48mhz / 64 = 750KHz
|
This function checks and initializes the Flash module for the other Flash APIs.
- Parameters
-
| config | Pointer to the storage for the driver runtime state. |
- Return values
-
This function erases the appropriate number of flash sectors based on the desired start address and length.
- Parameters
-
| config | The pointer to the storage for the driver runtime state. |
| start | The start address of the desired flash memory to be erased. The start address need to be 512bytes-aligned. |
| lengthInBytes | The length, given in bytes (not words or long-words) to be erased. Must be 512bytes-aligned. |
| key | The value used to validate all flash erase APIs. |
- Return values
-
| status_t FLASH_Program |
( |
flash_config_t * |
config, |
|
|
uint32_t |
start, |
|
|
const uint8_t * |
src, |
|
|
uint32_t |
lengthInBytes |
|
) |
| |
This function programs the flash memory with the desired data for a given flash area as determined by the start address and the length.
- Parameters
-
| config | A pointer to the storage for the driver runtime state. |
| start | The start address of the desired flash memory to be programmed. Must be 512bytes-aligned. |
| src | A 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 512bytes-aligned. |
- Return values
-
This function read the flash memory from a given flash area as determined by the start address and the length.
- Parameters
-
| config | A pointer to the storage for the driver runtime state. |
| start | The start address of the desired flash memory to be read. |
| dest | A pointer to the dest buffer of data that is to be read from the flash. |
| lengthInBytes | The length, given in bytes (not words or long-words), to be read. |
- Return values
-
This function checks the appropriate number of flash sectors based on the desired start address and length to check whether the flash is erased to the specified read margin level.
- Parameters
-
| config | A pointer to the storage for the driver runtime state. |
| start | The start address of the desired flash memory to be verified. The start address need to be 512bytes-aligned. |
| lengthInBytes | The length, given in bytes (not words or long-words), to be verified. Must be 512bytes-aligned. |
- Return values
-
| status_t FLASH_VerifyProgram |
( |
flash_config_t * |
config, |
|
|
uint32_t |
start, |
|
|
uint32_t |
lengthInBytes, |
|
|
const uint8_t * |
expectedData, |
|
|
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 to the expected data for a given flash area as determined by the start address and length.
- Parameters
-
| config | A pointer to the storage for the driver runtime state. |
| start | The start address of the desired flash memory to be verified. need be 512bytes-aligned. |
| lengthInBytes | The length, given in bytes (not words or long-words), to be verified. need be 512bytes-aligned. |
| expectedData | A pointer to the expected data that is to be verified against. |
| failedAddress | A pointer to the returned failing address. |
| failedData | A pointer to the returned failing data. Some derivatives do not include failed data as part of the FCCOBx registers. In this case, zeros are returned upon failure. |
- Return values
-
- Parameters
-
| config | A pointer to the storage for the driver runtime state. |
| whichProperty | The desired property from the list of properties in enum flash_property_tag_t |
| value | A pointer to the value returned for the desired flash property. |
- Return values
-
| void BOOTLOADER_UserEntry |
( |
void * |
arg | ) |
|
- Parameters
-
| arg | Indicates API prototype fields definition. Refer to the above user_app_boot_invoke_option_t structure |
