Adopt the LCOV convention for marking lines as unreachable by tests.

Document this convention.

Add a script to post-process .gcov files in order to stop nagging us
about excluded lines.

Teach cov-diff to handle these post-processed files.

Closes ticket 16792

scripts/test/cov-diff

@@ -9,8 +9,8 @@ DIRB="$2"
 
 for A in $DIRA/*; do
   B=$DIRB/`basename $A`
-  perl -pe 's/^\s*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$A" > "$A.tmp"
-  perl -pe 's/^\s*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$B" > "$B.tmp"
+  perl -pe 's/^\s*\!*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$A" > "$A.tmp"
+  perl -pe 's/^\s*\!*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$B" > "$B.tmp"
   diff -u "$A.tmp" "$B.tmp"
   rm "$A.tmp" "$B.tmp"
 done

scripts/test/cov-exclude

@@ -0,0 +1,28 @@
+#!/usr/bin/perl -p -i
+
+use warnings;
+use strict;
+our $excluding;
+
+# This script is meant to post-process a .gcov file for an input source
+# that was annotated with LCOV_EXCL_START, LCOV_EXCL_STOP, and LCOV_EXCL_LINE
+# entries.  It doesn't understand the LCOV_EXCL_BR* variations.
+#
+# It replaces unreached reached lines with x:, and reached excluded lines
+# with !!!num:.
+
+BEGIN { our $excluding = 0; }
+
+if (m/LCOV_EXCL_START/) {
+  $excluding = 1;
+}
+if ($excluding and m/LCOV_EXCL_STOP/) {
+  $excluding = 0;
+}
+
+my $exclude_this = (m/LCOV_EXCL_LINE/);
+
+if ($excluding or $exclude_this) {
+  s{^\s*\#\#+:}{        x:};
+  s{^   (\s*)(\d+):}{$1!!!$2:};
+}