source: rtems/doc/user/io.t @ 4ffbc49

4.104.114.95
Last change on this file since 4ffbc49 was 4ffbc49, checked in by Glenn Humphrey <glenn.humphrey@…>, on 10/25/07 at 19:46:41

2007-10-25 Glenn Humphrey <glenn.humphrey@…>

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