source: rtems/doc/user/io.t @ 21b1d51

4.9
Last change on this file since 21b1d51 was 21b1d51, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 20, 2008 at 3:22:29 PM

2008-11-20 Joel Sherrill <joel.sherrill@…>

PR 1339/Ada

  • user/io.t: Re-add IO Manager to Ada binding.
  • Property mode set to 100644
File size: 19.6 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008.
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_driver} - Register a device driver
24@item @code{@value{DIRPREFIX}io_unregister_driver} - Unregister a device driver
25@item @code{@value{DIRPREFIX}io_register_name} - Register a device name
26@item @code{@value{DIRPREFIX}io_lookup_name} - Look up a device name
27@item @code{@value{DIRPREFIX}io_open} - Open a device
28@item @code{@value{DIRPREFIX}io_close} - Close a device
29@item @code{@value{DIRPREFIX}io_read} - Read from a device
30@item @code{@value{DIRPREFIX}io_write} - Write to a device
31@item @code{@value{DIRPREFIX}io_control} - Special device services
32@end itemize
33
34@section Background
35
36@subsection Device Driver Table
37
38@cindex Device Driver Table
39
40Each application utilizing the RTEMS I/O manager must specify the
41address of a Device Driver Table in its Configuration Table. This table
42contains each device driver's entry points that is to be initialised by
43RTEMS during initialization.  Each device driver may contain the
44following entry points:
45
46@itemize @bullet
47@item Initialization
48@item Open
49@item Close
50@item Read
51@item Write
52@item Control
53@end itemize
54
55If the device driver does not support a particular
56entry point, then that entry in the Configuration Table should
57be NULL.  RTEMS will return
58@code{@value{RPREFIX}SUCCESSFUL} as the executive's and
59zero (0) as the device driver's return code for these device
60driver entry points.
61
62Applications can register and unregister drivers with the RTEMS I/O
63manager avoiding the need to have all drivers statically defined and
64linked into this table.
65
66The @file{confdefs.h} entry @code{CONFIGURE_MAXIMUM_DRIVERS} configures
67the number of driver slots available to the application.
68
69@subsection Major and Minor Device Numbers
70
71@cindex major device number
72@cindex minor device number
73
74Each call to the I/O manager must provide a device's
75major and minor numbers as arguments.  The major number is the
76index of the requested driver's entry points in the Device
77Driver Table, and is used to select a specific device driver.
78The exact usage of the minor number is driver specific, but is
79commonly used to distinguish between a number of devices
80controlled by the same driver.
81
82@findex rtems_device_major_number
83@findex rtems_device_minor_number
84
85The data types @code{@value{DIRPREFIX}device_major_number} and
86@code{@value{DIRPREFIX}device_minor_number} are used to
87manipulate device major and minor numbers, respectively.
88
89@subsection Device Names
90
91@cindex device names
92
93The I/O Manager provides facilities to associate a
94name with a particular device.  Directives are provided to
95register the name of a device and to look up the major/minor
96number pair associated with a device name.
97
98@subsection Device Driver Environment
99
100Application developers, as well as device driver
101developers, must be aware of the following regarding the RTEMS
102I/O Manager:
103
104@itemize @bullet
105@item A device driver routine executes in the context of the
106invoking task.  Thus if the driver blocks, the invoking task
107blocks.
108
109@item The device driver is free to change the modes of the
110invoking task, although the driver should restore them to their
111original values.
112
113@item Device drivers may be invoked from ISRs.
114
115@item Only local device drivers are accessible through the I/O
116manager.
117
118@item A device driver routine may invoke all other RTEMS
119directives, including I/O directives, on both local and global
120objects.
121
122@end itemize
123
124Although the RTEMS I/O manager provides a framework
125for device drivers, it makes no assumptions regarding the
126construction or operation of a device driver.
127
128@subsection Runtime Driver Registration
129
130@cindex runtime driver registration
131
132Board support package and application developers can select wether a
133device driver is statically entered into the default device table or
134registered at runtime.
135
136Dynamic registration helps applications where:
137
138@enumerate
139@item The BSP and kernel libraries are common to a range of applications
140for a specific target platform. An application may be built upon a
141common library with all drivers. The application selects and registers
142the drivers. Uniform driver name lookup protects the application.
143@item The type and range of drivers may vary as the application probes a
144bus during initialization.
145@item Support for hot swap bus system such as Compact PCI.
146@item Support for runtime loadable driver modules.
147@end enumerate
148
149@subsection Device Driver Interface
150
151@cindex device driver interface
152
153When an application invokes an I/O manager directive,
154RTEMS determines which device driver entry point must be
155invoked.  The information passed by the application to RTEMS is
156then passed to the correct device driver entry point.  RTEMS
157will invoke each device driver entry point assuming it is
158compatible with the following prototype:
159
160@ifset is-C
161@example
162rtems_device_driver io_entry(
163  rtems_device_major_number  major,
164  rtems_device_minor_number  minor,
165  void                      *argument_block
166);
167@end example
168@end ifset
169
170@ifset is-Ada
171@example
172function IO_Entry (
173  Major          : in     RTEMS.Device_Major_Number;
174  Minor          : in     RTEMS.Device_Major_Number;
175  Argument_Block : in     RTEMS.Address
176) return RTEMS.Status_Code;
177@end example
178@end ifset
179
180The format and contents of the parameter block are
181device driver and entry point dependent.
182
183It is recommended that a device driver avoid
184generating error codes which conflict with those used by
185application components.  A common technique used to generate
186driver specific error codes is to make the most significant part
187of the status indicate a driver specific code.
188
189@subsection Device Driver Initialization
190
191RTEMS automatically initializes all device drivers
192when multitasking is initiated via the
193@code{@value{DIRPREFIX}initialize_executive}
194directive.  RTEMS initializes the device drivers by invoking
195each device driver initialization entry point with the following
196parameters:
197
198@table @asis
199@item major
200the major device number for this device driver.
201
202@item minor
203zero.
204
205@item argument_block
206will point to  the Configuration Table.
207
208@end table
209
210The returned status will be ignored by RTEMS.  If the driver
211cannot successfully initialize the device, then it should invoke
212the fatal_error_occurred directive.
213
214@section Operations
215
216@subsection Register and Lookup Name
217
218The @code{@value{DIRPREFIX}io_register} directive associates a name with the
219specified device (i.e. major/minor number pair).  Device names
220are typically registered as part of the device driver
221initialization sequence.  The @code{@value{DIRPREFIX}io_lookup}
222directive is used to
223determine the major/minor number pair associated with the
224specified device name.  The use of these directives frees the
225application from being dependent on the arbitrary assignment of
226major numbers in a particular application.  No device naming
227conventions are dictated by RTEMS.
228
229@subsection Accessing an Device Driver
230
231The I/O manager provides directives which enable the
232application program to utilize device drivers in a standard
233manner.  There is a direct correlation between the RTEMS I/O
234manager directives
235@code{@value{DIRPREFIX}io_initialize},
236@code{@value{DIRPREFIX}io_open},
237@code{@value{DIRPREFIX}io_close},
238@code{@value{DIRPREFIX}io_read},
239@code{@value{DIRPREFIX}io_write}, and
240@code{@value{DIRPREFIX}io_control}
241and the underlying device driver entry points.
242
243@section Directives
244
245This section details the I/O manager's directives.  A
246subsection is dedicated to each of this manager's directives and
247describes the calling sequence, related constants, usage, and
248status codes.
249
250@c
251@c
252@c
253@page
254@subsection IO_REGISTER_DRIVER - Register a device driver
255
256@cindex register a device driver
257
258@subheading CALLING SEQUENCE:
259
260@ifset is-C
261@findex rtems_io_register_driver
262@example
263rtems_status_code rtems_io_register_driver(
264  rtems_device_major_number   major,
265  rtems_driver_address_table *driver_table,
266  rtems_device_major_number  *registered_major
267);
268@end example
269@end ifset
270
271@ifset is-Ada
272@example
273No Ada implementation.
274@end example
275@end ifset
276
277@subheading DIRECTIVE STATUS CODES:
278@code{@value{RPREFIX}SUCCESSFUL} - successfully registered@*
279@code{@value{RPREFIX}INVALID_ADDRESS} - invalid registered major pointer@*
280@code{@value{RPREFIX}INVALID_ADDRESS} - invalid driver table@*
281@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number@*
282@code{@value{RPREFIX}TOO_MANY} - no available major device table slot@*
283@code{@value{RPREFIX}RESOURCE_IN_USE} - major device number entry in use
284
285@subheading DESCRIPTION:
286
287This directive attempts to add a new device driver to the Device Driver
288Table. The user can specify a specific major device number via the
289directive's @code{major} parameter, or let the registration routine find
290the next available major device number by specifing a major number of
291@code{0}. The selected major device number is returned via the
292@code{registered_major} directive parameter. The directive automatically
293allocation major device numbers from the highest value down.
294
295This directive automatically invokes the IO_INITIALIZE directive if
296the driver address table has an initialization and open entry.
297
298The directive returns @value{RPREFIX}TOO_MANY if Device Driver Table is
299full, and @value{RPREFIX}RESOURCE_IN_USE if a specific major device
300number is requested and it is already in use.
301
302@subheading NOTES:
303
304The Device Driver Table size is specified in the Configuration Table
305condiguration. This needs to be set to maximum size the application
306requires.
307
308
309@c
310@c
311@c
312@page
313@subsection IO_UNREGISTER_DRIVER - Unregister a device driver
314
315@cindex unregister a device driver
316
317@subheading CALLING SEQUENCE:
318
319@ifset is-C
320@findex rtems_io_unregister_driver
321@example
322rtems_status_code rtems_io_unregister_driver(
323  rtems_device_major_number   major
324);
325@end example
326@end ifset
327
328@ifset is-Ada
329@example
330No Ada implementation.
331@end example
332@end ifset
333
334@subheading DIRECTIVE STATUS CODES:
335@code{@value{RPREFIX}SUCCESSFUL} - successfully registered@*
336@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
337
338@subheading DESCRIPTION:
339
340This directive removes a device driver from the Device Driver Table.
341
342@subheading NOTES:
343
344Currently no specific checks are made and the driver is not closed.
345
346
347@c
348@c
349@c
350@page
351@subsection IO_INITIALIZE - Initialize a device driver
352
353@cindex initialize a device driver
354
355@subheading CALLING SEQUENCE:
356
357@ifset is-C
358@findex rtems_io_initialize
359@example
360rtems_status_code rtems_io_initialize(
361  rtems_device_major_number  major,
362  rtems_device_minor_number  minor,
363  void                      *argument
364);
365@end example
366@end ifset
367
368@ifset is-Ada
369@example
370procedure IO_Initialize (
371   Major        : in     RTEMS.Device_Major_Number;
372   Minor        : in     RTEMS.Device_Minor_Number;
373   Argument     : in     RTEMS.Address;
374   Result       :    out RTEMS.Status_Codes
375);
376@end example
377@end ifset
378
379@subheading DIRECTIVE STATUS CODES:
380@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
381@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
382
383@subheading DESCRIPTION:
384
385This directive calls the device driver initialization
386routine specified in the Device Driver Table for this major
387number. This directive is automatically invoked for each device
388driver when multitasking is initiated via the
389initialize_executive directive.
390
391A device driver initialization module is responsible
392for initializing all hardware and data structures associated
393with a device. If necessary, it can allocate memory to be used
394during other operations.
395
396@subheading NOTES:
397
398This directive may or may not cause the calling task
399to be preempted.  This is dependent on the device driver being
400initialized.
401
402@c
403@c
404@c
405@page
406@subsection IO_REGISTER_NAME - Register a device
407
408@cindex register device
409
410@subheading CALLING SEQUENCE:
411
412@ifset is-C
413@findex rtems_io_register_name
414@example
415rtems_status_code rtems_io_register_name(
416  const char                *name,
417  rtems_device_major_number  major,
418  rtems_device_minor_number  minor
419);
420@end example
421@end ifset
422
423@ifset is-Ada
424@example
425procedure IO_Register_Name (
426   Name   : in     String;
427   Major  : in     RTEMS.Device_Major_Number;
428   Minor  : in     RTEMS.Device_Minor_Number;
429   Result :    out RTEMS.Status_Codes
430);
431@end example
432@end ifset
433
434@subheading DIRECTIVE STATUS CODES:
435@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
436@code{@value{RPREFIX}TOO_MANY} - too many devices registered
437
438@subheading DESCRIPTION:
439
440This directive associates name with the specified
441major/minor number pair.
442
443@subheading NOTES:
444
445This directive will not cause the calling task to be
446preempted.
447
448@c
449@c
450@c
451@page
452@subsection IO_LOOKUP_NAME - Lookup a device
453
454@cindex lookup device major and minor number
455
456@subheading CALLING SEQUENCE:
457
458@ifset is-C
459@findex rtems_io_lookup_name
460@example
461rtems_status_code rtems_io_lookup_name(
462  const char                *name,
463  rtems_driver_name_t       *device_info
464);
465@end example
466@end ifset
467
468@ifset is-Ada
469@example
470procedure IO_Lookup_Name (
471   Name         : in     String;
472   Device_Info  :    out RTEMS.Driver_Name_t_Pointer;
473   Result       :    out RTEMS.Status_Codes
474);
475@end example
476@end ifset
477
478@subheading DIRECTIVE STATUS CODES:
479@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
480@code{@value{RPREFIX}UNSATISFIED} - name not registered
481
482@subheading DESCRIPTION:
483
484This directive returns the major/minor number pair
485associated with the given device name in @code{device_info}.
486
487@subheading NOTES:
488
489This directive will not cause the calling task to be
490preempted.
491
492@c
493@c
494@c
495@page
496@subsection IO_OPEN - Open a device
497
498@cindex open a devive
499
500@subheading CALLING SEQUENCE:
501
502@ifset is-C
503@findex rtems_io_open
504@example
505rtems_status_code rtems_io_open(
506  rtems_device_major_number  major,
507  rtems_device_minor_number  minor,
508  void                      *argument
509);
510@end example
511@end ifset
512
513@ifset is-Ada
514@example
515procedure IO_Open (
516   Major        : in     RTEMS.Device_Major_Number;
517   Minor        : in     RTEMS.Device_Minor_Number;
518   Argument     : in     RTEMS.Address;
519   Result       :    out RTEMS.Status_Codes
520);
521@end example
522@end ifset
523
524@subheading DIRECTIVE STATUS CODES:
525@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
526@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
527
528@subheading DESCRIPTION:
529
530This directive calls the device driver open routine
531specified in the Device Driver Table for this major number.  The
532open entry point is commonly used by device drivers to provide
533exclusive access to a device.
534
535@subheading NOTES:
536
537This directive may or may not cause the calling task
538to be preempted.  This is dependent on the device driver being
539invoked.
540
541@c
542@c
543@c
544@page
545@subsection IO_CLOSE - Close a device
546
547@cindex close a device
548
549@subheading CALLING SEQUENCE:
550
551@ifset is-C
552@findex rtems_io_close
553@example
554rtems_status_code rtems_io_close(
555  rtems_device_major_number  major,
556  rtems_device_minor_number  minor,
557  void                      *argument
558);
559@end example
560@end ifset
561
562@ifset is-Ada
563@example
564procedure IO_Close (
565   Major        : in     RTEMS.Device_Major_Number;
566   Minor        : in     RTEMS.Device_Minor_Number;
567   Argument     : in     RTEMS.Address;
568   Result       :    out RTEMS.Status_Codes
569);
570@end example
571@end ifset
572
573@subheading DIRECTIVE STATUS CODES:
574@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
575@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
576
577@subheading DESCRIPTION:
578
579This directive calls the device driver close routine
580specified in the Device Driver Table for this major number.  The
581close entry point is commonly used by device drivers to
582relinquish exclusive access to a device.
583
584@subheading NOTES:
585
586This directive may or may not cause the calling task
587to be preempted.  This is dependent on the device driver being
588invoked.
589
590@c
591@c
592@c
593@page
594@subsection IO_READ - Read from a device
595
596@cindex read from a device
597
598@subheading CALLING SEQUENCE:
599
600@ifset is-C
601@findex rtems_io_read
602@example
603rtems_status_code rtems_io_read(
604  rtems_device_major_number  major,
605  rtems_device_minor_number  minor,
606  void                      *argument
607);
608@end example
609@end ifset
610
611@ifset is-Ada
612@example
613procedure IO_Read (
614   Major        : in     RTEMS.Device_Major_Number;
615   Minor        : in     RTEMS.Device_Minor_Number;
616   Argument     : in     RTEMS.Address;
617   Result       :    out RTEMS.Status_Codes
618);
619@end example
620@end ifset
621
622@subheading DIRECTIVE STATUS CODES:
623@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
624@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
625
626@subheading DESCRIPTION:
627
628This directive calls the device driver read routine
629specified in the Device Driver Table for this major number.
630Read operations typically require a buffer address as part of
631the argument parameter block.  The contents of this buffer will
632be replaced with data from the device.
633
634@subheading NOTES:
635
636This directive may or may not cause the calling task
637to be preempted.  This is dependent on the device driver being
638invoked.
639
640@c
641@c
642@c
643@page
644@subsection IO_WRITE - Write to a device
645
646@cindex write to a device
647
648@subheading CALLING SEQUENCE:
649
650@ifset is-C
651@findex rtems_io_write
652@example
653rtems_status_code rtems_io_write(
654  rtems_device_major_number  major,
655  rtems_device_minor_number  minor,
656  void                      *argument
657);
658@end example
659@end ifset
660
661@ifset is-Ada
662@example
663procedure IO_Write (
664   Major        : in     RTEMS.Device_Major_Number;
665   Minor        : in     RTEMS.Device_Minor_Number;
666   Argument     : in     RTEMS.Address;
667   Result       :    out RTEMS.Status_Codes
668);
669@end example
670@end ifset
671
672@subheading DIRECTIVE STATUS CODES:
673@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
674@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
675
676@subheading DESCRIPTION:
677
678This directive calls the device driver write routine
679specified in the Device Driver Table for this major number.
680Write operations typically require a buffer address as part of
681the argument parameter block.  The contents of this buffer will
682be sent to the device.
683
684@subheading NOTES:
685
686This directive may or may not cause the calling task
687to be preempted.  This is dependent on the device driver being
688invoked.
689
690@c
691@c
692@c
693@page
694@subsection IO_CONTROL - Special device services
695
696@cindex special device services
697@cindex IO Control
698
699@subheading CALLING SEQUENCE:
700
701@ifset is-C
702@findex rtems_io_control
703@example
704rtems_status_code rtems_io_control(
705  rtems_device_major_number  major,
706  rtems_device_minor_number  minor,
707  void                      *argument
708);
709@end example
710@end ifset
711
712@ifset is-Ada
713@example
714procedure IO_Control (
715   Major        : in     RTEMS.Device_Major_Number;
716   Minor        : in     RTEMS.Device_Minor_Number;
717   Argument     : in     RTEMS.Address;
718   Result       :    out RTEMS.Status_Codes
719);
720@end example
721@end ifset
722
723@subheading DIRECTIVE STATUS CODES:
724@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
725@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
726
727@subheading DESCRIPTION:
728
729This directive calls the device driver I/O control
730routine specified in the Device Driver Table for this major
731number.  The exact functionality of the driver entry called by
732this directive is driver dependent.  It should not be assumed
733that the control entries of two device drivers are compatible.
734For example, an RS-232 driver I/O control operation may change
735the baud rate of a serial line, while an I/O control operation
736for a floppy disk driver may cause a seek operation.
737
738@subheading NOTES:
739
740This directive may or may not cause the calling task
741to be preempted.  This is dependent on the device driver being
742invoked.
743
744
745
Note: See TracBrowser for help on using the repository browser.