source: rtems/cpukit/libblock/include/rtems/blkdev.h @ eb93595

4.11
Last change on this file since eb93595 was eb93595, checked in by Sebastian Huber <sebastian.huber@…>, on Oct 31, 2012 at 12:56:15 PM

libblock: Documentation

  • Property mode set to 100644
File size: 11.8 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup rtems_blkdev
5 *
6 * Block device management.
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_BLKDEV_H
15#define _RTEMS_BLKDEV_H
16
17#include <rtems.h>
18#include <rtems/diskdevs.h>
19#include <rtems/bspIo.h>
20#include <sys/ioctl.h>
21#include <stdio.h>
22
23#ifdef __cplusplus
24extern "C" {
25#endif
26
27/**
28 * @defgroup rtems_blkdev Block Device Management
29 *
30 * @ingroup rtems_libblock
31 *
32 * Interface between device drivers and the
33 * @ref rtems_bdbuf "block device buffer module".
34 *
35 * The heart of the block device driver is the @ref RTEMS_BLKIO_REQUEST IO
36 * control. This call puts IO @ref rtems_blkdev_request "requests" to the block
37 * device for asynchronous processing. When a driver executes a request, it
38 * invokes the request done callback function to finish the request.
39 *
40 * @{
41 */
42
43/**
44 * @brief Block device request type.
45 *
46 * @warning The sync request is an IO one and only used from the cache. Use the
47 *          Block IO when operating at the device level. We need a sync request
48 *          to avoid requests looping for ever.
49 */
50typedef enum rtems_blkdev_request_op {
51  RTEMS_BLKDEV_REQ_READ,       /**< Read the requested blocks of data. */
52  RTEMS_BLKDEV_REQ_WRITE,      /**< Write the requested blocks of data. */
53  RTEMS_BLKDEV_REQ_SYNC        /**< Sync any data with the media. */
54} rtems_blkdev_request_op;
55
56struct rtems_blkdev_request;
57
58/**
59 * @brief Block device request done callback function type.
60 */
61typedef void (*rtems_blkdev_request_cb)(
62  struct rtems_blkdev_request *req,
63  rtems_status_code status
64);
65
66/**
67 * @brief Block device scatter or gather buffer structure.
68 */
69typedef struct rtems_blkdev_sg_buffer {
70  /**
71   * Block index.
72   */
73  rtems_blkdev_bnum block;
74
75  /**
76   * Buffer length.
77   */
78  uint32_t length;
79
80  /**
81   * Buffer pointer.
82   */
83  void *buffer;
84
85  /**
86   * User pointer.
87   */
88  void *user;
89} rtems_blkdev_sg_buffer;
90
91/**
92 * @brief The block device transfer request is used to read or write a number
93 * of blocks from or to the device.
94 *
95 * Transfer requests are issued to the disk device driver with the
96 * @ref RTEMS_BLKIO_REQUEST IO control.  The transfer request completion status
97 * must be signalled with rtems_blkdev_request_done().  This function must be
98 * called exactly once per request.  The return value of the IO control will be
99 * ignored for transfer requests.
100 *
101 * @see rtems_blkdev_create().
102 */
103typedef struct rtems_blkdev_request {
104  /**
105   * Block device operation (read or write).
106   */
107  rtems_blkdev_request_op req;
108
109  /**
110   * Request done callback function.
111   */
112  rtems_blkdev_request_cb done;
113
114  /**
115   * Argument to be passed to callback function.
116   */
117  void *done_arg;
118
119  /**
120   * Last IO operation completion status.
121   */
122  rtems_status_code status;
123
124  /**
125   * Number of blocks for this request.
126   */
127  uint32_t bufnum;
128
129  /**
130   * The task requesting the IO operation.
131   */
132  rtems_id io_task;
133
134  /*
135   * TODO: The use of these req blocks is not a great design. The req is a
136   *       struct with a single 'bufs' declared in the req struct and the
137   *       others are added in the outer level struct. This relies on the
138   *       structs joining as a single array and that assumes the compiler
139   *       packs the structs. Why not just place on a list ? The BD has a
140   *       node that can be used.
141   */
142
143  /**
144   * List of scatter or gather buffers.
145   */
146  rtems_blkdev_sg_buffer bufs[0];
147} rtems_blkdev_request;
148
149/**
150 * @brief Signals transfer request completion status.
151 *
152 * This function must be called exactly once per request.
153 *
154 * @param[in,out] req The transfer request.
155 * @param[in] status The status of the operation should be
156 *  - @c RTEMS_SUCCESSFUL, if the operation was successful,
157 *  - @c RTEMS_IO_ERROR, if some sort of input or output error occured, or
158 *  - @c RTEMS_UNSATISFIED, if media is no more present.
159 */
160static inline void rtems_blkdev_request_done(
161  rtems_blkdev_request *req,
162  rtems_status_code status
163)
164{
165  (*req->done)(req, status);
166}
167
168/**
169 * @brief The start block in a request.
170 *
171 * Only valid if the driver has returned the
172 * @ref RTEMS_BLKDEV_CAP_MULTISECTOR_CONT capability.
173 */
174#define RTEMS_BLKDEV_START_BLOCK(req) (req->bufs[0].block)
175
176/**
177 * @name IO Control Request Codes
178 *
179 * @{
180 */
181
182#define RTEMS_BLKIO_REQUEST         _IOWR('B', 1, rtems_blkdev_request)
183#define RTEMS_BLKIO_GETMEDIABLKSIZE _IOR('B', 2, uint32_t)
184#define RTEMS_BLKIO_GETBLKSIZE      _IOR('B', 3, uint32_t)
185#define RTEMS_BLKIO_SETBLKSIZE      _IOW('B', 4, uint32_t)
186#define RTEMS_BLKIO_GETSIZE         _IOR('B', 5, rtems_blkdev_bnum)
187#define RTEMS_BLKIO_SYNCDEV         _IO('B', 6)
188#define RTEMS_BLKIO_DELETED         _IO('B', 7)
189#define RTEMS_BLKIO_CAPABILITIES    _IO('B', 8)
190#define RTEMS_BLKIO_GETDISKDEV      _IOR('B', 9, rtems_disk_device *)
191#define RTEMS_BLKIO_PURGEDEV        _IO('B', 10)
192#define RTEMS_BLKIO_GETDEVSTATS     _IOR('B', 11, rtems_blkdev_stats *)
193#define RTEMS_BLKIO_RESETDEVSTATS   _IO('B', 12)
194
195/** @} */
196
197static inline int rtems_disk_fd_get_media_block_size(
198  int fd,
199  uint32_t *media_block_size
200)
201{
202  return ioctl(fd, RTEMS_BLKIO_GETMEDIABLKSIZE, media_block_size);
203}
204
205static inline int rtems_disk_fd_get_block_size(int fd, uint32_t *block_size)
206{
207  return ioctl(fd, RTEMS_BLKIO_GETBLKSIZE, block_size);
208}
209
210static inline int rtems_disk_fd_set_block_size(int fd, uint32_t block_size)
211{
212  return ioctl(fd, RTEMS_BLKIO_SETBLKSIZE, &block_size);
213}
214
215static inline int rtems_disk_fd_get_block_count(
216  int fd,
217  rtems_blkdev_bnum *block_count
218)
219{
220  return ioctl(fd, RTEMS_BLKIO_GETSIZE, block_count);
221}
222
223static inline int rtems_disk_fd_get_disk_device(
224  int fd,
225  rtems_disk_device **dd_ptr
226)
227{
228  return ioctl(fd, RTEMS_BLKIO_GETDISKDEV, dd_ptr);
229}
230
231static inline int rtems_disk_fd_sync(int fd)
232{
233  return ioctl(fd, RTEMS_BLKIO_SYNCDEV);
234}
235
236static inline int rtems_disk_fd_purge(int fd)
237{
238  return ioctl(fd, RTEMS_BLKIO_PURGEDEV);
239}
240
241static inline int rtems_disk_fd_get_device_stats(
242  int fd,
243  rtems_blkdev_stats *stats
244)
245{
246  return ioctl(fd, RTEMS_BLKIO_GETDEVSTATS, stats);
247}
248
249static inline int rtems_disk_fd_reset_device_stats(int fd)
250{
251  return ioctl(fd, RTEMS_BLKIO_RESETDEVSTATS);
252}
253
254/**
255 * @name Block Device Driver Capabilities
256 *
257 * @{
258 */
259
260/**
261 * @brief Only consecutive multi-sector buffer requests are supported.
262 *
263 * This option means the cache will only supply multiple buffers that are
264 * inorder so the ATA multi-sector command for example can be used. This is a
265 * hack to work around the current ATA driver.
266 */
267#define RTEMS_BLKDEV_CAP_MULTISECTOR_CONT (1 << 0)
268
269/**
270 * @brief The driver will accept a sync call.
271 *
272 * A sync call is made to a driver after a bdbuf cache sync has finished.
273 */
274#define RTEMS_BLKDEV_CAP_SYNC (1 << 1)
275
276/** @} */
277
278/**
279 * @brief Common IO control primitive.
280 *
281 * Use this in all block devices to handle the common set of IO control
282 * requests.
283 */
284int
285rtems_blkdev_ioctl(rtems_disk_device *dd, uint32_t req, void *argp);
286
287/**
288 * @brief Creates a block device.
289 *
290 * The block size is set to the media block size.
291 *
292 * @param[in] device The path for the new block device.
293 * @param[in] media_block_size The media block size in bytes.  Must be positive.
294 * @param[in] media_block_count The media block count.  Must be positive.
295 * @param[in] handler The block device IO control handler.  Must not be @c NULL.
296 * @param[in] driver_data The block device driver data.
297 *
298 * @retval RTEMS_SUCCESSFUL Successful operation.
299 * @retval RTEMS_INVALID_NUMBER Media block size or count is not positive.
300 * @retval RTEMS_NO_MEMORY Not enough memory.
301 * @retval RTEMS_UNSATISFIED Cannot create generic device node.
302 *
303 * @see rtems_blkdev_create_partition(), rtems_bdbuf_set_block_size(), and
304 * rtems_blkdev_request.
305 */
306rtems_status_code rtems_blkdev_create(
307  const char *device,
308  uint32_t media_block_size,
309  rtems_blkdev_bnum media_block_count,
310  rtems_block_device_ioctl handler,
311  void *driver_data
312);
313
314/**
315 * @brief Creates a partition within a parent block device.
316 *
317 * A partition manages a subset of consecutive blocks contained in a parent block
318 * device.  The blocks must be within the range of blocks managed by the
319 * associated parent block device.  The media block size and IO control
320 * handler are inherited by the parent block device.  The block size is set to
321 * the media block size.
322 *
323 * @param[in] partition The path for the new partition device.
324 * @param[in] parent_block_device The parent block device path.
325 * @param[in] media_block_begin The media block begin of the partition within
326 * the parent block device.
327 * @param[in] media_block_count The media block count of the partition.
328 *
329 * @retval RTEMS_SUCCESSFUL Successful operation.
330 * @retval RTEMS_INVALID_ID Block device node does not exist.
331 * @retval RTEMS_INVALID_NODE File system node is not a block device.
332 * @retval RTEMS_NOT_IMPLEMENTED Block device implementation is incomplete.
333 * @retval RTEMS_INVALID_NUMBER Block begin or block count is invalid.
334 * @retval RTEMS_NO_MEMORY Not enough memory.
335 * @retval RTEMS_UNSATISFIED Cannot create generic device node.
336 *
337 * @see rtems_blkdev_create() and rtems_bdbuf_set_block_size().
338 */
339rtems_status_code rtems_blkdev_create_partition(
340  const char *partition,
341  const char *parent_block_device,
342  rtems_blkdev_bnum media_block_begin,
343  rtems_blkdev_bnum media_block_count
344);
345
346/**
347 * @brief Prints the block device statistics.
348 */
349void rtems_blkdev_print_stats(
350  const rtems_blkdev_stats *stats,
351  rtems_printk_plugin_t print,
352  void *print_arg
353);
354
355/**
356 * @brief Block device statistics command.
357 */
358void rtems_blkstats(
359  FILE *output,
360  const char *device,
361  bool reset
362);
363
364/** @} */
365
366/**
367 * @defgroup rtems_blkdev_generic Generic Disk Device
368 *
369 * @ingroup rtems_blkdev
370 *
371 * Generic disk device operations for standard RTEMS IO drivers.
372 *
373 * @{
374 */
375
376/**
377 * The device driver interface conventions suppose that a driver may contain an
378 * initialize, open, close, read, write and IO control entry points. These
379 * primitives (except initialize) can be implemented in a generic fashion based
380 * upon the supplied block device driver IO control handler. Every block device
381 * driver should provide an initialize entry point, which registers the
382 * appropriate IO control handler.
383 */
384#define RTEMS_GENERIC_BLOCK_DEVICE_DRIVER_ENTRIES \
385  rtems_blkdev_generic_open, \
386  rtems_blkdev_generic_close, \
387  rtems_blkdev_generic_read, \
388  rtems_blkdev_generic_write, \
389  rtems_blkdev_generic_ioctl
390
391/**
392 * Generic block device read primitive.
393 *
394 * Implemented using block device buffer management primitives.
395 */
396rtems_device_driver
397rtems_blkdev_generic_read(
398    rtems_device_major_number major,
399    rtems_device_minor_number minor,
400    void                    * arg
401);
402
403/**
404 * Generic block device write primitive.
405 *
406 * Implemented using block device buffer management primitives.
407 */
408rtems_device_driver
409rtems_blkdev_generic_write(
410    rtems_device_major_number major,
411    rtems_device_minor_number minor,
412    void                    * arg
413);
414
415/**
416 * Generic block device open primitive.
417 *
418 * Implemented using block device buffer management primitives.
419 */
420rtems_device_driver
421rtems_blkdev_generic_open(
422    rtems_device_major_number major,
423    rtems_device_minor_number minor,
424    void                    * arg
425);
426
427/**
428 * Generic block device close primitive.
429 *
430 * Implemented using block device buffer management primitives.
431 */
432rtems_device_driver
433rtems_blkdev_generic_close(
434    rtems_device_major_number major,
435    rtems_device_minor_number minor,
436    void                    * arg
437);
438
439/**
440 * Generic block device IO control primitive.
441 *
442 * Implemented using block device buffer management primitives.
443 */
444rtems_device_driver
445rtems_blkdev_generic_ioctl(
446    rtems_device_major_number major,
447    rtems_device_minor_number minor,
448    void                    * arg
449);
450
451/**
452 * @brief Generic block operations driver address table.
453 */
454extern const rtems_driver_address_table rtems_blkdev_generic_ops;
455
456/** @} */
457
458#ifdef __cplusplus
459}
460#endif
461
462#endif
Note: See TracBrowser for help on using the repository browser.