eCos Reference Manual
Prev | Chapter 29. 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:

1. 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.

2. 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.

Prev | Home | Next
FLASH I/O devices | Up | SPI Support