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

4.11
Last change on this file since 1680638 was 1680638, checked in by Sebastian Huber <sebastian.huber@…>, on Jan 21, 2011 at 9:43:24 AM

2011-01-21 Sebastian Huber <sebastian.huber@…>

  • libblock/src/blkdev-ops.c: New file.
  • libblock/Makefile.am: Reflect change from above.
  • libblock/include/rtems/blkdev.h: Declare rtems_blkdev_generic_ops.
  • Property mode set to 100644
File size: 6.9 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 * @(#) $Id$
14 */
15
16#ifndef _RTEMS_BLKDEV_H
17#define _RTEMS_BLKDEV_H
18
19#include <rtems.h>
20#include <rtems/diskdevs.h>
21#include <sys/ioctl.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 * 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
56/**
57 * @brief Block device request done callback function type.
58 *
59 * The first parameter @a arg must be the argument provided by the block device
60 * request structure @ref rtems_blkdev_request.
61 *
62 * The second parameter @a status should contain the status of the operation:
63 *  - @c RTEMS_SUCCESSFUL Operation was successful.
64 *  - @c RTEMS_IO_ERROR Some sort of input or output error.
65 *  - @c RTEMS_UNSATISFIED Media no more present.
66 */
67typedef void (*rtems_blkdev_request_cb)(void *arg, rtems_status_code status);
68
69/**
70 * Block device scatter or gather buffer structure.
71 */
72typedef struct rtems_blkdev_sg_buffer {
73  /**
74   * Block index.
75   */
76  rtems_blkdev_bnum block;
77
78  /**
79   * Buffer length.
80   */
81  uint32_t length;
82
83  /**
84   * Buffer pointer.
85   */
86  void *buffer;
87
88  /**
89   * User pointer.
90   */
91  void *user;
92} rtems_blkdev_sg_buffer;
93
94/**
95 * The block device request structure is used to read or write a number of
96 * blocks from or to the device.
97 *
98 * TODO: The use of these req blocks is not a great design. The req is a
99 *       struct with a single 'bufs' declared in the req struct and the
100 *       others are added in the outer level struct. This relies on the
101 *       structs joining as a single array and that assumes the compiler
102 *       packs the structs. Why not just place on a list ? The BD has a
103 *       node that can be used.
104 */
105typedef struct rtems_blkdev_request {
106  /**
107   * Block device operation (read or write).
108   */
109  rtems_blkdev_request_op req;
110
111  /**
112   * Request done callback function.
113   */
114  rtems_blkdev_request_cb req_done;
115
116  /**
117   * Argument to be passed to callback function.
118   */
119  void *done_arg;
120
121  /**
122   * Last IO operation completion status.
123   */
124  rtems_status_code status;
125
126  /**
127   * Number of blocks for this request.
128   */
129  uint32_t bufnum;
130
131  /**
132   * The task requesting the IO operation.
133   */
134  rtems_id io_task;
135
136  /**
137   * List of scatter or gather buffers.
138   */
139  rtems_blkdev_sg_buffer bufs[0];
140} rtems_blkdev_request;
141
142/**
143 * The start block in a request.
144 *
145 * Only valid if the driver has returned the @ref RTEMS_BLKIO_CAPABILITIES of
146 * @ref RTEMS_BLKDEV_CAP_MULTISECTOR_CONT.
147 */
148#define RTEMS_BLKDEV_START_BLOCK(req) (req->bufs[0].block)
149
150/**
151 * @name IO Control Request Codes
152 *
153 * @{
154 */
155
156#define RTEMS_BLKIO_REQUEST         _IOWR('B', 1, rtems_blkdev_request)
157#define RTEMS_BLKIO_GETMEDIABLKSIZE _IOR('B', 2, uint32_t)
158#define RTEMS_BLKIO_GETBLKSIZE      _IOR('B', 3, uint32_t)
159#define RTEMS_BLKIO_SETBLKSIZE      _IOW('B', 4, uint32_t)
160#define RTEMS_BLKIO_GETSIZE         _IOR('B', 5, rtems_blkdev_bnum)
161#define RTEMS_BLKIO_SYNCDEV         _IO('B', 6)
162#define RTEMS_BLKIO_DELETED         _IO('B', 7)
163#define RTEMS_BLKIO_CAPABILITIES    _IO('B', 8)
164
165/** @} */
166
167/**
168 * Only consecutive multi-sector buffer requests are supported.
169 *
170 * This option means the cache will only supply multiple buffers that are
171 * inorder so the ATA multi-sector command for example can be used. This is a
172 * hack to work around the current ATA driver.
173 */
174#define RTEMS_BLKDEV_CAP_MULTISECTOR_CONT (1 << 0)
175
176/**
177 * The driver will accept a sync call. A sync call is made to a driver
178 * after a bdbuf cache sync has finished.
179 */
180#define RTEMS_BLKDEV_CAP_SYNC (1 << 1)
181
182/**
183 * The device driver interface conventions suppose that a driver may contain an
184 * initialize, open, close, read, write and IO control entry points. These
185 * primitives (except initialize) can be implemented in a generic fashion based
186 * upon the supplied block device driver IO control handler. Every block device
187 * driver should provide an initialize entry point, which registers the
188 * appropriate IO control handler.
189 */
190#define RTEMS_GENERIC_BLOCK_DEVICE_DRIVER_ENTRIES \
191  rtems_blkdev_generic_open, \
192  rtems_blkdev_generic_close, \
193  rtems_blkdev_generic_read, \
194  rtems_blkdev_generic_write, \
195  rtems_blkdev_generic_ioctl
196
197/**
198 * Generic block device read primitive.
199 *
200 * Implemented using block device buffer management primitives.
201 */
202rtems_device_driver
203rtems_blkdev_generic_read(
204    rtems_device_major_number major,
205    rtems_device_minor_number minor,
206    void                    * arg
207);
208
209/**
210 * Generic block device write primitive.
211 *
212 * Implemented using block device buffer management primitives.
213 */
214rtems_device_driver
215rtems_blkdev_generic_write(
216    rtems_device_major_number major,
217    rtems_device_minor_number minor,
218    void                    * arg
219);
220
221/**
222 * Generic block device open primitive.
223 *
224 * Implemented using block device buffer management primitives.
225 */
226rtems_device_driver
227rtems_blkdev_generic_open(
228    rtems_device_major_number major,
229    rtems_device_minor_number minor,
230    void                    * arg
231);
232
233/**
234 * Generic block device close primitive.
235 *
236 * Implemented using block device buffer management primitives.
237 */
238rtems_device_driver
239rtems_blkdev_generic_close(
240    rtems_device_major_number major,
241    rtems_device_minor_number minor,
242    void                    * arg
243);
244
245/**
246 * Generic block device IO control primitive.
247 *
248 * Implemented using block device buffer management primitives.
249 */
250rtems_device_driver
251rtems_blkdev_generic_ioctl(
252    rtems_device_major_number major,
253    rtems_device_minor_number minor,
254    void                    * arg
255);
256
257/**
258 * Common IO control primitive.
259 *
260 * Use this in all block devices to handle the common set of ioctl requests.
261 */
262int
263rtems_blkdev_ioctl(rtems_disk_device *dd, uint32_t req, void *argp);
264
265/**
266 * @brief Generic block operations driver address table.
267 */
268extern const rtems_driver_address_table rtems_blkdev_generic_ops;
269
270/** @} */
271
272#ifdef __cplusplus
273}
274#endif
275
276#endif
Note: See TracBrowser for help on using the repository browser.