eepreg.h

eepreg interface definitions

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