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

4.104.114.84.95
Last change on this file since f4ab3d3 was f4ab3d3, checked in by Joel Sherrill <joel.sherrill@…>, on 02/03/03 at 23:58:50

2003-02-03 Joel Sherrill <joel@…>

PR 338/filesystem

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