From faaad766053574ebc7c06c73a58f65b6c080cbe6 Mon Sep 17 00:00:00 2001 From: janis Date: Mon, 20 Aug 2001 17:08:14 +0000 Subject: [PATCH] * doc/invoke.texi (Profiling options): Clarify the interactions between -fprofile-arcs and -ftest-coverage, -fprofile-arcs. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@45053 138bc75d-0d04-0410-961f-82ee72b054a4 --- gcc/ChangeLog | 5 +++ gcc/doc/invoke.texi | 88 +++++++++++++++++++++++++++++++++++------------------ 2 files changed, 64 insertions(+), 29 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 611d994..8e7eeeb 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,8 @@ +2001-08-20 Janis Johnson + + * doc/invoke.texi (Profiling options): Clarify the interactions + between -fprofile-arcs and -ftest-coverage, -fprofile-arcs. + 2001-08-20 Jeffrey Oldham * crtstuff.c (__do_global_ctors): Fix typo in preprocessing diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index c0e69e6..2e517e5 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -2756,33 +2756,46 @@ frequencies. @item -fprofile-arcs @opindex fprofile-arcs -Instrument @dfn{arcs} during compilation. For each function of your -program, GCC creates a program flow graph, then finds a spanning tree -for the graph. Only arcs that are not on the spanning tree have to be -instrumented: the compiler adds code to count the number of times that these -arcs are executed. When an arc is the only exit or only entrance to a -block, the instrumentation code can be added to the block; otherwise, a -new basic block must be created to hold the instrumentation code. - -Since not every arc in the program must be instrumented, programs -compiled with this option run faster than programs compiled with -@option{-a}, which adds instrumentation code to every basic block in the -program. The tradeoff: since @code{gcov} does not have -execution counts for all branches, it must start with the execution -counts for the instrumented branches, and then iterate over the program -flow graph until the entire graph has been solved. Hence, @code{gcov} -runs a little more slowly than a program which uses information from -@option{-a}. - -@option{-fprofile-arcs} also makes it possible to estimate branch -probabilities, and to calculate basic block execution counts. In -general, basic block execution counts do not give enough information to -estimate all branch probabilities. When the compiled program exits, it -saves the arc execution counts to a file called -@file{@var{sourcename}.da}. Use the compiler option +Instrument @dfn{arcs} during compilation to generate coverage data +or for profile-directed block ordering. During execution the program +records how many times each branch is executed and how many times it is +taken. When the compiled program exits it saves this data to a file +called @file{@var{sourcename}.da} for each source file. + +For profile-directed block ordering, compile the program with +@option{-fprofile-arcs} plus optimization and code generation options, +generate the arc profile information by running the program on a +selected workload, and then compile the program again with the same +optimization and code generation options plus @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that -Control Optimization}) when recompiling, to optimize using estimated -branch probabilities. +Control Optimization}). + +The other use of @option{-fprofile-arcs} is for use with @code{gcov}, +when it is used with the @option{-ftest-coverage} option. GCC +supports two methods of determining code coverage: the options that +support @code{gcov}, and options @option{-a} and @option{-ax}, which +write information to text files. The options that support @code{gcov} +do not need to instrument every arc in the program, so a program compiled +with them runs faster than a program compiled with @option{-a}, which +adds instrumentation code to every basic block in the program. The +tradeoff: since @code{gcov} does not have execution counts for all +branches, it must start with the execution counts for the instrumented +branches, and then iterate over the program flow graph until the entire +graph has been solved. Hence, @code{gcov} runs a little more slowly than +a program which uses information from @option{-a} and @option{-ax}. + +With @option{-fprofile-arcs}, for each function of your program GCC +creates a program flow graph, then finds a spanning tree for the graph. +Only arcs that are not on the spanning tree have to be instrumented: the +compiler adds code to count the number of times that these arcs are +executed. When an arc is the only exit or only entrance to a block, the +instrumentation code can be added to the block; otherwise, a new basic +block must be created to hold the instrumentation code. + +This option makes it possible to estimate branch probabilities and to +calculate basic block execution counts. In general, basic block +execution counts as provided by @option{-a} do not give enough +information to estimate all branch probabilities. @need 2000 @item -ftest-coverage @@ -2800,10 +2813,22 @@ associate basic block execution counts with line numbers. A list of all arcs in the program flow graph. This allows @code{gcov} to reconstruct the program flow graph, so that it can compute all basic block and arc execution counts from the information in the -@code{@var{sourcename}.da} file (this last file is the output from -@option{-fprofile-arcs}). +@code{@var{sourcename}.da} file. @end table +Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter +option adds instrumentation to the program, which then writes +execution counts to another data file: + +@table @gcctabopt +@item @var{sourcename}.da +Runtime arc execution counts, used in conjunction with the arc +information in the file @code{@var{sourcename}.bbg}. +@end table + +Coverage data will map better to the source files if +@option{-ftest-coverage} is used without optimization. + @item -d@var{letters} @opindex d Says to make debugging dumps during compilation at times specified by @@ -3571,7 +3596,12 @@ After running a program compiled with @option{-fprofile-arcs} (@pxref{Debugging Options,, Options for Debugging Your Program or @command{gcc}}), you can compile it a second time using @option{-fbranch-probabilities}, to improve optimizations based on -guessing the path a branch might take. +the number of times each branch was taken. When the program +compiled with @option{-fprofile-arcs} exits it saves arc execution +counts to a file called @file{@var{sourcename}.da} for each source +file The information in this data file is very dependent on the +structure of the generated code, so you must use the same source code +and the same optimization options for both compilations. @ifset INTERNALS With @option{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT} -- 2.7.4