All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
IAP: In Application Programming Driver

## Overview

The MCUXpresso SDK provides a driver for the In Application Programming (IAP) module of MCUXpresso SDK devices.

# Function groups

The driver provides a set of functions to call the on-chip in application programming interface. User code executing from on-chip RAM can call these functions to read information like part id; read and write flash, EEPROM and FAIM.

## Basic operations

The function IAP_ReadPartID() reads the part id of the board.

The function IAP_ReadBootCodeVersion() reads the boot code Version.

The function IAP_ReadUniqueID() reads the unique id of the boards.

The function IAP_ReinvokeISP() reinvokes the ISP mode.

The function IAP_ReadFactorySettings() reads the factory settings.

## Flash operations

The function IAP_PrepareSectorForWrite() prepares a sector for write or erase operation. Then, the function IAP_CopyRamToFlash() programs the flash memory.

The function IAP_EraseSector() erases a flash sector while the function IAP_ErasePage() erases a flash page.

The function IAP_BlankCheckSector() is used to blank check a sector or multiple sectors of on-chip flash memory.

The function IAP_Compare() is used to compare the memory contents at two locations. The user can compare several bytes (must be a multiple of 4) content in two different flash locations.

The function IAP_ReadFlashSignature() can get the 32-bits signature of the entire flash and the function IAP_ExtendedFlashSignatureRead() can calculate the signature of one or more flash pages.

## EEPROM operations

The function IAP_ReadEEPROMPage() reads the 128 bytes content of an EEPROM page and IAP_WriteEEPROMPage() writes 128 bytes content in an EEPROM page

## FAIM operations

The function IAP_ReadEEPROMPage() reads the 32 bits content of an FAIM page and IAP_WriteEEPROMPage() writes 32 bits content in an FAIM page

# Typical use case

## IAP Basic Operations

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/iap/iap_basic/

## IAP Flash Operations

Refer to the driver example codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/iap/iap_flash/

## IAP EEPROM Operations

Refer to the driver example codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/iap/iap_eeprom/

## IAP FAIM Operations

Refer to the driver example codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/iap/iap_faim/

## Files

file | fsl_iap.h

## Enumerations

enum

{
kStatus_IAP_Success = kStatus_Success,
kStatus_IAP_InvalidCommand = MAKE_STATUS(kStatusGroup_IAP, 1U),
kStatus_IAP_SrcAddrError = MAKE_STATUS(kStatusGroup_IAP, 2U),
kStatus_IAP_DstAddrError,
kStatus_IAP_SrcAddrNotMapped,
kStatus_IAP_DstAddrNotMapped,
kStatus_IAP_CountError,
kStatus_IAP_InvalidSector,
kStatus_IAP_SectorNotblank = MAKE_STATUS(kStatusGroup_IAP, 8U),
kStatus_IAP_NotPrepared,
kStatus_IAP_CompareError,
kStatus_IAP_Busy = MAKE_STATUS(kStatusGroup_IAP, 11U),
kStatus_IAP_ParamError,
kStatus_IAP_AddrError = MAKE_STATUS(kStatusGroup_IAP, 13U),
kStatus_IAP_AddrNotMapped = MAKE_STATUS(kStatusGroup_IAP, 14U),
kStatus_IAP_NoPower = MAKE_STATUS(kStatusGroup_IAP, 24U),
kStatus_IAP_NoClock = MAKE_STATUS(kStatusGroup_IAP, 27U),
kStatus_IAP_ReinvokeISPConfig = MAKE_STATUS(kStatusGroup_IAP, 0x1CU)
}

| iap status codes. More...

enum

_iap_commands {
kIapCmd_IAP_ReadFactorySettings = 40U,
kIapCmd_IAP_PrepareSectorforWrite = 50U,
kIapCmd_IAP_CopyRamToFlash = 51U,
kIapCmd_IAP_EraseSector = 52U,
kIapCmd_IAP_BlankCheckSector = 53U,
kIapCmd_IAP_ReadPartId = 54U,
kIapCmd_IAP_Read_BootromVersion = 55U,
kIapCmd_IAP_Compare = 56U,
kIapCmd_IAP_ReinvokeISP = 57U,
kIapCmd_IAP_ReadUid = 58U,
kIapCmd_IAP_ErasePage = 59U,
kIapCmd_IAP_ReadSignature = 70U,
kIapCmd_IAP_ExtendedReadSignature = 73U,
kIapCmd_IAP_ReadEEPROMPage = 80U,
kIapCmd_IAP_WriteEEPROMPage = 81U
}

