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
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
