Flash Disk Device

Files
file	flashdisk.h
	Interface to a Flash Disk Block Device.

Data Structures
struct	rtems_fdisk_monitor_data
	Flash Disk Monitoring Data allows a user to obtain the current status of the disk. More...
struct	rtems_fdisk_segment_desc
	Flash Segment Descriptor holds, number of continuous segments in the device of this type, the base segment number in the device, the address offset of the base segment in the device, and the size of segment. More...
struct	rtems_fdisk_driver_handlers
	Flash Low Level driver handlers. More...
struct	rtems_fdisk_device_desc
	Flash Device Descriptor holds the segments in a device. More...
struct	rtems_flashdisk_config
	RTEMS Flash Disk configuration table used to initialise the driver. More...

Macros
#define	RTEMS_FLASHDISK_DEVICE_BASE_NAME   "/dev/fdd"
	The base name of the flash disks.
#define	RTEMS_FDISK_IOCTL_ERASE_DISK   _IO('B', 128)
#define	RTEMS_FDISK_IOCTL_COMPACT   _IO('B', 129)
#define	RTEMS_FDISK_IOCTL_ERASE_USED   _IO('B', 130)
#define	RTEMS_FDISK_IOCTL_MONITORING   _IO('B', 131)
#define	RTEMS_FDISK_IOCTL_INFO_LEVEL   _IO('B', 132)
#define	RTEMS_FDISK_IOCTL_PRINT_STATUS   _IO('B', 133)
#define	RTEMS_FDISK_KBYTES(_k)   (UINT32_C(1024) * (_k))
	Return the number of kilo-bytes.
#define	RTEMS_FDISK_BACKGROUND_ERASE   (1 << 0)
#define	RTEMS_FDISK_BACKGROUND_COMPACT   (1 << 1)
#define	RTEMS_FDISK_CHECK_PAGES   (1 << 2)
#define	RTEMS_FDISK_BLANK_CHECK_BEFORE_WRITE   (1 << 3)

Typedefs
typedef struct rtems_fdisk_monitor_data	rtems_fdisk_monitor_data
	Flash Disk Monitoring Data allows a user to obtain the current status of the disk.
typedef struct rtems_fdisk_segment_desc	rtems_fdisk_segment_desc
	Flash Segment Descriptor holds, number of continuous segments in the device of this type, the base segment number in the device, the address offset of the base segment in the device, and the size of segment. More...
typedef struct rtems_fdisk_driver_handlers	rtems_fdisk_driver_handlers
	Flash Low Level driver handlers. More...
typedef struct rtems_fdisk_device_desc	rtems_fdisk_device_desc
	Flash Device Descriptor holds the segments in a device. More...
typedef struct rtems_flashdisk_config	rtems_flashdisk_config
	RTEMS Flash Disk configuration table used to initialise the driver. More...

Functions
rtems_device_driver	rtems_fdisk_initialize (rtems_device_major_number major, rtems_device_minor_number minor, void *arg)

Variables
const rtems_flashdisk_config	rtems_flashdisk_configuration []
	External reference to the configuration. Please supply. Support is present in confdefs.h for providing this variable.
uint32_t	rtems_flashdisk_configuration_size
	External reference to the number of configurations. Please supply. Support is present in confdefs.h for providing this variable.

Detailed Description

Flash disk driver for RTEMS provides support for block based file systems on flash devices. The driver is not a flash file system nor does it try to compete with flash file systems. It currently does not journal how-ever block sequence numbering could be added to allow recovery of a past positions if a power down occurred while being updated.

This flash driver provides block device support for most flash devices. The driver has been tested on NOR type devices such as the AMLV160 or M28W160. Support for NAND type devices may require driver changes to allow speedy recover of the block mapping data and to also handle the current use of word programming. Currently the page descriptors are stored in the first few pages of each segment.

The driver supports devices, segments and pages. You provide to the driver the device descriptions as a table of device descriptors. Each device descriptor contain a table of segment descriptions or segment descriptors. The driver uses this information to manage the devices.

A device is made up of segments. These are also called sectors or blocks. It is the smallest erasable part of a device. A device can have differing size segments at different offsets in the device. The segment descriptors support repeating segments that are continuous in the device. The driver breaks the segments up into pages. The first pages of a segment contain the page descriptors. A page descriptor hold the page flags, a CRC for the page of data and the block number the page holds. The block can appear in any order in the devices. A page is active if it hold a current block of data. If the used bit is set the page is counted as used. A page moves from erased to active to used then back to erased. If a block is written that is already in a page, the block is written to a new page the old page is flagged as used.

At initialization time each segment's page descriptors are read into memory and scanned to determine the active pages, the used pages and the bad pages. If a segment has any erased pages it is queue on the available queue. If the segment has no erased pages it is queue on the used queue.

The available queue is sorted from the least number available to the most number of available pages. A segment that has just been erased will placed at the end of the queue. A segment that has only a few available pages will be used sooner and once there are no available pages it is queued on the used queue. The used queue hold segments that have no available pages and is sorted from the least number of active pages to the most number of active pages.

