eCosPro® Reference Manual
Prev |  |

# Flash Safe Programmer Interface

## Name

Flash Safe -- API Details

## Synopsis

         #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);`

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

CYG_FLASHSAFE_ERR_OK

  This is returned when the operation succeeded.

CYG_FLASHSAFE_ERR_FLASH

  This is returned when the flash device failed to initialize.

CYG_FLASHSAFE_ERR_MISMATCH

  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.

CYG_FLASHSAFE_ERR_FLASH_PROG

  This is returned when the flash driver reports a programming error.

CYG_FLASHSAFE_ERR_FLASH_ERASE

  This is returned when the flash driver reports a block erase error.

CYG_FLASHSAFE_ERR_NO_DATA

  This is returned when there is no current valid block in the flashsafe. This will usually only happen when the flashsafe is new.

CYG_FLASHSAFE_ERR_BAD_KEY

  This is returned when a given key cannot be found in the flashsafe.

CYG_FLASHSAFE_ERR_NOT_OPEN

  This is returned when a `cyg_flashsafe_write()` or `cyg_flashsafe_commit()` are called before making a call to `cyg_flashsafe_open()`.

CYG_FLASHSAFE_ERR_NO_SPACE

  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.

Prev | Home |
Flash Safe | Up |