storage_api.h File Reference

Defines the required external storage API plus some convenience functions built around that API. More...

#include <stdint.h>
#include "statuses.h"

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	storage_api_t
	The external storage API. This must be supported by any storage system. E.g. EEPROM, SPI. More...

Typedefs
using	byte = uint8_t

Functions
storage_api_t	getEEPROMStorageApi (void)
	Create a storage_api_t instance that wraps getEEPROM()
bool	update (const storage_api_t &api, uint16_t address, byte value)
	Conditionally write a byte to storage if it differs from the one already saved.
void	updateBlock (const storage_api_t &api, uint16_t address, const byte *pFirst, const byte *pLast)
	Conditionally write bytes from block of memory to storage. Values are written only if they differ from the one already saved at the same address.
uint16_t	updateBlockLimitWriteOps (const storage_api_t &api, uint16_t address, const byte *pFirst, const byte *pLast, uint16_t maxWrites)
	Conditionally write bytes from block of memory to storage, with a limited number of write operations.
template<typename T >
static void	updateObject (const storage_api_t &api, const T &t, uint16_t address)
	Conditionally write bytes from a POD object to storage. Values are written only if they differ from the one already saved at the same address.
uint16_t	loadBlock (const storage_api_t &api, int16_t address, byte *pFirst, const byte *pLast)
	Copy a block of data from storage to memory.
template<typename T >
static T &	loadObject (const storage_api_t &api, uint16_t address, T &t)
	Copy a block of data from storage into a POD object.
void	fillBlock (const storage_api_t &api, uint16_t address, uint16_t length, byte value)
	Fills the given block with a constant.
void	moveBlock (const storage_api_t &api, uint16_t dest, uint16_t source, uint16_t size)
	Move a block of bytes.

Detailed Description

Defines the required external storage API plus some convenience functions built around that API.

Typedef Documentation

byte

using byte = uint8_t

Function Documentation

fillBlock()

void fillBlock	(	const storage_api_t &	api,
		uint16_t	address,
		uint16_t	length,
		byte	value
	)

Fills the given block with a constant.

Parameters

api	Raw storage API
address	the location to begin writing to (zero based)
length	number of bytes to write
value	fill value

Here is the call graph for this function:

Here is the caller graph for this function:

getEEPROMStorageApi()

storage_api_t getEEPROMStorageApi

(

void

)

Create a storage_api_t instance that wraps getEEPROM()

Applies the adapter pattern to provide storage_api_t from EEPROM_t

Here is the call graph for this function:

Here is the caller graph for this function:

loadBlock()

uint16_t loadBlock	(	const storage_api_t &	api,
		int16_t	address,
		byte *	pFirst,
		const byte *	pLast
	)

Copy a block of data from storage to memory.

This is essentially the opposite of updateBlock()

Parameters

api	Raw storage API
address	the location to begin reading from (zero based)
pFirst	Points to the start of the memory block
pLast	Points to one byte past the end of the block

Returns

uint16_t The storage address of pLast. Convenient for chaining calls.

Here is the call graph for this function:

Here is the caller graph for this function:

loadObject()

template<typename T >

static T & loadObject ( const storage_api_t &  api, uint16_t  address, T &  t  )

inlinestatic

Copy a block of data from storage into a POD object.

Template Parameters

T	- must be a POD type

Parameters

api	Raw storage API
address	the location to begin reading from (zero based)
t	Object to write to

Returns

T& Returns t

Here is the call graph for this function:

Here is the caller graph for this function:

moveBlock()

void moveBlock	(	const storage_api_t &	api,
		uint16_t	dest,
		uint16_t	source,
		uint16_t	size
	)

Move a block of bytes.

This will handle overlapping blocks. I.e. if [dest, size) overlaps [source, size)

Parameters

api	Raw storage API
dest	Address to copy to
source	Address to copy from
size	number of bytes to copy

Here is the call graph for this function:

update()

bool update	(	const storage_api_t &	api,
		uint16_t	address,
		byte	value
	)

Conditionally write a byte to storage if it differs from the one already saved.

Background: some storage hardware has a limited number of write cycles per cell. E.g. flash memory can only withstand a certain number of write/erase cycles before it begins to wear out and can no longer reliably store data. This is typically in the range of 3000-5000 cycles for multi-level cell (MLC) NAND flash, or 10,000-100,000 cycles for single-level cell (SLC) NAND flash. So we want to limit writes as much as possible. Hence this function.

Parameters

api	Raw storage API
address	the location to write to (zero based)
value	the value to write

Returns

true if the value was written, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

updateBlock()

void updateBlock	(	const storage_api_t &	api,
		uint16_t	address,
		const byte *	pFirst,
		const byte *	pLast
	)

Conditionally write bytes from block of memory to storage. Values are written only if they differ from the one already saved at the same address.

Warning

The code assumes address+(pLast-pFirst) < api.length(). I.e. that the block fits into the address space.

See also

update

Parameters

api	Raw storage API
address	the location to begin writing to (zero based)
pFirst	Points to the start of the memory block
pLast	Points to one byte past the end of the block

Here is the call graph for this function:

Here is the caller graph for this function:

updateBlockLimitWriteOps()

uint16_t updateBlockLimitWriteOps	(	const storage_api_t &	api,
		uint16_t	address,
		const byte *	pFirst,
		const byte *	pLast,
		uint16_t	maxWrites
	)

Conditionally write bytes from block of memory to storage, with a limited number of write operations.

Write operations are typically pretty slow (E.g. 3.3ms on AVR EEPROM). If a block contains many bytes that need to be written, we can cause the system to stutter as the main loop stalls waiting for writes to complete. So instead we limit the number of write operations per call to this function.

Note

This means that a call to this function may not update the entire block. If the return value is zero, we ran out of writes, and repeated calls will be required.

See also

updateBlock

Parameters

api	Raw storage API
address	the location to begin writing to (zero based)
pFirst	Points to the start of the memory block
pLast	Points to one byte past the end of the block
maxWrites	Maximum number of write operations.

Returns

Number of writes remaining. E.g. if maxWrites==7 and 2 bytes are written, result is 5

Here is the call graph for this function:

Here is the caller graph for this function:

updateObject()

template<typename T >

static void updateObject ( const storage_api_t &  api, const T &  t, uint16_t  address  )

inlinestatic

Conditionally write bytes from a POD object to storage. Values are written only if they differ from the one already saved at the same address.

This is purely a convenience function

Template Parameters

T	- must be a POD type

Parameters

api	Raw storage API
t	Object to write
address	the location to begin writing to (zero based)

Here is the call graph for this function:

Here is the caller graph for this function: