[PATCH] clarify branch profile options in invoke.texi

[Janis Johnson <janis at us dot ibm dot com>]

I found the documentation about profiling and branch probabilities
confusing, so here's what I believe to be an improvement.  This has
been through a build on i686-unknown-linux-gnu and the resulting
info file looks good.

2001-07-16  Janis Johnson <janis@us.ibm.com>

	* doc/invoke.texi: Clarify descriptions of branch profiling options
	-fprofile-arcs, -ftest-coverage, and -fbranch-probabilities.

--- doc/invoke.texi.orig	Mon Jul 16 16:57:49 2001
+++ doc/invoke.texi	Mon Jul 16 17:21:41 2001
@@ -2797,33 +2797,46 @@
 
 @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
@@ -2841,10 +2854,22 @@
 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
@@ -3621,7 +3646,12 @@
 (@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 is 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}