Documentation of Qualification Toolchain?

[Sebastian Huber]

On 24/06/2020 02:48, Chris Johns wrote:

> On 19/6/20 11:38 pm, Sebastian Huber wrote:
>> the qualification toolchain in
>>
>> https://git.rtems.org/sebh/rtems-qual.git/
>>
>> needs a bit of documentation. For a start, I propose to add it to the 
>> RTEMS Software Engineering manual.
>
> Does this mean adding references to that repo?

Yes, I already added a how-to section for the glossary of terms:

https://docs.rtems.org/branches/master/eng/req/howto.html

>
> I am not comfortable with the name of the repo and documenting a 
> personal repo is something we should avoid.
Yes, the name is not great. I think your proposal to name it 
rtems-central was a bit better. Another option is rtems-spec.
>
> I see the name rtems-qual.git as the project or outcome name that is 
> currently undersay and not what it is. If a core developer does not 
> need to use this repo to maintain RTEMS and that work can be qualified 
> what role does it perform? If it is simpler and easier for a core 
> developer to use this repo then this is not about qualification it is 
> about development of RTEMS that can be qualified.
>
> I would like to understand the intended workflow for this repo. Is 
> something we should promote as the developer workflow? If so we should 
> consider embracing this. For example the glossary generation. Editing 
> by hand the generated output does not make sense to me.
>

The stuff in this repository is already somewhat useful to maintain 
RTEMS. You can generate the glossary of terms for individual documents 
from a shared collection of terms. In the RTEMS Classic API Guide the 
project-wide glossary is located, other documents only include the terms 
they use in their glossary. All the application configuration options 
are available as specification items:

https://docs.rtems.org/branches/master/eng/req/items.html#spectypeapplicationconfigurationoptionitemtype

All the sections about application configuration options in the RTEMS 
Classic API Guide are generated from them. With a bit of work, we could 
also generate pages for the Doxygen documentation. The tool chain 
supports context-sensitive substitution. In the specification a 
${uid:attribute/path} syntax is used. For example:

   * The ${../attr/multiprocessor-resource-sharing:/name} attribute 
selects the
     MrsP locking protocol in SMP configurations, otherwise it selects the
     priority ceiling protocol.  For this locking protocol a priority 
ceiling
     shall be specified in ``${.:/params[3]/name}``.  This priority is 
used to set
     the priority ceiling in all scheduler instances.  This can be 
changed later
     with the ${set-priority:/name} directive using the returned semaphore
     identifier.

In the Sphinx output this is transformed to:

     * The RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attribute selects the MrsP
       locking protocol in SMP configurations, otherwise it selects the 
priority
       ceiling protocol.  For this locking protocol a priority ceiling 
shall be
       specified in ``priority_ceiling``.  This priority is used to set the
       priority ceiling in all scheduler instances.  This can be changed 
later
       with the :ref:`rtems_semaphore_set_priority()
       <InterfaceRtemsSemaphoreSetPriority>` directive using the returned
       semaphore identifier.

In the Doxygen output this is transformed to:

  * * The #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attribute selects the MrsP
  *   locking protocol in SMP configurations, otherwise it selects the 
priority
  *   ceiling protocol.  For this locking protocol a priority ceiling 
shall be
  *   specified in ``priority_ceiling``.  This priority is used to set the
  *   priority ceiling in all scheduler instances.  This can be changed 
later
  *   with the rtems_semaphore_set_priority() directive using the returned
  *   semaphore identifier.

I work currently on a complete specification of the RTEMS Classic API.

The tool chain has also support for test plan and code generation. I 
plan to specify the functionality of the RTEMS directives through so 
called action requirements:

https://docs.rtems.org/branches/master/eng/req/items.html#spectypeactionrequirementitemtype

This can be used to generate table based test loops to check all states 
of pre-conditions and post-conditions (see attached file).

> I have a concern about the long term maintenance of a git repo of git 
> repos. I know of a project that have developed tools to handle 
> something like this because it is hard to do manually. Maybe we should 
> find out more about this.
Which long term maintenance issues do you see? Working with Git 
submodules can be a bit annoying, however, the rate of change will not 
be that high in this project.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: tc-task-ident.c
Type: text/x-csrc
Size: 14950 bytes
Desc: not available
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200625/8dcc7fb5/attachment-0001.bin>