<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Apr 17, 2020 at 9:06 AM Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-brains.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello,<br>
<br>
with the pre-qualified build of RTEMS<br>
<br>
<a href="https://lists.rtems.org/pipermail/devel/2020-April/059445.html" rel="noreferrer" target="_blank">https://lists.rtems.org/pipermail/devel/2020-April/059445.html</a><br>
<br>
I try out the following approach. I run Doxygen on the set of <br>
pre-qualified files to produce the documentation and a tagfile:<br>
<br>
# The TAGFILES tag can be used to specify one or more tag files. For <br>
each tag<br>
# file the location of the external documentation should be added. The <br>
format of<br>
# a tag file without this location is as follows:<br>
# TAGFILES = file1 file2 ...<br>
# Adding location for the tag files is done as follows:<br>
# TAGFILES = file1=loc1 "file2 = loc2" ...<br>
# where loc1 and loc2 can be relative or absolute paths or URLs. See the<br>
# section "Linking to external documentation" for more information about <br>
the use<br>
# of tag files.<br>
# Note: Each tag file must have a unique name (where the name does NOT <br>
include<br>
# the path). If a tag file is not located in the directory in which <br>
doxygen is<br>
# run, you must also specify the path to the tagfile here.<br>
<br>
The tagfile is in XML and contains things like this:<br>
<br>
<member kind="function"><br>
<type>RTEMS_INLINE_ROUTINE uint64_t</type><br>
<name>_Watchdog_Ticks_from_seconds</name><br>
<anchorfile>group__RTEMSScoreWatchdog.html</anchorfile><br>
<anchor>gae368bd39a2a612b0e7701d954d363ce6</anchor><br>
<arglist>(uint32_t seconds)</arglist><br>
</member><br>
<br>
In the specification, I place a reference like this:<br>
<br>
ref:<br>
- kind: function<br>
name: _Watchdog_Ticks_from_seconds<br>
<br>
I can then use the tagfile to lookup this reference. With the <br>
information in the tagfile, I can generate additional documentation <br>
content, for example:<br>
<br>
/**<br>
* @fn RTEMS_INLINE_ROUTINE uint64_t _Watchdog_Ticks_from_seconds <br>
(uint32_t seconds)<br>
*<br>
* bla blub<br>
*/<br>
<br>
In a second Doxygen run, this information is added to the <br>
_Watchdog_Ticks_from_seconds() documentation:<br>
<br>
Converts the seconds to ticks.<br>
<br>
Parameters<br>
seconds The seconds to convert to ticks.<br>
<br>
Returns<br>
seconds converted to ticks.<br>
<br>
bla blub<br>
<br>
The benefits of this approach is that we don't have to modify the RTEMS <br>
sources for the specification traceability and the references in the <br>
specification can be done at a high level without a lot of details.<br></blockquote><div><br></div><div>I'm wading in late and the comments early on about annotations, tools, etc still applies.</div><div><br></div><div>But based on some non-RTEMS work OAR is currently doing and use of a</div><div>commercial tool which is approved for requirements and coverage analysis</div><div>by various certification authorities, I have more practical experience than I</div><div>did when we started this.</div><div><br></div><div>Code annotations are a must. Sebastian is right that putting something</div><div>above the body is the way to go. We are using a requirements comment </div><div>block above the entry point to the method. A script integrates with the </div><div>commercial tool. They analyse the source and provide file, line number,</div><div>and signature (e.g. tags). From that, you can easily find those special</div><div>comments with requirements. You do have to address the case where</div><div>there are no requirements or an incorrectly formatted set. But that's</div><div>the practical matter of what you have to do.</div><div><br></div><div>If you put in a bad requirement tag, then it will just show up as an</div><div>error when you process and some requirement will be uncovered</div><div>in the traceability report.</div><div><br></div><div>There are a lot of details to work out. Doxygen is slow. Would ctags</div><div>or something similar be faster? </div><div><br></div><div>We also do not have Level A requirements on our project but are being</div><div>very conscious of what we are missing to get there and are trying to</div><div>do things right so no rework is required to bump the level, just more work.</div><div>For example, the commercial tool generated Statement, Decision Coverage,</div><div>and MCDC. When an area hits 100% statement, we plan to set the other</div><div>coverage types acceptable minimum percentage at that point to what it</div><div>just happens to be. I think figuring out the RTEMS Project approach to </div><div>this is a wise thing.</div><div><br></div><div>Even though it is a largely ignored tool in the RTEMS Project quiver,</div><div>covoar is quite capable of being extended from doing object coverage</div><div>to tracing the requirements. That was part of what it was conceived of</div><div>doing. A bit of love to tidy up a few issues and make sure we like the </div><div>reports would be a valuable thing.</div><div><br></div><div>FWIW I have finally confirmed what I long believed. That writing simple</div><div>single logic expression if conditions makes statement coverage results</div><div>approach those of the higher levels. Those address if conditions with</div><div>multiple sub-expressions. Avoid using multiple sub-expressions and </div><div>coverage is much simpler. </div><div><br></div><div>I hope I actually helped on this thread. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a></blockquote></div></div>