Flash Safe — API Details


     #include <cyg/flashsafe/flashsafe.h>

int cyg_flashsafe_init(cyg_flashsafe *flashsafe);

int cyg_flashsafe_data(cyg_flashsafe *flashsafe, cyg_flashsafe_key key, void **data);

int cyg_flashsafe_read(cyg_flashsafe *flashsafe, cyg_flashsafe_key key, void *data, cyg_uint32 *len);

int cyg_flashsafe_open(cyg_flashsafe *flashsafe);

int cyg_flashsafe_write(cyg_flashsafe *flashsafe, cyg_flashsafe_key key, void *data, cyg_uint32 len);

int cyg_flashsafe_commit(cyg_flashsafe *flashsafe);

const char *cyg_flashsafe_errmsg(int err);


The flash safe is accessed through this API. The flashsafe is initialized by calling cyg_flashsafe_init() passing it a pointer to a cyg_flashsafe structure. Within this structure the base, block_count and block_size fields must have been initialized to describe the area of flash to be managed. Typically, the structure would be defined statically as follows:

cyg_flashsafe flashsafe =
    .base               = 0x40000000,
    .block_count        = 3,
    .block_size         = 0x2000

If the flashsafe already contains data, then items may be retrieved using cyg_flashsafe_data(). The key argument identifies the data item to be retrieved. The data argument is a pointer to a location where a pointer to the data will be stored. Typically the pointer returned will refer directly to the flash device, and will thus be read-only. No size is returned, the application should either know what size the data is (e.g a structure or fixed sized array), or arrange for the data to be self-sized (e.g. a zero terminated string or contains a size field).

The function cyg_flashsafe_read() performs a similar job to cyg_flashsafe_data() except that the data is copied out of the flash memory. The data argument points to a buffer into which the data will be copied, and the len points to a location where the size of the buffer is stored when the call is made, and will contain the size of data copied in on return. This function is useful where it is intended to update the data read from the flashsafe, possibly to write it back to flashsafe. cyg_flashsafe_data() is useful where the data only needs to be read, and saves valuable RAM space.

To open a flashsafe block for update the function cyg_flashsafe_open() should be called. This will select the oldest block in the safe, erase it and prepare it for writing.

The function cyg_flashsafe_write() is used to write new data to the current open block. The key argument should be an application selected 16 bit value that is used to identify this data item. This value should be unique for each item, otherwise the behaviour is undefined. The data and len arguments describe a buffer containing the data to be written. The size of the data written must be less than or equal to the value of CYGNUM_FLASHSAFE_BUFFER_SIZE.

The function cyg_flashsafe_commit() causes the current open block to be committed to the flash. This involves calculating the checksum and writing the header and trailer with the current sequence number.

Each of these functions may return one of a number of error codes. These may include the following:

This is returned when the operation succeeded.
This is returned when the flash device failed to initialize.
This is returned when there is a mismatch between the size any layout of the flashsafe described in the initialized cyg_flashsafe structure and the flashsafe found in flash.
This is returned when the flash driver reports a programming error.
This is returned when the flash driver reports a block erase error.
This is returned when there is no current valid block in the flashsafe. This will usually only happen when the flashsafe is new.
This is returned when a given key cannot be found in the flashsafe.
This is returned when a cyg_flashsafe_write() or cyg_flashsafe_commit() are called before making a call to cyg_flashsafe_open().
This is returned when the size of data is too large for either the buffer or the flashsafe block as a whole.

The function cyg_flashsafe_errmsg(), if given one of these error codes, will return a string describing the error.