summaryrefslogtreecommitdiffstats
path: root/c-user/io_manager.rst
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-11-08 15:26:50 +1100
committerChris Johns <chrisj@rtems.org>2016-11-08 15:28:32 +1100
commit53bb72e99669750ecbd7a418047711a21e32ac40 (patch)
treeb0cd10cb72041c45696ae9540c406b83ed1e62cb /c-user/io_manager.rst
parentpdf: Format lists for directives to sit on the next line. (diff)
downloadrtems-docs-53bb72e99669750ecbd7a418047711a21e32ac40.tar.bz2
c-user: Format the directives as descriptions.
This change combined with the element list change in latex generates a much better looking PDF. Add a page break before each directive to like th previous versions of the manuals.
Diffstat (limited to 'c-user/io_manager.rst')
-rw-r--r--c-user/io_manager.rst535
1 files changed, 263 insertions, 272 deletions
diff --git a/c-user/io_manager.rst b/c-user/io_manager.rst
index 50340c9..74ca5b1 100644
--- a/c-user/io_manager.rst
+++ b/c-user/io_manager.rst
@@ -221,371 +221,367 @@ 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
+
.. _rtems_io_register_driver:
IO_REGISTER_DRIVER - Register a device driver
---------------------------------------------
.. index:: register a device driver
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_register_driver
-.. 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.
+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.
+
+.. raw:: latex
+
+ \clearpage
.. _rtems_io_unregister_driver:
IO_UNREGISTER_DRIVER - Unregister a device driver
-------------------------------------------------
.. index:: unregister a device driver
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_unregister_driver
-.. code-block:: c
-
- rtems_status_code rtems_io_unregister_driver(
- rtems_device_major_number major
- );
+CALLING SEQUENCE:
+ .. code-block:: c
-**DIRECTIVE STATUS CODES:**
+ rtems_status_code rtems_io_unregister_driver(
+ rtems_device_major_number major
+ );
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+ .. list-table::
+ :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - successfully registered
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ * - ``RTEMS_SUCCESSFUL``
+ - successfully registered
+ * - ``RTEMS_INVALID_NUMBER``
+ - invalid major device number
-**DESCRIPTION:**
+DESCRIPTION:
+ This directive removes a device driver from the Device Driver Table.
-This directive removes a device driver from the Device Driver Table.
+NOTES:
+ Currently no specific checks are made and the driver is not closed.
-**NOTES:**
+.. raw:: latex
-Currently no specific checks are made and the driver is not closed.
+ \clearpage
.. _rtems_io_initialize:
IO_INITIALIZE - Initialize a device driver
------------------------------------------
.. index:: initialize a device driver
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_initialize
-.. code-block:: c
-
- rtems_status_code rtems_io_initialize(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
- );
+CALLING SEQUENCE:
+ .. code-block:: c
-**DIRECTIVE STATUS CODES:**
+ rtems_status_code rtems_io_initialize(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+ );
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+ .. list-table::
+ :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ * - ``RTEMS_SUCCESSFUL``
+ - successfully initialized
+ * - ``RTEMS_INVALID_NUMBER``
+ - invalid major device number
-**DESCRIPTION:**
+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.
-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.
-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.
-**NOTES:**
+.. raw:: latex
-This directive may or may not cause the calling task to be preempted. This is
-dependent on the device driver being initialized.
+ \clearpage
.. _rtems_io_register_name:
IO_REGISTER_NAME - Register a device
------------------------------------
.. index:: register device
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_register_name
-.. code-block:: c
-
- rtems_status_code rtems_io_register_name(
- const char *name,
- rtems_device_major_number major,
- rtems_device_minor_number minor
- );
+CALLING SEQUENCE:
+ .. code-block:: c
-**DIRECTIVE STATUS CODES:**
+ rtems_status_code rtems_io_register_name(
+ const char *name,
+ rtems_device_major_number major,
+ rtems_device_minor_number minor
+ );
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+ .. list-table::
+ :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_TOO_MANY``
- - too many devices registered
+ * - ``RTEMS_SUCCESSFUL``
+ - successfully initialized
+ * - ``RTEMS_TOO_MANY``
+ - too many devices registered
-**DESCRIPTION:**
+DESCRIPTION:
+ This directive associates name with the specified major/minor number pair.
-This directive associates name with the specified major/minor number pair.
+NOTES:
+ This directive will not cause the calling task to be preempted.
-**NOTES:**
+.. raw:: latex
-This directive will not cause the calling task to be preempted.
+ \clearpage
.. _rtems_io_lookup_name:
IO_LOOKUP_NAME - Lookup a device
--------------------------------
.. index:: lookup device major and minor number
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_lookup_name
-.. code-block:: c
-
- rtems_status_code rtems_io_lookup_name(
- const char *name,
- rtems_driver_name_t *device_info
- );
+CALLING SEQUENCE:
+ .. code-block:: c
-**DIRECTIVE STATUS CODES:**
+ rtems_status_code rtems_io_lookup_name(
+ const char *name,
+ rtems_driver_name_t *device_info
+ );
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+ .. list-table::
+ :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_UNSATISFIED``
- - name not registered
+ * - ``RTEMS_SUCCESSFUL``
+ - successfully initialized
+ * - ``RTEMS_UNSATISFIED``
+ - name not registered
-**DESCRIPTION:**
+DESCRIPTION:
+ This directive returns the major/minor number pair associated with the
+ given device name in ``device_info``.
-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.
-**NOTES:**
+.. raw:: latex
-This directive will not cause the calling task to be preempted.
+ \clearpage
.. _rtems_io_open:
IO_OPEN - Open a device
-----------------------
.. index:: open a devive
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_open
-.. code-block:: c
-
- rtems_status_code rtems_io_open(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
- );
+CALLING SEQUENCE:
+ .. code-block:: c
-**DIRECTIVE STATUS CODES:**
+ rtems_status_code rtems_io_open(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+ );
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+ .. list-table::
+ :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ * - ``RTEMS_SUCCESSFUL``
+ - successfully initialized
+ * - ``RTEMS_INVALID_NUMBER``
+ - invalid major device number
-**DESCRIPTION:**
+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.
-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.
-**NOTES:**
+.. raw:: latex
-This directive may or may not cause the calling task to be preempted. This is
-dependent on the device driver being invoked.
+ \clearpage
.. _rtems_io_close:
IO_CLOSE - Close a device
-------------------------
.. index:: close a device
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_close
-.. code-block:: c
-
- rtems_status_code rtems_io_close(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
- );
+CALLING SEQUENCE:
+ .. code-block:: c
-**DIRECTIVE STATUS CODES:**
+ rtems_status_code rtems_io_close(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+ );
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+ .. list-table::
+ :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ * - ``RTEMS_SUCCESSFUL``
+ - successfully initialized
+ * - ``RTEMS_INVALID_NUMBER``
+ - invalid major device number
-**DESCRIPTION:**
+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.
-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.
-**NOTES:**
+.. raw:: latex
-This directive may or may not cause the calling task to be preempted. This is
-dependent on the device driver being invoked.
+ \clearpage
.. _rtems_io_read:
IO_READ - Read from a device
----------------------------
.. index:: read from a device
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_read
-.. code-block:: c
-
- rtems_status_code rtems_io_read(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
- );
+CALLING SEQUENCE:
+ .. code-block:: c
-**DIRECTIVE STATUS CODES:**
+ rtems_status_code rtems_io_read(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+ );
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+ .. list-table::
+ :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ * - ``RTEMS_SUCCESSFUL``
+ - successfully initialized
+ * - ``RTEMS_INVALID_NUMBER``
+ - invalid major device number
-**DESCRIPTION:**
+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.
-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.
-**NOTES:**
+.. raw:: latex
-This directive may or may not cause the calling task to be preempted. This is
-dependent on the device driver being invoked.
+ \clearpage
.. _rtems_io_write:
IO_WRITE - Write to a device
----------------------------
.. index:: write to a device
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_write
-.. code-block:: c
-
- rtems_status_code rtems_io_write(
- rtems_device_major_number major,
- rtems_device_minor_number minor,
- void *argument
- );
+CALLING SEQUENCE:
+ .. code-block:: c
-**DIRECTIVE STATUS CODES:**
+ rtems_status_code rtems_io_write(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *argument
+ );
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+ .. list-table::
+ :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - successfully initialized
- * - ``RTEMS_INVALID_NUMBER``
- - invalid major device number
+ * - ``RTEMS_SUCCESSFUL``
+ - successfully initialized
+ * - ``RTEMS_INVALID_NUMBER``
+ - invalid major device number
-**DESCRIPTION:**
+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.
-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.
-**NOTES:**
+.. raw:: latex
-This directive may or may not cause the calling task to be preempted. This is
-dependent on the device driver being invoked.
+ \clearpage
.. _rtems_io_control:
@@ -593,40 +589,35 @@ IO_CONTROL - Special device services
------------------------------------
.. index:: special device services
.. index:: IO Control
-
-**CALLING SEQUENCE:**
-
.. index:: rtems_io_control
-.. 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.
+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.