summaryrefslogtreecommitdiffstats
path: root/doc/user/io.t
blob: 3ed5378555b5bf5704c702908b9d7102eca4d921 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
@c
@c  COPYRIGHT (c) 1988-1998.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@chapter I/O Manager

@section Introduction

The input/output interface manager provides a
well-defined mechanism for accessing device drivers and a
structured methodology for organizing device drivers.  The
directives provided by the I/O manager are:

@itemize @bullet
@item @code{@value{DIRPREFIX}io_initialize} - Initialize a device driver
@item @code{@value{DIRPREFIX}io_register_name} - Register a device name
@item @code{@value{DIRPREFIX}io_lookup_name} - Look up a device name
@item @code{@value{DIRPREFIX}io_open} - Open a device
@item @code{@value{DIRPREFIX}io_close} - Close a device
@item @code{@value{DIRPREFIX}io_read} - Read from a device
@item @code{@value{DIRPREFIX}io_write} - Write to a device
@item @code{@value{DIRPREFIX}io_control} - Special device services
@end itemize

@section Background

@subsection Device Driver Table

Each application utilizing the RTEMS I/O manager must
specify the address of a Device Driver Table in its
Configuration Table.  This table contains each device driver's
entry points.  Each device driver may contain the following
entry points:

@itemize @bullet
@item Initialization
@item Open
@item Close
@item Read
@item Write
@item Control
@end itemize

If the device driver does not support a particular
entry point, then that entry in the Configuration Table should
be NULL.  RTEMS will return
@code{@value{RPREFIX}SUCCESSFUL} as the executive's and
zero (0) as the device driver's return code for these device
driver entry points.

@subsection Major and Minor Device Numbers

Each call to the I/O manager must provide a device's
major and minor numbers as arguments.  The major number is the
index of the requested driver's entry points in the Device
Driver Table, and is used to select a specific device driver.
The exact usage of the minor number is driver specific, but is
commonly used to distinguish between a number of devices
controlled by the same driver.

@subsection Device Names

The I/O Manager provides facilities to associate a
name with a particular device.  Directives are provided to
register the name of a device and to look up the major/minor
number pair associated with a device name.

@subsection Device Driver Environment

Application developers, as well as device driver
developers, must be aware of the following regarding the RTEMS
I/O Manager:

@itemize @bullet
@item A device driver routine executes in the context of the
invoking task.  Thus if the driver blocks, the invoking task
blocks.

@item The device driver is free to change the modes of the
invoking task, although the driver should restore them to their
original values.

@item Device drivers may be invoked from ISRs.

@item Only local device drivers are accessible through the I/O
manager.

@item A device driver routine may invoke all other RTEMS
directives, including I/O directives, on both local and global
objects.

@end itemize

Although the RTEMS I/O manager provides a framework
for device drivers, it makes no assumptions regarding the
construction or operation of a device driver.

@subsection Device Driver Interface

When an application invokes an I/O manager directive,
RTEMS determines which device driver entry point must be
invoked.  The information passed by the application to RTEMS is
then passed to the correct device driver entry point.  RTEMS
will invoke each device driver entry point assuming it is
compatible with the following prototype:

@ifset is-C
@example
rtems_device_driver io_entry(
  rtems_device_major_number  major,
  rtems_device_minor_number  minor,
  void                      *argument_block
);
@end example
@end ifset

@ifset is-Ada
@example
function IO_Entry (
  Major          : in     RTEMS.Device_Major_Number;
  Minor          : in     RTEMS.Device_Major_Number;
  Argument_Block : in     RTEMS.Address
) return RTEMS.Status_Code;
@end example
@end ifset

The format and contents of the parameter block are
device driver and entry point dependent.

It is recommended that a device driver avoid
generating error codes which conflict with those used by
application components.  A common technique used to generate
driver specific error codes is to make the most significant part
of the status indicate a driver specific code.

@subsection Device Driver Initialization

RTEMS automatically initializes all device drivers
when multitasking is initiated via the initialize_executive
directive.  RTEMS initializes the device drivers by invoking
each device driver initialization entry point with the following
parameters:

