Where to Store Requirements for RTEMS Components

[Sebastian Huber]

Hello Joel,

On 22/05/2019 16:06, Joel Sherrill wrote:
> Where to store the artifacts and what component to do first are 
> independent topics and should be on separate threads. I have changed 
> the subject.
>
> On Wed, May 22, 2019 at 7:29 AM Ting Peng 
> <ting.peng at embedded-brains.de <mailto:ting.peng at embedded-brains.de>> 
> wrote:
>
>     Hello,
>
>     As to the requirements documentation, we need to decide a place to
>     store
>     those requirements documentation. One suggestion is to store in
>     rtems/reqs folder, the other is to store in rtems-docs/reqs
>     folder. We
>     suggest to put the requirements related files (by Doorstop) inside
>     rtems/reqs so that the versions of both source code and the
>     requirements
>     could be consistent. If you wouldn't express any disagreement,
>     then we
>     will use /rtems/reqs. Thank you for your attention.
>
>
> This is ambiguous to me. Is the suggestion to add a requirements/ 
> directory
> at either the top of the rtems source tree or the rtems-docs source tree?
>
> Note that rtems is at least one subdirectory in the RTEMS git repository
> so I could interpret that as adding a requirements directory per 
> component.
>
> Anyway, this can't be answered without knowing the processing 
> requirements.
> If we are tracing requirements to implementation to test implementation to
> coverage, it may make sense to put them in the source tree but that makes
> them harder to include in an RTEMS documentation build. Thinking out loud,
> it is probably easier to include them in the rtems-docs and have any 
> requirements
> tracing tools be told where the rtems-docs and rtems source is.
>
> Either way, I doubt we will end up with a flat set of requirement 
> files under the
> top requirements directory. Especially since Doorstop seemed to want one
> requirement per file. I see us with a directory per subsystem.
>
> But this is all assuming that having a separate repository for 
> qualification
> artifacts is not a desirable option.

it is not clear to me how all the bits and pieces related to 
requirements look like. This is why I would like to work out a small 
example software component.

We definitely need a repository to store the requirements files 
(Doorstop, YAML). This is the first thing we have to know. If it later 
turns out that the choice was bad, we can still remove it from one 
repository and do a subtree import in another.

Doorstop uses one file per requirement. We probably need some hierarchy 
in the requirements. This can be done by directories or 
a-b-c-d-lowest.yml file names. We can spread out the files across the 
sources or aggregate them in a "reqs" directory. I would use the "reqs" 
directory approach (this makes it easer to move to another repository if 
needed).

What can you do with the requirements files? You can generate a human 
readable Software Requirements Specification from them. We have to write 
a Sphinx generator for this. It may be used together with hand written 
Sphinx files.

YAML is quite a nice file format. We could also add test plans to it. 
 From this we could generate a test plan document maybe also together 
with hand written Sphinx files.

Depending on the requirements detail level, we could also generate API 
level header files with Doxygen markup. We could also generate partial 
content for the RTEMS Classic API Guide from this.

With test output form the new test framework we could automatically do 
some simple consistency checking between the test plan the actual test 
output.

We have to consider also various traceability requirements, e.g. from 
requirement to software component. We could use Doxygen group names and 
requirement IDs as tool input to generate the traceability information 
in various documents.

It is quite a lot of work ahead and my approach is to use a prototype 
(Interrupt Manager Extension) to figure out how we can do it.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.