gcov-io.h: Update documentation.

	* gcov-io.h: Update documentation.
	(GCOV_GRAPH_SUFFIX, GCOV_GRAPH_MAGIC): Rename to GCOV_NOTE_SUFFIX,
	GCOV_NOTE_MAGIC.
	(GCOV_DATA_SUFFIX, GCOV_NOTE_SUFFIX): Update.
	(GCOV_DATA_MAGIC, GCOV_NOTE_MAGIC): Make non-palindromic.
	(struct gcov_var): Change buffer's type. Add endian flag.
	(gcov_open): Remove mode in libgcov.
	(gcov_magic): Prototype.
	* gcov-io.c (from_file): New.
	(gcov_open): Clear endian flag.
	(gcov_magic): New.
	(gcov_write_bytes, gcov_read_bytes): Return gcov_unsigned_t
	pointers.
	(gcov_write_unsigned, gcov_write_counter, gcov_write_string,
	gcov_write_tag, gcov_write_length, gcov_write_tag_length): Update.
	(gcov_read_unsigned, gcov_read_counter, gcov_read_string): Update.
	* gcov-iov.c (main): Correct cast.
	* coverage.c (read_counts_file): Use gcov_magic. Remove endianness
	conversion.
	(gcov_begin_output): Use GCOV_NOTE_MAGIC.
	(coverage_init): Use GCOV_NOTE_SUFFIX.
	* libgcov.c (gcov_version_mismatch): Remove endianness conversion.
	Rename to gcov_version, and return flag.
	(gcov_exit): Use gcov_version.
	(__gcov_init): Use gcov_version.
	* Makefile.in (coverageexts): Update.
	* gcov.c (print_version): Remove endianness conversion.
	(create_file_names): Use GCOV_NOTE_SUFFIX.
	(read_graph_file): Use gcov_magic.
	(read_count_file): Likewise.
	* gcov-dump.c (dump_file): Remove endianness conversion, use
	gcov_magic.

From-SVN: r69137

1 files changed, 90 insertions, 84 deletions

diff --git a/gcc/gcov-io.h b/gcc/gcov-io.h
index 999d07eea08..35c31b955fe 100644
--- a/gcc/gcov-io.h
+++ b/gcc/gcov-io.h
@@ -28,24 +28,25 @@ Software Foundation, 59 Temple Place - Suite 330, Boston, MA
    This exception does not however invalidate any other reasons why
    the executable file might be covered by the GNU General Public License.  */
 
