[PATCH v3] c-user: Generate I/O Manager documentation

Sebastian Huber sebastian.huber at embedded-brains.de
Tue Oct 6 08:30:29 UTC 2020


The manager documentation is a consolidation of the comments in Doxygen
markup and the documentation sources in Sphinx markup.  The
documentation was transfered to interface specification items.  This
header file was generated from the items by a script.

Update #3993.
---
v2:

* Add comments to mention the specification items which produced a
  content block.

* Preserve original directive order.

* Re-order sections so that the description is between the calling
  sequence and the return values.

* Use .. rubric instead of nested definition lists to fix the vertical
  spacing.

* Add custom document index entries.

v3:

* Improve automatically generated warning comment on top of the files

* Fix list layout in HTML output

* Add directive section boilerplate

* Drop "DIRECTIVE" from subsection titles ("PARAMETERS",
  "RETURN VALUES")

Generated PDF:

https://ftp.rtems.org/pub/rtems/people/sebh/c-user-7.pdf

Generated HTML:

https://ftp.rtems.org/pub/rtems/people/sebh/c-user/html/index.html
 c-user/io/directives.rst   | 735 ++++++++++++++++++++++---------------
 c-user/io/introduction.rst |  62 +++-
 2 files changed, 481 insertions(+), 316 deletions(-)

diff --git a/c-user/io/directives.rst b/c-user/io/directives.rst
index d3098cb..7316f5a 100644
--- a/c-user/io/directives.rst
+++ b/c-user/io/directives.rst
@@ -1,421 +1,550 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 
+.. Do not manually edit this file.  It is part of the RTEMS quality process
+.. and was automatically generated.
+..
+.. If you find something that needs to be fixed or worded better please
+.. post a report to an RTEMS mailing list or raise a bug report:
+..
+.. https://docs.rtems.org/branches/master/user/support/bugs.html
+..
+.. For information on updating and regenerating please refer to:
+..
+.. https://docs.rtems.org/branches/master/eng/req/howto.html
+
+.. _IOManagerDirectives:
+
 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.
+This section details the directives of the I/O Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/io/if/register-driver
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_io_register_driver()
 .. index:: register a device driver
-.. index:: rtems_io_register_driver
-
-.. _rtems_io_register_driver:
-
-IO_REGISTER_DRIVER - Register a device driver
----------------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: 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:
-    .. list-table::
-     :class: rtems-table
-
-     * - ``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.
+
+.. _InterfaceRtemsIoRegisterDriver:
+
+rtems_io_register_driver()
+--------------------------
+
+Registers and initializes the device with the specified device driver address
+table and device major number in the Device Driver Table.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    rtems_status_code rtems_io_register_driver(
+      rtems_device_major_number         major,
+      const rtems_driver_address_table *driver_table,
+      rtems_device_major_number        *registered_major
+    );
+
+.. rubric:: PARAMETERS:
+
+major
+    This parameter is the device major number.  Use a value of zero to let the
+    system obtain a device major number automatically.
+
+driver_table
+    This parameter is the device driver address table.
+
+registered_major
+    This parameter is the pointer to a device major number variable.  The
+    device major number of the registered device will be stored in this
+    variable, in case of a successful operation.
+
+.. rubric:: RETURN VALUES:
+
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
+
+RTEMS_INVALID_ADDRESS
+    The device major number of the device was `NULL
+    <https://en.cppreference.com/w/c/types/NULL>`_.
+
+RTEMS_INVALID_ADDRESS
+    The device driver address table was empty.
+
+RTEMS_INVALID_NUMBER
+    The device major number of the device was out of range, see
+    :ref:`CONFIGURE_MAXIMUM_DRIVERS`.
+
+RTEMS_TOO_MANY
+    The system was unable to obtain a device major number.
+
+RTEMS_RESOURCE_IN_USE
+    The device major number was already in use.
+
+RTEMS_CALLED_FROM_ISR
+    The directive was called from interrupt context.
+
+Other status codes may be returned by :ref:`InterfaceRtemsIoInitialize`.
+
+.. rubric:: NOTES:
+
+If the device major number equals zero a device major number will be obtained.
+The device major number of the registered driver will be returned.
+
+After a successful registration, the :ref:`InterfaceRtemsIoInitialize`
+directive will be called to initialize the device.
+
+.. Generated from spec:/rtems/io/if/unregister-driver
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_io_unregister_driver()
 .. index:: unregister a device driver
-.. index:: rtems_io_unregister_driver
 
-.. _rtems_io_unregister_driver:
+.. _InterfaceRtemsIoUnregisterDriver:
+
+rtems_io_unregister_driver()
+----------------------------
+
+Removes a device driver specified by the device major number from the Device
+Driver Table.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    rtems_status_code rtems_io_unregister_driver(
+      rtems_device_major_number major
+    );
+
+.. rubric:: PARAMETERS:
+
+major
+    This parameter is the major number of the device.
 
-IO_UNREGISTER_DRIVER - Unregister a device driver
--------------------------------------------------
+.. rubric:: RETURN VALUES:
 
-CALLING SEQUENCE:
-    .. code-block:: c
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
 
-        rtems_status_code rtems_io_unregister_driver(
-            rtems_device_major_number   major
-        );
+RTEMS_UNSATISFIED
+    The device major number was invalid.
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+RTEMS_CALLED_FROM_ISR
+    The directive was called from interrupt context.
 
-     * - ``RTEMS_SUCCESSFUL``
-       - successfully registered
-     * - ``RTEMS_INVALID_NUMBER``
-       - invalid major device number
+.. rubric:: NOTES:
 
-DESCRIPTION:
-    This directive removes a device driver from the Device Driver Table.
+Currently no specific checks are made and the driver is not closed.
 
-NOTES:
-    Currently no specific checks are made and the driver is not closed.
+.. Generated from spec:/rtems/io/if/initialize
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_io_initialize()
 .. index:: initialize a device driver
-.. index:: rtems_io_initialize
 
-.. _rtems_io_initialize:
+.. _InterfaceRtemsIoInitialize:
 
-IO_INITIALIZE - Initialize a device driver
-------------------------------------------
+rtems_io_initialize()
+---------------------
 
-CALLING SEQUENCE:
-    .. code-block:: c
+Initializes the device specified by the device major and minor numbers.
 
-        rtems_status_code rtems_io_initialize(
-            rtems_device_major_number  major,
-            rtems_device_minor_number  minor,
-            void                      *argument
-        );
+.. rubric:: CALLING SEQUENCE:
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+.. code-block:: c
 
-     * - ``RTEMS_SUCCESSFUL``
-       - successfully initialized
-     * - ``RTEMS_INVALID_NUMBER``
-       - invalid major device number
+    rtems_status_code rtems_io_initialize(
+      rtems_device_major_number major,
+      rtems_device_minor_number minor,
+      void                     *argument
+    );
 
-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.
+.. rubric:: PARAMETERS:
 
-    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.
+major
+    This parameter is the major number of the device.
 
-NOTES:
-    This directive may or may not cause the calling task to be preempted.  This
-    is dependent on the device driver being initialized.
+minor
+    This parameter is the minor number of the device.
 
-.. raw:: latex
+argument
+    This parameter is the argument passed to the device driver initialization
+    entry.
 
-   \clearpage
+.. rubric:: DESCRIPTION:
 
-.. index:: register device
-.. index:: rtems_io_register_name
+This directive calls the device driver initialization entry registered in the
+Device Driver Table for the specified device major number.
 
-.. _rtems_io_register_name:
+.. rubric:: RETURN VALUES:
 
-IO_REGISTER_NAME - Register a device
-------------------------------------
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
 
-CALLING SEQUENCE:
-    .. code-block:: c
+RTEMS_INVALID_NUMBER
+    The device major number was invalid.
 
-        rtems_status_code rtems_io_register_name(
-            const char                *name,
-            rtems_device_major_number  major,
-            rtems_device_minor_number  minor
-        );
+Other status codes may be returned by the device driver initialization entry.
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+.. rubric:: NOTES:
 
-     * - ``RTEMS_SUCCESSFUL``
-       - successfully initialized
-     * - ``RTEMS_TOO_MANY``
-       - too many devices registered
+This directive is automatically invoked for each device driver defined by the
+application configuration during the system initialization and via the
+:ref:`InterfaceRtemsIoRegisterDriver` directive.
 
