EEPROM registration

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

Detailed Description

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.
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).

Files

file  eepreg.h
 eepreg interface definitions
 

Macros

#define EEPROM_RESERV_CPU_LOW   (0U)
 EEPROM reserved near beginning for use by CPU and related. More...
 
#define EEPROM_RESERV_CPU_HI   (0U)
 EEPROM reserved near end for use by CPU and related. More...
 
#define EEPROM_RESERV_BOARD_LOW   (0U)
 EEPROM reserved near beginning for use by board and related. More...
 
#define EEPROM_RESERV_BOARD_HI   (0U)
 EEPROM reserved near end for use by board and related. More...
 
#define EEPREG_PTR_LEN   (1U)
 Size in bytes of pointer meta-data in EEPROM.
 

Typedefs

typedef int(* eepreg_iter_cb_t) (char *name, void *arg)
 Signature of callback for iterating over entries in EEPROM registry. More...
 

Functions

int eepreg_add (uint32_t *pos, const char *name, uint32_t len)
 Load or write meta-data in EEPROM registry. More...
 
int eepreg_read (uint32_t *pos, const char *name)
 Read position meta-data from EEPROM registry. More...
 
int eepreg_write (uint32_t *pos, const char *name, uint32_t len)
 Write meta-data to EEPROM registry. More...
 
int eepreg_rm (const char *name)
 Remove entry from EEPROM registry and free space. More...
 
int eepreg_iter (eepreg_iter_cb_t cb, void *arg)
 Iterate over meta-data entries in EEPROM registry. More...
 
int eepreg_check (void)
 Check for the presence of meta-data registry. More...
 
int eepreg_reset (void)
 Clear existing meta-data registry. More...
 
int eepreg_len (uint32_t *len, const char *name)
 Calculate data length from meta-data in EEPROM registry. More...
 
int eepreg_free (uint32_t *len)
 Calculate length of remaining EEPROM free space. More...
 

Macro Definition Documentation

◆ EEPROM_RESERV_BOARD_HI

#define EEPROM_RESERV_BOARD_HI   (0U)

EEPROM reserved near end for use by board and related.

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

Definition at line 102 of file eepreg.h.

◆ EEPROM_RESERV_BOARD_LOW

#define EEPROM_RESERV_BOARD_LOW   (0U)

EEPROM reserved near beginning for use by board and related.

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

Definition at line 93 of file eepreg.h.

◆ EEPROM_RESERV_CPU_HI

#define EEPROM_RESERV_CPU_HI   (0U)

EEPROM reserved near end for use by CPU and related.

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

Definition at line 84 of file eepreg.h.

◆ EEPROM_RESERV_CPU_LOW

#define EEPROM_RESERV_CPU_LOW   (0U)

EEPROM reserved near beginning for use by CPU and related.

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

Definition at line 75 of file eepreg.h.

Typedef Documentation

◆ eepreg_iter_cb_t

typedef int(* eepreg_iter_cb_t) (char *name, void *arg)

Signature of callback for iterating over entries in EEPROM registry.

Parameters
[in]namename of an entry in the registry
[in]argargument for cb
Returns
0 on success
< 0 on failure

Definition at line 127 of file eepreg.h.

Function Documentation

◆ eepreg_add()

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
[out]pospointer to position variable
[in]namename of entry to load or write
[in]lenrequested amount of data storage
Returns
0 on success
-EIO on EEPROM I/O error
-ENOSPC on insufficient EEPROM for entry
-EADDRINUSE on existing entry with different length

◆ eepreg_check()

int eepreg_check ( void  )

Check for the presence of meta-data registry.

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

◆ eepreg_free()

int eepreg_free ( uint32_t *  len)

Calculate length of remaining EEPROM free space.

Parameters
[out]lenpointer to length variable
Returns
0 on success
-EIO on EEPROM I/O error
-ENOENT on non-existent registry

◆ eepreg_iter()

int eepreg_iter ( 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
[in]cbcallback to iterate over entries
[in]argargument for cb
Returns
0 on success
-EIO on EEPROM I/O error
-ENOENT on non-existent registry
return value of cb when cb returns < 0

◆ eepreg_len()

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
[out]lenpointer to length variable
[in]namename of entry to load or write
Returns
0 on success
-EIO on EEPROM I/O error
-ENOENT on non-existent registry or entry

◆ eepreg_read()

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
[out]pospointer to position variable
[in]namename of entry to load
Returns
0 on success
-EIO on EEPROM I/O error
-ENOENT on non-existent registry or entry

◆ eepreg_reset()

int eepreg_reset ( void  )

Clear existing meta-data registry.

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

Returns
0 on success
-EIO on EEPROM I/O error

◆ eepreg_rm()

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
[in]namename of entry to remove
Returns
0 on success
-EIO on EEPROM I/O error
-ENOENT on non-existent registry or entry

◆ eepreg_write()

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
[out]pospointer to position variable
[in]namename of entry to write
[in]lenrequested amount of data storage
Returns
0 on success
-EIO on EEPROM I/O error
-ENOSPC on insufficient EEPROM for entry