This directory contains a manual testcase for gcov. Currently it is
not suitable for automated testing. The testcase involves four
separate object files, and it is important that these are compiled
separately. Once the test has run the host-side needs to perform a
couple of extra gcov-specific steps, to get the coverage data over the
host and process it. The results are a set of .gcov files which
currently need manual checking, although in theory a script could be
used.

To run the tests manually, first copy the contents of this directory
somewhere suitable. The object, executable, .gcno, ecosgcov.out,
.gcda, and .gcov files will all end up in the working directory so
copying the contents elsewhere avoids polluting the component
repository.

Next create a suitable build tree. Either:

  ecosconfig new <target> default
  ecosconfig add gcov
  ecosconfig tree
  make

or:

  ecosconfig new <target> net
  ecosconfig add gcov
  ecosconfig tree
  make

The former means that the gcov_dump gdb macro has to be used to
transfer the coverage data to the host. The latter also allows the use
of tftp.

Then edit the tests makefile, changing the first line to point at the
build tree, and make the test case gcovtest. Run it on the target. The
main code should only take a few seconds. If networking is enabled
there will be a pause for 2 minutes at the end to allow for a tftp
transfer. Otherwise cyg_test_exit() gets called immediately.

To dump the coverage data using gdb, source the gcov.gdb macro file
and run gcov_dump. This will create a file ecosgcov.out in the current
directory. Dumping via tftp involves something like:

  tftp <target ip>
  tftp> binary
  tftp> get ecosgcov.out
  tftp> quit

This gives a file ecosgcov.out in the current directory containing all
the coverage data, but it is not yet in the format required by gcov.
Next run the ecosxda script. This will generate .gcda files for
gcovmain.c, gcov1.c and gcov2.cxx. There should not be a .gcda file
for gcov3.c since that contains no executable code.

gcov can now be used to process the .gcda files, together with the
.gcno files generated during compilation and the original source
files. It is important to use the version of gcov that matches the
compiler, e.g. arm-elf-gcov or m68k-elf-gcov, or just plain gcov in
the case of the synthetic target.

  m68k-elf-gcov gcovmain.c
  m68k-elf-gcov gcov1.c
  m68k-elf-gcov gcov2.cxx

This will generate files gcovmain.c.gcov, gcov1.c.gcov, and
gcov2.cxx.gcov containing coverage counts. These should be compared
with the provided sample files gcovmain.c.sample, gcov1.c.sample and
gcov2.cxx.sample, although the outputs may not match exactly and some
manual examination is recommended. Basically the application starts
ten threads in gcovmain.c. Eight of these threads run simple() in
gcov1.c, just going through a loop 10000 times, so much of the loop
should have a count of 80000. Part of the loop will only execute some
of the time so the counts will be less, and one line in the loop
should never get executed. Because of multithreading the counts may
not be exact, if a timeslice occurs in the middle of updating a
counter. One of the threads runs a dhrystone which occupies most of
gcov1.c, and the last threads does some floating point arithmetic in
gcov2.cxx. There is also a function near the top of gcov1.c which
never gets called.

Run ecosxda again, followed by gcov. This will merge the ecosgcov.out
data with the existing counts, so all the counts should double.
Finally run ecosxda -r, to replace the existing counts with the
ecosgcov.out ones. The counts should go back to what they were before.
