On Mon, Mar 30, 2020 at 8:18 AM Sebastian Huber <sebastian.hu...@embedded-brains.de> wrote: > > 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). >
This question is related to https://lists.rtems.org/pipermail/devel/2019-September/055519.html about code annotations, and similar discussion raised there applies here. > > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
