gccint: gcov Testing

1 
1 7.6 Support for testing 'gcov'
1 ==============================
1 
1 Language-independent support for testing 'gcov', and for checking that
1 branch profiling produces expected values, is provided by the expect
1 file 'lib/gcov.exp'.  'gcov' tests also rely on procedures in
1 'lib/gcc-dg.exp' to compile and run the test program.  A typical 'gcov'
1 test contains the following DejaGnu commands within comments:
1 
1      { dg-options "-fprofile-arcs -ftest-coverage" }
1      { dg-do run { target native } }
1      { dg-final { run-gcov sourcefile } }
1 
1  Checks of 'gcov' output can include line counts, branch percentages,
1 and call return percentages.  All of these checks are requested via
1 commands that appear in comments in the test's source file.  Commands to
1 check line counts are processed by default.  Commands to check branch
1 percentages and call return percentages are processed if the 'run-gcov'
1 command has arguments 'branches' or 'calls', respectively.  For example,
1 the following specifies checking both, as well as passing '-b' to
1 'gcov':
1 
1      { dg-final { run-gcov branches calls { -b sourcefile } } }
1 
1  A line count command appears within a comment on the source line that
1 is expected to get the specified count and has the form 'count(CNT)'.  A
1 test should only check line counts for lines that will get the same
1 count for any architecture.
1 
1  Commands to check branch percentages ('branch') and call return
1 percentages ('returns') are very similar to each other.  A beginning
1 command appears on or before the first of a range of lines that will
1 report the percentage, and the ending command follows that range of
1 lines.  The beginning command can include a list of percentages, all of
1 which are expected to be found within the range.  A range is terminated
1 by the next command of the same kind.  A command 'branch(end)' or
1 'returns(end)' marks the end of a range without starting a new one.  For
1 example:
1 
1      if (i > 10 && j > i && j < 20)  /* branch(27 50 75) */
1                                      /* branch(end) */
1        foo (i, j);
1 
1  For a call return percentage, the value specified is the percentage of
1 calls reported to return.  For a branch percentage, the value is either
1 the expected percentage or 100 minus that value, since the direction of
1 a branch can differ depending on the target or the optimization level.
1 
1  Not all branches and calls need to be checked.  A test should not check
1 for branches that might be optimized away or replaced with predicated
1 instructions.  Don't check for calls inserted by the compiler or ones
1 that might be inlined or optimized away.
1 
1  A single test can check for combinations of line counts, branch
1 percentages, and call return percentages.  The command to check a line
1 count must appear on the line that will report that count, but commands
1 to check branch percentages and call return percentages can bracket the
1 lines that report them.
1