source: rtems/cpukit/include/rtems/diskdevs.h @ 0b038bd4

Last change on this file since 0b038bd4 was 0b038bd4, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 4, 2018 at 8:38:48 AM

libblock: Add RTEMS_DEPRECATED

Close #3358.

  • Property mode set to 100644
File size: 9.0 KB
Line 
1/**
2 * @file
3 *
4 * @brief Block Device Disk Management API
5 *
6 * @ingroup rtems_disk
7 */
8
9/*
10 * Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
11 * Author: Victor V. Vengerov <vvv@oktet.ru>
12 */
13
14#ifndef _RTEMS_DISKDEVS_H
15#define _RTEMS_DISKDEVS_H
16
17#include <rtems.h>
18#include <rtems/libio.h>
19#include <rtems/chain.h>
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25typedef struct rtems_disk_device rtems_disk_device;
26
27/**
28 * @defgroup rtems_disk Block Device Disk Management
29 *
30 * @ingroup rtems_libblock
31 *
32 * @brief This module provides functions to manage disk devices.
33 *
34 * A disk is a set of blocks which are identified by a consecutive set of
35 * non-negative integers starting at zero.  There are also logical disks which
36 * contain a subset of consecutive disk blocks.  The logical disks are used to
37 * represent the partitions of a disk.  The disk devices are accessed via the
38 * @ref rtems_bdbuf "block device buffer module".
39 */
40/**@{**/
41
42/**
43 * @brief Block device block index type.
44 */
45typedef uint32_t rtems_blkdev_bnum;
46
47/**
48 * @brief Block device IO control handler type.
49 */
50typedef int (*rtems_block_device_ioctl)(
51  rtems_disk_device *dd,
52  uint32_t req,
53  void *argp
54);
55
56/**
57 * @brief Trigger value to disable further read-ahead requests.
58 */
59#define RTEMS_DISK_READ_AHEAD_NO_TRIGGER ((rtems_blkdev_bnum) -1)
60
61/**
62 * @brief Block device read-ahead control.
63 */
64typedef struct {
65  /**
66   * @brief Chain node for the read-ahead request queue of the read-ahead task.
67   */
68  rtems_chain_node node;
69
70  /**
71   * @brief Block value to trigger the read-ahead request.
72   *
73   * A value of @ref RTEMS_DISK_READ_AHEAD_NO_TRIGGER will disable further
74   * read-ahead requests since no valid block can have this value.
75   */
76  rtems_blkdev_bnum trigger;
77
78  /**
79   * @brief Start block for the next read-ahead request.
80   *
81   * In case the trigger value is out of range of valid blocks, this value my
82   * be arbitrary.
83   */
84  rtems_blkdev_bnum next;
85} rtems_blkdev_read_ahead;
86
87/**
88 * @brief Block device statistics.
89 *
90 * Integer overflows in the statistic counters may happen.
91 */
92typedef struct {
93  /**
94   * @brief Read hit count.
95   *
96   * A read hit occurs in the rtems_bdbuf_read() function in case the block is
97   * in the cached or modified state.
98   */
99  uint32_t read_hits;
100
101  /**
102   * @brief Read miss count.
103   *
104   * A read miss occurs in the rtems_bdbuf_read() function in case the block is
105   * in the empty state and a read transfer must be initiated to read the data
106   * from the device.
107   */
108  uint32_t read_misses;
109
110  /**
111   * @brief Read-ahead transfer count.
112   *
113   * Each read-ahead transfer may read multiple blocks.
114   */
115  uint32_t read_ahead_transfers;
116
117  /**
118   * @brief Count of blocks transfered from the device.
119   */
120  uint32_t read_blocks;
121
122  /**
123   * @brief Read error count.
124   *
125   * Error count of transfers issued by the read or read-ahead requests.
126   */
127  uint32_t read_errors;
128
129  /**
130   * @brief Write transfer count.
131   *
132   * Each write transfer may write multiple blocks.
133   */
134  uint32_t write_transfers;
135
136  /**
137   * @brief Count of blocks transfered to the device.
138   */
139  uint32_t write_blocks;
140
141  /**
142   * @brief Write error count.
143   *
144   * Error count of transfers issued by write requests.
145   */
146  uint32_t write_errors;
147} rtems_blkdev_stats;
148
149/**
150 * @brief Description of a disk device (logical and physical disks).
151 *
152 * An array of pointer tables to rtems_disk_device structures is maintained.
153 * The first table will be indexed by the major number and the second table
154 * will be indexed by the minor number.  This allows quick lookup using a data
155 * structure of moderated size.
156 */
157struct rtems_disk_device {
158  /**
159   * @brief Device identifier (concatenation of major and minor number).
160   */
161  dev_t dev;
162
163  /**
164   * @brief Physical device identifier (equals the @c dev entry if it specifies a
165   * physical device).
166   */
167  rtems_disk_device *phys_dev;
168
169  /**
170   * @brief Driver capabilities.
171   */
172  uint32_t capabilities;
173
174  /**
175   * @brief Disk device name.
176   */
177  char *name;
178
179  /**
180   * @brief Usage counter.
181   *
182   * Devices cannot be deleted if they are in use.
183   */
184  unsigned uses;
185
186  /**
187   * @brief Start media block number.
188   *
189   * Equals zero for physical devices.  It is a media block offset to the
190   * related physical device for logical device.
191   */
192  rtems_blkdev_bnum start;
193
194  /**
195   * @brief Size of the physical or logical disk in media blocks.
196   */
197  rtems_blkdev_bnum size;
198
199  /**
200   * @brief Media block size in bytes.
201   *
202   * This is the media transfer unit the hardware defaults to.
203   */
204  uint32_t media_block_size;
205
206  /**
207   * @brief Block size in bytes.
208   *
209   * This is the minimum transfer unit.  It may be a multiple of the media
210   * block size. It must be positive.
211   *
212   * @see rtems_bdbuf_set_block_size().
213   */
214  uint32_t block_size;
215
216  /**
217   * @brief Block count.
218   *
219   * @see rtems_bdbuf_set_block_size().
220   */
221  rtems_blkdev_bnum block_count;
222
223  /**
224   * @brief Media blocks per device blocks.
225   *
226   * @see rtems_bdbuf_set_block_size().
227   */
228  uint32_t media_blocks_per_block;
229
230  /**
231   * @brief Block to media block shift.
232   *
233   * In case this value is non-negative the media block of a block can be
234   * calculated as media block = block << block_to_media_block_shift, otherwise
235   * a 64-bit operation will be used.
236   *
237   * @see rtems_bdbuf_set_block_size().
238   */
239  int block_to_media_block_shift;
240
241  /**
242   * @brief Buffer descriptors per group count.
243   *
244   * @see rtems_bdbuf_set_block_size().
245   */
246  size_t bds_per_group;
247
248  /**
249   * @brief IO control handler for this disk.
250   */
251  rtems_block_device_ioctl ioctl;
252
253  /**
254   * @brief Private data for the disk driver.
255   */
256  void *driver_data;
257
258  /**
259   * @brief Indicates that this disk should be deleted as soon as the last user
260   * releases this disk.
261   */
262  bool deleted;
263
264  /**
265   * @brief Device statistics for this disk.
266   */
267  rtems_blkdev_stats stats;
268
269  /**
270   * @brief Read-ahead control for this disk.
271   */
272  rtems_blkdev_read_ahead read_ahead;
273};
274
275/**
276 * @name Disk Device Data
277 */
278/**@{**/
279
280/* Use fstat() instead */
281RTEMS_DEPRECATED static inline dev_t rtems_disk_get_device_identifier(
282  const rtems_disk_device *dd
283)
284{
285  return dd->dev;
286}
287
288/* Use fstat() instead */
289RTEMS_DEPRECATED static inline rtems_device_major_number rtems_disk_get_major_number(
290  const rtems_disk_device *dd
291)
292{
293  return rtems_filesystem_dev_major_t(dd->dev);
294}
295
296/* Use fstat() instead */
297RTEMS_DEPRECATED static inline rtems_device_minor_number rtems_disk_get_minor_number(
298  const rtems_disk_device *dd
299)
300{
301  return rtems_filesystem_dev_minor_t(dd->dev);
302}
303
304static inline void *rtems_disk_get_driver_data(
305  const rtems_disk_device *dd
306)
307{
308  return dd->driver_data;
309}
310
311static inline uint32_t rtems_disk_get_media_block_size(
312  const rtems_disk_device *dd
313)
314{
315  return dd->media_block_size;
316}
317
318static inline uint32_t rtems_disk_get_block_size(
319  const rtems_disk_device *dd
320)
321{
322  return dd->block_size;
323}
324
325static inline rtems_blkdev_bnum rtems_disk_get_block_begin(
326  const rtems_disk_device *dd
327)
328{
329  return dd->start;
330}
331
332static inline rtems_blkdev_bnum rtems_disk_get_block_count(
333  const rtems_disk_device *dd
334)
335{
336  return dd->size;
337}
338
339/** @} */
340
341/**
342 * @name Disk Device Maintainance
343 */
344/**@{**/
345
346/* Use rtems_blkdev_create() instead */
347RTEMS_DEPRECATED rtems_status_code rtems_disk_create_phys(
348  dev_t dev,
349  uint32_t block_size,
350  rtems_blkdev_bnum block_count,
351  rtems_block_device_ioctl handler,
352  void *driver_data,
353  const char *name
354);
355
356/* Use rtems_blkdev_create_partition() instead */
357RTEMS_DEPRECATED rtems_status_code rtems_disk_create_log(
358  dev_t dev,
359  dev_t phys,
360  rtems_blkdev_bnum block_begin,
361  rtems_blkdev_bnum block_count,
362  const char *name
363);
364
365/*
366 * Use rtems_blkdev_create() or rtems_blkdev_create_partition and unlink()
367 * instead.
368 */
369RTEMS_DEPRECATED rtems_status_code rtems_disk_delete(dev_t dev);
370
371/*
372 * Use rtems_blkdev_create() or rtems_blkdev_create_partition and open()
373 * instead.
374 */
375RTEMS_DEPRECATED rtems_disk_device *rtems_disk_obtain(dev_t dev);
376
377/*
378 * Use rtems_blkdev_create() or rtems_blkdev_create_partition and close()
379 * instead.
380 */
381RTEMS_DEPRECATED rtems_status_code rtems_disk_release(rtems_disk_device *dd);
382
383/** @} */
384
385/**
386 * @name Disk Management
387 */
388/**@{**/
389
390/* Just remove calls to this function */
391RTEMS_DEPRECATED rtems_status_code rtems_disk_io_initialize(void);
392
393/* Just remove calls to this function */
394RTEMS_DEPRECATED rtems_status_code rtems_disk_io_done(void);
395
396/** @} */
397
398/** @} */
399
400/*
401 * This functionality no longer available.  There is no global registration for
402 * disk devices.
403 */
404RTEMS_DEPRECATED rtems_disk_device *rtems_disk_next(dev_t dev);
405
406/* Internal function, do not use */
407rtems_status_code rtems_disk_init_phys(
408  rtems_disk_device *dd,
409  uint32_t block_size,
410  rtems_blkdev_bnum block_count,
411  rtems_block_device_ioctl handler,
412  void *driver_data
413);
414
415/* Internal function, do not use */
416rtems_status_code rtems_disk_init_log(
417  rtems_disk_device *dd,
418  rtems_disk_device *phys_dd,
419  rtems_blkdev_bnum block_begin,
420  rtems_blkdev_bnum block_count
421);
422
423#ifdef __cplusplus
424}
425#endif
426
427#endif
Note: See TracBrowser for help on using the repository browser.