Traceability from specification to source code?

Tue Mar 31 18:58:49 UTC 2020

Hi Helder,

On Tue, Mar 31, 2020 at 12:11 PM Helder Silva <Helder.Silva at edisoft.pt> wrote:
>
> 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.
>

I think there is also concern that not tying the spec to line numbers
will make it harder to know if it is still correctly linking to the
right place in the future. There doesn't seem to be an easy way to
help maintain the traceability during RTEMS public code review and
modifications if there is no way to identify that some code changed so
the link needs to be examined for validity.

I'm all for keeping it simple :) But there is also the cost of bit-rot
to consider.

Gedare

> 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
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel