invoke.texi (Profiling options): Clarify the interactions between -fprofile-arcs and -ftest-coverage, -fprofile-arcs.

* doc/invoke.texi (Profiling options): Clarify the interactions
	between -fprofile-arcs and -ftest-coverage, -fprofile-arcs.

From-SVN: r45053

gcc/ChangeLog

@@ -1,3 +1,8 @@
+2001-08-20  Janis Johnson  <janis187@us.ibm.com>
+
+	* doc/invoke.texi (Profiling options): Clarify the interactions
+	between -fprofile-arcs and -ftest-coverage, -fprofile-arcs.
+
 2001-08-20  Jeffrey Oldham  <oldham@codesourcery.com>
 
 	* crtstuff.c (__do_global_ctors): Fix typo in preprocessing

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
+Instrument @dfn{arcs} during compilation to generate coverage data
-program, GCC creates a program flow graph, then finds a spanning tree
+or for profile-directed block ordering.  During execution the program
-for the graph.  Only arcs that are not on the spanning tree have to be
+records how many times each branch is executed and how many times it is
-instrumented: the compiler adds code to count the number of times that these
+taken.  When the compiled program exits it saves this data to a file
-arcs are executed.  When an arc is the only exit or only entrance to a
+called @file{@var{sourcename}.da} for each source file.
-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
+For profile-directed block ordering, compile the program with
-compiled with this option run faster than programs compiled with
+@option{-fprofile-arcs} plus optimization and code generation options,
-@option{-a}, which adds instrumentation code to every basic block in the
+generate the arc profile information by running the program on a
-program.  The tradeoff: since @code{gcov} does not have
+selected workload, and then compile the program again with the same
-execution counts for all branches, it must start with the execution
+optimization and code generation options plus
-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
 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
-Control Optimization}) when recompiling, to optimize using estimated
+Control Optimization}).
-branch probabilities.
+
+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
+@code{@var{sourcename}.da} file.
-@option{-fprofile-arcs}).
 @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}