-DESCRIPTION:
-    This directive associates name with the specified major/minor number pair.
+A device driver initialization entry 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 will not cause the calling task to be preempted.
+.. Generated from spec:/rtems/io/if/register-name
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
+
+.. index:: rtems_io_register_name()
+.. index:: register a device in the file system
+
+.. _InterfaceRtemsIoRegisterName:
+
+rtems_io_register_name()
+------------------------
+
+Registers the device specified by the device major and minor numbers in the
+file system under the specified name.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
 
-.. index:: lookup device major and minor number
-.. index:: rtems_io_lookup_name
+    rtems_status_code rtems_io_register_name(
+      const char               *device_name,
+      rtems_device_major_number major,
+      rtems_device_minor_number minor
+    );
 
-.. _rtems_io_lookup_name:
+.. rubric:: PARAMETERS:
 
-IO_LOOKUP_NAME - Lookup a device
---------------------------------
+device_name
+    This parameter is the device name in the file system.
 
-CALLING SEQUENCE:
-    .. code-block:: c
+major
+    This parameter is the device major number.
 
-        rtems_status_code rtems_io_lookup_name(
-            const char          *name,
-            rtems_driver_name_t *device_info
-        );
+minor
+    This parameter is the device minor number.
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+.. rubric:: RETURN VALUES:
 
-     * - ``RTEMS_SUCCESSFUL``
-       - successfully initialized
-     * - ``RTEMS_UNSATISFIED``
-       - name not registered
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
 
-DESCRIPTION:
-    This directive returns the major/minor number pair associated with the
-    given device name in ``device_info``.
+RTEMS_TOO_MANY
+    The name was already in use or other errors occurred.
 
-NOTES:
-    This directive will not cause the calling task to be preempted.
+.. rubric:: NOTES:
+
+The device is registered as a character device.
+
+.. Generated from spec:/rtems/io/if/open
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
+
+.. index:: rtems_io_open()
+.. index:: open a device
+
+.. _InterfaceRtemsIoOpen:
+
+rtems_io_open()
+---------------
+
+Opens the device specified by the device major and minor numbers.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    rtems_status_code rtems_io_open(
+      rtems_device_major_number major,
+      rtems_device_minor_number minor,
+      void                     *argument
+    );
+
+.. rubric:: PARAMETERS:
+
+major
+    This parameter is the major number of the device.
+
+minor
+    This parameter is the minor number of the device.
+
+argument
+    This parameter is the argument passed to the device driver close entry.
 
-.. index:: open a devive
-.. index:: rtems_io_open
+.. rubric:: DESCRIPTION:
 
-.. _rtems_io_open:
+This directive calls the device driver open entry registered in the Device
+Driver Table for the specified device major number.
 
-IO_OPEN - Open a device
------------------------
+.. rubric:: RETURN VALUES:
 
-CALLING SEQUENCE:
-    .. code-block:: c
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
 
-        rtems_status_code rtems_io_open(
-            rtems_device_major_number  major,
-            rtems_device_minor_number  minor,
-            void                      *argument
-        );
+RTEMS_INVALID_NUMBER
+    The device major number was invalid.
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+Other status codes may be returned by the device driver open entry.
 
-     * - ``RTEMS_SUCCESSFUL``
-       - successfully initialized
-     * - ``RTEMS_INVALID_NUMBER``
-       - invalid major device number
+.. rubric:: NOTES:
 
-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.
+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.
+.. Generated from spec:/rtems/io/if/close
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_io_close()
 .. index:: close a device
-.. index:: rtems_io_close
 
-.. _rtems_io_close:
+.. _InterfaceRtemsIoClose:
 
-IO_CLOSE - Close a device
--------------------------
+rtems_io_close()
+----------------
 
-CALLING SEQUENCE:
-    .. code-block:: c
+Closes the device specified by the device major and minor numbers.
 
-        rtems_status_code rtems_io_close(
-            rtems_device_major_number  major,
-            rtems_device_minor_number  minor,
-            void                      *argument
-        );
+.. rubric:: CALLING SEQUENCE:
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+.. code-block:: c
 
-     * - ``RTEMS_SUCCESSFUL``
-       - successfully initialized
-     * - ``RTEMS_INVALID_NUMBER``
-       - invalid major device number
+    rtems_status_code rtems_io_close(
+      rtems_device_major_number major,
+      rtems_device_minor_number minor,
+      void                     *argument
+    );
 
