Requirement Traceability with All Substance and No Fuss

There is a popular quote in the software verification and validation community:

"Without a specification, a system cannot be right or wrong, it can only be surprising!"

(Paraphrased from W. D. Young, W. E. Boebert, and R. Y. Kain; "Proving a Computer System Secure", The Scientific Honeyweller 6(2), pp. 18-27, 1985.)

At least since 1993's Leveson’s and Turner’s investigation into the Therac-25 accidents, every professional would consider engineering a safety-critical system without proper specifications an irresponsible, if not criminal act. (Therac-25 was a radiation therapy machine. Between June 1985 and January 1987, six known accidents involved massive overdoses resulting in patient deaths and serious injuries.) It is thus no surprise that all major functional safety standards prescribe bidirectional traceability between lower-level and higher-level artifacts and test cases. In this context, "bidirectional" means you need both:

• backward traceability: each lower-level artifact (e.g., source code element) is justified by a higher-level artifact (e.g., a software specification);
• forward traceability: each higher-level artifact (e.g., a safety requirement) is implemented by one or more lower-level artifacts (e.g., software specifications).

Functional safety systems have complex, interdependent, and distributed requirements and specifications: getting them right without discipline and rigor is simply impossible. And this requires tools, of course. While large organization can afford expensive requirement management tools, smaller organizations often resort to Word documents and Excel sheets. The price tag is not the only obstacle to adoption: these tools tend to constrain work in a way that is perceived as overkill for small organizations and projects.

Luckily, there are alternatives that are much, much better than Word and Excel and do not incur significant extra cost. One such alternative is the combination of:

• StrictDoc, a well-designed tool for writing technical requirements and specifications with powerful visualization and traceability features;
• the ECLAIR static analysis platform service for MISRA C:2012 Directive 3.1 ("All code shall be traceable to documented requirements");
• Doxygen, one of the best source code documentation tools.

We recently followed the adoption of such a solution on a project with around 20 developers. Safety requirements were derived using STPA (System-Theoretic Process Analysis, a top-down hazard analysis methodology, based on control systems theory and systems engineering). These resulted in the definition of safety constraints. The safety constraints and other product requirements were then decomposed into a hierarchical structure, going down to high-level and low-level software requirements. All these constraints and requirements were captured in StrictDoc, which allowed easy checking of their bidirectional traceability as well as very convenient views for all team members. Low-level software requirements were then captured in the source code in the form of Doxygen comments, e.g.:

/*!
   * @brief
   *   Attempt starting the calibration process.
   *
   * @return
   *   Calibration process state after the starting attempt.
   *
   * @requirements
   *   CTL.TGM-LR-006.
   */
  extern process_state_t
  ctl_tgm_start_calibration (void);

 

ECLAIR, which is able to parse Doxygen comments (so as to, e.g., warn about misnaming the function parameters in the documentation block), collects the unique IDs of all requirements, it associates them to the corresponding program entity (i.e., function or non-local variable) and, as part of checking MISRA C:2012 Directive 3.1, it does two things:

1. generates a report whenever program entities are not associated to any requirement;
2. given a list of low-level software requirements automatically obtained by the StrictDoc input file, generates a report for each requirement that is not covered by any program entities.

As an extra, a trivial Doxygen customization allows for the generation of beautiful code documentation, including requirements. This methodology proved to be very powerful and successful and will be the subject of a future webinar.

Speaking of webinars, “A Guided Tour of the New Features in ECLAIR 3.11.0” is scheduled for September 7th, 11am CEST. Make sure you don’t miss the opportunity: this is especially useful to current users, to freshen up their knowledge of the tool, as well as to future users to get a good overview. You can check out the details and register here, on our website.

Let’s wrap this up, this is our last blog before the (much needed) summer holidays, so we wish you an invigorating and safe break. Talk to you soon!

Join our LinkedIn community to keep up to date with all our news.

 

Roberto Bagnara, PhD, is co-founder of BUGSENG, software verification expert and evangelist, and professor of Computer Science at the University of Parma. He is also a member of the ISO/IEC JTC1/SC22/WG14 - C Standardization Working Group and of the MISRA C Working Group.

Patricia M. Hill, PhD, is co-founder and director of BUGSENG, software verification expert, and former senior researcher at the University of Leeds. She is also a member of the MISRA C++ Working Group.