Simulated EEPROM system for wear leveling token storage across flash. See Simulated EEPROM for documentation.
License#
Copyright 2018 Silicon Laboratories Inc. www.silabs.com
The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.
/***************************************************************************/
#ifndef __SIM_EEPROM_H__
#define __SIM_EEPROM_H__
//pull in the platform specific information here
#if defined(CORTEXM3) || defined(EMBER_TEST)
#include "sim-eeprom-cortexm3.h"
#else
#error invalid sim-eeprom platform
#endif
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//Prototype for internal Startup for the public Init and Repair macros
EmberStatus halInternalSimEeStartup(bool forceRebuildAll);
//Properly round values when converting bytes to words
#define BYTES_TO_WORDS(x) (((x) + 1) / 2)
#endif
//application functions
void halSimEepromCallback(EmberStatus status);
uint8_t halSimEepromErasePage(void);
uint8_t halSimEepromPagesRemainingToBeErased(void);
void halSimEepromStatus(uint16_t *freeWordsUntilFull, uint16_t *totalPageUseCount);
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//NOTE: halInternal functions must not be called directly.
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus halInternalSimEeInit(void);
#else
#define halInternalSimEeInit() (halInternalSimEeStartup(false))
#endif
void halInternalSimEeGetData(void *vdata,
uint8_t compileId,
uint8_t index,
uint8_t len);
void halInternalSimEeSetData(uint8_t compileId,
void *vdata,
uint8_t index,
uint8_t len);
void halInternalSimEeIncrementCounter(uint8_t compileId);
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus halInternalSimEeRepair(bool forceRebuildAll);
#else
#define halInternalSimEeRepair(rebuild) (halInternalSimEeStartup(rebuild))
#endif
#endif //DOXYGEN_SHOULD_SKIP_THIS
#endif //__SIM_EEPROM_H__
Functions#
The Simulated EEPROM callback function, implemented by the application.
Erases a hardware flash page, if needed.
Get count of pages to be erased.
Provides two basic statistics.
Function Documentation#
halSimEepromCallback#
void halSimEepromCallback (EmberStatus status)
The Simulated EEPROM callback function, implemented by the application.
| N/A | 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.
130 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/platform/base/hal/plugin/sim-eeprom/sim-eeprom.hhalSimEepromErasePage#
uint8_t halSimEepromErasePage (void )
Erases a hardware flash page, if needed.
| N/A |
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.
158 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/platform/base/hal/plugin/sim-eeprom/sim-eeprom.hhalSimEepromPagesRemainingToBeErased#
uint8_t halSimEepromPagesRemainingToBeErased (void )
Get count of pages to be erased.
| N/A |
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.
168 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/platform/base/hal/plugin/sim-eeprom/sim-eeprom.hhalSimEepromStatus#
void halSimEepromStatus (uint16_t * freeWordsUntilFull, uint16_t * totalPageUseCount)
Provides two basic statistics.
| N/A | 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. |
| N/A | totalPageUseCount | The value of the highest page counter indicating how many times the Simulated EEPROM has rotated physical flash pages (and approximate write cycles). |
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).
190 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/platform/base/hal/plugin/sim-eeprom/sim-eeprom.h