-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.
+.. rubric:: PARAMETERS:
 
-NOTES:
-    This directive may or may not cause the calling task to be preempted.  This
-    is dependent on the device driver being invoked.
+major
+    This parameter is the major number of the device.
+
+minor
+    This parameter is the minor number of the device.
+
+argument
+    This parameter is the argument passed to the device driver close entry.
+
+.. rubric:: DESCRIPTION:
+
+This directive calls the device driver close entry registered in the Device
+Driver Table for the specified device major number.
+
+.. rubric:: RETURN VALUES:
+
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
+
+RTEMS_INVALID_NUMBER
+    The device major number was invalid.
+
+Other status codes may be returned by the device driver close entry.
+
+.. rubric:: NOTES:
+
+The close entry point is commonly used by device drivers to relinquish
+exclusive access to a device.
+
+.. Generated from spec:/rtems/io/if/read
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_io_read()
 .. index:: read from a device
-.. index:: rtems_io_read
 
-.. _rtems_io_read:
+.. _InterfaceRtemsIoRead:
 
-IO_READ - Read from a device
-----------------------------
+rtems_io_read()
+---------------
+
+Reads from the device specified by the device major and minor numbers.
+
+.. rubric:: CALLING SEQUENCE:
 
-CALLING SEQUENCE:
-    .. code-block:: c
+.. code-block:: c
 
-        rtems_status_code rtems_io_read(
-            rtems_device_major_number  major,
-            rtems_device_minor_number  minor,
-            void                      *argument
-        );
+    rtems_status_code rtems_io_read(
+      rtems_device_major_number major,
+      rtems_device_minor_number minor,
+      void                     *argument
+    );
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+.. rubric:: PARAMETERS:
 
-     * - ``RTEMS_SUCCESSFUL``
-       - successfully initialized
-     * - ``RTEMS_INVALID_NUMBER``
-       - invalid major device number
+major
+    This parameter is the major number of the device.
 
-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.
+minor
+    This parameter is the minor number of 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.
+argument
+    This parameter is the argument passed to the device driver read entry.
+
+.. rubric:: DESCRIPTION:
+
+This directive calls the device driver read entry registered in the Device
+Driver Table for the specified device major number.
+
+.. rubric:: RETURN VALUES:
+
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
+
+RTEMS_INVALID_NUMBER
+    The device major number was invalid.
+
+Other status codes may be returned by the device driver read entry.
+
+.. rubric:: NOTES:
+
+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.
+
+.. Generated from spec:/rtems/io/if/write
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_io_write()
 .. index:: write to a device
-.. index:: rtems_io_write
 
-.. _rtems_io_write:
+.. _InterfaceRtemsIoWrite:
 
-IO_WRITE - Write to a device
-----------------------------
+rtems_io_write()
+----------------
+
+Writes to the device specified by the device major and minor numbers.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
 
-CALLING SEQUENCE:
-    .. code-block:: c
+    rtems_status_code rtems_io_write(
+      rtems_device_major_number major,
+      rtems_device_minor_number minor,
+      void                     *argument
+    );
 
-        rtems_status_code rtems_io_write(
-            rtems_device_major_number  major,
-            rtems_device_minor_number  minor,
-            void                      *argument
-        );
+.. rubric:: PARAMETERS:
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+major
+    This parameter is the major number of the device.
 
-     * - ``RTEMS_SUCCESSFUL``
-       - successfully initialized
-     * - ``RTEMS_INVALID_NUMBER``
-       - invalid major device number
+minor
+    This parameter is the minor number of the device.
 
-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.
+argument
+    This parameter is the argument passed to the device driver write entry.
 
-NOTES:
-    This directive may or may not cause the calling task to be preempted.  This
-    is dependent on the device driver being invoked.
+.. rubric:: DESCRIPTION:
+
+This directive calls the device driver write entry registered in the Device
+Driver Table for the specified device major number.
+
+.. rubric:: RETURN VALUES:
+
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
+
+RTEMS_INVALID_NUMBER
+    The device major number was invalid.
+
+Other status codes may be returned by the device driver write entry.
+
+.. rubric:: NOTES:
+
+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.
+
+.. Generated from spec:/rtems/io/if/control
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_io_control()
+.. index:: IO control
 .. index:: special device services
