GCOV Coverage Tool:

• Code instrumentation during compilation:

  In order to turn on code coverage information, GCC must be used to compile the program with the flags -fprofile-arcs -ftest-coverage.
  When a file is compiled with GCC and code coverage is requested, the compiler instruments the code to count program arcs. The GCC compiler begins by constructing a program flow graph for each function. Optimization is performed to minimize the number of arcs that must be counted. Then a subset of program basic blocks are identified for the instrumentation. With the counst from this subset GCOV can reconstruct program arcs and line execution counts.
  In order to relate the various soure code line information with the program flow and the counter vector, GCC also generates two output files for each sourcefile.c compiled:
  
  • sourcefile.bb , which contains a list of source files (including headers) and functions within those files and line numbers correspondingto basic blocks in the source file;
  • sourcefile.bbg contains a list of the program flow arcs for each function which in combination with the *.bb file enables GCOV to reconstruct the program flow.

• Data collection during code execution:

  At runtime, the counter vector entries are incremented every time an instrumented basic block is entered.

• Data extraction at program exit time:

  At program exit time, the GCOV enabled main wrapper function walks the bb_head list and for each bbobj encountered, it creates a file sourcefile.da and populates the file with the size of the vector and the counters of the vector itself.

• Coverage analysis and presentation:

  The GCOV utility integrates and relates the information of the "*.bbg", "*.bb" and the "*.da" to produce the "*.gcov" files containing per line coverage output.
  For instrumented lines that are executed at least once, GCOV prefaces the text with the total number of times the line was executed, the text is prefaced by the string ####1
  For any lines of code that were not instrumented, such as comments, nothing is added to the line by GCOV.

Using GCOV and LCOV to generate output:

• Analysis:

  Once the .da files exist, GCOV is capable of analyzing the files and producing coverage output. To see the coverage data for a user space program, one may simply run 'gcov program.c' where program.c is the source file. The .da file must also exist in the same directory.
  The raw output from GCOV is useful, but not very readable. In order to produce nicer looking output, a utility called LCOV was written.

• Output generation:

  LCOV automates the process of extracting the coverage data using GCOV and producing HTML results based on that data.
  The LCOV tool first calls GCOV to generate the coverage data, then calls a script called geninfo to collect that data and produce a .info file to reprensent the coverage data.
  The .info file is a plaintext file with the following format:

        TN: [test name]
        SF: [path and filename of the source]
        FN: [function start line number], [function name]
        DA: [line number], [execution count]
        LH: [number of lineswith counter > 0]
        LF: [number of instrumented lines]
        end_of_record

• HTML output:

  Once the .info file has been created, the genhtml script may be used to create html output for all of the coverage data collected. The genhtml script will generate both ouput at a directory level and output on a file level.

-- Main.jbenard - 05 Apr 2005