source: rtems/cpukit/libblock/include/rtems/blkdev.h @ 4670d91

4.104.11
Last change on this file since 4670d91 was 4670d91, checked in by Joel Sherrill <joel.sherrill@…>, on May 15, 2009 at 12:52:12 PM

2009-05-15 Sebastian Huber <sebastian.huber@…>

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