[PATCH v2 07/16] c-user: Split up IO manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:01:01 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/index.rst | 2 +-
c-user/io/background.rst | 162 ++++++++++++++
c-user/{io_manager.rst => io/directives.rst} | 215 -------------------
c-user/io/index.rst | 16 ++
c-user/io/introduction.rst | 30 +++
c-user/io/operations.rst | 26 +++
6 files changed, 235 insertions(+), 216 deletions(-)
create mode 100644 c-user/io/background.rst
rename c-user/{io_manager.rst => io/directives.rst} (61%)
create mode 100644 c-user/io/index.rst
create mode 100644 c-user/io/introduction.rst
create mode 100644 c-user/io/operations.rst
diff --git a/c-user/index.rst b/c-user/index.rst
index d955cc8..cf73c77 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -43,7 +43,7 @@ RTEMS Classic API Guide (|version|).
partition_manager
region_manager
dual-ported-memory/index
- io_manager
+ io/index
fatal_error
board_support_packages
user_extensions
diff --git a/c-user/io/background.rst b/c-user/io/background.rst
new file mode 100644
index 0000000..28e5369
--- /dev/null
+++ b/c-user/io/background.rst
@@ -0,0 +1,162 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Background
+==========
+
+.. index:: Device Driver Table
+
+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.
+
+.. index:: major device number
+.. index:: minor device number
+
+Major and Minor Device Numbers
+------------------------------
+
+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.
+
+.. index:: device names
+
+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.
+
+.. index:: runtime driver registration
+
+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.
+
+.. index:: device driver interface
+
+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-block:: 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.
diff --git a/c-user/io_manager.rst b/c-user/io/directives.rst
similarity index 61%
rename from c-user/io_manager.rst
rename to c-user/io/directives.rst
index 12282d7..d3098cb 100644
--- a/c-user/io_manager.rst
+++ b/c-user/io/directives.rst
@@ -2,221 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: device drivers
-.. index:: IO Manager
-
-I/O 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
-==========
-
-.. index:: Device Driver Table
-
-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.
-
-.. index:: major device number
-.. index:: minor device number
-
-Major and Minor Device Numbers
-------------------------------
-
-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.
-
-.. index:: device names
-
-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.
-
-.. index:: runtime driver registration
-
-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.
-
-.. index:: device driver interface
-
-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-block:: 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
==========
diff --git a/c-user/io/index.rst b/c-user/io/index.rst
new file mode 100644
index 0000000..0b6ff6f
--- /dev/null
+++ b/c-user/io/index.rst
@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: device drivers
+.. index:: IO Manager
+
+I/O Manager
+***********
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/io/introduction.rst b/c-user/io/introduction.rst
new file mode 100644
index 0000000..e097c7f
--- /dev/null
+++ b/c-user/io/introduction.rst
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+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:
+
+- :ref:`rtems_io_initialize`
+
+- :ref:`rtems_io_register_driver`
+
+- :ref:`rtems_io_unregister_driver`
+
+- :ref:`rtems_io_register_name`
+
+- :ref:`rtems_io_lookup_name`
+
+- :ref:`rtems_io_open`
+
+- :ref:`rtems_io_close`
+
+- :ref:`rtems_io_read`
+
+- :ref:`rtems_io_write`
+
+- :ref:`rtems_io_control`
diff --git a/c-user/io/operations.rst b/c-user/io/operations.rst
new file mode 100644
index 0000000..ec0212d
--- /dev/null
+++ b/c-user/io/operations.rst
@@ -0,0 +1,26 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+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.
--
2.26.2
More information about the devel
mailing list