-.. index:: IO Control
-.. index:: rtems_io_control
-
-.. _rtems_io_control:
-
-IO_CONTROL - Special device services
-------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        rtems_status_code rtems_io_control(
-            rtems_device_major_number  major,
-            rtems_device_minor_number  minor,
-            void                      *argument
-        );
-
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
-
-     * - ``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.
+
+.. _InterfaceRtemsIoControl:
+
+rtems_io_control()
+------------------
+
+Controls the device specified by the device major and minor numbers.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    rtems_status_code rtems_io_control(
+      rtems_device_major_number major,
+      rtems_device_minor_number minor,
+      void                     *argument
+    );
+
+.. rubric:: PARAMETERS:
+
+major
+    This parameter is the major number of the device.
+
+minor
+    This parameter is the minor number of the device.
+
+argument
+    This parameter is the argument passed to the device driver I/O control
+    entry.
+
+.. rubric:: DESCRIPTION:
+
+This directive calls the device driver I/O control entry registered in the
+Device Driver Table for the specified device major number.
+
+.. rubric:: RETURN VALUES:
+
+RTEMS_SUCCESSFUL
+    The requested operation was successful.
+
+RTEMS_INVALID_NUMBER
+    The device major number was invalid.
+
+Other status codes may be returned by the device driver I/O control entry.
+
+.. rubric:: NOTES:
+
+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.
diff --git a/c-user/io/introduction.rst b/c-user/io/introduction.rst
index e097c7f..3432738 100644
--- a/c-user/io/introduction.rst
+++ b/c-user/io/introduction.rst
@@ -1,30 +1,66 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 
+.. Do not manually edit this file.  It is part of the RTEMS quality process
+.. and was automatically generated.
+..
+.. If you find something that needs to be fixed or worded better please
+.. post a report to an RTEMS mailing list or raise a bug report:
+..
+.. https://docs.rtems.org/branches/master/user/support/bugs.html
+..
+.. For information on updating and regenerating please refer to:
+..
+.. https://docs.rtems.org/branches/master/eng/req/howto.html
+
+.. Generated from spec:/rtems/io/if/group
+
+.. _IOManagerIntroduction:
+
 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:
+The Input/Output (I/O) 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`
+.. The following list was generated from:
+.. spec:/rtems/io/if/register-driver
+.. spec:/rtems/io/if/unregister-driver
+.. spec:/rtems/io/if/initialize
+.. spec:/rtems/io/if/register-name
+.. spec:/rtems/io/if/open
+.. spec:/rtems/io/if/close
+.. spec:/rtems/io/if/read
+.. spec:/rtems/io/if/write
+.. spec:/rtems/io/if/control
 
-- :ref:`rtems_io_register_driver`
+* :ref:`InterfaceRtemsIoRegisterDriver` - Registers and initializes the device
+  with the specified device driver address table and device major number in the
+  Device Driver Table.
 
-- :ref:`rtems_io_unregister_driver`
+* :ref:`InterfaceRtemsIoUnregisterDriver` - Removes a device driver specified
+  by the device major number from the Device Driver Table.
 
-- :ref:`rtems_io_register_name`
+* :ref:`InterfaceRtemsIoInitialize` - Initializes the device specified by the
+  device major and minor numbers.
 
-- :ref:`rtems_io_lookup_name`
+* :ref:`InterfaceRtemsIoRegisterName` - Registers the device specified by the
+  device major and minor numbers in the file system under the specified name.
 
-- :ref:`rtems_io_open`
+* :ref:`InterfaceRtemsIoOpen` - Opens the device specified by the device major
+  and minor numbers.
 
-- :ref:`rtems_io_close`
+* :ref:`InterfaceRtemsIoClose` - Closes the device specified by the device
+  major and minor numbers.
 
-- :ref:`rtems_io_read`
+* :ref:`InterfaceRtemsIoRead` - Reads from the device specified by the device
+  major and minor numbers.
 
-- :ref:`rtems_io_write`
+* :ref:`InterfaceRtemsIoWrite` - Writes to the device specified by the device
+  major and minor numbers.
 
-- :ref:`rtems_io_control`
+* :ref:`InterfaceRtemsIoControl` - Controls the device specified by the device
+  major and minor numbers.
-- 
2.26.2



More information about the devel mailing list