diff options
Diffstat (limited to 'contrib/gcc/doc/gcov.texi')
| -rw-r--r-- | contrib/gcc/doc/gcov.texi | 268 |
1 files changed, 183 insertions, 85 deletions
diff --git a/contrib/gcc/doc/gcov.texi b/contrib/gcc/doc/gcov.texi index 78e6667..85d5289 100644 --- a/contrib/gcc/doc/gcov.texi +++ b/contrib/gcc/doc/gcov.texi @@ -1,13 +1,15 @@ -@c Copyright (C) 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc. +@c Copyright (C) 1996, 1997, 1999, 2000, 2001, +@c 2002, 2003 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, 2001 Free Software Foundation, Inc. +Copyright @copyright{} 1996, 1997, 1999, 2000, 2001, 2002, 2003 +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 +under the terms of the GNU Free Documentation License, Version 1.2 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 @@ -47,12 +49,13 @@ test code coverage in your programs. @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. +to analyze your programs to help create more efficient, faster running +code and to discover untested parts of your program. 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 @@ -117,10 +120,13 @@ gcov @r{[}@var{options}@r{]} @var{sourcefile} @ignore @c man begin SYNOPSIS gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] - [@option{-b}|@option{--branch-probabilities}] [@option{-c}|@option{--branch-counts}] - [@option{-n}|@option{--no-output}] [@option{-l}|@option{--long-file-names}] + [@option{-b}|@option{--branch-probabilities}] + [@option{-c}|@option{--branch-counts}] + [@option{-n}|@option{--no-output}] + [@option{-l}|@option{--long-file-names}] + [@option{-p}|@option{--preserve-paths}] [@option{-f}|@option{--function-summaries}] - [@option{-o}|@option{--object-directory} @var{directory}] @var{sourcefile} + [@option{-o}|@option{--object-directory} @var{directory|file}] @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}. @@ -159,31 +165,71 @@ Do not create the @command{gcov} output file. 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}. +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 -p +@itemx --preserve-paths +Preserve complete path information in the names of generated +@file{.gcov} files. Without this option, just the filename component is +used. With this option, all directories are used, with '/' characters +translated to '#' characters, '.' directory components removed and '..' +components renamed to '^'. This is useful if sourcefiles are in several +different directories. It also affects the @samp{-l} option. + @item -f @itemx --function-summaries Output summaries for each function in addition to the file level summary. -@item -o @var{directory} +@item -o @var{directory|file} @itemx --object-directory @var{directory} -The directory where the object files live. Gcov will search for @file{.bb}, -@file{.bbg}, and @file{.da} files in this directory. +@itemx --object-file @var{file} +Specify either the directory containing the gcov data files, or the +object path name. The @file{.bb}, @file{.bbg}, and +@file{.da} data files are searched for using this option. If a directory +is specified, the data files are in that directory and named after the +source file name, without its extension. If a file is specified here, +the data files are named after that file, without its extension. If this +option is not supplied, it defaults to the current directory. + @end table -@need 3000 +@command{gcov} should be run with the current directory the same as that +when you invoked the compiler. Otherwise it will not be able to locate +the source files. @command{gcov} produces files called +@file{@var{mangledname}.gcov} in the current directory. These contain +the coverage information of the source file they correspond to. +One @file{.gcov} file is produced for each source file containing code, +which was compiled to produce the data files. The @file{.gcov} files +contain the ':' separated fields along with program source code. The +format is + +@smallexample +@var{execution_count}:@var{line_number}:@var{source line text} +@end smallexample + +Additional block information may succeed each line, when requested by +command line option. The @var{execution_count} is @samp{-} for lines +containing no code and @samp{#####} for lines which were never +executed. Some lines of information at the start have @var{line_number} +of zero. + +When printing percentages, 0% and 100% are only printed when the values +are @emph{exactly} 0% and 100% respectively. Other values which would +conventionally be rounded to 0% or 100% are instead printed as the +nearest non-boundary value. + 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. +directory where the object file 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. +file will be placed in the object file 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 @@ -194,7 +240,7 @@ is what you see when you use the basic @command{gcov} facility: $ gcc -fprofile-arcs -ftest-coverage tmp.c $ a.out $ gcov tmp.c - 87.50% of 8 source lines executed in file tmp.c +90.00% of 10 source lines executed in file tmp.c Creating tmp.c.gcov. @end smallexample @@ -202,20 +248,25 @@ 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 @} + -: 0:Source:tmp.c + -: 0:Object:tmp.bb + -: 1:#include <stdio.h> + -: 2: + -: 3:int main (void) + 1: 4:@{ + 1: 5: int i, total; + -: 6: + 1: 7: total = 0; + -: 8: + 11: 9: for (i = 0; i < 10; i++) + 10: 10: total += i; + -: 11: + 1: 12: if (total != 45) + #####: 13: printf ("Failure\n"); + -: 14: else + 1: 15: printf ("Success\n"); + 1: 16: return 0; + 1: 17:@} @end smallexample @need 450 @@ -223,37 +274,42 @@ 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 +90.00% of 10 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 @} + -: 0:Source:tmp.c + -: 0:Object:tmp.bb + -: 1:#include <stdio.h> + -: 2: + -: 3:int main (void) + 1: 4:@{ + 1: 5: int i, total; + -: 6: + 1: 7: total = 0; + -: 8: + 11: 9: for (i = 0; i < 10; i++) +branch 0: taken 90% +branch 1: taken 100% +branch 2: taken 100% + 10: 10: total += i; + -: 11: + 1: 12: if (total != 45) +branch 0: taken 100% + #####: 13: printf ("Failure\n"); +call 0: never executed +branch 1: never executed + -: 14: else + 1: 15: printf ("Success\n"); +call 0: returns 100% + 1: 16: return 0; + 1: 17:@} @end smallexample For each basic block, a line is printed after the last line of the basic @@ -286,11 +342,11 @@ 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. +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 @@ -319,10 +375,10 @@ 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; + 100: 12:if (a != b) + 100: 13: c = 1; + 100: 14:else + 100: 15: c = 0; @end smallexample The output shows that this block of code, combined by optimization, @@ -348,12 +404,13 @@ 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. +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 @@ -363,6 +420,8 @@ program flow. In the @file{.bbg} file, the format is: @smallexample + name of function #0 + checksum of function #0 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) @@ -383,22 +442,61 @@ 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 function name is stored as a @minus{}1 (4 bytes), the length (4 bytes), +the name itself (padded to 4-byte boundary) followed by a @minus{}1 (4 bytes). + +The flags are defined as follows: +@itemize +@item bit0 +On function spanning tree + +@item bit1 +Is a fake edge + +@item bit2 +Is the fall through edge from one block to its immediate successor. + +@item bit3-bit31 +For future expansion + +@end itemize + 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. +derived from the object file name by substituting a @file{.da} suffix. + +The @file{.da} consists of one or more blocks with the following +structure: +@smallexample + "magic" number @minus{}123 (4-byte number) + number of functions (4-byte number) + length of the "extension block" in bytes + extension block (variable length) + name of function #0 (the same format as in .bbg file) + checksum of function #0 + number of instrumented arcs (4-byte number) + count of arc #0 (8-byte number) + count of arc #1 (8-byte number) + @dots{} + count of arc #M_0 (8-byte number) + name of function #1 (the same format as in .bbg file) + checksum of function #1 + @dots{} +@end smallexample +Multiple program runs might merge data into a single block, or might +append a new block. The current structure of the extension block is as +follows: +@smallexample + number of instrumented arcs in whole program (4-byte number) + sum all of instrumented arcs in whole program (8-byte number) + maximal value of counter in whole program (8-byte number) + number of instrumented arcs in the object file (4-byte number) + sum all of instrumented arcs in the object file (8-byte number) + maximal value of counter in the object file (8-byte number) +@end smallexample 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 |
