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