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)