diff options
Diffstat (limited to 'gcc/doc/gcov.texi')
| -rw-r--r-- | gcc/doc/gcov.texi | 389 |
1 files changed, 389 insertions, 0 deletions
diff --git a/gcc/doc/gcov.texi b/gcc/doc/gcov.texi new file mode 100644 index 00000000000..3102abc621d --- /dev/null +++ b/gcc/doc/gcov.texi @@ -0,0 +1,389 @@ +@c Copyright (C) 1996, 1997, 1999, 2000 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@ignore +@c man begin COPYRIGHT +Copyright @copyright{} 1996, 1997, 1999, 2000 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'' and ``Funding +Free Software'', the Front-Cover texts being (a) (see below), and with +the Back-Cover Texts being (b) (see below). A copy of the license is +included in the gfdl(7) man page. + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. +@c man end +@c Set file name and title for the man page. +@setfilename gcov +@settitle coverage testing tool +@end ignore + +@node Gcov +@chapter @command{gcov}: a Test Coverage Program + +@command{gcov} is a tool you can use in conjunction with GCC to +test code coverage in your programs. + +This chapter describes version 1.5 of @command{gcov}. + +@menu +* Gcov Intro:: Introduction to gcov. +* Invoking Gcov:: How to use gcov. +* Gcov and Optimization:: Using gcov with GCC optimization. +* Gcov Data Files:: The files used by gcov. +@end menu + +@node Gcov Intro +@section Introduction to @command{gcov} +@c man begin DESCRIPTION + +@command{gcov} is a test coverage program. Use it in concert with GCC +to analyze your programs to help create more efficient, faster +running code. You can use @command{gcov} as a profiling tool to help +discover where your optimization efforts will best affect your code. You +can also use @command{gcov} along with the other profiling tool, +@command{gprof}, to assess which parts of your code use the greatest amount +of computing time. + +Profiling tools help you analyze your code's performance. Using a +profiler such as @command{gcov} or @command{gprof}, you can find out some +basic performance statistics, such as: + +@itemize @bullet +@item +how often each line of code executes + +@item +what lines of code are actually executed + +@item +how much computing time each section of code uses +@end itemize + +Once you know these things about how your code works when compiled, you +can look at each module to see which modules should be optimized. +@command{gcov} helps you determine where to work on optimization. + +Software developers also use coverage testing in concert with +testsuites, to make sure software is actually good enough for a release. +Testsuites can verify that a program works as expected; a coverage +program tests to see how much of the program is exercised by the +testsuite. Developers can then determine what kinds of test cases need +to be added to the testsuites to create both better testing and a better +final product. + +You should compile your code without optimization if you plan to use +@command{gcov} because the optimization, by combining some lines of code +into one function, may not give you as much information as you need to +look for `hot spots' where the code is using a great deal of computer +time. Likewise, because @command{gcov} accumulates statistics by line (at +the lowest resolution), it works best with a programming style that +places only one statement on each line. If you use complicated macros +that expand to loops or to other control structures, the statistics are +less helpful---they only report on the line where the macro call +appears. If your complex macros behave like functions, you can replace +them with inline functions to solve this problem. + +@command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which +indicates how many times each line of a source file @file{@var{sourcefile}.c} +has executed. You can use these logfiles along with @command{gprof} to aid +in fine-tuning the performance of your programs. @command{gprof} gives +timing information you can use along with the information you get from +@command{gcov}. + +@command{gcov} works only on code compiled with GCC@. It is not +compatible with any other profiling or test coverage mechanism. + +@c man end + +@node Invoking Gcov +@section Invoking gcov + +@smallexample +gcov [-b] [-c] [-v] [-n] [-l] [-f] [-o directory] @var{sourcefile} +@end smallexample + +@ignore +@c man begin SYNOPSIS +gcov [@option{-b}] [@option{-c}] [@option{-v}] [@option{-n}] [@option{-l}] [@option{-f}] [@option{-o} @var{directory}] @var{sourcefile} +@c man end +@c man begin SEEALSO +gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. +@c man end +@end ignore + +@c man begin OPTIONS +@table @gcctabopt +@item -b +Write branch frequencies to the output file, and write branch summary +info to the standard output. This option allows you to see how often +each branch in your program was taken. + +@item -c +Write branch frequencies as the number of branches taken, rather than +the percentage of branches taken. + +@item -v +Display the @command{gcov} version number (on the standard error stream). + +@item -n +Do not create the @command{gcov} output file. + +@item -l +Create long file names for included source files. For example, if the +header file @file{x.h} contains code, and was included in the file +@file{a.c}, then running @command{gcov} on the file @file{a.c} will produce +an output file called @file{a.c.x.h.gcov} instead of @file{x.h.gcov}. +This can be useful if @file{x.h} is included in multiple source files. + +@item -f +Output summaries for each function in addition to the file level summary. + +@item -o +The directory where the object files live. Gcov will search for @file{.bb}, +@file{.bbg}, and @file{.da} files in this directory. +@end table + +@need 3000 +When using @command{gcov}, you must first compile your program with two +special GCC options: @samp{-fprofile-arcs -ftest-coverage}. +This tells the compiler to generate additional information needed by +gcov (basically a flow graph of the program) and also includes +additional code in the object files for generating the extra profiling +information needed by gcov. These additional files are placed in the +directory where the source code is located. + +Running the program will cause profile output to be generated. For each +source file compiled with @option{-fprofile-arcs}, an accompanying @file{.da} +file will be placed in the source directory. + +Running @command{gcov} with your program's source file names as arguments +will now produce a listing of the code along with frequency of execution +for each line. For example, if your program is called @file{tmp.c}, this +is what you see when you use the basic @command{gcov} facility: + +@smallexample +$ gcc -fprofile-arcs -ftest-coverage tmp.c +$ a.out +$ gcov tmp.c + 87.50% of 8 source lines executed in file tmp.c +Creating tmp.c.gcov. +@end smallexample + +The file @file{tmp.c.gcov} contains output from @command{gcov}. +Here is a sample: + +@smallexample + main() + @{ + 1 int i, total; + + 1 total = 0; + + 11 for (i = 0; i < 10; i++) + 10 total += i; + + 1 if (total != 45) + ###### printf ("Failure\n"); + else + 1 printf ("Success\n"); + 1 @} +@end smallexample + +@need 450 +When you use the @option{-b} option, your output looks like this: + +@smallexample +$ gcov -b tmp.c + 87.50% of 8 source lines executed in file tmp.c + 80.00% of 5 branches executed in file tmp.c + 80.00% of 5 branches taken at least once in file tmp.c + 50.00% of 2 calls executed in file tmp.c +Creating tmp.c.gcov. +@end smallexample + +Here is a sample of a resulting @file{tmp.c.gcov} file: + +@smallexample + main() + @{ + 1 int i, total; + + 1 total = 0; + + 11 for (i = 0; i < 10; i++) +branch 0 taken = 91% +branch 1 taken = 100% +branch 2 taken = 100% + 10 total += i; + + 1 if (total != 45) +branch 0 taken = 100% + ###### printf ("Failure\n"); +call 0 never executed +branch 1 never executed + else + 1 printf ("Success\n"); +call 0 returns = 100% + 1 @} +@end smallexample + +For each basic block, a line is printed after the last line of the basic +block describing the branch or call that ends the basic block. There can +be multiple branches and calls listed for a single source line if there +are multiple basic blocks that end on that line. In this case, the +branches and calls are each given a number. There is no simple way to map +these branches and calls back to source constructs. In general, though, +the lowest numbered branch or call will correspond to the leftmost construct +on the source line. + +For a branch, if it was executed at least once, then a percentage +indicating the number of times the branch was taken divided by the +number of times the branch was executed will be printed. Otherwise, the +message ``never executed'' is printed. + +For a call, if it was executed at least once, then a percentage +indicating the number of times the call returned divided by the number +of times the call was executed will be printed. This will usually be +100%, but may be less for functions call @code{exit} or @code{longjmp}, +and thus may not return every time they are called. + +The execution counts are cumulative. If the example program were +executed again without removing the @file{.da} file, the count for the +number of times each line in the source was executed would be added to +the results of the previous run(s). This is potentially useful in +several ways. For example, it could be used to accumulate data over a +number of program runs as part of a test verification suite, or to +provide more accurate long-term information over a large number of +program runs. + +The data in the @file{.da} files is saved immediately before the program +exits. For each source file compiled with @option{-fprofile-arcs}, the profiling +code first attempts to read in an existing @file{.da} file; if the file +doesn't match the executable (differing number of basic block counts) it +will ignore the contents of the file. It then adds in the new execution +counts and finally writes the data to the file. + +@node Gcov and Optimization +@section Using @command{gcov} with GCC Optimization + +If you plan to use @command{gcov} to help optimize your code, you must +first compile your program with two special GCC options: +@samp{-fprofile-arcs -ftest-coverage}. Aside from that, you can use any +other GCC options; but if you want to prove that every single line +in your program was executed, you should not compile with optimization +at the same time. On some machines the optimizer can eliminate some +simple code lines by combining them with other lines. For example, code +like this: + +@smallexample +if (a != b) + c = 1; +else + c = 0; +@end smallexample + +@noindent +can be compiled into one instruction on some machines. In this case, +there is no way for @command{gcov} to calculate separate execution counts +for each line because there isn't separate code for each line. Hence +the @command{gcov} output looks like this if you compiled the program with +optimization: + +@smallexample + 100 if (a != b) + 100 c = 1; + 100 else + 100 c = 0; +@end smallexample + +The output shows that this block of code, combined by optimization, +executed 100 times. In one sense this result is correct, because there +was only one instruction representing all four of these lines. However, +the output does not indicate how many times the result was 0 and how +many times the result was 1. +@c man end + +@node Gcov Data Files +@section Brief description of @command{gcov} data files + +@command{gcov} uses three files for doing profiling. The names of these +files are derived from the original @emph{source} file by substituting +the file suffix with either @file{.bb}, @file{.bbg}, or @file{.da}. All +of these files are placed in the same directory as the source file, and +contain data stored in a platform-independent method. + +The @file{.bb} and @file{.bbg} files are generated when the source file +is compiled with the GCC @option{-ftest-coverage} option. The +@file{.bb} file contains a list of source files (including headers), +functions within those files, and line numbers corresponding to each +basic block in the source file. + +The @file{.bb} file format consists of several lists of 4-byte integers +which correspond to the line numbers of each basic block in the +file. Each list is terminated by a line number of 0. A line number of @minus{}1 +is used to designate that the source file name (padded to a 4-byte +boundary and followed by another @minus{}1) follows. In addition, a line number +of @minus{}2 is used to designate that the name of a function (also padded to a +4-byte boundary and followed by a @minus{}2) follows. + +The @file{.bbg} file is used to reconstruct the program flow graph for +the source file. It contains a list of the program flow arcs (possible +branches taken from one basic block to another) for each function which, +in combination with the @file{.bb} file, enables gcov to reconstruct the +program flow. + +In the @file{.bbg} file, the format is: +@smallexample + number of basic blocks for function #0 (4-byte number) + total number of arcs for function #0 (4-byte number) + count of arcs in basic block #0 (4-byte number) + destination basic block of arc #0 (4-byte number) + flag bits (4-byte number) + destination basic block of arc #1 (4-byte number) + flag bits (4-byte number) + @dots{} + destination basic block of arc #N (4-byte number) + flag bits (4-byte number) + count of arcs in basic block #1 (4-byte number) + destination basic block of arc #0 (4-byte number) + flag bits (4-byte number) + @dots{} +@end smallexample + +A @minus{}1 (stored as a 4-byte number) is used to separate each function's +list of basic blocks, and to verify that the file has been read +correctly. + +The @file{.da} file is generated when a program containing object files +built with the GCC @option{-fprofile-arcs} option is executed. A +separate @file{.da} file is created for each source file compiled with +this option, and the name of the @file{.da} file is stored as an +absolute pathname in the resulting object file. This path name is +derived from the source file name by substituting a @file{.da} suffix. + +The format of the @file{.da} file is fairly simple. The first 8-byte +number is the number of counts in the file, followed by the counts +(stored as 8-byte numbers). Each count corresponds to the number of +times each arc in the program is executed. The counts are cumulative; +each time the program is executed, it attempts to combine the existing +@file{.da} files with the new counts for this invocation of the +program. It ignores the contents of any @file{.da} files whose number of +arcs doesn't correspond to the current program, and merely overwrites +them instead. + +All three of these files use the functions in @file{gcov-io.h} to store +integers; the functions in this header provide a machine-independent +mechanism for storing and retrieving data from a stream. + |