| iap command codes. More...
enum | _flash_access_time { , kFlash_IAP_TwoSystemClockTime = 1U, kFlash_IAP_ThreeSystemClockTime = 2U }
| Flash memory access time. More...

## Driver version

#define | FSL_IAP_DRIVER_VERSION (MAKE_VERSION(2, 0, 6))

## Basic operations

status_t | IAP_ReadPartID (uint32_t *partID)
| Read part identification number. More...
status_t | IAP_ReadBootCodeVersion (uint32_t *bootCodeVersion)
| Read boot code version number. More...
void | IAP_ReinvokeISP (uint8_t ispType, uint32_t *status)
| Reinvoke ISP. More...
status_t | IAP_ReadUniqueID (uint32_t *uniqueID)
| Read unique identification. More...

## Flash operations

status_t | IAP_PrepareSectorForWrite (uint32_t startSector, uint32_t endSector)
| Prepare sector for write operation. More...
status_t | IAP_CopyRamToFlash (uint32_t dstAddr, uint32_t *srcAddr, uint32_t numOfBytes, uint32_t systemCoreClock)
| Copy RAM to flash. More...
status_t | IAP_EraseSector (uint32_t startSector, uint32_t endSector, uint32_t systemCoreClock)
| Erase sector. More...
status_t | IAP_ErasePage (uint32_t startPage, uint32_t endPage, uint32_t systemCoreClock)
| Erase page. More...
status_t | IAP_BlankCheckSector (uint32_t startSector, uint32_t endSector)
| Blank check sector(s) More...
status_t | IAP_Compare (uint32_t dstAddr, uint32_t *srcAddr, uint32_t numOfBytes)
| Compare memory contents of flash with ram. More...

## Enumeration Type Documentation

anonymous enum

Enumerator
kStatus_IAP_Success | Api is executed successfully.
kStatus_IAP_InvalidCommand | Invalid command.
kStatus_IAP_SrcAddrError | Source address is not on word boundary.
kStatus_IAP_DstAddrError | Destination address is not on a correct boundary.
kStatus_IAP_SrcAddrNotMapped | Source address is not mapped in the memory map.
kStatus_IAP_DstAddrNotMapped | Destination address is not mapped in the memory map.
kStatus_IAP_CountError | Byte count is not multiple of 4 or is not a permitted value.
kStatus_IAP_InvalidSector | Sector/page number is invalid or end sector/page number is greater than start sector/page number.
kStatus_IAP_SectorNotblank | One or more sectors are not blank.
kStatus_IAP_NotPrepared | Command to prepare sector for write operation has not been executed.
kStatus_IAP_CompareError | Destination and source memory contents do not match.
kStatus_IAP_Busy | Flash programming hardware interface is busy.
kStatus_IAP_ParamError | Insufficient number of parameters or invalid parameter.
kStatus_IAP_AddrError | Address is not on word boundary.
kStatus_IAP_AddrNotMapped | Address is not mapped in the memory map.
kStatus_IAP_NoPower | Flash memory block is powered down.
kStatus_IAP_NoClock | Flash memory block or controller is not clocked.
kStatus_IAP_ReinvokeISPConfig | Reinvoke configuration error.

enum _iap_commands

