Traceability from specification to source code?

[Helder Silva]

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).
-From the architectural components to detailed design components. 
-From the detailed design components to source code.

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.  

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

My vote would be to not place specification/requirements directly in the source code, only doxygen tags (design components), and to not place references to the source code line number.

Hope it have helped,
Helder

-----Original Message-----
From: devel [mailto:devel-bounces at rtems.org] On Behalf Of Sebastian Huber
Sent: segunda-feira, 30 de março de 2020 15:18
To: RTEMS
Subject: Traceability from specification to source code?

Hello,

I started with the specification of RTEMS and created the first 
specification items (the application configuration options):

https://git.rtems.org/sebh/rtems-qual.git/tree/spec/acfg/opt

For the RTEMS Qualification project we need traceability from the 
specification to the source code and vice versa. For example, there 
should be a link from

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

to

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

and

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

To avoid redundancy we should store only one link direction (either from 
source code to requirement or from requirement to source code). A tool 
should scan everything and generate the bidirectional links.

The question is now where do we want to place the links? We can place 
them in the specification items or the source code.

In the specification item it could be something like this:

refs:
- repository: rtems
   source: cpukit/rtems/src/barrier.c
   lines:
   - [42, 47]
   hash: 8gsKsqCCY-PEXVGihoUMEk_q2YIGyWuGlPsMTA5v_jI=
   attribute: appl-config-option-default-value
- repository: rtems
   source: include/rtems/confdefs/objectsclassic.h
   lines:
   - [49, 51]

   hash: bSf7xgvXVpy1u_mxP7Fk8qCHwxGCpkc9LrwgT9RzWSY=

The hash covers the referenced content, e.g. here specified by a line 
range (there could be more means, e.g. regular expressions for begin and 
end markers). If the source code changes in this area, the reference is 
invalidated.

Pros:

* No need to modify the sources.

Cons:

* Requirements are invisible in the sources.

* Writing the links is tedious.

In the sources it could be something like this:

/* $satisfy{RTEMS-ACFG-OPT-MAXBARRIERS} */

#if CONFIGURE_MAXIMUM_BARRIERS > 0
   #include <rtems/rtems/barrierdata.h>
#endif

/* $satisfy{RTEMS-ACFG-OPT-MAXBARRIERS:appl-config-option-default-value} */
OBJECTS_INFORMATION_DEFINE_ZERO(
   _Barrier,
   OBJECTS_CLASSIC_API,
   OBJECTS_RTEMS_BARRIERS,
   OBJECTS_NO_STRING_NAME
);

The $satisfy could cover the next statement or function. We can use ${ 
and $} markers to reference statement blocks. We could also add a line 
count (makes the change tracker much simpler, no need to know what a 
statement is).

A tool can collect all referenced sources in a defined order and 
generate an overall hash value which is stored in the specification 
item. This allows to track changes relevant for a particular requirement.

Pros:

* Requirements are directly visible in the sources.

* Writing the links is easy, just a comment.

Cons:

* We have to modify the sources (with special comments).

* The tool to track changes in the code could be complex, e.g. needs to 
parse C sources (there are third-party modules to help with this 
https://github.com/eliben/pycparser).


_______________________________________________
devel mailing list
devel at rtems.org
http://lists.rtems.org/mailman/listinfo/devel