Traceability from specification to source code?

[Sebastian Huber]

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