The driver is required to compact segments. Compacting takes the segment with the most number of available pages from the available queue then takes segments with the least number of active pages from the used queue until it has enough pages to fill the empty segment. As the active pages are moved they flagged as used and once the segment has only used pages it is erased.

A flash block driver like this never knows if a page is not being used by the file-system. A typical file system is not design with the idea of erasing a block on a disk once it is not being used. The file-system will normally use a flag or a location as a marker to say that part of the disk is no longer in use. This means a number of blocks could be held in active pages but are no in use by the file system. The file system may also read blocks that have never been written to disk. This complicates the driver and may make the wear, usage and erase patterns harsher than a flash file system. The driver may also suffer from problems if power is lost.

There are some flash disk specific IO control request types. To use open the device and issue the ioctl() call.

int fd = open ("/dev/flashdisk0", O_WRONLY, 0);
if (fd < 0)
{
  printf ("driver open failed: %s\n", strerror (errno));
  exit (1);
}
if (ioctl (fd, RTEMS_FDISK_IOCTL_ERASE_DISK) < 0)
{
  printf ("driver erase failed: %s\n", strerror (errno));
  exit (1);
}
close (fd);

Macro Definition Documentation

RTEMS_FDISK_BACKGROUND_COMPACT

#define RTEMS_FDISK_BACKGROUND_COMPACT   (1 << 1)

Leave the compacting of of used segment to the background handler.

RTEMS_FDISK_BACKGROUND_ERASE

#define RTEMS_FDISK_BACKGROUND_ERASE   (1 << 0)

Leave the erasing of used segment to the background handler.

RTEMS_FDISK_BLANK_CHECK_BEFORE_WRITE

#define RTEMS_FDISK_BLANK_CHECK_BEFORE_WRITE   (1 << 3)

Blank check the flash device before writing to them. This is needed if you think you have a driver or device problem.

RTEMS_FDISK_CHECK_PAGES

#define RTEMS_FDISK_CHECK_PAGES   (1 << 2)

Check the pages during initialisation to see which pages are valid and which are not. This could slow down initialising the disk driver.

Typedef Documentation

rtems_fdisk_device_desc

typedef struct rtems_fdisk_device_desc rtems_fdisk_device_desc

Flash Device Descriptor holds the segments in a device.

The placing of the segments in a device decriptor allows the low level driver to share the segment descriptors for a number of devices.

Typically this structure is part of a table of segments in the device which is referenced in the flash disk configuration table. The reference is kept in the driver and used all the time to manage the flash device, therefore it must always exist.

rtems_fdisk_driver_handlers

typedef struct rtems_fdisk_driver_handlers rtems_fdisk_driver_handlers

Flash Low Level driver handlers.

Typically this structure is part of a table of handlers in the device which is referenced in the flash disk configuration table. The reference is kept in the driver and used all the time to manage the flash device, therefore it must always exist.

rtems_fdisk_segment_desc

typedef struct rtems_fdisk_segment_desc rtems_fdisk_segment_desc

Flash Segment Descriptor holds, number of continuous segments in the device of this type, the base segment number in the device, the address offset of the base segment in the device, and the size of segment.

Typically this structure is part of a table of segments in the device which is referenced in the flash disk configuration table. The reference is kept in the driver and used all the time to manage the flash device, therefore it must always exist.

rtems_flashdisk_config

typedef struct rtems_flashdisk_config rtems_flashdisk_config

RTEMS Flash Disk configuration table used to initialise the driver.

The unavailable blocks count is the number of blocks less than the available number of blocks the file system is given. This means there will always be that number of blocks available when the file system thinks the disk is full. The compaction code needs blocks to compact with so you will never be able to have all the blocks allocated to the file system and be able to full the disk.

The compacting segment count is the number of segments that are moved into a new segment. A high number will mean more segments with low active page counts and high used page counts will be moved into avaliable pages how-ever this extends the compaction time due to time it takes the erase the pages. There is no pont making this number greater than the maximum number of pages in a segment.

The available compacting segment count is the level when compaction occurs when writing. If you set this to 0 then compaction will fail because there will be no segments to compact into.

The info level can be 0 for off with error, and abort messages allowed. Level 1 is warning messages, level 1 is informational messages, and level 3 is debugging type prints. The info level can be turned off with a compile time directive on the command line to the compiler of:

-DRTEMS_FDISK_TRACE=0

Function Documentation

rtems_fdisk_initialize()

rtems_device_driver rtems_fdisk_initialize	(	rtems_device_major_number	major,
		rtems_device_minor_number	minor,
		void *	arg
	)

Flash disk device driver initialization. Place in a table as the initialisation entry and remainder of the entries are the RTEMS block device generic handlers.

Parameters

major	Flash disk major device number.
minor	Minor device number, not applicable.
arg	Initialization argument, not applicable.

Returns

The rtems_device_driver is actually just rtems_status_code.