Enumerator
kIapCmd_IAP_ReadFactorySettings | Read the factory settings.
kIapCmd_IAP_PrepareSectorforWrite | Prepare Sector for write.
kIapCmd_IAP_CopyRamToFlash | Copy RAM to flash.
kIapCmd_IAP_EraseSector | Erase Sector.
kIapCmd_IAP_BlankCheckSector | Blank check sector.
kIapCmd_IAP_ReadPartId | Read part id.
kIapCmd_IAP_Read_BootromVersion | Read bootrom version.
kIapCmd_IAP_Compare | Compare.
kIapCmd_IAP_ReinvokeISP | Reinvoke ISP.
kIapCmd_IAP_ReadUid | Read Uid.
kIapCmd_IAP_ErasePage | Erase Page.
kIapCmd_IAP_ReadSignature | Read Signature.
kIapCmd_IAP_ExtendedReadSignature | Extended Read Signature.
kIapCmd_IAP_ReadEEPROMPage | Read EEPROM page.
kIapCmd_IAP_WriteEEPROMPage | Write EEPROM page.

enum _flash_access_time

Enumerator
kFlash_IAP_TwoSystemClockTime | 1 system clock flash access time
kFlash_IAP_ThreeSystemClockTime | 2 system clock flash access time

## Function Documentation

status_t IAP_ReadPartID | ( | uint32_t * | partID | ) |

This function is used to read the part identification number.

Parameters

  partID | Address to store the part identification number.

Return values

  kStatus_IAP_Success | Api has been executed successfully.

status_t IAP_ReadBootCodeVersion | ( | uint32_t * | bootCodeVersion | ) |

This function is used to read the boot code version number.

Parameters

  bootCodeVersion | Address to store the boot code version.

Return values

  kStatus_IAP_Success | Api has been executed successfully.

note Boot code version is two 32-bit words. Word 0 is the major version, word 1 is the minor version.

void IAP_ReinvokeISP | ( | uint8_t | ispType,
|  | uint32_t * | status
| ) |  |

This function is used to invoke the boot loader in ISP mode. It maps boot vectors and configures the peripherals for ISP.

Parameters

  ispType | ISP type selection.
  status | store the possible status.

Return values

  kStatus_IAP_ReinvokeISPConfig | reinvoke configuration error.

note The error response will be returned when IAP is disabled or an invalid ISP type selection appears. The call won't return unless an error occurs, so there can be no status code.

status_t IAP_ReadUniqueID | ( | uint32_t * | uniqueID | ) |

This function is used to read the unique id.

Parameters

  uniqueID | store the uniqueID.

Return values

  kStatus_IAP_Success | Api has been executed successfully.

status_t IAP_PrepareSectorForWrite | ( | uint32_t | startSector,
|  | uint32_t | endSector
| ) |  |

This function prepares sector(s) for write/erase operation. This function must be called before calling the IAP_CopyRamToFlash() or IAP_EraseSector() or IAP_ErasePage() function. The end sector number must be greater than or equal to the start sector number.

Parameters

  startSector | Start sector number.
  endSector | End sector number.

Return values

  kStatus_IAP_Success | Api has been executed successfully.
  kStatus_IAP_NoPower | Flash memory block is powered down.
  kStatus_IAP_NoClock | Flash memory block or controller is not clocked.
  kStatus_IAP_InvalidSector | Sector number is invalid or end sector number is greater than start sector number.
  kStatus_IAP_Busy | Flash programming hardware interface is busy.

status_t IAP_CopyRamToFlash | ( | uint32_t | dstAddr,
|  | uint32_t * | srcAddr,
|  | uint32_t | numOfBytes,
|  | uint32_t | systemCoreClock
| ) |  |

This function programs the flash memory. Corresponding sectors must be prepared via IAP_PrepareSectorForWrite before calling this function. The addresses should be a 256 byte boundary and the number of bytes should be 256 | 512 | 1024 | 4096.

Parameters

  dstAddr | Destination flash address where data bytes are to be written.
  srcAddr | Source ram address from where data bytes are to be read.
  numOfBytes | Number of bytes to be written.
  systemCoreClock | SystemCoreClock in Hz. It is converted to KHz before calling the rom IAP function. When the flash controller has a fixed reference clock, this parameter is bypassed.

