embedded software boot camp

Keeping your EEPROM data valid through firmware updates

Thursday, November 26th, 2009 by Nigel Jones

Back when embedded systems used EPROM (no that is not a typo for my younger readers) rather than Flash, the likelihood of the code being updated in the field was close to nil. Today however, it is common for embedded systems to contain mechanisms to allow the code to be updated easily. Like most people, I embraced this feature enthusiastically. However, after I’d implemented a few systems that were field upgradable, I discovered that the ability to update in the field had an unexpected impact on my EEPROM data. To see what I mean, read on…

Most of the embedded systems I work on contain EEPROM. One of the prime uses for this EEPROM is for storing configuration / calibration information for the system. As a result, I often store data in EEPROM as a series of data structures at fixed locations, with gaps in between them. Thus, my EEPROM map might look something like this:

#define CAL_DATA_LOCATION     0x0010
#define CONFIG_DATA_LOCATION  0x0200
...
#define SYSTEM_PARAMS_LOCATION  0x1000
typedef struct
{
 uint32_t param1;
 uint16_t param2;
 ...
 uint8_t  spare[10];
} CALIBRATION_DATA;
__eeprom CALIBRATION_DATA Cal_Data @ CAL_DATA_LOCATION;
__eeprom CONFIGURATION_DATA Config_Data @ CONFIG_DATA_LOCATION;
...
__eeprom SYSTEM_DATA System_Data @ SYSTEM_PARAMS_LOCATION;

As you can see, I was smart enough to allow room for growth within the structure via the spare[] array. (I have intentionally omitted support related to corruption detection to avoid complicating the issue at hand). As a result I thought I was all set if at some time a SW update caused me to have to use more parameters in a given EEPROM structure. Well I went along in this blissful state of ignorance for a few years until the real world intruded in a rather ugly way. Here’s what happened. The firmware upgrade didn’t require me to add any new parameters to the EEPROM, per se, but it did require that the data type of some of the parameters be changed. For example, my CALIBRATION_DATA structure example might have to change to this:

typedef struct
{
 float     param1;
 uint16_t  param2;
 ...
 uint8_t   spare[10];
} CALIBRATION_DATA;

Thus param1 has changed from a uint32_t type to a float. Thus when the new code powered up, it had to read param1 as a uint32_t, and then convert it to a float type and write it back to the EEPROM. This clearly was quite straightforward. However, where the problem came was the next time the system powered up. I realized that without some sort of logic in place, I would re-read param1, treat it as a uint32_t (even though it is a float), ‘convert’ it to a float and write it back to EEPROM. Clearly I needed some method of signaling that I had already performed the requisite upgrade. As I pondered this problem, I realized that it was even more complicated. Let us denote the two versions of CALIBRATION_DATA as version 1 and version 2 respectively. Furthermore, let’s assume that in version 3 of the code, param1 gets changed to a double (thus shifting all the other parameters down and consuming some of the spare allocation). I.e. it looks like this:

typedef struct
{
 double     param1;
 uint16_t   param2;
 ...
 uint8_t    spare[6];
} CALIBRATION_DATA;

In this case, we must not only be able to handle the upgrade from version 2 to version 3 – but also directly from version 1 to version 3. (You could of course require that users perform all upgrades in order. While I recognize that sometimes this is unavoidable, I suspect that most times it’s because the developer has backed themselves in to the sort of corner I describe here).

Anyway, with this insight in hand, I realized that I needed a generic system for both tagging an EEPROM structure with the version of software that created it, together with a means of providing arbitrary updates. This is how I do it.

Step 1.
Make the first location of each EEPROM structure a version field. This version field contains the firmware version that created the structure. By making it the first location in the EEPROM data structure, you ensure that you can always read it regardless of what else happens to the structure. Thus my CALIBRATION_DATA structure now looks something like this:

typedef struct
{
 uint16_t version;
 uint32_t param1;
 uint16_t param2;
 ...
 uint8_t  spare[10];
} CALIBRATION_DATA;

Step 2.
Add code to handle the upgrades. This code must be called before any parameters are used from EEPROM. The code looks something like this:

void eeprom_Update(void)
{
if (Cal_Data.version != SW_VERSION)
{
 switch (Cal_Data.version)
 {
  case 0x100:
   /* Do necessary steps to perform upgrade */
  break;
  case 0x200:
   /* Do necessary steps to perform upgrade */
  break;
  default:
  break;
  Cal_Data.version = SW_VERSION;  /* Update the EEPROM version number */
 }
}

Incidentally, I find that is often one of those cases where falling through case statements is really useful. Of course doing this is usually banned and so one ends up with much more clumsy code than would otherwise be required.

An Apology
Regular readers will no doubt have noticed that this is my first post in a while. A deadly combination of vacation and urgent projects with tight deadlines had conspired against me to prevent me blogging at my usual pace.

Home

Tags: ,

4 Responses to “Keeping your EEPROM data valid through firmware updates”

  1. John says:

    I came across your column via a reference from Michael Barr of Netrino. He sparked my attention by his comment "Fellow EmbeddedGurus blogger Nigel Jones is obsessed with writing efficient C code. He experiments with alternative coding constructs, carefully examining the compiler's output for each, when normal people are sleeping." I thought I was the only one who experiments with the output of various 'C' constructs every time I use a new compiler (or version) to determine which generate more efficient code.At my company we have been using EEPROM versioning similar to your suggestion for years. It works very well except for the problem of customers who insist on flashing backwards to old versions of code. Our only solution to this has been to clear EEPROM and set all values to default if an unknown version is found. This of course has it's problems. So many that it took management approval to make a version change. As such we have finally resorted to clearing all EEPROM settings on manufacturing and never changing previous locations only adding new ones. Any new values added are designed so the cleared value is either the default setting or an invalid one. This enables us to tell if the location has ever been set.Do you have any ways to handle this?

  2. ashleigh says:

    Another couple of suggestions:1. Add a signature to the configuration block, before the version information. The signature should be AT LEAST 32 bits, in which you store a unique code per product (keep a company wide register of signautures used). Common geeky examples are 0xFEEDBEEF, or 0xABADBABE. Then you compare the signature present against the signature expected to see if the config block is even present.2. Checksum the configuration as the last step of loading a new one – but only if the configuration is totally static and treated by the program as read-only. Store the checksum after the version, make sure its set to 0 during the load and calculate and set it when load is complete. On start up, check the checksum.3. Never ever ever ever automatically detect bad configuration data and auto-regenerate it. I've had a case where a former employee did this, and dodginess in the design led to about 1 in 100 cases where at power up all the settings got blown out and re-created with defaults. If defaults are to be loaded, it must always be by an explicit action – preferably in the factory.

  3. Nigel Jones says:

    John:The downgrade problem is indeed an interesting problem – and certainly one that I can't address adequately in the comments section. I'll endeavor to put together a blog posting on this in the near future.

  4. Nigel Jones says:

    Ashleigh:I agree with you about the checksums. I'll point out that I did say in the post that I was ignoring issues related to corruption – which is the principal job of the checksum.I don't agree with you concerning loading default values. I've designed products where effectively halting and doing nothing is far worse than loading default values and proceeding. I do agree that it is essential that the user be informed that default values have been loaded.

Leave a Reply