source: rtems/doc/user/io.t @ 8218f5f

4.104.114.9
Last change on this file since 8218f5f was 8218f5f, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 20, 2008 at 5:14:00 PM

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

  • user/io.t: Fix typos for IO unregister reported by Catalin Morosan <catalin.morosan at gmail.com>.
  • Property mode set to 100644
File size: 18.1 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007.
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
172NOT SUPPORTED FROM Ada BINDING
173@end example
174@end ifset
175
176The format and contents of the parameter block are
177device driver and entry point dependent.
178
179It is recommended that a device driver avoid
180generating error codes which conflict with those used by
181application components.  A common technique used to generate
182driver specific error codes is to make the most significant part
183of the status indicate a driver specific code.
184
185@subsection Device Driver Initialization
186
187RTEMS automatically initializes all device drivers
188when multitasking is initiated via the
189@code{@value{DIRPREFIX}initialize_executive}
190directive.  RTEMS initializes the device drivers by invoking
191each device driver initialization entry point with the following
192parameters:
193
194@table @asis
195@item major
196the major device number for this device driver.
197
198@item minor
199zero.
200
201@item argument_block
202will point to  the Configuration Table.
203
204@end table
205
206The returned status will be ignored by RTEMS.  If the driver
207cannot successfully initialize the device, then it should invoke
208the fatal_error_occurred directive.
209
210@section Operations
211
212@subsection Register and Lookup Name
213
214The @code{@value{DIRPREFIX}io_register} directive associates a name with the
215specified device (i.e. major/minor number pair).  Device names
216are typically registered as part of the device driver
217initialization sequence.  The @code{@value{DIRPREFIX}io_lookup}
218directive is used to
219determine the major/minor number pair associated with the
220specified device name.  The use of these directives frees the
221application from being dependent on the arbitrary assignment of
222major numbers in a particular application.  No device naming
223conventions are dictated by RTEMS.
224
225@subsection Accessing an Device Driver
226
227The I/O manager provides directives which enable the
228application program to utilize device drivers in a standard
229manner.  There is a direct correlation between the RTEMS I/O
230manager directives
231@code{@value{DIRPREFIX}io_initialize},
232@code{@value{DIRPREFIX}io_open},
233@code{@value{DIRPREFIX}io_close},
234@code{@value{DIRPREFIX}io_read},
235@code{@value{DIRPREFIX}io_write}, and
236@code{@value{DIRPREFIX}io_control}
237and the underlying device driver entry points.
238
239@section Directives
240
241This section details the I/O manager's directives.  A
242subsection is dedicated to each of this manager's directives and
243describes the calling sequence, related constants, usage, and
244status codes.
245
246@c
247@c
248@c
249@page
250@subsection IO_REGISTER_DRIVER - Register a device driver
251
252@cindex register a device driver
253
254@subheading CALLING SEQUENCE:
255
256@ifset is-C
257@findex rtems_io_register_driver
258@example
259rtems_status_code rtems_io_register_driver(
260  rtems_device_major_number   major,
261  rtems_driver_address_table *driver_table,
262  rtems_device_major_number  *registered_major
263);
264@end example
265@end ifset
266
267@ifset is-Ada
268@example
269NOT SUPPORTED FROM Ada BINDING
270@end example
271@end ifset
272
273@subheading DIRECTIVE STATUS CODES:
274@code{@value{RPREFIX}SUCCESSFUL} - successfully registered@*
275@code{@value{RPREFIX}INVALID_ADDRESS} - invalid registered major pointer@*
276@code{@value{RPREFIX}INVALID_ADDRESS} - invalid driver table@*
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_unregister_driver(
319  rtems_device_major_number   major
320);
321@end example
322@end ifset
323
324@ifset is-Ada
325@example
326NOT SUPPORTED FROM Ada BINDING
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
366NOT SUPPORTED FROM Ada BINDING
367@end example
368@end ifset
369
370@subheading DIRECTIVE STATUS CODES:
371@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
372@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
373
374@subheading DESCRIPTION:
375
376This directive calls the device driver initialization
377routine specified in the Device Driver Table for this major
378number. This directive is automatically invoked for each device
379driver when multitasking is initiated via the
380initialize_executive directive.
381
382A device driver initialization module is responsible
383for initializing all hardware and data structures associated
384with a device. If necessary, it can allocate memory to be used
385during other operations.
386
387@subheading NOTES:
388
389This directive may or may not cause the calling task
390to be preempted.  This is dependent on the device driver being
391initialized.
392
393@c
394@c
395@c
396@page
397@subsection IO_REGISTER_NAME - Register a device
398
399@cindex register device
400
401@subheading CALLING SEQUENCE:
402
403@ifset is-C
404@findex rtems_io_register_name
405@example
406rtems_status_code rtems_io_register_name(
407  const char                *name,
408  rtems_device_major_number  major,
409  rtems_device_minor_number  minor
410);
411@end example
412@end ifset
413
414@ifset is-Ada
415@example
416NOT SUPPORTED FROM Ada BINDING
417@end example
418@end ifset
419
420@subheading DIRECTIVE STATUS CODES:
421@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
422@code{@value{RPREFIX}TOO_MANY} - too many devices registered
423
424@subheading DESCRIPTION:
425
426This directive associates name with the specified
427major/minor number pair.
428
429@subheading NOTES:
430
431This directive will not cause the calling task to be
432preempted.
433
434@c
435@c
436@c
437@page
438@subsection IO_LOOKUP_NAME - Lookup a device
439
440@cindex lookup device major and minor number
441
442@subheading CALLING SEQUENCE:
443
444@ifset is-C
445@findex rtems_io_lookup_name
446@example
447rtems_status_code rtems_io_lookup_name(
448  const char                *name,
449  rtems_driver_name_t       *device_info
450);
451@end example
452@end ifset
453
454@ifset is-Ada
455@example
456NOT SUPPORTED FROM Ada BINDING
457@end example
458@end ifset
459
460@subheading DIRECTIVE STATUS CODES:
461@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
462@code{@value{RPREFIX}UNSATISFIED} - name not registered
463
464@subheading DESCRIPTION:
465
466This directive returns the major/minor number pair
467associated with the given device name in @code{device_info}.
468
469@subheading NOTES:
470
471This directive will not cause the calling task to be
472preempted.
473
474@c
475@c
476@c
477@page
478@subsection IO_OPEN - Open a device
479
480@cindex open a devive
481
482@subheading CALLING SEQUENCE:
483
484@ifset is-C
485@findex rtems_io_open
486@example
487rtems_status_code rtems_io_open(
488  rtems_device_major_number  major,
489  rtems_device_minor_number  minor,
490  void                      *argument
491);
492@end example
493@end ifset
494
495@ifset is-Ada
496@example
497NOT SUPPORTED FROM Ada BINDING
498@end example
499@end ifset
500
501@subheading DIRECTIVE STATUS CODES:
502@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
503@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
504
505@subheading DESCRIPTION:
506
507This directive calls the device driver open routine
508specified in the Device Driver Table for this major number.  The
509open entry point is commonly used by device drivers to provide
510exclusive access to a device.
511
512@subheading NOTES:
513
514This directive may or may not cause the calling task
515to be preempted.  This is dependent on the device driver being
516invoked.
517
518@c
519@c
520@c
521@page
522@subsection IO_CLOSE - Close a device
523
524@cindex close a device
525
526@subheading CALLING SEQUENCE:
527
528@ifset is-C
529@findex rtems_io_close
530@example
531rtems_status_code rtems_io_close(
532  rtems_device_major_number  major,
533  rtems_device_minor_number  minor,
534  void                      *argument
535);
536@end example
537@end ifset
538
539@ifset is-Ada
540@example
541NOT SUPPORTED FROM Ada BINDING
542@end example
543@end ifset
544
545@subheading DIRECTIVE STATUS CODES:
546@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
547@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
548
549@subheading DESCRIPTION:
550
551This directive calls the device driver close routine
552specified in the Device Driver Table for this major number.  The
553close entry point is commonly used by device drivers to
554relinquish exclusive access to a device.
555
556@subheading NOTES:
557
558This directive may or may not cause the calling task
559to be preempted.  This is dependent on the device driver being
560invoked.
561
562@c
563@c
564@c
565@page
566@subsection IO_READ - Read from a device
567
568@cindex read from a device
569
570@subheading CALLING SEQUENCE:
571
572@ifset is-C
573@findex rtems_io_read
574@example
575rtems_status_code rtems_io_read(
576  rtems_device_major_number  major,
577  rtems_device_minor_number  minor,
578  void                      *argument
579);
580@end example
581@end ifset
582
583@ifset is-Ada
584@example
585NOT SUPPORTED FROM Ada BINDING
586@end example
587@end ifset
588
589@subheading DIRECTIVE STATUS CODES:
590@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
591@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
592
593@subheading DESCRIPTION:
594
595This directive calls the device driver read routine
596specified in the Device Driver Table for this major number.
597Read operations typically require a buffer address as part of
598the argument parameter block.  The contents of this buffer will
599be replaced with data from the device.
600
601@subheading NOTES:
602
603This directive may or may not cause the calling task
604to be preempted.  This is dependent on the device driver being
605invoked.
606
607@c
608@c
609@c
610@page
611@subsection IO_WRITE - Write to a device
612
613@cindex write to a device
614
615@subheading CALLING SEQUENCE:
616
617@ifset is-C
618@findex rtems_io_write
619@example
620rtems_status_code rtems_io_write(
621  rtems_device_major_number  major,
622  rtems_device_minor_number  minor,
623  void                      *argument
624);
625@end example
626@end ifset
627
628@ifset is-Ada
629@example
630NOT SUPPORTED FROM Ada BINDING
631@end example
632@end ifset
633
634@subheading DIRECTIVE STATUS CODES:
635@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
636@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
637
638@subheading DESCRIPTION:
639
640This directive calls the device driver write routine
641specified in the Device Driver Table for this major number.
642Write operations typically require a buffer address as part of
643the argument parameter block.  The contents of this buffer will
644be sent to the device.
645
646@subheading NOTES:
647
648This directive may or may not cause the calling task
649to be preempted.  This is dependent on the device driver being
650invoked.
651
652@c
653@c
654@c
655@page
656@subsection IO_CONTROL - Special device services
657
658@cindex special device services
659@cindex IO Control
660
661@subheading CALLING SEQUENCE:
662
663@ifset is-C
664@findex rtems_io_control
665@example
666rtems_status_code rtems_io_control(
667  rtems_device_major_number  major,
668  rtems_device_minor_number  minor,
669  void                      *argument
670);
671@end example
672@end ifset
673
674@ifset is-Ada
675@example
676NOT SUPPORTED FROM Ada BINDING
677@end example
678@end ifset
679
680@subheading DIRECTIVE STATUS CODES:
681@code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@*
682@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number
683
684@subheading DESCRIPTION:
685
686This directive calls the device driver I/O control
687routine specified in the Device Driver Table for this major
688number.  The exact functionality of the driver entry called by
689this directive is driver dependent.  It should not be assumed
690that the control entries of two device drivers are compatible.
691For example, an RS-232 driver I/O control operation may change
692the baud rate of a serial line, while an I/O control operation
693for a floppy disk driver may cause a seek operation.
694
695@subheading NOTES:
696
697This directive may or may not cause the calling task
698to be preempted.  This is dependent on the device driver being
699invoked.
700
701
702
Note: See TracBrowser for help on using the repository browser.