Return values

  kStatus_IAP_Success | Api has been executed successfully.
  kStatus_IAP_NoPower | Flash memory block is powered down.
  kStatus_IAP_NoClock | Flash memory block or controller is not clocked.
  kStatus_IAP_SrcAddrError | Source address is not on word boundary.
  kStatus_IAP_DstAddrError | Destination address is not on a correct boundary.
  kStatus_IAP_SrcAddrNotMapped | Source address is not mapped in the memory map.
  kStatus_IAP_DstAddrNotMapped | Destination address is not mapped in the memory map.
  kStatus_IAP_CountError | Byte count is not multiple of 4 or is not a permitted value.
  kStatus_IAP_NotPrepared | Command to prepare sector for write operation has not been executed.
  kStatus_IAP_Busy | Flash programming hardware interface is busy.

status_t IAP_EraseSector | ( | uint32_t | startSector,
|  | uint32_t | endSector,
|  | uint32_t | systemCoreClock
| ) |  |

This function erases sector(s). The end sector number must be greater than or equal to the start sector number.

Parameters

  startSector | Start sector number.
  endSector | End sector number.
  systemCoreClock | SystemCoreClock in Hz. It is converted to KHz before calling the rom IAP function. When the flash controller has a fixed reference clock, this parameter is bypassed.

Return values

  kStatus_IAP_Success | Api has been executed successfully.
  kStatus_IAP_NoPower | Flash memory block is powered down.
  kStatus_IAP_NoClock | Flash memory block or controller is not clocked.
  kStatus_IAP_InvalidSector | Sector number is invalid or end sector number is greater than start sector number.
  kStatus_IAP_NotPrepared | Command to prepare sector for write operation has not been executed.
  kStatus_IAP_Busy | Flash programming hardware interface is busy.

status_t IAP_ErasePage | ( | uint32_t | startPage,
|  | uint32_t | endPage,
|  | uint32_t | systemCoreClock
| ) |  |

This function erases page(s). The end page number must be greater than or equal to the start page number.

Parameters

  startPage | Start page number.
  endPage | End page number.
  systemCoreClock | SystemCoreClock in Hz. It is converted to KHz before calling the rom IAP function. When the flash controller has a fixed reference clock, this parameter is bypassed.

Return values

  kStatus_IAP_Success | Api has been executed successfully.
  kStatus_IAP_NoPower | Flash memory block is powered down.
  kStatus_IAP_NoClock | Flash memory block or controller is not clocked.
  kStatus_IAP_InvalidSector | Page number is invalid or end page number is greater than start page number.
  kStatus_IAP_NotPrepared | Command to prepare sector for write operation has not been executed.
  kStatus_IAP_Busy | Flash programming hardware interface is busy.

status_t IAP_BlankCheckSector | ( | uint32_t | startSector,
|  | uint32_t | endSector
| ) |  |

Blank check single or multiples sectors of flash memory. The end sector number must be greater than or equal to the start sector number. It can be used to verify the sector erasure after IAP_EraseSector call.

Parameters

  startSector | Start sector number.
  endSector | End sector number.

Return values

  kStatus_IAP_Success | One or more sectors are in erased state.
  kStatus_IAP_NoPower | Flash memory block is powered down.
  kStatus_IAP_NoClock | Flash memory block or controller is not clocked.
  kStatus_IAP_SectorNotblank | One or more sectors are not blank.

status_t IAP_Compare | ( | uint32_t | dstAddr,
|  | uint32_t * | srcAddr,
|  | uint32_t | numOfBytes
| ) |  |

This function compares the contents of flash and ram. It can be used to verify the flash memory contents after IAP_CopyRamToFlash call.

Parameters

  dstAddr | Destination flash address.
  srcAddr | Source ram address.
  numOfBytes | Number of bytes to be compared.

Return values

  kStatus_IAP_Success | Contents of flash and ram match.
  kStatus_IAP_NoPower | Flash memory block is powered down.
  kStatus_IAP_NoClock | Flash memory block or controller is not clocked.
  kStatus_IAP_AddrError | Address is not on word boundary.
  kStatus_IAP_AddrNotMapped | Address is not mapped in the memory map.
  kStatus_IAP_CountError | Byte count is not multiple of 4 or is not a permitted value.
  kStatus_IAP_CompareError | Destination and source memory contents do not match.