@table @asis
@item major
the major device number for this device driver.

@item minor
zero.

@item argument_block
will point to  the Configuration Table.

@end table

The returned status will be ignored by RTEMS.  If the driver
cannot successfully initialize the device, then it should invoke
the fatal_error_occurred directive.

@section Operations

@subsection Register and Lookup Name

The @code{@value{DIRPREFIX}io_register} directive associates a name with the
specified device (i.e. major/minor number pair).  Device names
are typically registered as part of the device driver
initialization sequence.  The @code{@value{DIRPREFIX}io_lookup}
directive is used to
determine the major/minor number pair associated with the
specified device name.  The use of these directives frees the
application from being dependent on the arbitrary assignment of
major numbers in a particular application.  No device naming
conventions are dictated by RTEMS.

@subsection Accessing an Device Driver

The I/O manager provides directives which enable the
application program to utilize device drivers in a standard
manner.  There is a direct correlation between the RTEMS I/O
manager directives
@code{@value{DIRPREFIX}io_initialize},
@code{@value{DIRPREFIX}io_open},
@code{@value{DIRPREFIX}io_close},
@code{@value{DIRPREFIX}io_read},
@code{@value{DIRPREFIX}io_write}, and
@code{@value{DIRPREFIX}io_control}
and the underlying device driver entry points.

@section Directives

This section details the I/O manager's directives.  A
subsection is dedicated to each of this manager's directives and
describes the calling sequence, related constants, usage, and
status codes.

@page
@subsection IO_INITIALIZE - Initialize a device driver

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_io_initialize(
  rtems_device_major_number  major,
  rtems_device_minor_number  minor,
  void                      *argument
);
@end example
@end ifset

