RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

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

Browse Source 
* io.t, conf.t: PR 160. Added the IO Manager's register and
	unregister interface documentation.
This commit is contained in:
Joel Sherrill
2002-03-27 14:39:06 +00:00
parent f4c118d7a3
commit 6d0009508f
3 changed files with 156 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/user/ChangeLog
View File

@@ -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.

31
doc/user/conf.t
View File

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

133
doc/user/io.t
View File

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