source: rtems/doc/user/io.t @ 6449498

4.104.114.84.95
Last change on this file since 6449498 was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on 01/17/02 at 21:47:47

2001-01-17 Joel Sherrill <joel@…>

  • SUPPORT, LICENSE: New files.
  • Numerous files touched as part of merging the 4.5 branch onto the mainline development trunk and ensuring that the script that cuts snapshots and releases works on the documentation.
  • Property mode set to 100644
File size: 16.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter I/O Manager
10
11@cindex device drivers
12@cindex IO Manager
13
14@section Introduction
15
16The input/output interface manager provides a
17well-defined mechanism for accessing device drivers and a
18structured methodology for organizing device drivers.  The
19directives provided by the I/O manager are:
20
21@itemize @bullet
22@item @code{@value{DIRPREFIX}io_initialize} - Initialize a device driver
23@item @code{@value{DIRPREFIX}io_register_name} - Register a device name
24@item @code{@value{DIRPREFIX}io_lookup_name} - Look up a device name
25@item @code{@value{DIRPREFIX}io_open} - Open a device
26@item @code{@value{DIRPREFIX}io_close} - Close a device
27@item @code{@value{DIRPREFIX}io_read} - Read from a device
28@item @code{@value{DIRPREFIX}io_write} - Write to a device
29@item @code{@value{DIRPREFIX}io_control} - Special device services
30@end itemize
31
32@section Background
33
34@subsection Device Driver Table
35
36@cindex Device Driver Table
37
38Each application utilizing the RTEMS I/O manager must
39specify the address of a Device Driver Table in its
40Configuration Table.  This table contains each device driver's
41entry points.  Each device driver may contain the following
42entry points:
43
44@itemize @bullet
45@item Initialization
46@item Open
47@item Close
48@item Read
49@item Write
50@item Control
51@end itemize
52
53If the device driver does not support a particular
54entry point, then that entry in the Configuration Table should
55be NULL.  RTEMS will return
56@code{@value{RPREFIX}SUCCESSFUL} as the executive's and
57zero (0) as the device driver's return code for these device
58driver entry points.
59
60@subsection Major and Minor Device Numbers
61
62@cindex major device number
63@cindex minor device number
64
65Each call to the I/O manager must provide a device's
66major and minor numbers as arguments.  The major number is the
67index of the requested driver's entry points in the Device
68Driver Table, and is used to select a specific device driver.
69The exact usage of the minor number is driver specific, but is
70commonly used to distinguish between a number of devices
71controlled by the same driver.
72
73@findex rtems_device_major_number
74@findex rtems_device_minor_number
75
76The data types @code{@value{DIRPREFIX}device_major_number} and
77@code{@value{DIRPREFIX}device_minor_number} are used to
78manipulate device major and minor numbers, respectively.
79
80@subsection Device Names
81
82@cindex device names
83
84The I/O Manager provides facilities to associate a
85name with a particular device.  Directives are provided to
86register the name of a device and to look up the major/minor
87number pair associated with a device name.
88
89@subsection Device Driver Environment
90
91Application developers, as well as device driver
92developers, must be aware of the following regarding the RTEMS
93I/O Manager:
94
95@itemize @bullet
96@item A device driver routine executes in the context of the
97invoking task.  Thus if the driver blocks, the invoking task
98blocks.
99
100@item The device driver is free to change the modes of the
101invoking task, although the driver should restore them to their
102original values.
103
104@item Device drivers may be invoked from ISRs.
105
106@item Only local device drivers are accessible through the I/O
107manager.
108
109@item A device driver routine may invoke all other RTEMS
110directives, including I/O directives, on both local and global
111objects.
112
113@end itemize
114
115Although the RTEMS I/O manager provides a framework
116for device drivers, it makes no assumptions regarding the
117construction or operation of a device driver.
118
119@subsection Device Driver Interface
120
121@cindex device driver interface
122
123When an application invokes an I/O manager directive,
124RTEMS determines which device driver entry point must be
125invoked.  The information passed by the application to RTEMS is
126then passed to the correct device driver entry point.  RTEMS
127will invoke each device driver entry point assuming it is
128compatible with the following prototype:
129
130@ifset is-C
131@example
132rtems_device_driver io_entry(
133  rtems_device_major_number  major,
134  rtems_device_minor_number  minor,
135  void                      *argument_block
136);
137@end example
138@end ifset
139
140@ifset is-Ada
141@example
142function IO_Entry (
143  Major          : in     RTEMS.Device_Major_Number;
144  Minor          : in     RTEMS.Device_Major_Number;
145  Argument_Block : in     RTEMS.Address
146) return RTEMS.Status_Code;
147@end example
148@end ifset
149
150The format and contents of the parameter block are
151device driver and entry point dependent.
152
153It is recommended that a device driver avoid
154generating error codes which conflict with those used by
155application components.  A common technique used to generate
156driver specific error codes is to make the most significant part
157of the status indicate a driver specific code.
158
159@subsection Device Driver Initialization
160
161RTEMS automatically initializes all device drivers
162when multitasking is initiated via the
163@code{@value{DIRPREFIX}initialize_executive}
164directive.  RTEMS initializes the device drivers by invoking
165each device driver initialization entry point with the following
166parameters:
167
168@table @asis
169@item major
170the major device number for this device driver.
171
172@item minor
173zero.
174
175@item argument_block
176will point to  the Configuration Table.
177
178@end table
179
180The returned status will be ignored by RTEMS.  If the driver
181cannot successfully initialize the device, then it should invoke
182the fatal_error_occurred directive.
183
184@section Operations
185
186@subsection Register and Lookup Name
187
188The @code{@value{DIRPREFIX}io_register} directive associates a name with the
189specified device (i.e. major/minor number pair).  Device names
190are typically registered as part of the device driver
191initialization sequence.  The @code{@value{DIRPREFIX}io_lookup}
192directive is used to
193determine the major/minor number pair associated with the
194specified device name.  The use of these directives frees the
195application from being dependent on the arbitrary assignment of
196major numbers in a particular application.  No device naming
197conventions are dictated by RTEMS.
198
199@subsection Accessing an Device Driver
200
201The I/O manager provides directives which enable the
202application program to utilize device drivers in a standard
203manner.  There is a direct correlation between the RTEMS I/O
204manager directives
205@code{@value{DIRPREFIX}io_initialize},
206@code{@value{DIRPREFIX}io_open},
207@code{@value{DIRPREFIX}io_close},
208@code{@value{DIRPREFIX}io_read},
209@code{@value{DIRPREFIX}io_write}, and
210@code{@value{DIRPREFIX}io_control}
211and the underlying device driver entry points.
212
213@section Directives
214
215This section details the I/O manager's directives.  A
216subsection is dedicated to each of this manager's directives and
217describes the calling sequence, related constants, usage, and
218status codes.
219
220@c
221@c
222@c
223@page
224@subsection IO_INITIALIZE - Initialize a device driver
225
226@cindex initialize a device driver
227
228@subheading CALLING SEQUENCE:
229
230@ifset is-C
231@findex rtems_io_initialize
232@example
233rtems_status_code rtems_io_initialize(
234  rtems_device_major_number  major,
235  rtems_device_minor_number  minor,
236  void                      *argument
237);
238@end example
239@end ifset
240
241@ifset is-Ada
242@example
243procedure IO_Initialize (
244   Major        : in     RTEMS.Device_Major_Number;
245   Minor        : in     RTEMS.Device_Minor_Number;
246   Argument     : in     RTEMS.Address;
247   Return_Value :    out RTEMS.Unsigned32;
248   Result       :    out RTEMS.Status_Codes
249);
250@end example
251@end ifset
252
253@subheading DIRECTIVE STATUS CODES:
254@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
255@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
256
257@subheading DESCRIPTION:
258
259This directive calls the device driver initialization
260routine specified in the Device Driver Table for this major
261number. This directive is automatically invoked for each device
262driver when multitasking is initiated via the
263initialize_executive directive.
264
265A device driver initialization module is responsible
266for initializing all hardware and data structures associated
267with a device. If necessary, it can allocate memory to be used
268during other operations.
269
270@subheading NOTES:
271
272This directive may or may not cause the calling task
273to be preempted.  This is dependent on the device driver being
274initialized.
275
276@c
277@c
278@c
279@page
280@subsection IO_REGISTER_NAME - Register a device
281
282@cindex register device
283
284@subheading CALLING SEQUENCE:
285
286@ifset is-C
287@findex rtems_io_register_name
288@example
289rtems_status_code rtems_io_register_name(
290  char                      *name,
291  rtems_device_major_number  major,
292  rtems_device_minor_number  minor
293);
294@end example
295@end ifset
296
297@ifset is-Ada
298@example
299procedure IO_Register_Name (
300   Name   : in     String;
301   Major  : in     RTEMS.Device_Major_Number;
302   Minor  : in     RTEMS.Device_Minor_Number;
303   Result :    out RTEMS.Status_Codes
304);
305@end example
306@end ifset
307
308@subheading DIRECTIVE STATUS CODES:
309@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
310@code{@value{RPREFIX}TOO_MANY} - too many devices registered
311
312@subheading DESCRIPTION:
313
314This directive associates name with the specified
315major/minor number pair.
316
317@subheading NOTES:
318
319This directive will not cause the calling task to be
320preempted.
321
322@c
323@c
324@c
325@page
326@subsection IO_LOOKUP_NAME - Lookup a device
327
328@cindex lookup device major and minor number
329
330@subheading CALLING SEQUENCE:
331
332@ifset is-C
333@findex rtems_io_lookup_name
334@example
335rtems_status_code rtems_io_lookup_name(
336  const char                *name,
337  rtems_driver_name_t      **device_info
338);
339@end example
340@end ifset
341
342@ifset is-Ada
343@example
344procedure IO_Lookup_Name (
345   Name         : in     String;
346   Device_Info  :    out RTEMS.Driver_Name_t;
347   Result       :    out RTEMS.Status_Codes
348);
349@end example
350@end ifset
351
352@subheading DIRECTIVE STATUS CODES:
353@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
354@code{@value{RPREFIX}UNSATISFIED} - name not registered
355
356@subheading DESCRIPTION:
357
358This directive returns the major/minor number pair
359associated with the given device name in device_info.
360
361@subheading NOTES:
362
363This directive will not cause the calling task to be
364preempted.
365
366@c
367@c
368@c
369@page
370@subsection IO_OPEN - Open a device
371
372@cindex open a devive
373
374@subheading CALLING SEQUENCE:
375
376@ifset is-C
377@findex rtems_io_open
378@example
379rtems_status_code rtems_io_open(
380  rtems_device_major_number  major,
381  rtems_device_minor_number  minor,
382  void                      *argument
383);
384@end example
385@end ifset
386
387@ifset is-Ada
388@example
389procedure IO_Open (
390   Major        : in     RTEMS.Device_Major_Number;
391   Minor        : in     RTEMS.Device_Minor_Number;
392   Argument     : in     RTEMS.Address;
393   Return_Value :    out RTEMS.Unsigned32;
394   Result       :    out RTEMS.Status_Codes
395);
396@end example
397@end ifset
398
399@subheading DIRECTIVE STATUS CODES:
400@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
401@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
402
403@subheading DESCRIPTION:
404
405This directive calls the device driver open routine
406specified in the Device Driver Table for this major number.  The
407open entry point is commonly used by device drivers to provide
408exclusive access to a device.
409
410@subheading NOTES:
411
412This directive may or may not cause the calling task
413to be preempted.  This is dependent on the device driver being
414invoked.
415
416@c
417@c
418@c
419@page
420@subsection IO_CLOSE - Close a device
421
422@cindex close a device
423
424@subheading CALLING SEQUENCE:
425
426@ifset is-C
427@findex rtems_io_close
428@example
429rtems_status_code rtems_io_close(
430  rtems_device_major_number  major,
431  rtems_device_minor_number  minor,
432  void                      *argument
433);
434@end example
435@end ifset
436
437@ifset is-Ada
438@example
439procedure IO_Close (
440   Major        : in     RTEMS.Device_Major_Number;
441   Minor        : in     RTEMS.Device_Minor_Number;
442   Argument     : in     RTEMS.Address;
443   Return_Value :    out RTEMS.Unsigned32;
444   Result       :    out RTEMS.Status_Codes
445);
446@end example
447@end ifset
448
449@subheading DIRECTIVE STATUS CODES:
450@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
451@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
452
453@subheading DESCRIPTION:
454
455This directive calls the device driver close routine
456specified in the Device Driver Table for this major number.  The
457close entry point is commonly used by device drivers to
458relinquish exclusive access to a device.
459
460@subheading NOTES:
461
462This directive may or may not cause the calling task
463to be preempted.  This is dependent on the device driver being
464invoked.
465
466@c
467@c
468@c
469@page
470@subsection IO_READ - Read from a device
471
472@cindex read from a device
473
474@subheading CALLING SEQUENCE:
475
476@ifset is-C
477@findex rtems_io_read
478@example
479rtems_status_code rtems_io_read(
480  rtems_device_major_number  major,
481  rtems_device_minor_number  minor,
482  void                      *argument
483);
484@end example
485@end ifset
486
487@ifset is-Ada
488@example
489procedure IO_Read (
490   Major        : in     RTEMS.Device_Major_Number;
491   Minor        : in     RTEMS.Device_Minor_Number;
492   Argument     : in     RTEMS.Address;
493   Return_Value :    out RTEMS.Unsigned32;
494   Result       :    out RTEMS.Status_Codes
495);
496@end example
497@end ifset
498
499@subheading DIRECTIVE STATUS CODES:
500@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
501@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
502
503@subheading DESCRIPTION:
504
505This directive calls the device driver read routine
506specified in the Device Driver Table for this major number.
507Read operations typically require a buffer address as part of
508the argument parameter block.  The contents of this buffer will
509be replaced with data from the device.
510
511@subheading NOTES:
512
513This directive may or may not cause the calling task
514to be preempted.  This is dependent on the device driver being
515invoked.
516
517@c
518@c
519@c
520@page
521@subsection IO_WRITE - Write to a device
522
523@cindex write to a device
524
525@subheading CALLING SEQUENCE:
526
527@ifset is-C
528@findex rtems_io_write
529@example
530rtems_status_code rtems_io_write(
531  rtems_device_major_number  major,
532  rtems_device_minor_number  minor,
533  void                      *argument
534);
535@end example
536@end ifset
537
538@ifset is-Ada
539@example
540procedure IO_Write (
541   Major        : in     RTEMS.Device_Major_Number;
542   Minor        : in     RTEMS.Device_Minor_Number;
543   Argument     : in     RTEMS.Address;
544   Return_Value :    out RTEMS.Unsigned32;
545   Result       :    out RTEMS.Status_Codes
546);
547@end example
548@end ifset
549
550@subheading DIRECTIVE STATUS CODES:
551@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
552@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
553
554@subheading DESCRIPTION:
555
556This directive calls the device driver write routine
557specified in the Device Driver Table for this major number.
558Write operations typically require a buffer address as part of
559the argument parameter block.  The contents of this buffer will
560be sent to the device.
561
562@subheading NOTES:
563
564This directive may or may not cause the calling task
565to be preempted.  This is dependent on the device driver being
566invoked.
567
568@c
569@c
570@c
571@page
572@subsection IO_CONTROL - Special device services
573
574@cindex special device services
575@cindex IO Control
576
577@subheading CALLING SEQUENCE:
578
579@ifset is-C
580@findex rtems_io_control
581@example
582rtems_status_code rtems_io_control(
583  rtems_device_major_number  major,
584  rtems_device_minor_number  minor,
585  void                      *argument
586);
587@end example
588@end ifset
589
590@ifset is-Ada
591@example
592procedure IO_Control (
593   Major        : in     RTEMS.Device_Major_Number;
594   Minor        : in     RTEMS.Device_Minor_Number;
595   Argument     : in     RTEMS.Address;
596   Return_Value :    out RTEMS.Unsigned32;
597   Result       :    out RTEMS.Status_Codes
598);
599@end example
600@end ifset
601
602@subheading DIRECTIVE STATUS CODES:
603@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
604@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
605
606@subheading DESCRIPTION:
607
608This directive calls the device driver I/O control
609routine specified in the Device Driver Table for this major
610number.  The exact functionality of the driver entry called by
611this directive is driver dependent.  It should not be assumed
612that the control entries of two device drivers are compatible.
613For example, an RS-232 driver I/O control operation may change
614the baud rate of a serial line, while an I/O control operation
615for a floppy disk driver may cause a seek operation.
616
617@subheading NOTES:
618
619This directive may or may not cause the calling task
620to be preempted.  This is dependent on the device driver being
621invoked.
622
623
624
Note: See TracBrowser for help on using the repository browser.