-/* Coverage information is held in two files.  A basic block graph
-   file, which is generated by the compiler, and a counter file, which
-   is generated by the program under test.  Both files use a similar
-   structure.  We do not attempt to make these files backwards
-   compatible with previous versions, as you only need coverage
-   information when developing a program.  We do hold version
-   information, so that mismatches can be detected, and we use a
-   format that allows tools to skip information they do not understand
-   or are not interested in.
-
-   Numbers are recorded in big endian unsigned binary form.  Either in
-   32 or 64 bits.  Strings are stored with a length count and NUL
-   terminator, and 0 to 3 bytes of zero padding up to the next 4 byte
-   boundary.  Zero length and NULL strings are simply stored as a
-   length of zero (they have no trailing NUL or padding).
-
-   	int32:  byte3 byte2 byte1 byte0
-	int64:  byte7 byte6 byte5 byte4 byte3 byte2 byte1 byte0
+/* Coverage information is held in two files.  A notes file, which is
+   generated by the compiler, and a data file, which is generated
+   by the program under test.  Both files use a similar structure.  We
+   do not attempt to make these files backwards compatible with
+   previous versions, as you only need coverage information when
+   developing a program.  We do hold version information, so that
+   mismatches can be detected, and we use a format that allows tools
+   to skip information they do not understand or are not interested
+   in.
+
+   Numbers are recorded in the 32 bit unsigned binary form of the
+   endianness of the machine generating the file. 64 bit numbers are
+   stored as two 32 bit numbers, the low part first.  Strings are
+   stored as length rounded up to 4 followed by the string and then 1
+   to 4 NUL bytes.  Zero length and NULL strings are simply stored as
+   a length of zero (they have no trailing NUL or padding).
+
+   	int32:  byte3 byte2 byte1 byte0 | byte0 byte1 byte2 byte3
+	int64:  int32:low int32:high
 	string: int32:0 | int32:length char* char:0 padding
 	padding: | char:0 | char:0 char:0 | char:0 char:0 char:0
 	item: int32 | int64 | string
@@ -54,31 +55,30 @@ Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 
    	file : int32:magic int32:version int32:stamp record*
 
-   The magic ident is different for the bbg and the counter files.
-   The version is the same for both files and is derived from gcc's
-   version number. The stamp value is used to synchronize bbg and
-   counter files and to synchronize merging within a counter file. It
-   need not be an absolute time stamp, merely a ticker that increments
-   fast enough and cycles slow enough to distinguish different
-   compile/run/compile cycles.
+   The magic ident is different for the notes and the data files.  The
+   magic ident is used to determine the endianness of the file, when
+   reading.  The version is the same for both files and is derived
+   from gcc's version number. The stamp value is used to synchronize
+   note and data files and to synchronize merging within a data
+   file. It need not be an absolute time stamp, merely a ticker that
+   increments fast enough and cycles slow enough to distinguish
+   different compile/run/compile cycles.
    
-   Although the ident and version are formally 32 bit
-   numbers, they are derived from 4 character ASCII strings.  The
-   version number consists of the single character major version
-   number, a two character minor version number (leading zero for
-   versions less than 10), and a single character indicating the
-   status of the release.  That will be 'e' experimental, 'p'
-   prerelease and 'r' for release.  Because, by good fortune, these are
-   in alphabetical order, string collating can be used to compare
-   version strings, and because numbers are stored big endian, numeric
-   comparison can be used when it is read as a 32 bit value.  Be aware
-   that the 'e' designation will (naturally) be unstable and might be
+   Although the ident and version are formally 32 bit numbers, they
+   are derived from 4 character ASCII strings.  The version number
+   consists of the single character major version number, a two
+   character minor version number (leading zero for versions less than
+   10), and a single character indicating the status of the release.
+   That will be 'e' experimental, 'p' prerelease and 'r' for release.
+   Because, by good fortune, these are in alphabetical order, string
+   collating can be used to compare version strings.  Be aware that
+   the 'e' designation will (naturally) be unstable and might be
    incompatible with itself.  For gcc 3.4 experimental, it would be
-   '304e' (0x33303465).  When the major version reaches 10, the letters
-   A-Z will be used.  Assuming minor increments releases every 6
-   months, we have to make a major increment every 50 years.  Assuming
-   major increments releases every 5 years, we're ok for the next 155
-   years -- good enough for me.
+   '304e' (0x33303465).  When the major version reaches 10, the
+   letters A-Z will be used.  Assuming minor increments releases every
+   6 months, we have to make a major increment every 50 years.
+   Assuming major increments releases every 5 years, we're ok for the
+   next 155 years -- good enough for me.
 
    A record has a tag, length and variable amount of data.
 
@@ -87,21 +87,21 @@ Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 	data: item*
 
    Records are not nested, but there is a record hierarchy.  Tag
-   numbers reflect this hierarchy.  Tags are unique across bbg and da
-   files.  Some record types have a varying amount of data.  The LENGTH
-   is usually used to determine how much data.  The tag value is split
-   into 4 8-bit fields, one for each of four possible levels.  The
-   most significant is allocated first.  Unused levels are zero.
+   numbers reflect this hierarchy.  Tags are unique across note and
+   data files.  Some record types have a varying amount of data.  The
+   LENGTH is usually used to determine how much data.  The tag value
+   is split into 4 8-bit fields, one for each of four possible levels.
+   The most significant is allocated first.  Unused levels are zero.
    Active levels are odd-valued, so that the LSB of the level is one.
    A sub-level incorporates the values of its superlevels.  This
    formatting allows you to determine the tag hierarchy, without
    understanding the tags themselves, and is similar to the standard
    section numbering used in technical documents.  Level values
-   [1..3f] are used for common tags, values [41..9f] for the graph
-   file and [a1..ff] for the counter file.
+   [1..3f] are used for common tags, values [41..9f] for the notes
+   file and [a1..ff] for the data file.
 
    The basic block graph file contains the following records
-   	bbg:  unit function-graph*
+   	note: unit function-graph*
 	unit: header int32:checksum string:source
 	function-graph: announce_function basic_blocks {arcs | lines}*
 	announce_function: header int32:ident int32:checksum
@@ -130,7 +130,7 @@ Software Foundation, 59 Temple Place - Suite 330, Boston, MA
    blocks they are for.
 
    The data file contains the following records.
-        da: {unit function-data* summary:object summary:program*}*
+        data: {unit function-data* summary:object summary:program*}*
 	unit: header int32:checksum
         function-data:	announce_function arc_counts
 	announce_function: header int32:ident int32:checksum
@@ -139,17 +139,16 @@ Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 	count-summary:	int32:num int32:runs int64:sum
 			int64:max int64:sum_max
 
-   The ANNOUNCE_FUNCTION record is the same as that in the BBG file,
-   but without the source location.
-   The ARC_COUNTS gives the counter values for those arcs that are
-   instrumented.  The SUMMARY records give information about the whole
-   object file and about the whole program.  The checksum is used for
-   whole program summaries, and disambiguates different programs which
-   include the same instrumented object file.  There may be several
-   program summaries, each with a unique checksum.  The object
-   summary's checkum is zero.  Note that the da file might contain
-   information from several runs concatenated, or the data might be
-   merged.
+   The ANNOUNCE_FUNCTION record is the same as that in the note file,
+   but without the source location.  The ARC_COUNTS gives the counter
+   values for those arcs that are instrumented.  The SUMMARY records
+   give information about the whole object file and about the whole
+   program.  The checksum is used for whole program summaries, and
+   disambiguates different programs which include the same
+   instrumented object file.  There may be several program summaries,
+   each with a unique checksum.  The object summary's checkum is zero.
+   Note that the data file might contain information from several runs
+   concatenated, or the data might be merged.
 
    This file is included by both the compiler, gcov tools and the
    runtime support library libgcov. IN_LIBGCOV and IN_GCOV are used to
@@ -231,7 +230,7 @@ typedef HOST_WIDEST_INT gcov_type;
 
 /* Poison these, so they don't accidentally slip in.  */
 #pragma GCC poison gcov_write_string gcov_write_tag gcov_write_length
