Flash Safe Programmer Interface

Description

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

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