LXR 6.1/​cpukit/​include/​rtems/​flashdisk.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:13

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
  * @file
  *
  * @ingroup RTEMSFDisk
  *
  * @brief Interface to a Flash Disk Block Device
  *
  * This file defines the interface to a flash disk block device.
  */
 
 /*
  * Copyright (C) 2007 Chris Johns
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
 #if !defined (_RTEMS_FLASHDISK_H_)
 #define _RTEMS_FLASHDISK_H_
 
 #include <stdint.h>
 #include <sys/ioctl.h>
 
 #include <rtems.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
 
 /**
  * @defgroup RTEMSFDisk Flash Disk Device
  *
  * @ingroup rtems_blkdev
  *
  * 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.
  *
  * @code
  *  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);
  * @endcode
  */
 /**@{**/
 
 /**
  * @brief The base name of the flash disks.
  */
 #define RTEMS_FLASHDISK_DEVICE_BASE_NAME "/dev/fdd"
 
 #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)
 
 /**
  * @brief Flash Disk Monitoring Data allows a user to obtain
  * the current status of the disk.
  */
 typedef struct rtems_fdisk_monitor_data
 {
   uint32_t block_size;
   uint32_t block_count;
   uint32_t unavail_blocks;
   uint32_t device_count;
   uint32_t segment_count;
   uint32_t page_count;
   uint32_t blocks_used;
   uint32_t segs_available;
   uint32_t segs_used;
   uint32_t segs_failed;
   uint32_t seg_erases;
   uint32_t pages_desc;
   uint32_t pages_active;
   uint32_t pages_used;
   uint32_t pages_bad;
   uint32_t info_level;
 } rtems_fdisk_monitor_data;
 
 /**
  * @brief 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.
  */
 typedef struct rtems_fdisk_segment_desc
 {
   uint16_t count;    /**< Number of segments of this type in a row. */
   uint16_t segment;  /**< The base segment number. */
   uint32_t offset;   /**< Address offset of base segment in device. */
   uint32_t size;     /**< Size of the segment in bytes. */
 } rtems_fdisk_segment_desc;
 
 /**
  * @brief Return the number of kilo-bytes.
  */
 #define RTEMS_FDISK_KBYTES(_k) (UINT32_C(1024) * (_k))
 
 /**
  * Forward declaration of the device descriptor.
  */
 struct rtems_fdisk_device_desc;
 
 /**
  * @brief 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.
  */
 typedef struct rtems_fdisk_driver_handlers
 {
   /**
    * Read data from the device into the buffer. Return an errno
    * error number if the device cannot be read. A segment descriptor
    * can describe more than one segment in a device if the device has
    * repeating segments. The segment number is the device segment to
    * access and the segment descriptor must reference the segment
    * being requested. For example the segment number must resided in
    * the range [base, base + count).
    *
    * @param sd The segment descriptor.
    * @param device The device to read data from.
    * @param segment The segment within the device to read.
    * @param offset The offset in the segment to read.
    * @param buffer The buffer to read the data into.
    * @param size The amount of data to read.
    * @retval 0 No error.
    * @retval EIO The read did not complete.
    */
   int (*read) (const rtems_fdisk_segment_desc* sd,
                uint32_t                        device,
                uint32_t                        segment,
                uint32_t                        offset,
                void*                           buffer,
                uint32_t                        size);
 
   /**
    * Write data from the buffer to the device. Return an errno
    * error number if the device cannot be written to. A segment
    * descriptor can describe more than segment in a device if the
    * device has repeating segments. The segment number is the device
    * segment to access and the segment descriptor must reference
    * the segment being requested. For example the segment number must
    * resided in the range [base, base + count).
    *
    * @param sd The segment descriptor.
    * @param device The device to write data from.
    * @param segment The segment within the device to write to.
    * @param offset The offset in the segment to write.
    * @param buffer The buffer to write the data from.
    * @param size The amount of data to write.
    * @retval 0 No error.
    * @retval EIO The write did not complete or verify.
    */
   int (*write) (const rtems_fdisk_segment_desc* sd,
                 uint32_t                        device,
                 uint32_t                        segment,
                 uint32_t                        offset,
                 const void*                     buffer,
                 uint32_t                        size);
 
   /**
    * Blank a segment in the device. Return an errno error number
    * if the device cannot be read or is not blank. A segment descriptor
    * can describe more than segment in a device if the device has
    * repeating segments. The segment number is the device segment to
    * access and the segment descriptor must reference the segment
    * being requested. For example the segment number must resided in
    * the range [base, base + count).
    *
    * @param sd The segment descriptor.
    * @param device The device to read data from.
    * @param segment The segment within the device to read.
    * @param offset The offset in the segment to checl.
    * @param size The amount of data to check.
    * @retval 0 No error.
    * @retval EIO The segment is not blank.
    */
   int (*blank) (const rtems_fdisk_segment_desc* sd,
                 uint32_t                        device,
                 uint32_t                        segment,
                 uint32_t                        offset,
                 uint32_t                        size);
 
   /**
    * Verify data in the buffer to the data in the device. Return an
    * errno error number if the device cannot be read. A segment
    * descriptor can describe more than segment in a device if the
    * device has repeating segments. The segment number is the
    * segment to access and the segment descriptor must reference
    * the device segment being requested. For example the segment number
    * must resided in the range [base, base + count).
    *
    * @param sd The segment descriptor.
    * @param device The device to verify data in.
    * @param segment The segment within the device to verify.
    * @param offset The offset in the segment to verify.
    * @param buffer The buffer to verify the data in the device with.
    * @param size The amount of data to verify.
    * @retval 0 No error.
    * @retval EIO The data did not verify.
    */
   int (*verify) (const rtems_fdisk_segment_desc* sd,
                  uint32_t                        device,
                  uint32_t                        segment,
                  uint32_t                        offset,
                  const void*                     buffer,
                  uint32_t                        size);
 
   /**
    * Erase the segment. Return an errno error number if the
    * segment cannot be erased. A segment descriptor can describe
    * more than segment in a device if the device has repeating
    * segments. The segment number is the device segment to access and
    * the segment descriptor must reference the segment being requested.
    *
    * @param sd The segment descriptor.
    * @param device The device to erase the segment of.
    * @param segment The segment within the device to erase.
    * @retval 0 No error.
    * @retval EIO The segment was not erased.
    */
   int (*erase) (const rtems_fdisk_segment_desc* sd,
                 uint32_t                        device,
                 uint32_t                        segment);
 
   /**
    * Erase the device. Return an errno error number if the
    * segment cannot be erased. A segment descriptor can describe
    * more than segment in a device if the device has repeating
    * segments. The segment number is the segment to access and
    * the segment descriptor must reference the segment being requested.
    *
    * @param sd The segment descriptor.
    * @param device The device to erase.
    * @retval 0 No error.
    * @retval EIO The device was not erased.
    */
   int (*erase_device) (const struct rtems_fdisk_device_desc* dd,
                        uint32_t                              device);
 
 } rtems_fdisk_driver_handlers;
 
 /**
  * @brief 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.
  */
 typedef struct rtems_fdisk_device_desc
 {
   uint32_t                           segment_count; /**< Number of segments. */
   const rtems_fdisk_segment_desc*    segments;      /**< Array of segments. */
   const rtems_fdisk_driver_handlers* flash_ops;     /**< Device handlers. */
 } rtems_fdisk_device_desc;
 
 /**
  * @brief 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
  */
 typedef struct rtems_flashdisk_config
 {
   uint32_t                       block_size;     /**< The block size. */
   uint32_t                       device_count;   /**< The number of devices. */
   const rtems_fdisk_device_desc* devices;        /**< The device descriptions. */
   uint32_t                       flags;          /**< Set of flags to control
                                                       driver. */
   /**
    * Number of blocks not available to the file system.  This number must be
    * greater than or equal to the number of blocks in the largest segment to
    * avoid starvation of erased blocks.
    */
   uint32_t                       unavail_blocks;
 
   uint32_t                       compact_segs;   /**< Max number of segs to
                                                       compact in one pass. */
   /**
    * The number of segments when compaction occurs when writing.  In case the
    * number of segments in the available queue is less than or equal to this
    * number the compaction process will be triggered.  The available queue
    * contains all segments with erased blocks.
    */
   uint32_t                       avail_compact_segs;
   uint32_t                       info_level;     /**< Default info level. */
 } rtems_flashdisk_config;
 
 /*
  * Driver flags.
  */
 
 /**
  * Leave the erasing of used segment to the background handler.
  */
 #define RTEMS_FDISK_BACKGROUND_ERASE (1 << 0)
 
 /**
  * Leave the compacting of of used segment to the background handler.
  */
 #define RTEMS_FDISK_BACKGROUND_COMPACT (1 << 1)
 
 /**
  * Check the pages during initialisation to see which pages are
  * valid and which are not. This could slow down initialising the
  * disk driver.
  */
 #define RTEMS_FDISK_CHECK_PAGES (1 << 2)
 
 /**
  * Blank check the flash device before writing to them. This is needed if
  * you think you have a driver or device problem.
  */
 #define RTEMS_FDISK_BLANK_CHECK_BEFORE_WRITE (1 << 3)
 
 /**
  * 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.
  *
  * @param major Flash disk major device number.
  * @param minor Minor device number, not applicable.
  * @param arg Initialization argument, not applicable.
  * @return The rtems_device_driver is actually just
  *         rtems_status_code.
  */
 rtems_device_driver
 rtems_fdisk_initialize (rtems_device_major_number major,
                         rtems_device_minor_number minor,
                         void*                     arg);
 
 /**
  * @brief External reference to the configuration. Please supply.
  * Support is present in confdefs.h for providing this variable.
  */
 extern const rtems_flashdisk_config rtems_flashdisk_configuration[];
 
 /**
  * @brief External reference to the number of configurations. Please supply.
  * Support is present in confdefs.h for providing this variable.
  */
 extern uint32_t rtems_flashdisk_configuration_size;
 
 /** @} */
 
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team