@ifset is-Ada
@example
procedure IO_Initialize (
   Major        : in     RTEMS.Device_Major_Number;
   Minor        : in     RTEMS.Device_Minor_Number;
   Argument     : in     RTEMS.Address;
   Return_Value :    out RTEMS.Unsigned32;
   Result       :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number

@subheading DESCRIPTION:

This directive calls the device driver initialization
routine specified in the Device Driver Table for this major
number. This directive is automatically invoked for each device
driver when multitasking is initiated via the
initialize_executive directive.

A device driver initialization module is responsible
for initializing all hardware and data structures associated
with a device. If necessary, it can allocate memory to be used
during other operations.

@subheading NOTES:

This directive may or may not cause the calling task
to be preempted.  This is dependent on the device driver being
initialized.

@page
@subsection IO_REGISTER_NAME - Register a device

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_io_register_name(
  char                      *name,
  rtems_device_major_number  major,
  rtems_device_minor_number  minor
);
@end example
@end ifset

@ifset is-Ada
@example
procedure IO_Register_Name (
   Name   : in     String;
   Major  : in     RTEMS.Device_Major_Number;
   Minor  : in     RTEMS.Device_Minor_Number;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
@code{@value{RPREFIX}TOO_MANY} - too many devices registered

@subheading DESCRIPTION:

This directive associates name with the specified
major/minor number pair.

@subheading NOTES:

This directive will not cause the calling task to be
preempted.

@page
@subsection IO_LOOKUP_NAME - Lookup a device

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_io_lookup_name(
  const char                *name,
  rtems_driver_name_t      **device_info
);
@end example
@end ifset

@ifset is-Ada
@example
procedure IO_Lookup_Name (
   Name         : in     String;
   Device_Info  :    out RTEMS.Driver_Name_t;
   Result       :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
@code{@value{RPREFIX}UNSATISFIED} - name not registered

@subheading DESCRIPTION:

This directive returns the major/minor number pair
associated with the given device name in device_info.

@subheading NOTES:

This directive will not cause the calling task to be
preempted.

@page
@subsection IO_OPEN - Open a device

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_io_open(
  rtems_device_major_number  major,
  rtems_device_minor_number  minor,
  void                      *argument
);
@end example
@end ifset

@ifset is-Ada
@example
procedure IO_Open (
   Major        : in     RTEMS.Device_Major_Number;
   Minor        : in     RTEMS.Device_Minor_Number;
   Argument     : in     RTEMS.Address;
   Return_Value :    out RTEMS.Unsigned32;
   Result       :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number

@subheading DESCRIPTION:

This directive calls the device driver open routine
specified in the Device Driver Table for this major number.  The
open entry point is commonly used by device drivers to provide
exclusive access to a device.

@subheading NOTES:

This directive may or may not cause the calling task
to be preempted.  This is dependent on the device driver being
invoked.

@page
@subsection IO_CLOSE - Close a device

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_io_close(
  rtems_device_major_number  major,
  rtems_device_minor_number  minor,
  void                      *argument
);
@end example
@end ifset

@ifset is-Ada
@example
procedure IO_Close (
   Major        : in     RTEMS.Device_Major_Number;
   Minor        : in     RTEMS.Device_Minor_Number;
   Argument     : in     RTEMS.Address;
   Return_Value :    out RTEMS.Unsigned32;
   Result       :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number

@subheading DESCRIPTION:

This directive calls the device driver close routine
specified in the Device Driver Table for this major number.  The
close entry point is commonly used by device drivers to
relinquish exclusive access to a device.

@subheading NOTES:

This directive may or may not cause the calling task
to be preempted.  This is dependent on the device driver being
invoked.

@page
@subsection IO_READ - Read from a device

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_io_read(
  rtems_device_major_number  major,
  rtems_device_minor_number  minor,
  void                      *argument
);
@end example
@end ifset

@ifset is-Ada
@example
procedure IO_Read (
   Major        : in     RTEMS.Device_Major_Number;
   Minor        : in     RTEMS.Device_Minor_Number;
   Argument     : in     RTEMS.Address;
   Return_Value :    out RTEMS.Unsigned32;
   Result       :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number

@subheading DESCRIPTION:

This directive calls the device driver read routine
specified in the Device Driver Table for this major number.
Read operations typically require a buffer address as part of
the argument parameter block.  The contents of this buffer will
be replaced with data from the device.

@subheading NOTES:

This directive may or may not cause the calling task
to be preempted.  This is dependent on the device driver being
invoked.

@page
@subsection IO_WRITE - Write to a device

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_io_write(
  rtems_device_major_number  major,
  rtems_device_minor_number  minor,
  void                      *argument
);
@end example
@end ifset

@ifset is-Ada
@example
procedure IO_Write (
   Major        : in     RTEMS.Device_Major_Number;
   Minor        : in     RTEMS.Device_Minor_Number;
   Argument     : in     RTEMS.Address;
   Return_Value :    out RTEMS.Unsigned32;
   Result       :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number

@subheading DESCRIPTION:

This directive calls the device driver write routine
specified in the Device Driver Table for this major number.
Write operations typically require a buffer address as part of
the argument parameter block.  The contents of this buffer will
be sent to the device.

@subheading NOTES:

This directive may or may not cause the calling task
to be preempted.  This is dependent on the device driver being
invoked.

@page
@subsection IO_CONTROL - Special device services

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_io_control(
  rtems_device_major_number  major,
  rtems_device_minor_number  minor,
  void                      *argument
);
@end example
@end ifset

@ifset is-Ada
@example
procedure IO_Control (
   Major        : in     RTEMS.Device_Major_Number;
   Minor        : in     RTEMS.Device_Minor_Number;
   Argument     : in     RTEMS.Address;
   Return_Value :    out RTEMS.Unsigned32;
   Result       :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number

@subheading DESCRIPTION:

This directive calls the device driver I/O control
routine specified in the Device Driver Table for this major
number.  The exact functionality of the driver entry called by
this directive is driver dependent.  It should not be assumed
that the control entries of two device drivers are compatible.
For example, an RS-232 driver I/O control operation may change
the baud rate of a serial line, while an I/O control operation
for a floppy disk driver may cause a seek operation.

@subheading NOTES:

This directive may or may not cause the calling task
to be preempted.  This is dependent on the device driver being
invoked.