-#pragma GCC poison gcov_read_string gcov_sync gcov_time
+#pragma GCC poison gcov_read_string gcov_sync gcov_time gcov_magic
 
 #endif
 
@@ -240,21 +239,21 @@ typedef HOST_WIDEST_INT gcov_type;
 #endif
 
 /* File suffixes.  */
-#define GCOV_DATA_SUFFIX ".da"
-#define GCOV_GRAPH_SUFFIX ".bbg"
+#define GCOV_DATA_SUFFIX ".gcda"
+#define GCOV_NOTE_SUFFIX ".gcno"
 
-/* File magic.  */
-#define GCOV_DATA_MAGIC  0x67636f76 /* "gcov" */
-#define GCOV_GRAPH_MAGIC 0x67626267 /* "gbbg" */
+/* File magic. Must not be palindromes.  */
+#define GCOV_DATA_MAGIC ((gcov_unsigned_t)0x67636461) /* "gcda" */
+#define GCOV_NOTE_MAGIC ((gcov_unsigned_t)0x67636e6f) /* "gcno" */
 
 /* gcov-iov.h is automatically generated by the makefile from
    version.c, it looks like
-   	#define GCOV_VERSION ((unsigned)0x89abcdef)
+   	#define GCOV_VERSION ((gcov_unsigned_t)0x89abcdef)
 */
 #include "gcov-iov.h"
 
 /* The record tags.  Values [1..3f] are for tags which may be in either
-   file.  Values [41..9f] for those in the bbg file and [a1..ff] for
+   file.  Values [41..9f] for those in the note file and [a1..ff] for
    the data file.  */
 
 #define GCOV_TAG_FUNCTION	 ((gcov_unsigned_t)0x01000000)
