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. Hope it have helped, Helder -----Original Message----- From: devel [mailto:devel-boun...@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@rtems.org http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
