Chapter 63. The legacy Version 1 eCos FLASH API

The library has a number of limitations:

  1. Only one family of FLASH device may be supported at once.
  2. Multiple devices of one family are supported, but they must be contiguous in memory.
  3. The library is not thread or interrupt safe under some conditions.
  4. The library currently does not use the eCos naming convention for its functions. This may change in the future but backward compatibility is likely to be kept.

There are two APIs described here. The first is the application API which programs should use. The second API is that between the FLASH io library and the device drivers.

63.1. FLASH user API

All of the functions described below are declared in the header file <cyg/io/flash.h> which all users of the FLASH library should include.

63.1.1. Initializing the FLASH library

The FLASH library needs to be initialized before other FLASH operations can be performed. This only needs to be done once. The following function will only do the initialization once so it's safe to call multiple times:

externC int flash_init( _printf *pf );
typedef int _printf(const char *fmt, …); 

The parameter pf is a pointer to a function which is to be used for diagnostic output. Typically the function diag_printf() will be passed. Normally this function is not used by the higher layer of the library unless CYGSEM_IO_FLASH_CHATTER is enabled. Passing a NULL is not recommended, even when CYGSEM_IO_FLASH_CHATTER is disabled. The lower layers of the library may unconditionally call this function, especially when errors occur, probably resulting in a more serious error/crash!.

63.1.2. Retrieving information about the FLASH

The following four functions return information about the FLASH.

externC int flash_get_block_info(int *block_size, int *blocks);
externC int flash_get_limits(void *target, void **start, void **end);
externC int flash_verify_addr(void *target);
externC bool flash_code_overlaps(void *start, void *end);

The function flash_get_block_info() returns the size and number of blocks. When the device has a mixture of block sizes, the size of the "normal" block will be returned. Please read the source code to determine exactly what this means. flash_get_limits() returns the lower and upper memory address the FLASH occupies (NOTE: For the upper memory address this is the last valid FLASH location, and not the first memory address after the FLASH). The target parameter is currently unused. flash_verify_addr() tests if the target addresses is within the flash, returning FLASH_ERR_OK if so. Lastly, flash_code_overlaps() checks if the executing code is resident in the section of flash indicated by start and end. If this function returns true, erase and program operations within this range are very likely to cause the target to crash and burn horribly. Note the FLASH library does allow you to shoot yourself in the foot in this way.

63.1.3. Reading from FLASH

There are two methods for reading from FLASH. The first is to use the following function.

externC int flash_read(void *flash_base, void *ram_base, int len, void **err_address);

flash_base is where in the flash to read from. ram_base indicates where the data read from flash should be placed into RAM. len is the number of bytes to be read from the FLASH and err_address is used to return the location in FLASH that any error occurred while reading.

The second method is to simply memcpy() directly from the FLASH. This is not recommended since some types of device cannot be read in this way, eg NAND FLASH. Using the FLASH library function to read the FLASH will always work so making it easy to port code from one FLASH device to another.

63.1.4. Erasing areas of FLASH

Blocks of FLASH can be erased using the following function:

externC int flash_erase(void *flash_base, int len, void **err_address);

flash_base is where in the flash to erase from. len is the minimum number of bytes to erase in the FLASH and err_address is used to return the location in FLASH that any error occurred while erasing. It should be noted that FLASH devices are block oriented when erasing. It is not possible to erase a few bytes within a block, the whole block will be erased. flash_base may be anywhere within the first block to be erased and flash_base+len may be anywhere in the last block to be erased.

63.1.5. Programming the FLASH

Programming of the flash is achieved using the following function.

externC int flash_program(void *flash_base, void *ram_base, int len, void **err_address);

flash_base is where in the flash to program from. ram_base indicates where the data to be programmed into FLASH should be read from in RAM. len is the number of bytes to be program into the FLASH and err_address is used to return the location in FLASH that any error occurred while programming.

63.1.6. Locking and unlocking blocks

Some flash devices have the ability to lock and unlock blocks. A locked block cannot be erased or programmed without it first being unlocked. For devices which support this feature and when CYGHWR_IO_FLASH_BLOCK_LOCKING is enabled then the following two functions are available:

externC int flash_lock(void *flash_base, int len, void **err_address);
externC int flash_unlock(void *flash_base, int len, void **err_address);

63.1.7. Return values and errors

All the functions above, except flash_code_overlaps() return one of the following return values.

FLASH_ERR_OK              No error - operation complete
FLASH_ERR_INVALID         Invalid FLASH address
FLASH_ERR_ERASE           Error trying to erase
FLASH_ERR_LOCK            Error trying to lock/unlock
FLASH_ERR_PROGRAM         Error trying to program
FLASH_ERR_PROTOCOL        Generic error
FLASH_ERR_PROTECT         Device/region is write-protected
FLASH_ERR_NOT_INIT        FLASH info not yet initialized
FLASH_ERR_HWR             Hardware (configuration?) problem
FLASH_ERR_ERASE_SUSPEND   Device is in erase suspend mode
FLASH_ERR_PROGRAM_SUSPEND Device is in program suspend mode
FLASH_ERR_DRV_VERIFY      Driver failed to verify data
FLASH_ERR_DRV_TIMEOUT     Driver timed out waiting for device
FLASH_ERR_DRV_WRONG_PART  Driver does not support device
FLASH_ERR_LOW_VOLTAGE     Not enough juice to complete job

