Changeset 6d00095 in rtems

Timestamp:

03/27/02 14:39:06 (22 years ago)

Author:

Joel Sherrill <joel.sherrill@…>

Branches:

4.10, 4.11, 4.8, 4.9, 5, master

Children:

9b02fa65

Parents:

f4c118d

Message:

2002-03-22 Chris Johns <ccj@…>

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

Location:

doc/user

Files:

• ChangeLog (modified) (1 diff)
• conf.t (modified) (4 diffs)
• io.t (modified) (4 diffs)

doc/user/ChangeLog

@@ +1 @@
+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>
 

doc/user/conf.t

@@ -256 +256 @@
 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
@@ -717 +722 @@
   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;
@@ -801 +807 @@
 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
@@ -1398 +1412 @@
 @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

doc/user/io.t

@@ -36 +36 @@
 @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
@@ -58 +58 @@
 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
 
@@ -116 +123 @@
 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
@@ -222 +250 @@
 @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