source: rtems/doc/user/io.t @ 6829e03

4.104.114.84.95
Last change on this file since 6829e03 was 6829e03, checked in by Joel Sherrill <joel.sherrill@…>, on 05/29/07 at 18:50:50

2007-05-29 Joel Sherrill <joel.sherrill@…>

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