EEPROM registration

eepreg provides a facility to easily manage the locations of data stored in EEPROM via a meta-data registry.

The structure of the meta-data registry is intended to make it easy to detect the exact layout of existent data so that automatic tools may be written to migrate legacy data to new formats. It also allows the addition and removal of new entries dynamically.

Note

Names are used as identifiers and must be unique! It is also recommended to keep them as short as possible (while still being unique and human readable), as many systems have very small amounts of EEPROM. Disemvowelment can shorten long names while still retaining readability.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
The layout of the EEPROM used looks like this:
   EEPROM_RESERV_CPU_LOW
   EEPROM_RESERV_BOARD_LOW
   Registry magic number ("RIOTREG")
   Registry end pointer
   Registry entry 1 meta-data length (1 byte)
   Registry entry 1 name (unterminated)
   Registry entry 1 data pointer
   Registry entry 2 meta-data length
   Registry entry 2 name
   Registry entry 2 data pointer
   ... (new registry meta-data may be added in ascending order)
   unused space
   ... (new data locations may be added in descending order)
   Entry 2 data
   Entry 1 data
   EEPROM_RESERV_BOARD_HI
   EEPROM_RESERV_CPU_HI

Pointer length is dependent on the size of the available EEPROM (see EEPREG_PTR_LEN below).

int(* eepreg_iter_cb_t()

Signature of callback for iterating over entries in EEPROM registry.

Parameters

name:name of an entry in the registry
arg:argument for cb

Return values

  • 0 on success
  • < 0 on failure
int eepreg_add(uint32_t * pos, const char * name, uint32_t len)

Load or write meta-data in EEPROM registry.

This checks to see if relevant meta-data exists in the EEPROM registry, and returns that data position if it exists. If an entry does not exist in the registry, meta-data is written and allocated data space if there is enough remaining. Requesting a different length for an existent entry returns an error.

Parameters

pos:pointer to position variable
name:name of entry to load or write
len:requested amount of data storage

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
  • -ENOSPC on insufficient EEPROM for entry
  • -EADDRINUSE on existing entry with different length
int eepreg_read(uint32_t * pos, const char * name)

Read position meta-data from EEPROM registry.

This is similar to eepreg_add, except it never writes meta-data.

Parameters

pos:pointer to position variable
name:name of entry to load

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
  • -ENOENT on non-existent registry or entry
int eepreg_write(uint32_t * pos, const char * name, uint32_t len)

Write meta-data to EEPROM registry.

This ignores existing meta-data and always makes a new entry in the registry. Typical use should be through eepreg_add and not eepreg_write. If multiple entries with the same name exist, eepreg functions will find the oldest. Mainly intended for use by migration utilities.

Parameters

pos:pointer to position variable
name:name of entry to write
len:requested amount of data storage

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
  • -ENOSPC on insufficient EEPROM for entry
int eepreg_rm(const char * name)

Remove entry from EEPROM registry and free space.

This removes an entry from the EEPROM registry and its corresponding data and moves the data and meta-data of entries after removed entry to occupy the freed space. This preserves the structure of the EEPROM registry. Warning: this is a read/write intensive operation! Mainly intended for use by migration utilities.

Parameters

name:name of entry to remove

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
  • -ENOENT on non-existent registry or entry
int eepreg_iter(eepreg.h::eepreg_iter_cb_t cb, void * arg)

Iterate over meta-data entries in EEPROM registry.

This executes a callback over each name in the EEPROM registry. The intended work-flow for migration is to: iterate over each entry, check to see if migration is needed, duplicate using eepreg_write if needed, migrate data to duplicate entry, then delete old entry using eepreg_rm.

Note

It is safe for the callback to remove the entry it is called with, or to add new entries.

Parameters

cb:callback to iterate over entries
arg:argument for cb

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
  • -ENOENT on non-existent registry
  • return value of cb when cb returns < 0
int eepreg_check(void)

Check for the presence of meta-data registry.

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
  • -ENOENT on non-existent registry
int eepreg_reset(void)

Clear existing meta-data registry.

This removes any existing meta-data registry by writing a new registry with no entries.

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
int eepreg_len(uint32_t * len, const char * name)

Calculate data length from meta-data in EEPROM registry.

Note

This information is typically already available to code that has called eepreg_add.

Parameters

len:pointer to length variable
name:name of entry to load or write

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
  • -ENOENT on non-existent registry or entry
int eepreg_free(uint32_t * len)

Calculate length of remaining EEPROM free space.

Parameters

len:pointer to length variable

Return values

  • 0 on success
  • -EIO on EEPROM I/O error
  • -ENOENT on non-existent registry
EEPROM_RESERV_CPU_LOW

EEPROM reserved near beginning for use by CPU and related.

1
(0U)

Change with care, as it may make existing data difficult to migrate

EEPROM_RESERV_CPU_HI

EEPROM reserved near end for use by CPU and related.

1
(0U)

Change with care, as it may make existing data difficult to migrate

EEPROM_RESERV_BOARD_LOW

EEPROM reserved near beginning for use by board and related.

1
(0U)

Change with care, as it may make existing data difficult to migrate

EEPROM_RESERV_BOARD_HI

EEPROM reserved near end for use by board and related.

1
(0U)

Change with care, as it may make existing data difficult to migrate

EEPREG_PTR_LEN

Size in bytes of pointer meta-data in EEPROM.

1
(1U)