source: rtems/cpukit/libblock/include/rtems/flashdisk.h @ fb5785cc

4.104.11
Last change on this file since fb5785cc was fb5785cc, checked in by Ralf Corsepius <ralf.corsepius@…>, on Oct 22, 2009 at 11:56:01 AM

2009-10-22 Ralf Corsépius <ralf.corsepius@…>

  • libblock/include/rtems/flashdisk.h: Use UINT32_C consts to avoid implicit int-cast overflows in RTEMS_FDISK_KBYTES.
  • Property mode set to 100644
File size: 13.8 KB
Line 
1/*
2 * flashdisk.h -- Flash disk block device implementation
3 *
4 * Copyright (C) 2007 Chris Johns
5 *
6 * The license and distribution terms for this file may be
7 * found in the file LICENSE in this distribution or at
8 * http://www.rtems.com/license/LICENSE.
9 *
10 * $Id$
11 */
12
13#if !defined (_RTEMS_FLASHDISK_H_)
14#define _RTEMS_FLASHDISK_H_
15
16#include <stdint.h>
17#include <sys/ioctl.h>
18
19#include <rtems.h>
20
21/**
22 * The base name of the flash disks.
23 */
24#define RTEMS_FLASHDISK_DEVICE_BASE_NAME "/dev/fdd"
25
26/**
27 * Flash disk specific ioctl request types. To use open the
28 * device and issue the ioctl call.
29 *
30 * @code
31 *  int fd = open ("/dev/flashdisk0", O_WRONLY, 0);
32 *  if (fd < 0)
33 *  {
34 *    printf ("driver open failed: %s\n", strerror (errno));
35 *    exit (1);
36 *  }
37 *  if (ioctl (fd, RTEMS_FDISK_IOCTL_ERASE_DISK) < 0)
38 *  {
39 *    printf ("driver erase failed: %s\n", strerror (errno));
40 *    exit (1);
41 *  }
42 *  close (fd);
43 * @endcode
44 */
45#define RTEMS_FDISK_IOCTL_ERASE_DISK   _IO('B', 128)
46#define RTEMS_FDISK_IOCTL_COMPACT      _IO('B', 129)
47#define RTEMS_FDISK_IOCTL_ERASE_USED   _IO('B', 130)
48#define RTEMS_FDISK_IOCTL_MONITORING   _IO('B', 131)
49#define RTEMS_FDISK_IOCTL_INFO_LEVEL   _IO('B', 132)
50#define RTEMS_FDISK_IOCTL_PRINT_STATUS _IO('B', 133)
51
52/**
53 * Flash Disk Monitoring Data allows a user to obtain
54 * the current status of the disk.
55 */
56typedef struct rtems_fdisk_monitor_data
57{
58  uint32_t block_size;
59  uint32_t block_count;
60  uint32_t unavail_blocks;
61  uint32_t device_count;
62  uint32_t segment_count;
63  uint32_t page_count;
64  uint32_t blocks_used;
65  uint32_t segs_available;
66  uint32_t segs_used;
67  uint32_t segs_failed;
68  uint32_t seg_erases;
69  uint32_t pages_desc;
70  uint32_t pages_active;
71  uint32_t pages_used;
72  uint32_t pages_bad;
73  uint32_t info_level;
74} rtems_fdisk_monitor_data;
75
76/**
77 * Flash Segment Descriptor holds, number of continuous segments in the
78 * device of this type, the base segment number in the device, the
79 * address offset of the base segment in the device, and the size of
80 * segment.
81 *
82 * Typically this structure is part of a table of segments in the
83 * device which is referenced in the flash disk configuration table.
84 * The reference is kept in the driver and used all the time to
85 * manage the flash device, therefore it must always exist.
86 */
87typedef struct rtems_fdisk_segment_desc
88{
89  uint16_t count;    /**< Number of segments of this type in a row. */
90  uint16_t segment;  /**< The base segment number. */
91  uint32_t offset;   /**< Address offset of base segment in device. */
92  uint32_t size;     /**< Size of the segment in bytes. */
93} rtems_fdisk_segment_desc;
94
95/**
96 * Return the number of kilo-bytes.
97 */
98#define RTEMS_FDISK_KBYTES(_k) (UINT32_C(1024) * (_k))
99
100/**
101 * Forward declaration of the device descriptor.
102 */
103struct rtems_fdisk_device_desc;
104
105/**
106 * Flash Low Level driver handlers.
107
108 * Typically this structure is part of a table of handlers in the
109 * device which is referenced in the flash disk configuration table.
110 * The reference is kept in the driver and used all the time to
111 * manage the flash device, therefore it must always exist.
112 */
113typedef struct rtems_fdisk_driver_handlers
114{
115  /**
116   * Read data from the device into the buffer. Return an errno
117   * error number if the device cannot be read. A segment descriptor
118   * can describe more than one segment in a device if the device has
119   * repeating segments. The segment number is the device segment to
120   * access and the segment descriptor must reference the segment
121   * being requested. For example the segment number must resided in
122   * the range [base, base + count).
123   *
124   * @param sd The segment descriptor.
125   * @param device The device to read data from.
126   * @param segment The segment within the device to read.
127   * @param offset The offset in the segment to read.
128   * @param buffer The buffer to read the data into.
129   * @param size The amount of data to read.
130   * @retval 0 No error.
131   * @retval EIO The read did not complete.
132   */
133  int (*read) (const rtems_fdisk_segment_desc* sd,
134               uint32_t                        device,
135               uint32_t                        segment,
136               uint32_t                        offset,
137               void*                           buffer,
138               uint32_t                        size);
139
140  /**
141   * Write data from the buffer to the device. Return an errno
142   * error number if the device cannot be written to. A segment
143   * descriptor can describe more than segment in a device if the
144   * device has repeating segments. The segment number is the device
145   * segment to access and the segment descriptor must reference
146   * the segment being requested. For example the segment number must
147   * resided in the range [base, base + count).
148   *
149   * @param sd The segment descriptor.
150   * @param device The device to write data from.
151   * @param segment The segment within the device to write to.
152   * @param offset The offset in the segment to write.
153   * @param buffer The buffer to write the data from.
154   * @param size The amount of data to write.
155   * @retval 0 No error.
156   * @retval EIO The write did not complete or verify.
157   */
158  int (*write) (const rtems_fdisk_segment_desc* sd,
159                uint32_t                        device,
160                uint32_t                        segment,
161                uint32_t                        offset,
162                const void*                     buffer,
163                uint32_t                        size);
164
165  /**
166   * Blank a segment in the device. Return an errno error number
167   * if the device cannot be read or is not blank. A segment descriptor
168   * can describe more than segment in a device if the device has
169   * repeating segments. The segment number is the device segment to
170   * access and the segment descriptor must reference the segment
171   * being requested. For example the segment number must resided in
172   * the range [base, base + count).
173   *
174   * @param sd The segment descriptor.
175   * @param device The device to read data from.
176   * @param segment The segment within the device to read.
177   * @param offset The offset in the segment to checl.
178   * @param size The amount of data to check.
179   * @retval 0 No error.
180   * @retval EIO The segment is not blank.
181   */
182  int (*blank) (const rtems_fdisk_segment_desc* sd,
183                uint32_t                        device,
184                uint32_t                        segment,
185                uint32_t                        offset,
186                uint32_t                        size);
187
188  /**
189   * Verify data in the buffer to the data in the device. Return an
190   * errno error number if the device cannot be read. A segment
191   * descriptor can describe more than segment in a device if the
192   * device has repeating segments. The segment number is the
193   * segment to access and the segment descriptor must reference
194   * the device segment being requested. For example the segment number
195   * must resided in the range [base, base + count).
196   *
197   * @param sd The segment descriptor.
198   * @param device The device to verify data in.
199   * @param segment The segment within the device to verify.
200   * @param offset The offset in the segment to verify.
201   * @param buffer The buffer to verify the data in the device with.
202   * @param size The amount of data to verify.
203   * @retval 0 No error.
204   * @retval EIO The data did not verify.
205   */
206  int (*verify) (const rtems_fdisk_segment_desc* sd,
207                 uint32_t                        device,
208                 uint32_t                        segment,
209                 uint32_t                        offset,
210                 const void*                     buffer,
211                 uint32_t                        size);
212
213  /**
214   * Erase the segment. Return an errno error number if the
215   * segment cannot be erased. A segment descriptor can describe
216   * more than segment in a device if the device has repeating
217   * segments. The segment number is the device segment to access and
218   * the segment descriptor must reference the segment being requested.
219   *
220   * @param sd The segment descriptor.
221   * @param device The device to erase the segment of.
222   * @param segment The segment within the device to erase.
223   * @retval 0 No error.
224   * @retval EIO The segment was not erased.
225   */
226  int (*erase) (const rtems_fdisk_segment_desc* sd,
227                uint32_t                        device,
228                uint32_t                        segment);
229
230  /**
231   * Erase the device. Return an errno error number if the
232   * segment cannot be erased. A segment descriptor can describe
233   * more than segment in a device if the device has repeating
234   * segments. The segment number is the segment to access and
235   * the segment descriptor must reference the segment being requested.
236   *
237   * @param sd The segment descriptor.
238   * @param device The device to erase.
239   * @retval 0 No error.
240   * @retval EIO The device was not erased.
241   */
242  int (*erase_device) (const struct rtems_fdisk_device_desc* dd,
243                       uint32_t                              device);
244
245} rtems_fdisk_driver_handlers;
246
247/**
248 * Flash Device Descriptor holds the segments in a device. The
249 * placing of the segments in a device decriptor allows the
250 * low level driver to share the segment descriptors for a
251 * number of devices.
252 *
253 * Typically this structure is part of a table of segments in the
254 * device which is referenced in the flash disk configuration table.
255 * The reference is kept in the driver and used all the time to
256 * manage the flash device, therefore it must always exist.
257 */
258typedef struct rtems_fdisk_device_desc
259{
260  uint32_t                           segment_count; /**< Number of segments. */
261  const rtems_fdisk_segment_desc*    segments;      /**< Array of segments. */
262  const rtems_fdisk_driver_handlers* flash_ops;     /**< Device handlers. */
263} rtems_fdisk_device_desc;
264
265/**
266 * RTEMS Flash Disk configuration table used to initialise the
267 * driver.
268 *
269 * The unavailable blocks count is the number of blocks less than the
270 * available number of blocks the file system is given. This means there
271 * will always be that number of blocks available when the file system
272 * thinks the disk is full. The compaction code needs blocks to compact
273 * with so you will never be able to have all the blocks allocated to the
274 * file system and be able to full the disk.
275 *
276 * The compacting segment count is the number of segments that are
277 * moved into a new segment. A high number will mean more segments with
278 * low active page counts and high used page counts will be moved into
279 * avaliable pages how-ever this extends the compaction time due to
280 * time it takes the erase the pages. There is no pont making this number
281 * greater than the maximum number of pages in a segment.
282 *
283 * The available compacting segment count is the level when compaction occurs
284 * when writing. If you set this to 0 then compaction will fail because
285 * there will be no segments to compact into.
286 *
287 * The info level can be 0 for off with error, and abort messages allowed.
288 * Level 1 is warning messages, level 1 is informational messages, and level 3
289 * is debugging type prints. The info level can be turned off with a compile
290 * time directive on the command line to the compiler of:
291 *
292 *     -DRTEMS_FDISK_TRACE=0
293 */
294typedef struct rtems_flashdisk_config
295{
296  uint32_t                       block_size;     /**< The block size. */
297  uint32_t                       device_count;   /**< The number of devices. */
298  const rtems_fdisk_device_desc* devices;        /**< The device descriptions. */
299  uint32_t                       flags;          /**< Set of flags to control
300                                                      driver. */
301  uint32_t                       unavail_blocks; /**< Number of blocks not
302                                                      available to the file sys. */
303  uint32_t                       compact_segs;   /**< Max number of segs to
304                                                      compact in one pass. */
305  uint32_t                       avail_compact_segs; /**< The number of segments
306                                                          when compaction occurs
307                                                          when writing. */
308  uint32_t                       info_level;     /**< Default info level. */
309} rtems_flashdisk_config;
310
311/*
312 * Driver flags.
313 */
314
315/**
316 * Leave the erasing of used segment to the background handler.
317 */
318#define RTEMS_FDISK_BACKGROUND_ERASE (1 << 0)
319
320/**
321 * Leave the compacting of of used segment to the background handler.
322 */
323#define RTEMS_FDISK_BACKGROUND_COMPACT (1 << 1)
324
325/**
326 * Check the pages during initialisation to see which pages are
327 * valid and which are not. This could slow down initialising the
328 * disk driver.
329 */
330#define RTEMS_FDISK_CHECK_PAGES (1 << 2)
331
332/**
333 * Blank check the flash device before writing to them. This is needed if
334 * you think you have a driver or device problem.
335 */
336#define RTEMS_FDISK_BLANK_CHECK_BEFORE_WRITE (1 << 3)
337
338/**
339 * Flash disk device driver initialization. Place in a table as the
340 * initialisation entry and remainder of the entries are the
341 * RTEMS block device generic handlers.
342 *
343 * @param major Flash disk major device number.
344 * @param minor Minor device number, not applicable.
345 * @param arg Initialization argument, not applicable.
346 * @return The rtems_device_driver is actually just
347 *         rtems_status_code.
348 */
349rtems_device_driver
350rtems_fdisk_initialize (rtems_device_major_number major,
351                        rtems_device_minor_number minor,
352                        void*                     arg);
353
354/**
355 * External reference to the configuration. Please supply.
356 * Support is present in confdefs.h for providing this variable.
357 */
358extern const rtems_flashdisk_config rtems_flashdisk_configuration[];
359
360/**
361 * External reference to the number of configurations. Please supply.
362 * Support is present in confdefs.h for providing this variable.
363 */
364extern uint32_t rtems_flashdisk_configuration_size;
365
366#endif
Note: See TracBrowser for help on using the repository browser.