Documentation of Qualification Toolchain?

[Chris Johns]

On 25/6/20 3:26 pm, Sebastian Huber wrote:
> 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

Ah OK. We need to make some choices and get something more formal in 
place. Stray links to things that will change does not help anyone.

>> 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.

Yes rtems-central is nice but is this a place a user will come to and use?

>> 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).
> 

Great. I think what you have explained would benefit the development of 
RTEMS and so I think this is something we should look at promoting as a 
development tool.

>> 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.

We have a number of repositories that have links in them and I am 
wondering if the 'external' directory in your repo be renamed 'sources' 
or something like that so in time we can add more of our source repos. I 
am wondering if this would aid our management of these separate repos, a 
sort of "one repo to rule them all". Doing this may expose any 
submodules complexities that may exist.

I raised this because it was mention in last years flight software 
workshop. I can follow it up if you like.
Chris