source: rtems/cpukit/libblock/include/rtems/blkdev.h @ 47c2327

4.104.11
Last change on this file since 47c2327 was 47c2327, checked in by Thomas Doerfler <Thomas.Doerfler@…>, on Nov 30, 2009 at 12:39:51 PM

documentation fixes
Avoid designated initializers for C++ compatibility
Fixed invalid state transition from FRESH to CACHED
Free memory in case of an error.

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