From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/io_manager.rst | 588 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 588 insertions(+) create mode 100644 c_user/io_manager.rst (limited to 'c_user/io_manager.rst') diff --git a/c_user/io_manager.rst b/c_user/io_manager.rst new file mode 100644 index 0000000..f870580 --- /dev/null +++ b/c_user/io_manager.rst @@ -0,0 +1,588 @@ +I/O Manager +########### + +.. index:: device drivers +.. index:: IO Manager + +Introduction +============ + +The input/output interface manager provides a +well-defined mechanism for accessing device drivers and a +structured methodology for organizing device drivers. The +directives provided by the I/O manager are: + +- ``rtems_io_initialize`` - Initialize a device driver + +- ``rtems_io_register_driver`` - Register a device driver + +- ``rtems_io_unregister_driver`` - Unregister a device driver + +- ``rtems_io_register_name`` - Register a device name + +- ``rtems_io_lookup_name`` - Look up a device name + +- ``rtems_io_open`` - Open a device + +- ``rtems_io_close`` - Close a device + +- ``rtems_io_read`` - Read from a device + +- ``rtems_io_write`` - Write to a device + +- ``rtems_io_control`` - Special device services + +Background +========== + +Device Driver Table +------------------- +.. index:: 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: + +- Initialization + +- Open + +- Close + +- Read + +- Write + +- Control + +If the device driver does not support a particular +entry point, then that entry in the Configuration Table should +be NULL. RTEMS will return``RTEMS_SUCCESSFUL`` as the executive’s and +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 ``CONFIGURE_MAXIMUM_DRIVERS`` configures +the number of driver slots available to the application. + +Major and Minor Device Numbers +------------------------------ +.. index:: major device number +.. index:: minor device number + +Each call to the I/O manager must provide a device’s +major and minor numbers as arguments. The major number is the +index of the requested driver’s entry points in the Device +Driver Table, and is used to select a specific device driver. +The exact usage of the minor number is driver specific, but is +commonly used to distinguish between a number of devices +controlled by the same driver... index:: rtems_device_major_number +.. index:: rtems_device_minor_number + +The data types ``rtems_device_major_number`` and``rtems_device_minor_number`` are used to +manipulate device major and minor numbers, respectively. + +Device Names +------------ +.. index:: device names + +The I/O Manager provides facilities to associate a +name with a particular device. Directives are provided to +register the name of a device and to look up the major/minor +number pair associated with a device name. + +Device Driver Environment +------------------------- + +Application developers, as well as device driver +developers, must be aware of the following regarding the RTEMS +I/O Manager: + +- A device driver routine executes in the context of the + invoking task. Thus if the driver blocks, the invoking task + blocks. + +- The device driver is free to change the modes of the + invoking task, although the driver should restore them to their + original values. + +- Device drivers may be invoked from ISRs. + +- Only local device drivers are accessible through the I/O + manager. + +- A device driver routine may invoke all other RTEMS + directives, including I/O directives, on both local and global + objects. + +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. + +Runtime Driver Registration +--------------------------- +.. index:: 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: + +# 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. + +# The type and range of drivers may vary as the application probes a + bus during initialization. + +# Support for hot swap bus system such as Compact PCI. + +# Support for runtime loadable driver modules. + +Device Driver Interface +----------------------- +.. index:: device driver interface + +When an application invokes an I/O manager directive, +RTEMS determines which device driver entry point must be +invoked. The information passed by the application to RTEMS is +then passed to the correct device driver entry point. RTEMS +will invoke each device driver entry point assuming it is +compatible with the following prototype: +.. code:: c + + rtems_device_driver io_entry( + rtems_device_major_number major, + rtems_device_minor_number minor, + void \*argument_block + ); + +The format and contents of the parameter block are +device driver and entry point dependent. + +It is recommended that a device driver avoid +generating error codes which conflict with those used by +application components. A common technique used to generate +driver specific error codes is to make the most significant part +of the status indicate a driver specific code. + +Device Driver Initialization +---------------------------- + +RTEMS automatically initializes all device drivers +when multitasking is initiated via the``rtems_initialize_executive`` +directive. RTEMS initializes the device drivers by invoking +each device driver initialization entry point with the following +parameters: + +major + the major device number for this device driver. + +minor + zero. + +argument_block + will point to the Configuration Table. + +The returned status will be ignored by RTEMS. If the driver +cannot successfully initialize the device, then it should invoke +the fatal_error_occurred directive. + +Operations +========== + +Register and Lookup Name +------------------------ + +The ``rtems_io_register`` directive associates a name with the +specified device (i.e. major/minor number pair). Device names +are typically registered as part of the device driver +initialization sequence. The ``rtems_io_lookup`` +directive is used to +determine the major/minor number pair associated with the +specified device name. The use of these directives frees the +application from being dependent on the arbitrary assignment of +major numbers in a particular application. No device naming +conventions are dictated by RTEMS. + +Accessing an Device Driver +-------------------------- + +The I/O manager provides directives which enable the +application program to utilize device drivers in a standard +manner. There is a direct correlation between the RTEMS I/O +manager directives``rtems_io_initialize``,``rtems_io_open``,``rtems_io_close``,``rtems_io_read``,``rtems_io_write``, and``rtems_io_control`` +and the underlying device driver entry points. + +Directives +========== + +This section details the I/O manager’s directives. A +subsection is dedicated to each of this manager’s directives and +describes the calling sequence, related constants, usage, and +status codes. + +IO_REGISTER_DRIVER - Register a device driver +--------------------------------------------- +.. index:: register a device driver + +**CALLING SEQUENCE:** + +.. index:: rtems_io_register_driver + +.. code:: c + + rtems_status_code rtems_io_register_driver( + rtems_device_major_number major, + rtems_driver_address_table \*driver_table, + rtems_device_major_number \*registered_major + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully registered +``RTEMS_INVALID_ADDRESS`` - invalid registered major pointer +``RTEMS_INVALID_ADDRESS`` - invalid driver table +``RTEMS_INVALID_NUMBER`` - invalid major device number +``RTEMS_TOO_MANY`` - no available major device table slot +``RTEMS_RESOURCE_IN_USE`` - major device number entry in use + +**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 ``major`` parameter, or let the registration routine find +the next available major device number by specifing a major number of``0``. The selected major device number is returned via the``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 RTEMS_TOO_MANY if Device Driver Table is +full, and RTEMS_RESOURCE_IN_USE if a specific major device +number is requested and it is already in use. + +**NOTES:** + +The Device Driver Table size is specified in the Configuration Table +condiguration. This needs to be set to maximum size the application +requires. + +IO_UNREGISTER_DRIVER - Unregister a device driver +------------------------------------------------- +.. index:: unregister a device driver + +**CALLING SEQUENCE:** + +.. index:: rtems_io_unregister_driver + +.. code:: c + + rtems_status_code rtems_io_unregister_driver( + rtems_device_major_number major + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully registered +``RTEMS_INVALID_NUMBER`` - invalid major device number + +**DESCRIPTION:** + +This directive removes a device driver from the Device Driver Table. + +**NOTES:** + +Currently no specific checks are made and the driver is not closed. + +IO_INITIALIZE - Initialize a device driver +------------------------------------------ +.. index:: initialize a device driver + +**CALLING SEQUENCE:** + +.. index:: rtems_io_initialize + +.. code:: c + + rtems_status_code rtems_io_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor, + void \*argument + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully initialized +``RTEMS_INVALID_NUMBER`` - invalid major device number + +**DESCRIPTION:** + +This directive calls the device driver initialization +routine specified in the Device Driver Table for this major +number. This directive is automatically invoked for each device +driver when multitasking is initiated via the +initialize_executive directive. + +A device driver initialization module is responsible +for initializing all hardware and data structures associated +with a device. If necessary, it can allocate memory to be used +during other operations. + +**NOTES:** + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +initialized. + +IO_REGISTER_NAME - Register a device +------------------------------------ +.. index:: register device + +**CALLING SEQUENCE:** + +.. index:: rtems_io_register_name + +.. code:: c + + rtems_status_code rtems_io_register_name( + const char \*name, + rtems_device_major_number major, + rtems_device_minor_number minor + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully initialized +``RTEMS_TOO_MANY`` - too many devices registered + +**DESCRIPTION:** + +This directive associates name with the specified +major/minor number pair. + +**NOTES:** + +This directive will not cause the calling task to be +preempted. + +IO_LOOKUP_NAME - Lookup a device +-------------------------------- +.. index:: lookup device major and minor number + +**CALLING SEQUENCE:** + +.. index:: rtems_io_lookup_name + +.. code:: c + + rtems_status_code rtems_io_lookup_name( + const char \*name, + rtems_driver_name_t \*device_info + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully initialized +``RTEMS_UNSATISFIED`` - name not registered + +**DESCRIPTION:** + +This directive returns the major/minor number pair +associated with the given device name in ``device_info``. + +**NOTES:** + +This directive will not cause the calling task to be +preempted. + +IO_OPEN - Open a device +----------------------- +.. index:: open a devive + +**CALLING SEQUENCE:** + +.. index:: rtems_io_open + +.. code:: c + + rtems_status_code rtems_io_open( + rtems_device_major_number major, + rtems_device_minor_number minor, + void \*argument + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully initialized +``RTEMS_INVALID_NUMBER`` - invalid major device number + +**DESCRIPTION:** + +This directive calls the device driver open routine +specified in the Device Driver Table for this major number. The +open entry point is commonly used by device drivers to provide +exclusive access to a device. + +**NOTES:** + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +IO_CLOSE - Close a device +------------------------- +.. index:: close a device + +**CALLING SEQUENCE:** + +.. index:: rtems_io_close + +.. code:: c + + rtems_status_code rtems_io_close( + rtems_device_major_number major, + rtems_device_minor_number minor, + void \*argument + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully initialized +``RTEMS_INVALID_NUMBER`` - invalid major device number + +**DESCRIPTION:** + +This directive calls the device driver close routine +specified in the Device Driver Table for this major number. The +close entry point is commonly used by device drivers to +relinquish exclusive access to a device. + +**NOTES:** + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +IO_READ - Read from a device +---------------------------- +.. index:: read from a device + +**CALLING SEQUENCE:** + +.. index:: rtems_io_read + +.. code:: c + + rtems_status_code rtems_io_read( + rtems_device_major_number major, + rtems_device_minor_number minor, + void \*argument + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully initialized +``RTEMS_INVALID_NUMBER`` - invalid major device number + +**DESCRIPTION:** + +This directive calls the device driver read routine +specified in the Device Driver Table for this major number. +Read operations typically require a buffer address as part of +the argument parameter block. The contents of this buffer will +be replaced with data from the device. + +**NOTES:** + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +IO_WRITE - Write to a device +---------------------------- +.. index:: write to a device + +**CALLING SEQUENCE:** + +.. index:: rtems_io_write + +.. code:: c + + rtems_status_code rtems_io_write( + rtems_device_major_number major, + rtems_device_minor_number minor, + void \*argument + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully initialized +``RTEMS_INVALID_NUMBER`` - invalid major device number + +**DESCRIPTION:** + +This directive calls the device driver write routine +specified in the Device Driver Table for this major number. +Write operations typically require a buffer address as part of +the argument parameter block. The contents of this buffer will +be sent to the device. + +**NOTES:** + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +IO_CONTROL - Special device services +------------------------------------ +.. index:: special device services +.. index:: IO Control + +**CALLING SEQUENCE:** + +.. index:: rtems_io_control + +.. code:: c + + rtems_status_code rtems_io_control( + rtems_device_major_number major, + rtems_device_minor_number minor, + void \*argument + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - successfully initialized +``RTEMS_INVALID_NUMBER`` - invalid major device number + +**DESCRIPTION:** + +This directive calls the device driver I/O control +routine specified in the Device Driver Table for this major +number. The exact functionality of the driver entry called by +this directive is driver dependent. It should not be assumed +that the control entries of two device drivers are compatible. +For example, an RS-232 driver I/O control operation may change +the baud rate of a serial line, while an I/O control operation +for a floppy disk driver may cause a seek operation. + +**NOTES:** + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +.. COMMENT: COPYRIGHT (c) 1988-2002. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + -- cgit v1.2.3