Traceability from specification to source code?

[Helder Silva]

HI Sebastian,

Marked below with [HS].

-----Original Message-----
From: Sebastian Huber [mailto:sebastian.huber at embedded-brains.de] 
Sent: quarta-feira, 1 de abril de 2020 06:31
To: Helder Silva; RTEMS
Subject: Re: Traceability from specification to source code?

Hello Helder,

On 31/03/2020 20:11, Helder Silva wrote:

> Hi Sebastian,
>
> The traceability (e.g. ECSS and also DO) have several layers:
> -From the requirements specification (and/or interface requirements) to the architectural components (and/or interfaces).
the proposal is to use Doxygen groups for architectural components and 
use an @satisfy Doxygen custom command to link to the requirement.
> -From the architectural components to detailed design components.

The proposal is to use Doxygen groups for architectural components and 
use an @satisfy Doxygen custom command to link to the requirement.

> -From the detailed design components to source code.

This is partly also done via Doxygen means (@ingroup, @defgroup, 
@addtogroup, @file):

https://docs.rtems.org/branches/master/eng/req-eng.html#traceability-between-software-requirements-architecture-and-design

>
> The traceability to the source code line number is too much, not required and increases significantly the future maintainability of the source code and specification.
>
> In the specification of the interface requirement (RTEMS-ACFG-OPT-MAXBARRIERS.yml) I would put the reference to the RTEMS API Architecture Component (or whatever architecture component). From the RTEMS API Architecture Component to the Barrier Detailed Design Component (defined in the Doxygen annotations in the source code). In this way we will have the full traceability from requirements to the source code.

I would like to use this example to work out a solution for the 
traceability:

https://git.rtems.org/sebh/rtems-qual.git/tree/spec/acfg/opt/RTEMS-ACFG-OPT-MAXBARRIERS.yml

there is a requirement included which says that the default value of 
this configuration option is 0. There are two code places involved here:

https://git.rtems.org/rtems/tree/cpukit/include/rtems/confdefs/objectsclassic.h#n86

#if CONFIGURE_MAXIMUM_BARRIERS > 0
   BARRIER_INFORMATION_DEFINE( CONFIGURE_MAXIMUM_BARRIERS );
#endif

https://git.rtems.org/rtems/tree/cpukit/rtems/src/barrier.c#n42

OBJECTS_INFORMATION_DEFINE_ZERO(
   _Barrier,
   OBJECTS_CLASSIC_API,
   OBJECTS_RTEMS_BARRIERS,
   OBJECTS_NO_STRING_NAME
);

The source file barrier.c is linked to the software architecture 
component "Barrier Handler" through the @file @ingroup. The 
_Barrier_Information is included in the software architecture component 
through @addtogroup:

https://git.rtems.org/rtems/tree/cpukit/include/rtems/rtems/barrierdata.h#n50

It has potentially more than implementation, one in barrier.c

https://git.rtems.org/rtems/tree/cpukit/rtems/src/barrier.c#n42

and optionally one in the application configuration via

https://git.rtems.org/rtems/tree/cpukit/include/rtems/confdefs/objectsclassic.h#n86

Both implementations have no Doxygen markup since it is only placed to 
the declaration in barrierimpl.h.

[HS] I am not understanding the sentence above: 
- https://git.rtems.org/rtems/tree/cpukit/rtems/src/barrier.c#n42 - Has @ingroup ClassicBarrier
- https://git.rtems.org/rtems/tree/cpukit/include/rtems/confdefs/objectsclassic.h#n86  - Has @ingroup RTEMSApplicationConfiguration

Helder, what do you propose to link these two code places to the 
requirement that the default value of this configuration is 0?

[HS] Maybe I am not understanding your point, but you can make traceability from one requirement to two componentes. That's no problem. 

>
> Comments to the https://git.rtems.org/sebh/rtems-qual.git/tree/spec/acfg/opt/RTEMS-ACFG-OPT-BDBUFBUFFERMAXSIZE.yml :
> -Please take into mind the future maintainability of the specification and source code. Do we need all these options?
I guess this depends on who is we. Having an approach in the RTEMS 
Project which covers only a subset of the application configuration with 
respect to a pre-qualification is not really great. The application 
configuration glues everything together. For example we don't want to 
pre-qualify bdbuf, however, the bdbuf configuration influences the 
maximum Classic API tasks value. I don't want a specialized confdefs.h 
for the pre-qualified RTEMS. Also ESA would likes to have the 
non-pre-qualified parts of RTEMS as an add-on package. Both parts meet 
in the application configuration. This makes it necessary to pre-qualify 
all of the application configuration from my point of view. Helder, what 
would be your approach?

[HS] I did not said that I would suggest a partial specification of the Application Configuration. My point was regarding the amount of options (e.g., SPDX-License-Identifier, copyrights, derived, header) in the requirements specification template. They are a lot, maybe we do not need all of them and they will be hard to maintain. Imagine that you have several hundreds of them. 

> -The appl-config-option-description should be something like "The CONFIGURE_BDBUF_BUFFER_MAX_SIZE (or value if you wish) shall define the maximum size of the buffer in bytes".

This is the problem 1. I mentioned here:

https://lists.rtems.org/pipermail/devel/2020-March/058745.html

We need a requirement and a description for the configuration option. 
The description

"The value of this configuration option defines the maximum number of 
Classic
   API Barriers that can be concurrently active."

is close to a requirement formulation. Should we use the descriptions as 
is as a requirement? Should we add some text like this for each option:

"The system shall provide an application configuration option which 
defines the maximum number of Classic
   API Barriers that can be concurrently active."

[HS] Yes, we should have the requirements specification similar to requirements wording. Please remember the required requirement verbal form in the ECSS-E-ST-10-06C, section 8.3.2. The standards have usually this requirement.