profile.c: Add file comment describing the overall algorithm and structures.

* profile.c: Add file comment describing the overall algorithm and
	structures.
	(struct edge_info): Add comments.
	(struct bb_info): Add comments.
	* basic-block.h (EDGE_*): Add comments.
	* doc/gcov.texi (Gcov Data Files): Document bit flags.

From-SVN: r55842

gcc/ChangeLog

@@ -1,3 +1,12 @@
+2002-07-29  Nathan Sidwell  <nathan@codesourcery.com>
+
+	* profile.c: Add file comment describing the overall algorithm and
+	structures.
+	(struct edge_info): Add comments.
+	(struct bb_info): Add comments.
+	* basic-block.h (EDGE_*): Add comments.
+	* doc/gcov.texi (Gcov Data Files): Document bit flags.
+
 2002-07-29  Bob Wilson  <bob.wilson@acm.org>
 
 	* config/xtensa/elf.h, config/xtensa/linux.h

gcc/basic-block.h

@@ -135,13 +135,16 @@ typedef struct edge_def {
 				   in profile.c  */
 } *edge;
 
-#define EDGE_FALLTHRU		1
-#define EDGE_ABNORMAL		2
-#define EDGE_ABNORMAL_CALL	4
-#define EDGE_EH			8
-#define EDGE_FAKE		16
-#define EDGE_DFS_BACK		32
-#define EDGE_CAN_FALLTHRU	64
+#define EDGE_FALLTHRU		1	/* 'Straight line' flow */
+#define EDGE_ABNORMAL		2	/* Strange flow, like computed
+					   label, or eh */
+#define EDGE_ABNORMAL_CALL	4	/* Call with abnormal exit
+					   like an exception, or sibcall */
+#define EDGE_EH			8	/* Exception throw */
+#define EDGE_FAKE		16	/* Not a real edge (profile.c) */
+#define EDGE_DFS_BACK		32	/* A backwards edge */
+#define EDGE_CAN_FALLTHRU	64	/* Candidate for straight line
+					   flow. */
 
 #define EDGE_COMPLEX	(EDGE_ABNORMAL | EDGE_ABNORMAL_CALL | EDGE_EH)
 

gcc/doc/gcov.texi

@@ -348,12 +348,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
@@ -388,6 +389,22 @@ 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
@@ -395,7 +412,8 @@ 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 @file{.da} consists of several blocks (one for each run) with the following structure:
+The @file{.da} consists of several blocks (one for each run) with the
+following structure:
 @smallexample
         "magic" number @minus{}123 (4-byte number)
 	number of functions (4-byte number)

gcc/profile.c

@@ -22,6 +22,40 @@ along with GCC; see the file COPYING.  If not, write to the Free
 Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 02111-1307, USA.  */
 
+/* Generate basic block profile instrumentation and auxiliary files.
+   Profile generation is optimized, so that not all arcs in the basic
+   block graph need instrumenting. First, the BB graph is closed with
+   one entry (function start), and one exit (function exit).  Any
+   ABNORMAL_EDGE cannot be instrumented (because there is no control
+   path to place the code). We close the graph by inserting fake
+   EDGE_FAKE edges to the EXIT_BLOCK, from the sources of abnormal
+   edges that do not go to the exit_block. We ignore such abnormal
+   edges.  Naturally these fake edges are never directly traversed,
+   and so *cannot* be directly instrumented.  Some other graph
+   massaging is done. To optimize the instrumentation we generate the
+   BB minimal span tree, only edges that are not on the span tree
+   (plus the entry point) need instrumenting. From that information
+   all other edge counts can be deduced.  By construction all fake
+   edges must be on the spanning tree. We also attempt to place
+   EDGE_CRITICAL edges on the spanning tree.
+
+   The two auxiliary files generated are <dumpbase>.bb and
+   <dumpbase>.bbg. The former contains the BB->linenumber
+   mappings, and the latter describes the BB graph.
+
+   The BB file contains line numbers for each block. For each basic
+   block, a zero count is output (to mark the start of a block), then
+   the line numbers of that block are listed. A zero ends the file
+   too.
+
+   The BBG file contains a count of the blocks, followed by edge
+   information, for every edge in the graph. The edge information
+   lists the source and target block numbers, and a bit mask
+   describing the type of edge.
+
+   The BB and BBG file formats are fully described in the gcov
+   documentation.  */
+
 /* ??? Register allocation should use basic block execution counts to
    give preference to the most commonly executed blocks.  */
 
@@ -54,18 +88,24 @@ Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 #include "langhooks.h"
 
 /* Additional information about the edges we need.  */
-struct edge_info
-  {
-    unsigned int count_valid : 1;
-    unsigned int on_tree : 1;
-    unsigned int ignore : 1;
-  };
-struct bb_info
-  {
-    unsigned int count_valid : 1;
-    gcov_type succ_count;
-    gcov_type pred_count;
-  };
+struct edge_info {
+  unsigned int count_valid : 1;
+  
+  /* Is on the spanning tree. */
+  unsigned int on_tree : 1;
+  
+  /* Pretend this edge does not exist (it is abnormal and we've
+     inserted a fake to compensate). */
+  unsigned int ignore : 1;
+};
+
+struct bb_info {
+  unsigned int count_valid : 1;
+
+  /* Number of successor and predecessor edges. */
+  gcov_type succ_count;
+  gcov_type pred_count;
+};
 
 #define EDGE_INFO(e)  ((struct edge_info *) (e)->aux)
 #define BB_INFO(b)  ((struct bb_info *) (b)->aux)