Simulated EEPROM#

halSimEepromCallback#

void halSimEepromCallback (EmberStatus status)

The Simulated EEPROM callback function, implemented by the application.

This callback will report an EmberStatus of EMBER_SIM_EEPROM_ERASE_PAGE_GREEN whenever a token is set and a page needs to be erased. If the main application loop does not periodically call halSimEepromErasePage(), it is best to then erase a page in response to EMBER_SIM_EEPROM_ERASE_PAGE_GREEN.

This callback will report an EmberStatus of EMBER_SIM_EEPROM_ERASE_PAGE_RED when the pages must be erased to prevent data loss. halSimEepromErasePage() needs to be called until it returns 0 to indicate there are no more pages that need to be erased. Ignoring this indication and not erasing the pages will cause dropping the new data trying to be written.

This callback will report an EmberStatus of EMBER_SIM_EEPROM_FULL when the new data cannot be written due to unerased pages. Not erasing pages regularly, not erasing in response to EMBER_SIM_EEPROM_ERASE_PAGE_GREEN, or not erasing in response to EMBER_SIM_EEPROM_ERASE_PAGE_RED will cause EMBER_SIM_EEPROM_FULL and the new data will be lost!. Any future write attempts will be lost as well.

This callback will report an EmberStatus of EMBER_SIM_EEPROM_REPAIRING when the Simulated EEPROM needs to repair itself. While there's nothing for an app to do when the SimEE is going to repair itself (SimEE has to be fully functional for the rest of the system to work), alert the application to the fact that repairing is occuring. There are debugging scenarios where an app might want to know that repairing is happening; such as monitoring frequency. Note

• Common situations will trigger an expected repair, such as using a new chip or changing token definitions.

If the callback ever reports the status EMBER_ERR_FLASH_WRITE_INHIBITED or EMBER_ERR_FLASH_VERIFY_FAILED, this indicates a catastrophic failure in flash writing, meaning either the address being written is not empty or the write itself has failed. If EMBER_ERR_FLASH_WRITE_INHIBITED is encountered, the function ::halInternalSimEeRepair(false) should be called and the chip should then be reset to allow proper initialization to recover. If EMBER_ERR_FLASH_VERIFY_FAILED is encountered the Simulated EEPROM (and tokens) on the specific chip with this error should not be trusted anymore.

halSimEepromErasePage#

uint8_t halSimEepromErasePage (void )

Erases a hardware flash page, if needed.

This function can be called at anytime from anywhere in the application (except ISRs) and will only take effect if needed (otherwise it will return immediately). Since this function takes 21ms to erase a hardware page during which interrupts cannot be serviced, it is preferable to call this function while in a state that can withstand being unresponsive for so long. The Simulated EEPROM will periodically request through the halSimEepromCallback() that a page be erased. The Simulated EEPROM will never erase a page (which could result in data loss) and relies entirely on the application to call this function to approve a page erase (only one erase per call to this function).

The Simulated EEPROM depends on the ability to move between two Virtual Pages, which are comprised of multiple hardware pages. Before moving to the unused Virtual Page, all hardware pages comprising the unused Virtual Page must be erased first. The erase time of a hardware flash page is 21ms. During this time the chip will be unresponsive and unable to service an interrupt or execute any code (due to the flash being unavailable during the erase procedure). This function is used to trigger a page erase.

Returns

• A count of how many hardware pages are left to be erased. This return value allows for calling code to easily loop over this function until the function returns 0.

halSimEepromPagesRemainingToBeErased#

uint8_t halSimEepromPagesRemainingToBeErased (void )

Get count of pages to be erased.

This function returns the same value halSimEepromErasePage() would return, but without modifying/erasing any flash.

Returns

• A count of how many hardware pages are left to be erased. This code assist with loops wanting to know how much is left to erase.

halSimEepromStatus#

void halSimEepromStatus (uint16_t * freeWordsUntilFull, uint16_t * totalPageUseCount)

Provides two basic statistics.

• The number of unused words until SimEE is full

• The total page use count

There is a lot of management and state processing involved with the Simulated EEPROM, and most of it has no practical purpose in the application. These two parameters provide a simple metric for knowing how soon the Simulated EEPROM will be full (::freeWordsUntilFull) and how many times (approximatly) SimEE has rotated pysical flash pages (::totalPageUseCount).