[PATCH v2] c-user: Generate I/O Manager documentation
sebastian.huber at embedded-brains.de
Tue Oct 6 08:11:09 UTC 2020
On 05/10/2020 18:10, Gedare Bloom wrote:
> On Mon, Oct 5, 2020 at 8:40 AM Sebastian Huber
> <sebastian.huber at 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.
>> * 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
>> * Add custom document index entries.
>> Generated PDF:
>> Generated 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
>> +.. for information how to maintain and re-generate this file.
> "information about how"
> 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:
>> -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
>> +.. _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
>> - 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.
>> - The Device Driver Table size is specified in the Configuration Table
>> - condiguration. This needs to be set to maximum size the application
>> - requires.
>> +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"
>> + This parameter is the device major number. Use a value of zero to let the
>> + system obtain a device major number automatically.
>> + This parameter is the device driver address table.
>> + 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
More information about the devel