Add 'unreachable region' feature. (#433)

This is similiar to 'excluded regions' - except that lcov will generate an 'unreachable' message if any coverpoints in the region are hit.

Signed-off-by: Henry Cox <[email protected]>

Author: henry2cox

lcovrc

@@ -510,6 +510,15 @@ lcov_json_module = auto
 # override end of exclude region regexp
 #lcov_excl_stop = LCOV_EXCL_STOP
 
+# override unreachable line default line exclusion regexp
+#lcov_unreachable_line = LCOV_UNREACHABLE_LINE
+
+# override start of unreachable region regexp
+#lcov_unreachable_start = LCOV_UNREACHABLE_START
+
+# override end of unreachable region regexp
+#lcov_unreachable_stop = LCOV_UNREACHABLE_STOP
+
 # override start of branch exclude region regexp
 #lcov_excl_br_start = LCOV_EXCL_BR_START
 

lib/lcovutil.pm

@@ -2301,12 +2301,12 @@ Ignore line and branch coverpoints on lines which are out-of range/whose line nu
 .PP
 
 .IP region: 3
-apply LCOV_EXCL_START/LCOV_EXCL_STOP directives found in source text to the coverpoints found in the current and baseline .info files.
+apply LCOV_EXCL_START/LCOV_EXCL_STOP/LCOV_EXCL_LINE and LCOV_UNREACHABLE_START/LCOV_UNREACHABLE_STOP/LCOV_UNREACHABLE_LINE directives found in source text to the coverpoints found in the current and baseline .info files.
 This option may be useful in cases that the source code was not found during 'lcov \-\-capture ...' but is accessible now.
 .PP
 
 .IP branch_region: 3
-apply LCOV_EXCL_BR_START/LCOV_EXCL_BR_STOP directives found in source text to the coverpoints found in the current and baseline .info files.
+apply LCOV_EXCL_BR_START/LCOV_EXCL_BR_STOP/LCOV_EXCL_BR_LINE directives found in source text to the coverpoints found in the current and baseline .info files.
 This is similar to the 'region option, above - but applies to branch coverpoints only.
 .PP
 
@@ -3130,6 +3130,20 @@ Coverage data for a particular line cannot be found, possibly because the source
 This can happen if the source file used in HTML generation is not the same as the file used to generate the coverage data - for example, lines have been added or removed.
 .PP
 
+.IP unreachable: 3
+a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong.
+If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the
+.I retain_unreachable_coverpoints_if_executed
+configuration parameter.
+See man
+.B lcovrc(5)
+and the
+.I "Exclusion markers"
+section of man
+.B geninfo(1)
+for more information.
+.PP
+
 .IP unsupported: 3
 The requested feature is not supported for this tool configuration.  For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases.
 .PP

man/genhtml.1

@@ -233,13 +233,29 @@ man page for more information on .gcda, .gcno and .gcov output formats.
 .SS "Exclusion markers"
 
 To exclude specific lines of code from a tracefile, you can add exclusion
-markers to the source code. Additionally you can exclude specific branches from
-branch coverage without excluding the involved lines from line and function
-coverage. Exclusion markers are keywords which can for example be added in the
+markers to the source code. Similarly, you can mark specific regions of code
+as "unreachable".  An "unreachable" error message is generated if any
+coverpoints in unreachable regions are executed (
+.I i.e.,
+have non-zero hit counts.
+See the
+.I retain_unreachable_coverpoints_if_executed
+section in man
+.B lcovrc(1)
+for a description of the actions taken in this case.
+
+Additionally you can exclude specific branches or MC/DC expressions from
+without excluding the involved lines from line and function
+coverage.
+
+ Exclusion markers are keywords which can for example be added in the
 form of a comment.
 See man
 .BR lcovrc (5)
-how to override some of them.
+how to override the exclusion keywords (
+.I e.g.,
+to reuse markers inserted for other tools or to generate reports with different
+sets of excluded regions).
 
 The following markers are recognized by geninfo:
 
@@ -266,6 +282,34 @@ section.
 .br
 .RE
 
+.B LCOV_UNREACHABLE_LINE
+.br
+.RS
+If the marked line is 'hit', then generate an error:  we believe the marked code
+is unreachable and so there is a bug in the code, the plaement of the directive, or both.
+Lines containing this marker will be excluded from reporting.
+.br
+Apart from error reporting, this directive is equivalent to
+.I LCOV_EXCL_LINE.
+.RE
+
+.B LCOV_UNREACHABLE_START
+.br
+.RS
+Marks the beginning of an unreachable section of code. The current line in part of this region.
+.br
+As described in the
+.I LCOV_UNREACHABLE_LINE
+section, above: an error is generated if any code in the region is hit, but the code is excluded from reporting.
+.RE
+
+.B LCOV_UNREACHABLE_STOP
+.br
+.RS
+Marks the end of the region of unreachable code. The current line not part of this
+section.
+.RE
+
 .B LCOV_EXCL_BR_LINE
 .br
 .RS
@@ -319,7 +363,9 @@ The current line not part of this section
 In general, (almost) all
 .B geninfo
 options can also be specified in your personal, group, project, or site
-configuration file - see man
+configuration file - see the
+.I \-\-config\-file
+section, below, and man
 .B lcovrc(5)
 for details.
 
@@ -1013,7 +1059,19 @@ data.
 .IP source: 3
 the source code file for a data set could not be found.
 .PP
-`<
+
+.IP unreachable: 3
+a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong.
+If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the
+.I retain_unreachable_coverpoints_if_executed
+configuration parameter.
+See man
+.B lcovrc(5)
+and the
+.I "Exclusion markers"
+section, above.
+.PP
+
 .IP unsupported: 3
 the requested feature is not supported for this tool configuration.  For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases.
 .PP

man/geninfo.1

@@ -1445,6 +1445,20 @@ data.
 the source code file for a data set could not be found.
 .PP
 
+.IP unreachable: 3
+a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong.
+If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the
+.I retain_unreachable_coverpoints_if_executed
+configuration parameter.
+See man
+.B lcovrc(5)
+and the
+.I "Exclusion markers"
+section of man
+.B geninfo(1)
+for more information.
+.PP
+
 .IP unsupported: 3
 the requested feature is not supported for this tool configuration.  For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases.
 .PP

man/lcov.1

@@ -714,6 +714,24 @@ maximum during parallel processing.
 #lcov_excl_stop = LCOV_EXCL_STOP
 .br
 
+.br
+# override unreachable line default line exclusion regexp
+.br
+#lcov_unreachable_line = LCOV_UNREACHABLE_LINE
+.br
+.br
+# override start of unreachable region regexp
+.br
+#lcov_unreachable_start = LCOV_UNREACHABLE_START
+.br
+
+.br
+# override end of unreachable region regexp
+.br
+#lcov_unreachable_stop = LCOV_UNREACHABLE_STOP
+.br
+
+
 .br
 # override start of branch exclude region regexp
 .br
@@ -2551,6 +2569,37 @@ Specify the regexp used to mark the end of a region where exception-related bran
 
 Default is 'LCOV_EXCL_EXECEPTION_BR_STOP'.
 
+.BR lcov_unreachable_line " ="
+.I expression
+.IP
+Specify the regular expression of unreachable line which should be excluded from reporting, but should generate an "inconsistent" error if hit.
+That is:  we believe that the marked code is unreachable, so there is a bug in the code, the placement of the directive, or both if the "unreachable" code is executed.
+Line, branch, and function coverpoints are associated with lines where this regexp is found are dropped.
+.br
+
+Default is 'LCOV_UNREACHABLE_LINE'.
+.PP
+
+.BR lcov_unreachable_start " ="
+.IR expression
+.IP
+Specify the regexp mark the start of an unreachable code block.
+All coverpoints within exception regions are dropped, but the tool will generate
+an "inconsistent" error if any code in the block is executed.
+.br
+
+Default is 'LCOV_UNREACHABLE_START'.
+
+.PP
+
+.BR lcov_unreachable_stop " ="
+.IR expression
+.IP
+Specify the regexp mark the end of the unreachable code block.
+.br
+
+Default is 'LCOV_UNREACHABLE_STOP'.
+
 .PP
 
 .BR fail_under_branches " ="
@@ -2565,7 +2614,21 @@ for more detailes.
 
 .br
 The default is 0 (no threshold).
+.PP
+
+.BR retain_unreachable_coverpoints_if_executed " ="
+.I [0 | 1]
+.IP
+Specify whether coverpoints in "unreachable" regions which are 'hit' are
+dropped (0) - because the region is excluded - or retained (1) - because
+the directive appears to be incorrect.
+.br
+See the "Exclusion markers" section in man
+.B geninfo(1)
+for more details.
+
 
+The default is 1 (retain the coverpoints).
 .PP
 
 .BR fail_under_lines " ="

man/lcovrc.5

@@ -48,6 +48,24 @@ if [ $NO_INITIAL_CAPTURE != $? ] ; then
     fi
 fi
 
+# enable branch filter without line/region filter - to hit some additional code
+$COVER $CAPTURE $LCOV_OPTS --initial -o initial_br.info $IGNORE_EMPTY $IGNORE_USAGE --filter branch_region
+if [ $NO_INITIAL_CAPTURE != $? ] ; then
+    echo "Error:  unexpected error code from lcov --initial"
+    if [ $KEEP_GOING == 0 ] ; then
+        exit 1
+    fi
+fi
+for info in initial.info initial_br.info ; do
+    grep 'BRDA:8,e0' $info
+    if [ 0 == $? ] ; then
+	echo "Error:  exception branch should be filtered out of $info"
+	if [ $KEEP_GOING == 0 ] ; then
+            exit 1
+	fi
+    fi
+done
+
 ./a.out
 if [ 0 != $? ] ; then
     echo "Error:  unexpected error return from a.out"

tests/lcov/exception/exception.sh

@@ -3,7 +3,7 @@
 #include <iostream>
 #include <string>
 
-int main(int argc, const char *argv[])
+int main(int argc, const char *argv[]) // TEST_UNREACH_FUNCTION
 {
   bool b = false;
   if (strcmp(argv[1], "1") == 0)
@@ -18,17 +18,19 @@ int main(int argc, const char *argv[])
 
   // TEST_OVERLAP_START
   // TEST_OVERLAP_START
+  // TEST_UNREACHABLE_START
   std::string str("asdads");
+  // TEST_UNREACHABLE_END
   str = "cd";
   // TEST_OVERLAP_END
 
   //TEST_DANGLING_START
   //TEST_UNMATCHED_END
 
-  std::cout << str << std::endl;
+  std::cout << str << std::endl; // TEST_UNREACHABLE_LINE
 
-  // LCOV_EXCL_START
+  // LCOV_EXCL_START_1
   std::cout << "adding some code to ignore" << std::endl;
-  // LCOV_EXCL_STOP
+  // LCOV_EXCL_STOP_1
   return 0;
 }