summaryrefslogtreecommitdiffstats
path: root/c_user/io_manager.rst
diff options
context:
space:
mode:
Diffstat (limited to 'c_user/io_manager.rst')
-rw-r--r--c_user/io_manager.rst588
1 files changed, 588 insertions, 0 deletions
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.
+
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-24 04:53:27 +0000