On 05/10/2020 18:10, Gedare Bloom wrote:
On Mon, Oct 5, 2020 at 8:40 AM Sebastian Huber
<sebastian.hu...@embedded-brains.de> wrote:
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.
Generated PDF:
https://ftp.rtems.org/pub/rtems/people/sebh/c-user-6.pdf
Generated HTML:
https://ftp.rtems.org/pub/rtems/people/sebh/c-user/html/index.html
I think this is really quite a great start to the automatic
generation. I have just a couple of comments.
c-user/io/directives.rst | 726 +++++++++++++++++++++----------------
c-user/io/introduction.rst | 64 +++-
2 files changed, 472 insertions(+), 318 deletions(-)
diff --git a/c-user/io/directives.rst b/c-user/io/directives.rst
index d3098cb..8bf5aea 100644
--- a/c-user/io/directives.rst
+++ b/c-user/io/directives.rst
@@ -1,421 +1,537 @@
.. 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)
+.. This file was automatically generated. Do not edit it manually.
+.. Please have a look at
+..
+..https://docs.rtems.org/branches/master/eng/req/howto.html
+..
+.. for information how to maintain and re-generate this file.
"information about how"
"regenerate"
I know we have the input files listed below now, but maybe it makes
sense to generate a "transcript" of all the input files here as a
block of comments?
I added the comment block from Chris.
+
+.. _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.
+.. Generated from spec:/rtems/io/if/register-driver
-.. raw:: latex
+.. index:: rtems_io_register_driver()
+.. index:: register a device driver
- \clearpage
In the original docs, there is a page break on each new directive
including the first one. I guess now since the boilerplate text
description of Directives has been dropped it would just be a blank
page with Directives on it. This may be a minor point of
inconsistency. I think it looks fine without the page break since
there is no additional text. Joel?
I can also add a boilerplate text and clear the page before the first
directive.
+.. _InterfaceRtemsIoRegisterDriver:
-.. 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.
+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:: DIRECTIVE PARAMETERS:
More a question for Joel, the original subheadings here include
"DIRECTIVE" but all of this is nested underneath Directives.
Should/Can we simplify these? then this would be "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:: DIRECTIVE RETURN VALUES:
and "RETURN VALUES"
This is easy to change. Dropping the DIRECTIVE would be in line with the
Doxygen output.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
