The In Application Programming driver (IAP) API implements a wrapper for the actual code which is in ROM, and which is exposed via the binary IAP interface. The driver exposes the following features:
- Read factory settings.
- Prepare (unprotect) sectors for flash erase/program operations.
- Erase flash sectors.
- Erase flash pages.
- Copy the data from RAM/EEPROM and write to flash.
- Perform blank checking of the flash sectors.
- Read Part Identification.
- Read boot code version.
- Read UID (Unique Identification) which is the device serial number.
- Perform comparison of two memory spaces.
The "Prepare" command will unprotect the sectors, and upon success execution of the flash operations including sector erase, page erase, and program commands, the touched sectors will be protected automatically.
- Warning
- To erase/program the flash, the system clock must be set to a clock frequency of minimum 125kHz.
- See also
- Please refer to the chapter "In Application Programming Firmware" of the User Manual for details on the IAP interface.
- Warning
- During an erase or program operation, the flash is not accessible, hence if the Interrupt Vector Table is placed in Flash (default setup) the application should make sure that no interrupts are triggered. To disable all interrupts please refer to __disable_irq(void).
- Example1 - Erase flash sector 10 and write 4 pages (e.g. 64 bytes per page)
- of data to the start address of sector 10
- Data : stored in ram buffer "buffer[256]"
- Flash address : start address of sector 10. (Since each sector contain 16 pages, the first page in sector 10 is 10 * 16 = 160. Since sectors are 1024 bytes, the start address of sector 10 is 10 * 1024 = 10240.)
- System clock : 8 MHz
uint32_t offset;
uint32_t content;
void *pFlash;
pFlash = (void *)10240;
- Example 2 - Load RTC factory calibration value into RTC
-
- Example 3 - Read Part ID, boot version & UID
|
enum | IAP_STATUS_T {
IAP_STATUS_CMD_SUCCESS = 0,
IAP_STATUS_INVALID_COMMAND = 1,
IAP_STATUS_SRC_ADDR_ERROR = 2,
IAP_STATUS_DST_ADDR_ERROR = 3,
IAP_STATUS_SRC_ADDR_NOT_MAPPED = 4,
IAP_STATUS_DST_ADDR_NOT_MAPPED = 5,
IAP_STATUS_COUNT_ERROR = 6,
IAP_STATUS_INVALID_SECTOR = 7,
IAP_STATUS_SECTOR_NOT_BLANK = 8,
IAP_STATUS_SECTOR_NOT_PREPARED = 9,
IAP_STATUS_COMPARE_ERROR = 10,
IAP_STATUS_BUSY = 11,
IAP_STATUS_PARAM_ERROR = 12,
IAP_STATUS_ADDR_ERROR = 13
} |
|
|
uint32_t | Chip_IAP_ReadFactorySettings (uint32_t address) |
|
uint32_t | Chip_IAP_ReadPartID (void) |
|
int | Chip_IAP_ReadBootVersion (void) |
|
void | Chip_IAP_ReadUID (uint32_t uid[4]) |
|
IAP_STATUS_T | Chip_IAP_Flash_PrepareSector (uint32_t sectorStart, uint32_t sectorEnd) |
|
IAP_STATUS_T | Chip_IAP_Flash_EraseSector (uint32_t sectorStart, uint32_t sectorEnd, uint32_t kHzSysClk) |
|
IAP_STATUS_T | Chip_IAP_Flash_ErasePage (uint32_t pageStart, uint32_t pageEnd, uint32_t kHzSysClk) |
|
IAP_STATUS_T | Chip_IAP_Flash_Program (const void *pSrc, const void *pFlash, uint32_t size, uint32_t kHzSysClk) |
|
IAP_STATUS_T | Chip_IAP_Flash_SectorBlankCheck (uint32_t sectorStart, uint32_t sectorEnd, uint32_t *pOffset, uint32_t *pContent) |
|
IAP_STATUS_T | Chip_IAP_Compare (const void *pAddress1, const void *pAddress2, uint32_t size, uint32_t *pOffset) |
|
◆ IAP_STATUS_T
Possible return codes from the IAP
Enumerator |
---|
IAP_STATUS_CMD_SUCCESS | SUCCESS
|
IAP_STATUS_INVALID_COMMAND | Command number is invalid
|
IAP_STATUS_SRC_ADDR_ERROR | Source address not on word boundary
|
IAP_STATUS_DST_ADDR_ERROR | Destination address not on word or 64 byte boundary
|
IAP_STATUS_SRC_ADDR_NOT_MAPPED | Source address is out of range
|
IAP_STATUS_DST_ADDR_NOT_MAPPED | Destination address is out of range
|
IAP_STATUS_COUNT_ERROR | Byte count is not multiple of 4 or is not a permitted value
|
IAP_STATUS_INVALID_SECTOR | Sector number is invalid
|
IAP_STATUS_SECTOR_NOT_BLANK | Sector is not blank
|
IAP_STATUS_SECTOR_NOT_PREPARED | Sector is not prepared, or still protected
|
IAP_STATUS_COMPARE_ERROR | Compare error which means the data buffers contain different content
|
IAP_STATUS_BUSY | Flash hardware is busy
|
IAP_STATUS_PARAM_ERROR | Insufficient number of parameters
|
IAP_STATUS_ADDR_ERROR | Address is not on word boundary
|
◆ Chip_IAP_ReadFactorySettings()
uint32_t Chip_IAP_ReadFactorySettings |
( |
uint32_t |
address | ) |
|
Read factory settings for calibration registers
- Parameters
-
address | : Address of the targeted calibration register that needs to read the factory setting, Please see the user manual to find out which registers have factory setting available. |
- Returns
- Output parameter for the factory setting
- Note
- This function asserts that the requested address does correspond to a supported factory setting.
- Warning
- As part of this API call, EEPROM is de-initialized before the IAP command execution, if it was already in initialized state. Following that, it will get initialized back after the IAP command gets executed. Thus the execution time for this function will vary depending on the state of EEPROM prior to calling this function.
◆ Chip_IAP_ReadPartID()
uint32_t Chip_IAP_ReadPartID |
( |
void |
| ) |
|
Read Part Identification Number
- Returns
- Part Identification Number read via IAP command.
◆ Chip_IAP_ReadBootVersion()
int Chip_IAP_ReadBootVersion |
( |
void |
| ) |
|
Read boot version number
- Returns
- Boot version number. Read as:
- <Byte 3> : Reserved.
- <Byte 2> : Reserved.
- <Byte 1> : Major Version Number, 8 bits.
- <Byte 0> : Minor Version Number, 8 bits, LSB.
- Note
- Mask operation is required in order to get the correct version number.
◆ Chip_IAP_ReadUID()
void Chip_IAP_ReadUID |
( |
uint32_t |
uid[4] | ) |
|
Read UID - the device serial number
- Parameters
-
uid | : array with caller allocated space of 4 words that will be filled with the UID. |
- Warning
- As part of this API call, EEPROM is de-initialized before the IAP command execution, if it was already in initialized state. Following that, it will get initialized back after the IAP command gets executed. Thus the execution time for this function will vary depending on the state of EEPROM prior to calling this function.
◆ Chip_IAP_Flash_PrepareSector()
IAP_STATUS_T Chip_IAP_Flash_PrepareSector |
( |
uint32_t |
sectorStart, |
|
|
uint32_t |
sectorEnd |
|
) |
| |
Prepare (i.e. unprotect) the flash sectors
- Parameters
-
sectorStart | : The first sector that will be unprotected. |
sectorEnd | : The last sector that will be unprotected. |
- Returns
- Result of the operation.
- Note
- Both the start sector and end sector are inclusive.
-
Please keep the claimed RAM area untouched. Refer to user manual for more details.
◆ Chip_IAP_Flash_EraseSector()
IAP_STATUS_T Chip_IAP_Flash_EraseSector |
( |
uint32_t |
sectorStart, |
|
|
uint32_t |
sectorEnd, |
|
|
uint32_t |
kHzSysClk |
|
) |
| |
Erase flash sectors
- Parameters
-
sectorStart | : The first sector to be erased. |
sectorEnd | : The last sector to be erased. |
kHzSysClk | : The actual CPU clock speed in kHz. This parameter will be ignored for chips without external clock. |
- Returns
- Result of the operation.
- Note
- Both the start sector and end sector are inclusive.
-
Chip_IAP_Flash_PrepareSector must be called in advance for all sectors.
-
For page level erase, please refer to API Chip_IAP_Flash_ErasePage.
-
Please keep the claimed RAM area untouched. Refer to user manual for more details.
- Precondition
- If the Interrupt Vector Table is placed in Flash (default setup) disable all interrupts: __disable_irq(void)
- Postcondition
- If interrupts were disabled, enable them again: __enable_irq(void)
◆ Chip_IAP_Flash_ErasePage()
IAP_STATUS_T Chip_IAP_Flash_ErasePage |
( |
uint32_t |
pageStart, |
|
|
uint32_t |
pageEnd, |
|
|
uint32_t |
kHzSysClk |
|
) |
| |
Erase flash pages
- Parameters
-
pageStart | : The first page to be erased. |
pageEnd | : The last page to be erased. |
kHzSysClk | : The actual CPU clock speed in kHz. This parameter will be ignored for chips without external clock. |
- Returns
- Result of the operation.
- Note
- Both the start page and end page are inclusive.
-
Chip_IAP_Flash_PrepareSector must be called in advance for all sectors involved.
-
For sector level erase, please refer to API Chip_IAP_Flash_EraseSector.
-
Please keep the claimed RAM area untouched. Refer to user manual for more details.
- Precondition
- If the Interrupt Vector Table is placed in Flash (default setup) disable all interrupts: __disable_irq(void)
- Postcondition
- If interrupts were disabled, enable them again: __enable_irq(void)
◆ Chip_IAP_Flash_Program()
IAP_STATUS_T Chip_IAP_Flash_Program |
( |
const void * |
pSrc, |
|
|
const void * |
pFlash, |
|
|
uint32_t |
size, |
|
|
uint32_t |
kHzSysClk |
|
) |
| |
Copy data from RAM and write/program to flash
- Parameters
-
pSrc | : The ram or EEPROM address where the data is copied from. Must be word (32 bits) aligned. |
pFlash | : The flash address where the data is copied to. Must be page (64 bytes) aligned. |
size | : Number of bytes to be copied from RAM to flash. Must be multiple of 64. |
kHzSysClk | : The actual CPU clock speed in kHz. This parameter will be ignored for chips without external clock. |
- Returns
- Result of the operation.
- Note
- This API implements the IAP command "Copy RAM to Flash" listed in user manual.
-
The involved pages (or sectors) must be erased before this function is called, unless partial page write is intended (see note below).
-
If partial page writes are intended:
- User needs to ensure that the region of the page to be written is previously erased (all 0xFFs)
- User needs to ensure that the region of the page to be left untouched is overwritten with the same data or with all 0xFFs
- User needs to ensure that partial writes are always in a word boundary (the content of one word shall not be written more than once after erasing)
Typical flow:
- Erase page (content is FFFFFFFF FFFFFFFF ... FFFFFFFF)
- Write first word 0x01234567 by writing "01234567 FFFFFFFF ... FFFFFFFF" (content becomes 01234567 FFFFFFFF ... FFFFFFFF)
- Write second word 0x89ABCDEF by either:
- writing "FFFFFFFF 89ABCDEF ... FFFFFFFF", or
- writing "01234567 89ABCDEF ... FFFFFFFF" (content becomes 01234567 89ABCDEF ... FFFFFFFF)
Writing to the first and second word after this flow requires a new erase procedure, but writing words 3 to 16 not.
-
Please keep the claimed RAM area untouched. Refer to user manual for more details.
- Precondition
- If the Interrupt Vector Table is placed in Flash (default setup) disable all interrupts: __disable_irq(void)
- Postcondition
- If interrupts were disabled, enable them again: __enable_irq(void)
◆ Chip_IAP_Flash_SectorBlankCheck()
IAP_STATUS_T Chip_IAP_Flash_SectorBlankCheck |
( |
uint32_t |
sectorStart, |
|
|
uint32_t |
sectorEnd, |
|
|
uint32_t * |
pOffset, |
|
|
uint32_t * |
pContent |
|
) |
| |
Blank check on flash sectors
- Parameters
-
sectorStart | : The first sector to be checked. |
sectorEnd | : The last sector to be checked. |
pOffset | : output parameter with the (word) offset for the first non-blank word; when the result is IAP_STATUS_SECTOR_NOT_BLANK . |
pContent | : output parameter with the value of the first non-blank word; when the result is IAP_STATUS_SECTOR_NOT_BLANK . |
- Returns
- Result of the operation.
- Note
pOffset
and/or pContent
may be NULL
. In that case, offset and/or content are not reported, but the function still performs.
◆ Chip_IAP_Compare()
IAP_STATUS_T Chip_IAP_Compare |
( |
const void * |
pAddress1, |
|
|
const void * |
pAddress2, |
|
|
uint32_t |
size, |
|
|
uint32_t * |
pOffset |
|
) |
| |
Compare two memory spaces to find out if their contents are same.
- Parameters
-
pAddress1 | : The start address of the memory block to be compared. Must be word (32 bits) aligned. |
pAddress2 | : The start address of the memory block to compare with. Must be word (32 bits) aligned. |
size | : Number of bytes to be compared. Must be multiple of 4. |
pOffset | : The output parameter with the (word) offset for the first unequal words; when the compare result is IAP_STATUS_COMPARE_ERROR. |
- Returns
- Result of the operation.
- Note
pOffset
may be NULL
. In that case, offset is not reported, but the function still performs.