[PATCH 1/1] c-user: Generate I/O Manager documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Sep 29 14:59:59 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.
---
c-user/io/directives.rst | 550 ++++++++++++++++++-------------------
c-user/io/introduction.rst | 37 ++-
2 files changed, 295 insertions(+), 292 deletions(-)
diff --git a/c-user/io/directives.rst b/c-user/io/directives.rst
index d3098cb..5ffac5f 100644
--- a/c-user/io/directives.rst
+++ b/c-user/io/directives.rst
@@ -1,421 +1,413 @@
.. 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)
+.. _InputOutputInterfaceManagerDirectives:
+
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.
-
-.. raw:: latex
-
- \clearpage
+.. _InterfaceRtemsIoClose:
-.. index:: register a device driver
-.. index:: rtems_io_register_driver
+rtems_io_close()
+----------------
-.. _rtems_io_register_driver:
-
-IO_REGISTER_DRIVER - Register a device driver
----------------------------------------------
+Closes the device specified by the device major and minor numbers.
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
+ rtems_status_code rtems_io_close(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
);
-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
+DIRECTIVE PARAMETERS:
+ major
+ This parameter is the major number of the device.
-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.
+ minor
+ This parameter is the minor number of the device.
- This directive automatically invokes the ``IO_INITIALIZE`` directive if the
- driver address table has an initialization and open entry.
+ argument
+ This parameter is the argument passed to the device driver close 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.
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
-NOTES:
- The Device Driver Table size is specified in the Configuration Table
- condiguration. This needs to be set to maximum size the application
- requires.
+ RTEMS_INVALID_NUMBER
+ The device major number was invalid.
-.. raw:: latex
+ Other status codes may be returned by the device driver close entry.
- \clearpage
+DESCRIPTION:
+ This directive calls the device driver close entry registered in the Device
+ Driver Table for the specified device major number.
-.. index:: unregister a device driver
-.. index:: rtems_io_unregister_driver
+NOTES:
+ The close entry point is commonly used by device drivers to relinquish
+ exclusive access to a device.
-.. _rtems_io_unregister_driver:
+.. _InterfaceRtemsIoControl:
-IO_UNREGISTER_DRIVER - Unregister a device driver
--------------------------------------------------
+rtems_io_control()
+------------------
+
+Controls the device specified by the device major and minor numbers.
CALLING SEQUENCE:
.. code-block:: c
- rtems_status_code rtems_io_unregister_driver(
- rtems_device_major_number major
+ 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
+DIRECTIVE PARAMETERS:
+ major
+ This parameter is the major number of the device.
- * - ``RTEMS_SUCCESSFUL``
- - successfully registered
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ minor
+ This parameter is the minor number of the device.
-DESCRIPTION:
- This directive removes a device driver from the Device Driver Table.
+ argument
+ This parameter is the argument passed to the device driver I/O control
+ entry.
-NOTES:
- Currently no specific checks are made and the driver is not closed.
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
+
+ RTEMS_INVALID_NUMBER
+ The device major number was invalid.
-.. raw:: latex
+ Other status codes may be returned by the device driver I/O control entry.
+
+DESCRIPTION:
+ This directive calls the device driver I/O control entry registered in the
+ Device Driver Table for the specified device major number.
- \clearpage
+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.
-.. index:: initialize a device driver
-.. index:: rtems_io_initialize
+.. _InterfaceRtemsIoInitialize:
-.. _rtems_io_initialize:
+rtems_io_initialize()
+---------------------
-IO_INITIALIZE - Initialize a device driver
-------------------------------------------
+Initializes the device specified by the device major and minor numbers.
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_io_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
);
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+DIRECTIVE PARAMETERS:
+ 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 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.
+ argument
+ This parameter is the argument passed to the device driver
+ initialization entry.
- 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.
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
-NOTES:
- This directive may or may not cause the calling task to be preempted. This
- is dependent on the device driver being initialized.
+ RTEMS_INVALID_NUMBER
+ The device major number was invalid.
+
+ Other status codes may be returned by the device driver initialization
+ routine.
+
+DESCRIPTION:
+ This directive calls the device driver initialization entry registered in
+ the Device Driver Table for the specified device major number.
-.. raw:: latex
+NOTES:
+ This directive is automatically invoked for each device driver defined by
+ the application configuration during the system initialization and via the
+ :ref:`InterfaceRtemsIoRegisterDriver` directive.
- \clearpage
+ 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.
-.. index:: register device
-.. index:: rtems_io_register_name
+.. _InterfaceRtemsIoOpen:
-.. _rtems_io_register_name:
+rtems_io_open()
+---------------
-IO_REGISTER_NAME - Register a device
-------------------------------------
+Opens the device specified by the device major and minor numbers.
CALLING SEQUENCE:
.. code-block:: c
- rtems_status_code rtems_io_register_name(
- const char *name,
- rtems_device_major_number major,
- rtems_device_minor_number minor
+ rtems_status_code rtems_io_open(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
);
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+DIRECTIVE PARAMETERS:
+ major
+ This parameter is the major number of the device.
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_TOO_MANY``
- - too many devices registered
+ minor
+ This parameter is the minor number of the device.
-DESCRIPTION:
- This directive associates name with the specified major/minor number pair.
+ argument
+ This parameter is the argument passed to the device driver close entry.
-NOTES:
- This directive will not cause the calling task to be preempted.
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
+
+ RTEMS_INVALID_NUMBER
+ The device major number was invalid.
-.. raw:: latex
+ Other status codes may be returned by the device driver open routine.
- \clearpage
+DESCRIPTION:
+ This directive calls the device driver open entry registered in the Device
+ Driver Table for the specified device major number.
+
+NOTES:
+ The open entry point is commonly used by device drivers to provide
+ exclusive access to a device.
-.. index:: lookup device major and minor number
-.. index:: rtems_io_lookup_name
+.. _InterfaceRtemsIoRead:
-.. _rtems_io_lookup_name:
+rtems_io_read()
+---------------
-IO_LOOKUP_NAME - Lookup a device
---------------------------------
+Reads from the device specified by the device major and minor numbers.
CALLING SEQUENCE:
.. code-block:: c
- rtems_status_code rtems_io_lookup_name(
- const char *name,
- rtems_driver_name_t *device_info
+ 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
+DIRECTIVE PARAMETERS:
+ major
+ This parameter is the major number of the device.
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_UNSATISFIED``
- - name not registered
+ minor
+ This parameter is the minor number of the device.
-DESCRIPTION:
- This directive returns the major/minor number pair associated with the
- given device name in ``device_info``.
+ argument
+ This parameter is the argument passed to the device driver read entry.
-NOTES:
- This directive will not cause the calling task to be preempted.
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
-.. raw:: latex
+ RTEMS_INVALID_NUMBER
+ The device major number was invalid.
- \clearpage
+ Other status codes may be returned by the device driver read routine.
-.. index:: open a devive
-.. index:: rtems_io_open
+DESCRIPTION:
+ This directive calls the device driver read entry registered in the Device
+ Driver Table for the specified device major number.
-.. _rtems_io_open:
+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.
+
+.. _InterfaceRtemsIoRegisterDriver:
+
+rtems_io_register_driver()
+--------------------------
-IO_OPEN - Open a device
------------------------
+Registers and initializes the device with the specified device driver address
+table and device major number in the Device Driver Table.
CALLING SEQUENCE:
.. code-block:: c
- rtems_status_code rtems_io_open(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
+ 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
);
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+DIRECTIVE PARAMETERS:
+ major
+ This parameter is the device major number. Use a value of zero to let
+ the system obtain a device major number automatically.
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ driver_table
+ This parameter is the device driver address table.
-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.
+ 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.
-NOTES:
- This directive may or may not cause the calling task to be preempted. This
- is dependent on the device driver being invoked.
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
-.. raw:: latex
+ RTEMS_INVALID_ADDRESS
+ The device major number of the device was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
- \clearpage
+ RTEMS_INVALID_ADDRESS
+ The device driver address table was empty.
-.. index:: close a device
-.. index:: rtems_io_close
+ RTEMS_INVALID_NUMBER
+ The device major number of the device was out of range, see
+ :ref:`CONFIGURE_MAXIMUM_DRIVERS`.
-.. _rtems_io_close:
+ RTEMS_TOO_MANY
+ The system was unable to obtain a device major number.
-IO_CLOSE - Close a device
--------------------------
+ RTEMS_RESOURCE_IN_USE
+ The device major number was in use.
-CALLING SEQUENCE:
- .. code-block:: c
+ RTEMS_CALLED_FROM_ISR
+ The directive was called from interrupt context.
- rtems_status_code rtems_io_close(
- 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 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.
+ Other status codes may be returned by the device driver initialization
+ routine.
NOTES:
- This directive may or may not cause the calling task to be preempted. This
- is dependent on the device driver being invoked.
+ 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.
-.. raw:: latex
+ After a successful registration :ref:`InterfaceRtemsIoInitialize` routine
+ will be called to initialize the device.
- \clearpage
+.. _InterfaceRtemsIoRegisterName:
-.. index:: read from a device
-.. index:: rtems_io_read
+rtems_io_register_name()
+------------------------
-.. _rtems_io_read:
-
-IO_READ - Read from a device
-----------------------------
+Registers the device specified by the device major and minor numbers in the
+file system under the specified name.
CALLING SEQUENCE:
.. 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_register_name(
+ const char *device_name,
+ rtems_device_major_number major,
+ rtems_device_minor_number minor
);
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+DIRECTIVE PARAMETERS:
+ device_name
+ This parameter is the device name in the file system.
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ major
+ This parameter is the device major 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.
+ minor
+ This parameter is the device minor number.
-.. raw:: latex
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
- \clearpage
+ RTEMS_TOO_MANY
+ The name was already in use or other errors occurred.
-.. index:: write to a device
-.. index:: rtems_io_write
+NOTES:
+ The device is registered as a character device.
-.. _rtems_io_write:
+.. _InterfaceRtemsIoUnregisterDriver:
-IO_WRITE - Write to a device
+rtems_io_unregister_driver()
----------------------------
+Removes a device driver specified by the device major number from the Device
+Driver Table.
+
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_unregister_driver(
+ rtems_device_major_number major
);
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+DIRECTIVE PARAMETERS:
+ major
+ This parameter is the major number of the device.
- * - ``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.
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
-NOTES:
- This directive may or may not cause the calling task to be preempted. This
- is dependent on the device driver being invoked.
+ RTEMS_UNSATISFIED
+ The device major number was invalid.
-.. raw:: latex
+ RTEMS_CALLED_FROM_ISR
+ The directive was called from interrupt context.
- \clearpage
+NOTES:
+ Currently no specific checks are made and the driver is not closed.
-.. index:: special device services
-.. index:: IO Control
-.. index:: rtems_io_control
+.. _InterfaceRtemsIoWrite:
-.. _rtems_io_control:
+rtems_io_write()
+----------------
-IO_CONTROL - Special device services
-------------------------------------
+Writes to the device specified by the device major and minor numbers.
CALLING SEQUENCE:
.. code-block:: c
- rtems_status_code rtems_io_control(
- 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
);
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+DIRECTIVE 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 write entry.
+
+DIRECTIVE RETURN VALUES:
+ RTEMS_SUCCESSFUL
+ The requested operation was successful.
+
+ RTEMS_INVALID_NUMBER
+ The device major number was invalid.
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ Other status codes may be returned by the device driver write routine.
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.
+ This directive calls the device driver write entry registered in the Device
+ Driver Table for the specified device major number.
NOTES:
- This directive may or may not cause the calling task to be preempted. This
- is dependent on the device driver being invoked.
+ 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.
diff --git a/c-user/io/introduction.rst b/c-user/io/introduction.rst
index e097c7f..cb4900b 100644
--- a/c-user/io/introduction.rst
+++ b/c-user/io/introduction.rst
@@ -1,30 +1,41 @@
.. 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)
+.. _InputOutputInterfaceManagerIntroduction:
+
Introduction
============
-The input/output interface manager provides a well-defined mechanism for
+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`
+drivers. The directives provided by the Input/Output Interface Manager are:
-- :ref:`rtems_io_register_driver`
+* :ref:`InterfaceRtemsIoClose` - Closes the device specified by the device
+ major and minor numbers.
-- :ref:`rtems_io_unregister_driver`
+* :ref:`InterfaceRtemsIoControl` - Controls the device specified by the device
+ major and minor numbers.
-- :ref:`rtems_io_register_name`
+* :ref:`InterfaceRtemsIoInitialize` - Initializes the device specified by the
+ device major and minor numbers.
-- :ref:`rtems_io_lookup_name`
+* :ref:`InterfaceRtemsIoOpen` - Opens the device specified by the device major
+ and minor numbers.
-- :ref:`rtems_io_open`
+* :ref:`InterfaceRtemsIoRead` - Reads from the device specified by the device
+ major and minor numbers.
-- :ref:`rtems_io_close`
+* :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_read`
+* :ref:`InterfaceRtemsIoRegisterName` - Registers the device specified by the
+ device major and minor numbers in the file system under the specified name.
-- :ref:`rtems_io_write`
+* :ref:`InterfaceRtemsIoUnregisterDriver` - Removes a device driver specified
+ by the device major number from the Device Driver Table.
-- :ref:`rtems_io_control`
+* :ref:`InterfaceRtemsIoWrite` - Writes to the device specified by the device
+ major and minor numbers.
--
2.26.2
More information about the devel
mailing list