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

4.104.11
Last change on this file since d8602eb was d8602eb, checked in by Thomas Doerfler <Thomas.Doerfler@…>, on May 5, 2009 at 12:56:30 PM

Documentation

  • Property mode set to 100644
File size: 5.6 KB
Line 
1/**
2 * @file
3 *
4 * Block device management.
5 */
6 
7/*
8 * Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
9 * Author: Victor V. Vengerov <vvv@oktet.ru>
10 *
11 * @(#) $Id$
12 */
13
14#ifndef _RTEMS_BLKDEV_H
15#define _RTEMS_BLKDEV_H
16
17#include <rtems.h>
18#include <sys/ioctl.h>
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24/**
25 * @defgroup rtems_blkdev Block Device Management
26 *
27 * @ingroup rtems_libblock
28 *
29 * Interface between device drivers and the
30 * @ref rtems_bdbuf "block device buffer module".
31 *
32 * The heart of the block device driver is the @ref RTEMS_BLKIO_REQUEST IO
33 * control. This call puts IO @ref rtems_blkdev_request "requests" to the block
34 * device for asynchronous processing. When a driver executes a request, it
35 * invokes the request done callback function to finish the request.
36 *
37 * @{
38 */
39
40/**
41 * Block device block index type.
42 */
43typedef uint32_t rtems_blkdev_bnum;
44
45/**
46 * Block device request type.
47 */
48typedef enum rtems_blkdev_request_op {
49  RTEMS_BLKDEV_REQ_READ,
50  RTEMS_BLKDEV_REQ_WRITE,
51  RTEMS_BLKDEV_CAPABILITIES
52} rtems_blkdev_request_op;
53
54/**
55 * Only consecutive multi-sector buffer requests are supported.
56 *
57 * This option means the cache will only supply multiple buffers that are
58 * inorder so the ATA multi-sector command for example can be used. This is a
59 * hack to work around the current ATA driver.
60 */
61#define RTEMS_BLKDEV_CAP_MULTISECTOR_CONT (1 << 0)
62
63/**
64 * Type for block device request done callback function.
65 *
66 * @param arg Argument supplied in @ref rtems_blkdev_request.
67 * @param status Status code for this operation.
68 * @param errno The @c errno value to be passed to the user when status is not
69 * equal to @c RTEMS_SUCCESSFUL.
70 */
71typedef void (* rtems_blkdev_request_cb)(void *arg,
72                                         rtems_status_code status,
73                                         int error);
74
75/**
76 * Block device scatter or gather buffer structure.
77 */
78typedef struct rtems_blkdev_sg_buffer {
79  /**
80   * Block index.
81   */
82  rtems_blkdev_bnum block;
83
84  /**
85   * Buffer length.
86   */
87  uint32_t length;
88
89  /**
90   * Buffer pointer.
91   */
92  void *buffer;
93
94  /**
95   * User pointer.
96   */
97  void *user;
98} rtems_blkdev_sg_buffer;
99
100/**
101 * The block device request structure is used to read or write a number of
102 * blocks from or to the device.
103 */
104typedef struct rtems_blkdev_request {
105  /**
106   * Block device operation (read or write).
107   */
108  rtems_blkdev_request_op req;
109
110  /**
111   * Request done callback function.
112   */
113  rtems_blkdev_request_cb req_done;
114
115  /**
116   * Argument to be passed to callback function.
117   */
118  void *done_arg;
119
120  /**
121   * Last IO operation completion status.
122   */
123  rtems_status_code status; 
124
125  /**
126   * If @c status is not equal to @c RTEMS_SUCCESSFUL, this field contains the
127   * error number.
128   */
129  int error;
130
131  /**
132   * Number of blocks for this request.
133   */
134  uint32_t bufnum;
135
136  /**
137   * The task requesting the IO operation.
138   */
139  rtems_id io_task;
140
141  /**
142   * List of scatter or gather buffers.
143   */
144  rtems_blkdev_sg_buffer bufs[0];
145} rtems_blkdev_request;
146
147/**
148 * The start block in a request.
149 *
150 * Only valid if the driver has returned the @ref RTEMS_BLKDEV_CAPABILITIES of
151 * @ref RTEMS_BLKDEV_CAP_MULTISECTOR_CONT.
152 */
153#define RTEMS_BLKDEV_START_BLOCK(req) (req->bufs[0].block)
154
155/**
156 * @name IO Control Request Codes
157 *
158 * @{
159 */
160
161#define RTEMS_BLKIO_REQUEST _IOWR('B', 1, rtems_blkdev_request)
162#define RTEMS_BLKIO_GETBLKSIZE _IO('B', 2)
163#define RTEMS_BLKIO_GETSIZE _IO('B', 3)
164#define RTEMS_BLKIO_SYNCDEV _IO('B', 4)
165
166/** @} */
167
168/**
169 * The device driver interface conventions suppose that a driver may contain an
170 * initialize, open, close, read, write and IO control entry points. These
171 * primitives (except initialize) can be implemented in a generic fashion based
172 * upon the supplied block device driver IO control handler. Every block device
173 * driver should provide an initialize entry point, which registers the
174 * appropriate IO control handler.
175 */
176#define RTEMS_GENERIC_BLOCK_DEVICE_DRIVER_ENTRIES \
177  .open_entry = rtems_blkdev_generic_open, \
178  .close_entry = rtems_blkdev_generic_close, \
179  .read_entry = rtems_blkdev_generic_read, \
180  .write_entry = rtems_blkdev_generic_write, \
181  .control_entry = rtems_blkdev_generic_ioctl
182
183/**
184 * Generic block device read primitive.
185 *
186 * Implemented using block device buffer management primitives.
187 */
188rtems_device_driver
189rtems_blkdev_generic_read(
190    rtems_device_major_number major,
191    rtems_device_minor_number minor,
192    void                    * arg
193);
194
195/**
196 * Generic block device write primitive.
197 *
198 * Implemented using block device buffer management primitives.
199 */
200rtems_device_driver
201rtems_blkdev_generic_write(
202    rtems_device_major_number major,
203    rtems_device_minor_number minor,
204    void                    * arg
205);
206
207/**
208 * Generic block device open primitive.
209 *
210 * Implemented using block device buffer management primitives.
211 */
212rtems_device_driver
213rtems_blkdev_generic_open(
214    rtems_device_major_number major,
215    rtems_device_minor_number minor,
216    void                    * arg
217);
218
219/**
220 * Generic block device close primitive.
221 *
222 * Implemented using block device buffer management primitives.
223 */
224rtems_device_driver
225rtems_blkdev_generic_close(
226    rtems_device_major_number major,
227    rtems_device_minor_number minor,
228    void                    * arg
229);
230
231/**
232 * Generic block device IO control primitive.
233 *
234 * Implemented using block device buffer management primitives.
235 */
236rtems_device_driver
237rtems_blkdev_generic_ioctl(
238    rtems_device_major_number major,
239    rtems_device_minor_number minor,
240    void                    * arg
241);
242
243/** @} */
244
245#ifdef __cplusplus
246}
247#endif
248
249#endif
Note: See TracBrowser for help on using the repository browser.