NHS31xx SW API
iap: In Application Programming driver

Detailed Description

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:

  1. Read factory settings.
  2. Prepare (unprotect) sectors for flash erase/program operations.
  3. Erase flash sectors.
  4. Erase flash pages.
  5. Copy the data from RAM/EEPROM and write to flash.
  6. Perform blank checking of the flash sectors.
  7. Read Part Identification.
  8. Read boot code version.
  9. Read UID (Unique Identification) which is the device serial number.
  10. 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;
IAP_STATUS_T result;
result = Chip_IAP_Flash_PrepareSector(10, 10);
result = Chip_IAP_Flash_EraseSector(10, 10, 8000);
result = Chip_IAP_Flash_SectorBlankCheck(10, 10, &offset, &content); /* Optional */
result = Chip_IAP_Flash_PrepareSector(10, 10);
pFlash = (void *)10240; /* pFlash points to start address of sector 10 */
result = Chip_IAP_Flash_Program(buffer, pFlash, 256, 8000);
result = Chip_IAP_Compare(buffer, pFlash, 256, &offset); /* Optional */
Example 2 - Load RTC factory calibration value into RTC
uint32_t rtcCal = Chip_IAP_ReadFactorySettings((uint32_t) &NSS_RTC->CAL);
Example 3 - Read Part ID, boot version & UID
uint32_t partID = Chip_IAP_ReadPartID();
int bootVersion = Chip_IAP_ReadBootVersion() & 0x0000FFFF; /* Mask off byte2 and byte3 */
uint32_t uid[4];

Enumerations

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
}
 

Functions

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)
 

Enumeration Type Documentation

◆ 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

Function Documentation

◆ 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:
  1. Erase page (content is FFFFFFFF FFFFFFFF ... FFFFFFFF)
  2. Write first word 0x01234567 by writing "01234567 FFFFFFFF ... FFFFFFFF" (content becomes 01234567 FFFFFFFF ... FFFFFFFF)
  3. 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.