Changeset a757d0f in rtems for cpukit/libblock


Ignore:
Timestamp:
Mar 14, 2012, 9:33:55 AM (8 years ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
4.11, master
Children:
9f808d1f
Parents:
a309a79
git-author:
Sebastian Huber <sebastian.huber@…> (03/14/12 09:33:55)
git-committer:
Sebastian Huber <sebastian.huber@…> (03/14/12 09:49:49)
Message:

PR2040: libblock: Flash disk documentation

Location:
cpukit/libblock
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • cpukit/libblock/include/rtems/flashdisk.h

    ra309a79 ra757d0f  
    11/**
    2  * @file rtems/flashdisk.h
     2 * @file
     3 *
     4 * @ingroup RTEMSFDisk
    35 *
    46 * This file defines the interface to a flash disk block device.
     
    2426
    2527/**
    26  * The base name of the flash disks.
    27  */
    28 #define RTEMS_FLASHDISK_DEVICE_BASE_NAME "/dev/fdd"
    29 
    30 /**
    31  * Flash disk specific ioctl request types. To use open the
    32  * device and issue the ioctl call.
     28 * @defgroup RTEMSFDisk Flash Disk Device
     29 *
     30 * @ingroup rtems_blkdev
     31 *
     32 * Flash disk driver for RTEMS provides support for block based
     33 * file systems on flash devices. The driver is not a flash file
     34 * system nor does it try to compete with flash file systems. It
     35 * currently does not journal how-ever block sequence numbering
     36 * could be added to allow recovery of a past positions if
     37 * a power down occurred while being updated.
     38 *
     39 * This flash driver provides block device support for most flash
     40 * devices. The driver has been tested on NOR type devices such
     41 * as the AMLV160 or M28W160. Support for NAND type devices may
     42 * require driver changes to allow speedy recover of the block
     43 * mapping data and to also handle the current use of word programming.
     44 * Currently the page descriptors are stored in the first few pages
     45 * of each segment.
     46 *
     47 * The driver supports devices, segments and pages. You provide
     48 * to the driver the device descriptions as a table of device
     49 * descriptors. Each device descriptor contain a table of
     50 * segment descriptions or segment descriptors. The driver uses
     51 * this information to manage the devices.
     52 *
     53 * A device is made up of segments. These are also called
     54 * sectors or blocks. It is the smallest erasable part of a device.
     55 * A device can have differing size segments at different
     56 * offsets in the device. The segment descriptors support repeating
     57 * segments that are continuous in the device. The driver breaks the
     58 * segments up into pages. The first pages of a segment contain
     59 * the page descriptors. A page descriptor hold the page flags,
     60 * a CRC for the page of data and the block number the page
     61 * holds. The block can appear in any order in the devices. A
     62 * page is active if it hold a current block of data. If the
     63 * used bit is set the page is counted as used. A page moves
     64 * from erased to active to used then back to erased. If a block
     65 * is written that is already in a page, the block is written to
     66 * a new page the old page is flagged as used.
     67 *
     68 * At initialization time each segment's page descriptors are
     69 * read into memory and scanned to determine the active pages,
     70 * the used pages and the bad pages. If a segment has any erased
     71 * pages it is queue on the available queue. If the segment has
     72 * no erased pages it is queue on the used queue.
     73 *
     74 * The available queue is sorted from the least number available
     75 * to the most number of available pages. A segment that has just
     76 * been erased will placed at the end of the queue. A segment that
     77 * has only a few available pages will be used sooner and once
     78 * there are no available pages it is queued on the used queue.
     79 * The used queue hold segments that have no available pages and
     80 * is sorted from the least number of active pages to the most
     81 * number of active pages.
     82 *
     83 * The driver is required to compact segments. Compacting takes
     84 * the segment with the most number of available pages from the
     85 * available queue then takes segments with the least number of
     86 * active pages from the used queue until it has enough pages
     87 * to fill the empty segment. As the active pages are moved
     88 * they flagged as used and once the segment has only used pages
     89 * it is erased.
     90 *
     91 * A flash block driver like this never knows if a page is not
     92 * being used by the file-system. A typical file system is not
     93 * design with the idea of erasing a block on a disk once it is
     94 * not being used. The file-system will normally use a flag
     95 * or a location as a marker to say that part of the disk is
     96 * no longer in use. This means a number of blocks could be
     97 * held in active pages but are no in use by the file system.
     98 * The file system may also read blocks that have never been
     99 * written to disk. This complicates the driver and may make
     100 * the wear, usage and erase patterns harsher than a flash
     101 * file system. The driver may also suffer from problems if
     102 * power is lost.
     103 *
     104 * There are some flash disk specific IO control request types.
     105 * To use open the device and issue the ioctl() call.
    33106 *
    34107 * @code
     
    46119 *  close (fd);
    47120 * @endcode
    48  */
     121 *
     122 * @{
     123 */
     124
     125/**
     126 * @brief The base name of the flash disks.
     127 */
     128#define RTEMS_FLASHDISK_DEVICE_BASE_NAME "/dev/fdd"
     129
    49130#define RTEMS_FDISK_IOCTL_ERASE_DISK   _IO('B', 128)
    50131#define RTEMS_FDISK_IOCTL_COMPACT      _IO('B', 129)
     
    55136
    56137/**
    57  * Flash Disk Monitoring Data allows a user to obtain
     138 * @brief Flash Disk Monitoring Data allows a user to obtain
    58139 * the current status of the disk.
    59140 */
     
    79160
    80161/**
    81  * Flash Segment Descriptor holds, number of continuous segments in the
    82  * device of this type, the base segment number in the device, the
    83  * address offset of the base segment in the device, and the size of
    84  * segment.
     162 * @brief Flash Segment Descriptor holds, number of continuous segments in the
     163 * device of this type, the base segment number in the device, the address
     164 * offset of the base segment in the device, and the size of segment.
    85165 *
    86166 * Typically this structure is part of a table of segments in the
     
    98178
    99179/**
    100  * Return the number of kilo-bytes.
     180 * @brief Return the number of kilo-bytes.
    101181 */
    102182#define RTEMS_FDISK_KBYTES(_k) (UINT32_C(1024) * (_k))
     
    108188
    109189/**
    110  * Flash Low Level driver handlers.
    111 
     190 * @brief Flash Low Level driver handlers.
     191 *
    112192 * Typically this structure is part of a table of handlers in the
    113193 * device which is referenced in the flash disk configuration table.
     
    250330
    251331/**
    252  * Flash Device Descriptor holds the segments in a device. The
    253  * placing of the segments in a device decriptor allows the
    254  * low level driver to share the segment descriptors for a
    255  * number of devices.
     332 * @brief Flash Device Descriptor holds the segments in a device.
     333 *
     334 * The placing of the segments in a device decriptor allows the low level
     335 * driver to share the segment descriptors for a number of devices.
    256336 *
    257337 * Typically this structure is part of a table of segments in the
     
    268348
    269349/**
    270  * RTEMS Flash Disk configuration table used to initialise the
     350 * @brief RTEMS Flash Disk configuration table used to initialise the
    271351 * driver.
    272352 *
     
    303383  uint32_t                       flags;          /**< Set of flags to control
    304384                                                      driver. */
    305   uint32_t                       unavail_blocks; /**< Number of blocks not
    306                                                       available to the file sys. */
     385  /**
     386   * Number of blocks not available to the file system.  This number must be
     387   * greater than or equal to the number of blocks in the largest segment to
     388   * avoid starvation of erased blocks.
     389   */
     390  uint32_t                       unavail_blocks;
     391
    307392  uint32_t                       compact_segs;   /**< Max number of segs to
    308393                                                      compact in one pass. */
    309   uint32_t                       avail_compact_segs; /**< The number of segments
    310                                                           when compaction occurs
    311                                                           when writing. */
     394  /**
     395   * The number of segments when compaction occurs when writing.  In case the
     396   * number of segments in the available queue is less than or equal to this
     397   * number the compaction process will be triggered.  The available queue
     398   * contains all segments with erased blocks.
     399   */
     400  uint32_t                       avail_compact_segs;
    312401  uint32_t                       info_level;     /**< Default info level. */
    313402} rtems_flashdisk_config;
     
    357446
    358447/**
    359  * External reference to the configuration. Please supply.
     448 * @brief External reference to the configuration. Please supply.
    360449 * Support is present in confdefs.h for providing this variable.
    361450 */
     
    363452
    364453/**
    365  * External reference to the number of configurations. Please supply.
     454 * @brief External reference to the number of configurations. Please supply.
    366455 * Support is present in confdefs.h for providing this variable.
    367456 */
    368457extern uint32_t rtems_flashdisk_configuration_size;
    369458
     459/** @} */
     460
    370461#endif
  • cpukit/libblock/src/flashdisk.c

    ra309a79 ra757d0f  
    1010 * $Id$
    1111 */
    12 /**
    13  * @file
    14  *
    15  * Flash disk driver for RTEMS provides support for block based
    16  * file systems on flash devices. The driver is not a flash file
    17  * system nor does it try to compete with flash file systems. It
    18  * currently does not journal how-ever block sequence numbering
    19  * could be added to allow recovery of a past positions if
    20  * a power down occurred while being updated.
    21  *
    22  * This flash driver provides block device support for most flash
    23  * devices. The driver has been tested on NOR type devices such
    24  * as the AMLV160 or M28W160. Support for NAND type devices may
    25  * require driver changes to allow speedy recover of the block
    26  * mapping data and to also handle the current use of word programming.
    27  * Currently the page descriptors are stored in the first few pages
    28  * of each segment.
    29  *
    30  * The driver supports devices, segments and pages. You provide
    31  * to the driver the device descriptions as a table of device
    32  * descriptors. Each device descriptor contain a table of
    33  * segment descriptions or segment descriptors. The driver uses
    34  * this information to manage the devices.
    35  *
    36  * A device is made up of segments. These are also called
    37  * sectors or blocks. It is the smallest erasable part of a device.
    38  * A device can have differing size segments at different
    39  * offsets in the device. The segment descriptors support repeating
    40  * segments that are continous in the device. The driver breaks the
    41  * segments up into pages. The first pages of a segment contain
    42  * the page descriptors. A page descriptor hold the page flags,
    43  * a CRC for the page of data and the block number the page
    44  * holds. The block can appear in any order in the devices. A
    45  * page is active if it hold a current block of data. If the
    46  * used bit is set the page is counted as used. A page moves
    47  * from erased to active to used then back to erased. If a block
    48  * is written that is already in a page, the block is written to
    49  * a new page the old page is flagged as used.
    50  *
    51  * At initialisation time each segment's page descriptors are
    52  * read into memory and scanned to determine the active pages,
    53  * the used pages and the bad pages. If a segment has any erased
    54  * pages it is queue on the available queue. If the segment has
    55  * no erased pages it is queue on the used queue.
    56  *
    57  * The available queue is sorted from the least number available
    58  * to the most number of available pages. A segment that has just
    59  * been erased will placed at the end of the queue. A segment that
    60  * has only a few available pages will be used sooner and once
    61  * there are no available pages it is queued on the used queue.
    62  * The used queue hold segments that have no available pages and
    63  * is sorted from the least number of active pages to the most
    64  * number of active pages.
    65  *
    66  * The driver is required to compact segments. Compacting takes
    67  * the segment with the most number of available pages from the
    68  * available queue then takes segments with the least number of
    69  * active pages from the used queue until it has enough pages
    70  * to fill the empty segment. As the active pages are moved
    71  * they flagged as used and once the segment has only used pages
    72  * it is erased.
    73  *
    74  * A flash block driver like this never knows if a page is not
    75  * being used by the file-system. A typical file system is not
    76  * design with the idea of erasing a block on a disk once it is
    77  * not being used. The file-system will normally use a flag
    78  * or a location as a marker to say that part of the disk is
    79  * no longer in use. This means a number of blocks could be
    80  * held in active pages but are no in use by the file system.
    81  * The file system may also read blocks that have never been
    82  * written to disk. This complicates the driver and may make
    83  * the wear, usage and erase patterns harsher than a flash
    84  * file system. The driver may also suffer from problems if
    85  * power is lost.
    86  *
    87  * @note
    88  *
     12
     13/*
    8914 * The use of pages can vary. The rtems_fdisk_seg_*_page set
    9015 * routines use an absolute page number relative to the segment
    91  * while all other page numbera are relative to the number of
     16 * while all other page numbers are relative to the number of
    9217 * page descriptor pages a segment has. You need to add the
    9318 * number of page descriptor pages (pages_desc) to the page number
Note: See TracChangeset for help on using the changeset viewer.