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.

#define	EEPROM_RESERV_CPU_HI (0U)
	EEPROM reserved near end for use by CPU and related.

#define	EEPROM_RESERV_BOARD_LOW (0U)
	EEPROM reserved near beginning for use by board and related.

#define	EEPROM_RESERV_BOARD_HI (0U)
	EEPROM reserved near end for use by board and related.

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

Functions
int	eepreg_add (uint32_t pos, const char name, uint32_t len)
	Load or write meta-data in EEPROM registry.

int	eepreg_read (uint32_t pos, const char name)
	Read position meta-data from EEPROM registry.

int	eepreg_write (uint32_t pos, const char name, uint32_t len)
	Write meta-data to EEPROM registry.

int	eepreg_rm (const char *name)
	Remove entry from EEPROM registry and free space.

int	eepreg_iter (eepreg_iter_cb_t cb, void *arg)
	Iterate over meta-data entries in EEPROM registry.

int	eepreg_check (void)
	Check for the presence of meta-data registry.

int	eepreg_reset (void)
	Clear existing meta-data registry.

int	eepreg_len (uint32_t len, const char name)
	Calculate data length from meta-data in EEPROM registry.

int	eepreg_free (uint32_t *len)
	Calculate length of remaining EEPROM free space.

Macro Definition Documentation

◆ EEPREG_PTR_LEN

#define EEPREG_PTR_LEN (1U)

Size in bytes of pointer meta-data in EEPROM.

Definition at line 115 of file eepreg.h.

◆ 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]	name	name of an entry in the registry
[in]	arg	argument 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]	pos	pointer to position variable
[in]	name	name of entry to load or write
[in]	len	requested 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] len pointer 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]	cb	callback to iterate over entries
[in]	arg	argument 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]	len	pointer to length variable
[in]	name	name 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]	pos	pointer to position variable
[in]	name	name 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] name name 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]	pos	pointer to position variable
[in]	name	name of entry to write
[in]	len	requested amount of data storage

Returns: 0 on success; -EIO on EEPROM I/O error; -ENOSPC on insufficient EEPROM for entry

Detailed Description

Files

Macros

Typedefs

Functions

Macro Definition Documentation

◆ EEPREG_PTR_LEN

◆ EEPROM_RESERV_BOARD_HI

◆ EEPROM_RESERV_BOARD_LOW

◆ EEPROM_RESERV_CPU_HI

◆ EEPROM_RESERV_CPU_LOW

Typedef Documentation

◆ eepreg_iter_cb_t

Function Documentation

◆ eepreg_add()

◆ eepreg_check()

◆ eepreg_free()

◆ eepreg_iter()

◆ eepreg_len()

◆ eepreg_read()

◆ eepreg_reset()

◆ eepreg_rm()

◆ eepreg_write()