To turn an error code into a human readable string the following function can be used:

externC char *flash_errmsg(int err);

63.1.8.  Notes on using the FLASH library

The FLASH library evolved from the needs and environment of RedBoot rather than being a general purpose eCos component. This history explains some of the problems with the library.

The library is not thread safe. Multiple simultaneous calls to its library functions will likely fail and may cause a crash. It is the callers responsibility to use the necessary mutex's if needed.

63.2. FLASH device API

This section describes the API between the FLASH IO library the FLASH device drivers.

63.2.1. The flash_info structure

The flash_infostructure is used by both the FLASH IO library and the device driver.

struct flash_info {
  int   block_size;   // Assuming fixed size "blocks"
  int   blocks;       // Number of blocks
  int   buffer_size;  // Size of write buffer (only defined for some devices)
  unsigned long block_mask;
  void *start, *end;  // Address range
  int   init;         // FLASH API initialised
  _printf *pf;        // printf like function for diagnostics

block_mask is used internally in the FLASH IO library. It contains a mask which can be used to turn an arbitrary address in flash to the base address of the block which contains the address.

There exists one global instance of this structure with the name flash_info. All calls into the device driver makes use of this global structure to maintain state.

63.2.2. Initializing the device driver

The FLASH IO library will call the following function to initialize the device driver:

externC int  flash_hwr_init(void);

The device driver should probe the hardware to see if the FLASH devices exist. If it does it should fill in start, end, blocks and block_size.If the FLASH contains a write buffer the size of this should be placed in buffer_size. On successful probing the function should return FLASH_ERR_OK. When things go wrong it can be assumed that pf points to a printf like function for outputting error messages.

63.2.3. Querying the FLASH

FLASH devices can be queried to return there manufacture ID, size etc. This function allows this information to be returned.

int flash_query(unsigned char *data);

The caller must know the size of data to be returned and provide an appropriately sized buffer pointed to be parameter data. This function is generally used by flash_hwr_init().

63.2.4. Erasing a block of FLASH

So that the FLASH IO layer can erase a block of FLASH the following function should be provided.

int flash_erase_block(volatile flash_t *block, unsigned int block_size);

63.2.5. Programming a region of FLASH

The following function must be provided so that data can be written into the FLASH.

int flash_program_buf(volatile flash_t *addr, flash_t *data, int len,
unsigned long block_mask, int buffer_size);

The device will only be asked to program data in one block of the flash. The FLASH IO layer will break longer user requests into a smaller writes.

63.2.6. Reading a region from FLASH

Some FLASH devices are not memory mapped so it is not possible to read there contents directly. The following function read a region of FLASH.

int flash_read_buf(volatile flash_t* addr, flash_t* data, int len);

As with writing to the flash, the FLASH IO layer will break longer user requests for data into a number of reads which are at maximum one block in size.

A device which cannot be read directy should set CYGSEM_IO_FLASH_READ_INDIRECT so that the IO layer makes use of the flash_read_buf()function.

63.2.7. Locking and unlocking FLASH blocks

Some flash devices allow blocks to be locked so that they cannot be written to. The device driver should provide the following functions to manipulate these locks.

int flash_lock_block(volatile flash_t *block);
int flash_unlock_block(volatile flash_t *block, int block_size, int blocks);

These functions are only used if CYGHWR_IO_FLASH_BLOCK_LOCKING

63.2.8. Mapping FLASH error codes to FLASH IO error codes

The functions flash_erase_block(), flash_program_buf(), flash_read_buf(), flash_lock_block() and flash_unlock_block() return an error code which is specific to the flash device. To map this into a FLASH IO error code, the driver should provide the following function:

int flash_hwr_map_error(int err);

63.2.9. Determining if code is in FLASH

Although a general function, the device driver is expected to provide the implementation of the function flash_code_overlaps().

63.2.10. Implementation Notes

The FLASH IO layer will manipulate the caches as required. The device drivers do not need to enable/disable caches when performing operations of the FLASH.

Device drivers should keep all chatter to a minimum when CYGSEM_IO_FLASH_CHATTER is not defined. All output should use the print function in the pf in flash_info and not diag_printf()

Device driver functions which manipulate the state of the flash so that it cannot be read from for program execute need to ensure there code is placed into RAM. The linker will do this if the appropriate attribute is added to the function. e.g:

int flash_program_buf(volatile flash_t *addr, flash_t *data, int len,
                      unsigned long block_mask, int buffer_size)
__attribute__ ((section (".2ram.flash_program_buf")));