Ticket #160: io-dynreg-doc.patch

Index: conf.t
===================================================================
RCS file: /usr1/CVS/rtems/doc/user/conf.t,v
retrieving revision 1.30
diff -c -r1.30 conf.t
*** conf.t      2002/01/17 21:47:47     1.30
--- conf.t      2002/03/21 18:19:08
***************
*** 255,260 ****
--- 255,265 ----
  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,721 ****
--- 721,727 ----
    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,805 ****
--- 806,819 ----
  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,1410 ****
  
  @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}:
  
  @ifset is-C
  @findex rtems_driver_address_table
--- 1411,1425 ----
  
  @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.  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
Index: io.t
===================================================================
RCS file: /usr1/CVS/rtems/doc/user/io.t,v
retrieving revision 1.14
diff -c -r1.14 io.t
*** io.t        2002/01/17 21:47:47     1.14
--- io.t        2002/03/21 18:19:08
***************
*** 35,45 ****
  
  @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:
  
  @itemize @bullet
  @item Initialization
--- 35,45 ----
  
  @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 that is to be initialised by
! RTEMS during initialization.  Each device driver may contain the
! following entry points:
  
  @itemize @bullet
  @item Initialization
***************
*** 57,62 ****
--- 57,69 ----
  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,121 ****
--- 123,149 ----
  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
***************
*** 216,221 ****
--- 244,344 ----
  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
0a1,5
> 2002-03-22      Chris Johns <ccj@acm.org>
> 
>         * io.t, conf.t: PR 160. Added the IO Manager's register and 
>           unregister interface documentation.
>