From 6d0009508f1c3183493b073e5cf08864348cb266 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 27 Mar 2002 14:39:06 +0000 Subject: 2002-03-22 Chris Johns * io.t, conf.t: PR 160. Added the IO Manager's register and unregister interface documentation. --- doc/user/ChangeLog | 5 ++ doc/user/conf.t | 31 +++++++++---- doc/user/io.t | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 156 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/user/ChangeLog b/doc/user/ChangeLog index 20467e62a2..73bda085a6 100644 --- a/doc/user/ChangeLog +++ b/doc/user/ChangeLog @@ -1,3 +1,8 @@ +2002-03-22 Chris Johns + + * io.t, conf.t: PR 160. Added the IO Manager's register and + unregister interface documentation. + 2002-03-15 Eric Norum * rtmon.t: Correct example and correctly used ensure not insure. diff --git a/doc/user/conf.t b/doc/user/conf.t index df8b92731e..c931c4ea65 100644 --- a/doc/user/conf.t +++ b/doc/user/conf.t @@ -255,6 +255,11 @@ entries named @code{Device_drivers}. By default, this is not defined indicating the @code{confdefs.h} is providing the device driver table. +@findex CONFIGURE_MAXIMUM_DRIVERS +@item @code{CONFIGURE_MAXIMUM_DRIVERS} is defined +as the number of device drivers per node. By default, this is +set to 10. + @findex CONFIGURE_MAXIMUM_DEVICES @item @code{CONFIGURE_MAXIMUM_DEVICES} is defined to the number of individual devices that may be registered @@ -716,6 +721,7 @@ typedef struct @{ rtems_unsigned32 microseconds_per_tick; rtems_unsigned32 ticks_per_timeslice; rtems_unsigned32 maximum_devices; + rtems_unsigned32 maximum_drivers; rtems_unsigned32 number_of_device_drivers; rtems_driver_address_table *Device_driver_table; rtems_unsigned32 number_of_initial_extensions; @@ -800,6 +806,14 @@ When using the @code{confdefs.h} mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro @code{CONFIGURE_MAXIMUM_DEVICES}. +@item maximum_drivers +is the maximum number of device drivers that can be registered. +When using the @code{confdefs.h} mechanism for configuring +an RTEMS application, the value for this field corresponds +to the setting of the macro @code{CONFIGURE_MAXIMUM_DRIVERS}. +This value is set to @code{maximum_devices} if it is greater +than @code{maximum_drivers}. + @item number_of_device_drivers is the number of device drivers for the system. There should be the same number of entries in the Device Driver Table. If this field @@ -1397,14 +1411,15 @@ Initialization_Tasks : aliased @cindex Device Driver Table -The Device Driver Table is used to inform the I/O -Manager of the set of entry points for each device driver -configured in the system. The table contains one entry for each -device driver required by the application. The number of -entries is defined in the number_of_device_drivers entry in the -Configuration Table. The format of each entry in the Device -Driver Table is defined in -the following @value{LANGUAGE} @value{STRUCTURE}: +The Device Driver Table is used to inform the I/O Manager of the set of +entry points for each device driver configured in the system. The table +contains one entry for each device driver required by the application. +The number of entries is defined in the number_of_device_drivers entry +in the Configuration Table. This table is copied to the Device Drive +Table during the IO Manager's initialization giving the entries in this +table the lower major numbers. The format of each entry in the Device +Driver Table is defined in the following @value{LANGUAGE} +@value{STRUCTURE}: @ifset is-C @findex rtems_driver_address_table diff --git a/doc/user/io.t b/doc/user/io.t index 64ace623df..88874ebb93 100644 --- a/doc/user/io.t +++ b/doc/user/io.t @@ -35,11 +35,11 @@ directives provided by the I/O manager are: @cindex Device Driver Table -Each application utilizing the RTEMS I/O manager must -specify the address of a Device Driver Table in its -Configuration Table. This table contains each device driver's -entry points. Each device driver may contain the following -entry points: +Each application utilizing the RTEMS I/O manager must specify the +address of a Device Driver Table in its Configuration Table. This table +contains each device driver's entry points that is to be initialised by +RTEMS during initialization. Each device driver may contain the +following entry points: @itemize @bullet @item Initialization @@ -57,6 +57,13 @@ be NULL. RTEMS will return zero (0) as the device driver's return code for these device driver entry points. +Applications can register and unregister drivers with the RTEMS I/O +manager avoiding the need to have all drivers statically defined and +linked into this table. + +The @file{confdefs.h} entry @code{CONFIGURE_MAXIMUM_DRIVERS} configures +the number of driver slots available to the application. + @subsection Major and Minor Device Numbers @cindex major device number @@ -116,6 +123,27 @@ Although the RTEMS I/O manager provides a framework for device drivers, it makes no assumptions regarding the construction or operation of a device driver. +@sybsection Runtime Driver Registration + +@cindex runtime driver registration + +Board support package and application developers can select wether a +device driver is statically entered into the default device table or +registered at runtime. + +Dynamic registration helps applications where: + +@enumerate +@item The BSP and kernel libraries are common to a range of applications +for a specific target platform. An application may be built upon a +common library with all drivers. The application selects and registers +the drivers. Uniform driver name lookup protects the application. +@item The type and range of drivers may vary as the application probes a +bus during initialization. +@item Support for hot swap bus system such as Compact PCI. +@item Support for runtime loadable driver modules. +@end enumerate + @subsection Device Driver Interface @cindex device driver interface @@ -217,6 +245,101 @@ subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes. +@c +@c +@c +@page +@subsection IO_REGISTER_DRIVER - Register a device driver + +@cindex register a device driver + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_io_register_driver +@example +rtems_status_code rtems_io_register_driver( + rtems_device_major_number major, + rtems_driver_address_table *driver_table, + rtems_device_major_number *registered_major +); +@end example +@end ifset + +@ifset is-Ada +@example +No Ada implementation. +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - successfully registered@* +@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number@* +@code{@value{RPREFIX}TOO_MANY} - no available major device table slot@* +@code{@value{RPREFIX}RESOURCE_IN_USE} - major device number entry in use + +@subheading DESCRIPTION: + +This directive attempts to add a new device driver to the Device Driver +Table. The user can specify a specific major device number via the +directive's @code{major} parameter, or let the registration routine find +the next available major device number by specifing a major number of +@code{0}. The selected major device number is returned via the +@code{registered_major} directive parameter. The directive automatically +allocation major device numbers from the highest value down. + +This directive automatically invokes the IO_INITIALIZE directive if +the driver address table has an initialization and open entry. + +The directive returns @value{RPREFIX}TOO_MANY if Device Driver Table is +full, and @value{RPREFIX}RESOURCE_IN_USE if a specific major device +number is requested and it is already in use. + +@subheading NOTES: + +The Device Driver Table size is specified in the Configuration Table +condiguration. This needs to be set to maximum size the application +requires. + + +@c +@c +@c +@page +@subsection IO_UNREGISTER_DRIVER - Unregister a device driver + +@cindex unregister a device driver + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_io_unregister_driver +@example +rtems_status_code rtems_io_register_driver( + rtems_device_major_number major +); +@end example +@end ifset + +@ifset is-Ada +@example +No Ada implementation. +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - successfully registered@* +@code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive removes a device driver from the Device Driver Table. + +@subheading NOTES: + +Currently no specific checks are made and the driver is not closed. + + @c @c @c -- cgit v1.2.3