Simulated EEPROM
Hardware Abstraction Layer (HAL) API Reference > Token Access

Functions

void halSimEepromCallback ( EmberStatus status)
The Simulated EEPROM callback function, implemented by the application.
uint8_t halSimEepromErasePage (void)
Erases a hardware flash page, if needed.
uint8_t halSimEepromPagesRemainingToBeErased (void)
Get count of pages to be erased.
void halSimEepromStatus (uint16_t *freeWordsUntilFull, uint16_t *totalPageUseCount)
Provides two basic statistics.

Detailed Description

The Simulated EEPROM system (typically referred to as SimEE) is designed to operate under the Token Access API and provide a non-volatile storage system. Since the flash write cycles are finite, the Simulated EEPROM's primary purpose is to perform wear leveling across several hardware flash pages, ultimately increasing the number of times tokens may be written before a hardware failure.

The Simulated EEPROM needs to periodically perform a page erase operation to recover storage area for future token writes. The page erase operation requires an ATOMIC block of 21ms. Since this is such a long time to not be able to service any interrupts, the page erase operation is under application control providing the application the opportunity to decide when to perform the operation and complete any special handling needed that might be needed.

Note
The best, safest, and recommended practice is for the application to regularly and always call the function halSimEepromErasePage() when the application can expect and deal with the page erase delay. halSimEepromErasePage() will immediately return if there is nothing to erase. If there is something that needs to be erased, doing so as regularly and as soon as possible will keep the SimEE in the healthiest state possible.

::ERASE_CRITICAL_THRESHOLD is the metric the freePtr is compared against. This metric is set to about 3/4 full. The freePtr is a marker used internally by the Simulated EEPROM to track where data ends and where available write space begins. If the freePtr crosses this threhold, halSimEepromCallback() will be called with an EmberStatus of EMBER_SIM_EEPROM_ERASE_PAGE_RED , indicating a critical need for the application to call halSimEepromErasePage() which will erase a hardware page and provide fresh storage for the Simulated EEPROM to write token data. If freePtr is less than the threshold, the callback will have an EmberStatus of EMBER_SIM_EEPROM_ERASE_PAGE_GREEN indicating the application should call halSimEepromErasePage() at its earliest convenience, but doing so is not critically important at this time.

Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus return values.

See hal/plugin/sim-eeprom/sim-eeprom.h for source code.

Function Documentation

void halSimEepromCallback ( EmberStatus status )
Parameters
status An EmberStatus error code indicating one of the conditions described below.

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.

References assert , EMBER_ERR_FLASH_VERIFY_FAILED , EMBER_ERR_FLASH_WRITE_INHIBITED , EMBER_SIM_EEPROM_ERASE_PAGE_GREEN , EMBER_SIM_EEPROM_ERASE_PAGE_RED , EMBER_SIM_EEPROM_FULL , EMBER_SIM_EEPROM_REPAIRING , halInternalSysReset() , halSimEepromErasePage() , and halSimEepromPagesRemainingToBeErased() .

uint8_t halSimEepromErasePage ( void )

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.

Referenced by halSimEepromCallback() .

uint8_t halSimEepromPagesRemainingToBeErased ( void )

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.

Referenced by halSimEepromCallback() .

void halSimEepromStatus ( uint16_t * freeWordsUntilFull,
uint16_t * totalPageUseCount
)
  • 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).

Parameters
freeWordsUntilFull Number of unused words available to SimEE until the SimEE is full and would trigger an EMBER_SIM_EEPROM_ERASE_PAGE_RED then EMBER_SIM_EEPROM_FULL callback.
totalPageUseCount The value of the highest page counter indicating how many times the Simulated EEPROM has rotated physical flash pages (and approximate write cycles).