@@ -374,7 +373,7 @@ struct gcov_ctr_info
 struct gcov_info
 {
   gcov_unsigned_t version;	/* expected version number */
-  struct gcov_info *next;	/* link to next, used by libgcc */
+  struct gcov_info *next;	/* link to next, used by libgcov */
 
   gcov_unsigned_t stamp;	/* uniquifying time stamp */
   const char *filename;		/* output file name */
@@ -398,11 +397,11 @@ extern void __gcov_flush (void);
 /* The merge function that just sums the counters.  */
 extern void __gcov_merge_add (gcov_type *, unsigned);
 
-/* The merge function to choose the most often value.  */
+/* The merge function to choose the most common value.  */
 extern void __gcov_merge_single (gcov_type *, unsigned);
 
-/* The merge function to choose the most often difference between consecutive
-   values.  */
+/* The merge function to choose the most common difference between
+   consecutive values.  */
 extern void __gcov_merge_delta (gcov_type *, unsigned);
 #endif /* IN_LIBGCOV */
 
@@ -425,24 +424,31 @@ GCOV_LINKAGE struct gcov_var
      fit within this buffer and we always can transfer GCOV_BLOCK_SIZE
      to and from the disk. libgcov never backtracks and only writes 4
      or 8 byte objects.  */
-  unsigned char buffer[GCOV_BLOCK_SIZE + 4];
+  char buffer[GCOV_BLOCK_SIZE + 4] __attribute__ ((aligned (4)));
 #else
+  int endian;			/* Swap endianness.  */
   /* Holds a variable length block, as the compiler can write
      strings and needs to backtrack.  */
   size_t alloc;
-  unsigned char *buffer;
+  char *buffer;
 #endif
 } gcov_var;
 
-/* Functions for reading and writing gcov files. You can open a file
-   for (1) reading or (2) writing or (3) reading then rewriting. When
-   reading a file you may use the gcov_read_* functions, gcov_sync,
-   gcov_position, & gcov_error. When writing a file you
-   may use the gcov_write functions, gcov_seek & gcov_error. When a
-   file is to be rewritten you use the functions for reading, then
-   gcov_rewrite then the functions for writing.  Your file may become
-   corrupted if you break these invariants.  */
-GCOV_LINKAGE int gcov_open (const char */*name*/, int /*truncate*/);
+/* Functions for reading and writing gcov files. In libgcov you can
+   open the file for reading then writing. Elsewhere you can open the
+   file either for reading or for writing. When reading a file you may
+   use the gcov_read_* functions, gcov_sync, gcov_position, &
+   gcov_error. When writing a file you may use the gcov_write
+   functions, gcov_seek & gcov_error. When a file is to be rewritten
+   you use the functions for reading, then gcov_rewrite then the
+   functions for writing.  Your file may become corrupted if you break
+   these invariants. */
+#if IN_LIBGCOV
+GCOV_LINKAGE int gcov_open (const char */*name*/);
+#else
+GCOV_LINKAGE int gcov_open (const char */*name*/, int /*direction*/);
+GCOV_LINKAGE int gcov_magic (gcov_unsigned_t, gcov_unsigned_t);
+#endif
 GCOV_LINKAGE int gcov_close (void);
 
 /* Available everywhere.  */