Traceability from specification to source code?

[Gedare Bloom]

On Mon, Mar 30, 2020 at 8:18 AM Sebastian Huber
<sebastian.huber at 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 at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel