2002-03-22 Chris Johns <ccj@acm.org>

	* io.t, conf.t: PR 160. Added the IO Manager's register and
	unregister interface documentation.

3 files changed, 156 insertions, 13 deletions

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 <ccj@acm.org>
+
+	* io.t, conf.t: PR 160. Added the IO Manager's register and 
+	unregister interface documentation.
+
 2002-03-15	Eric Norum <eric.norum@usask.ca>
 
 	* 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
@@ -221,6 +249,101 @@ status codes.
 @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
+@page
 @subsection IO_INITIALIZE - Initialize a device driver
 
 @cindex initialize a device driver