eCos Reference Manual
Prev	Chapter 30. FLASH I/O devices	Next

Using FLASH I/O devices

The FLASH I/O block devices can be accessed, read and written using the standard interface supplied by the generic I/O (CYGPKG_IO) package. These include the functions: cyg_io_lookup() to access the device and get a handle, cyg_io_read() and cyg_io_write() for sequential read and write operations, cyg_io_bread() and cyg_io_bwrite() for random access read and write operations, and cyg_io_get_config() and cyg_io_setconfig() for run-time configuration inspection and control.

However there are two aspects that differ from some other I/O devices accessed this way:

The first is that the lookup operation uses up resources which must be subsequently freed when the last user of the I/O handle is finished. The number of FLASH I/O devices that may be simultaneously opened is configured with the CYGNUM_IO_FLASH_BLOCK_DEVICES CDL option. After the last user is finished, the device may be closed using cyg_io_setconfig() with the CYG_IO_SET_CONFIG_CLOSE key. Reference counting to ensure that it is only the last user that causes a close, is left to higher layers.
The second is that write operations assume that the flash is already erased. Attempting to write to Flash that has already been written to may result in errors. Instead FLASH must be erased before it may be written.

FLASH block devices can also be read and written using the standard POSIX primitives, open(), close(), read(), write(), lseek(), and so on if the POSIX file I/O package (CYGPKG_FILEIO) is included in the configuration. As with the eCos generic I/O interface you must call close() to ensure resources are freed when the device is no longer used.

Other configuration keys are provided to perform FLASH erase operations, and to retrieve device sizes, and FLASH block sizes at a particular address. These operations are accessed with cyg_io_get_config() (or if using the POSIX file I/O API, cyg_fs_getinfo()) with the following keys:

CYG_IO_GET_CONFIG_FLASH_ERASE

This erases a region of FLASH. cyg_io_get_config() must be passed a structure defined as per the following, which is also supplied in <cyg/io/flash.h>:

typedef struct {
    CYG_ADDRESS offset;
    size_t len;
    int flasherr;
    cyg_flashaddr_t err_address;
} cyg_io_flash_getconfig_erase_t;

In this structure, offset specifies the offset within the block device to erase, len specifies the amount to address, flasherr is set on return to specify an error with the FLASH erase operation itself, and err_address is used if there was an error to specify at which address the error happened.

CYG_IO_GET_CONFIG_FLASH_LOCK

This protects a region of FLASH using the locking facilities available on the card, if provided by the underlying driver. cyg_io_get_config() must be passed a structure defined as per the following:

typedef struct {
    CYG_ADDRESS offset;
    size_t len;
    int flasherr;
    cyg_flashaddr_t err_address;
} cyg_io_flash_getconfig_lock_t;

In this structure, offset specifies the offset within the block device to lock, len specifies the amount to address, flasherr is set on return to specify an error with the FLASH lock operation itself, and err_address is used if there was an error to specify at which address the error happened. If locking support is not available -EINVAL will be returned from cyg_io_get_config().

CYG_IO_GET_CONFIG_FLASH_UNLOCK

This disables protection for a region of FLASH using the unlocking facilities available on the card, if provided by the underlying driver. cyg_io_get_config() must be passed a structure defined as per the following:

typedef struct {
    CYG_ADDRESS offset;
    size_t len;
    int flasherr;
    cyg_flashaddr_t err_address;
} cyg_io_flash_getconfig_unlock_t;

In this structure, offset specifies the offset within the block device to unlock, len specifies the amount to address, flasherr is set on return to specify an error with the FLASH unlock operation itself, and err_address is used if there was an error to specify at which address the error happened. If unlocking support is not available -EINVAL will be returned from cyg_io_get_config().

CYG_IO_GET_CONFIG_FLASH_DEVSIZE

This returns the size of the FLASH block device. The cyg_io_get_config() function must be passed a structure defined as per the following, which is also supplied in <cyg/io/flash.h>:

typedef struct {
    size_t dev_size;
} cyg_io_flash_getconfig_devsize_t;

In this structure, dev_size is used to return the size of the FLASH device.

CYG_IO_GET_CONFIG_FLASH_DEVADDR

This returns the address in the virtual memory map that the generic flash layer has been informed that this FLASH device is mapped to. Note that some flash devices such as dataflash are not truly memory mapped, and so this function only returns useful information when used with a true memory mapped FLASH device. The cyg_io_get_config() function must be passed a structure defined as per the following, which is also supplied in <cyg/io/flash.h>:

typedef struct {
    cyg_flashaddr_t dev_addr;
} cyg_io_flash_getconfig_devaddr_t;

In this structure, dev_addr is used to return the address corresponding to the base of the FLASH device in the virtual memory map.

CYG_IO_GET_CONFIG_FLASH_BLOCKSIZE

This returns the size of a FLASH block at a supplied offset in the FLASH block device. The cyg_io_get_config() function must be passed a structure defined as per the following, which is also supplied in <cyg/io/flash.h>:

typedef struct {
    CYG_ADDRESS offset;
    size_t block_size;
} cyg_io_flash_getconfig_blocksize_t;

In this structure, offset specifies the address within the block device of which the FLASH block size is required - a single FLASH device may contain blocks of differing sizes. The block_size field is used to return the block size at the specified offset.