gcc/gcov-io.h

   1 /* File format for coverage information
   2    Copyright (C) 1996, 1997, 1998, 2000, 2002 Free Software Foundation, Inc.
   3    Contributed by Bob Manson <manson@cygnus.com>.
   4    Completely remangled by Nathan Sidwell <nathan@codesourcery.com>.
   5
   6 This file is part of GCC.
   7
   8 GCC is free software; you can redistribute it and/or modify it under
   9 the terms of the GNU General Public License as published by the Free
  10 Software Foundation; either version 2, or (at your option) any later
  11 version.
  12
  13 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
  14 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  15 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16 for more details.
  17
  18 You should have received a copy of the GNU General Public License
  19 along with GCC; see the file COPYING.  If not, write to the Free
  20 Software Foundation, 59 Temple Place - Suite 330, Boston, MA
  21 02111-1307, USA.  */
  22
  23 /* Coverage information is held in two files.  A basic block graph
  24    file, which is generated by the compiler, and a counter file, which
  25    is generated by the program under test.  Both files use a similar
  26    structure.  We do not attempt to make these files backwards
  27    compatible with previous versions, as you only need coverage
  28    information when developing a program.  We do hold version
  29    information, so that mismatches can be detected, and we use a
  30    format that allows tools to skip information they do not understand
  31    or are not interested in.
  32
  33    Numbers are recorded in big endian unsigned binary form.  Either in
  34    32 or 64 bits.  Strings are stored with a length count and NUL
  35    terminator, and 0 to 3 bytes of zero padding up to the next 4 byte
  36    boundary.  Zero length and NULL strings are simply stored as a
  37    length of zero (they have no trailing NUL or padding).
  38
  39         int32:  byte3 byte2 byte1 byte0
  40         int64:  byte7 byte6 byte5 byte4 byte3 byte2 byte1 byte0
  41         string: int32:0 | int32:length char* char:0 padding
  42         padding: | char:0 | char:0 char:0 | char:0 char:0 char:0
  43         item: int32 | int64 | string
  44
  45    The basic format of the files is
  46
  47         file : int32:magic int32:version record*
  48
  49    The magic ident is different for the bbg and the counter files.
  50    The version is the same for both files and is derived from gcc's
  51    version number.  Although the ident and version are formally 32 bit
  52    numbers, they are derived from 4 character ASCII strings.  The
  53    version number consists of the single character major version
  54    number, a two character minor version number (leading zero for
  55    versions less than 10), and a single character indicating the
  56    status of the release.  That will be 'e' experimental, 'p'
  57    prerelease and 'r' for release.  Because, by good fortune, these are
  58    in alphabetical order, string collating can be used to compare
  59    version strings, and because numbers are stored big endian, numeric
  60    comparison can be used when it is read as a 32 bit value.  Be aware
  61    that the 'e' designation will (naturally) be unstable and might be
  62    incompatible with itself.  For gcc 3.4 experimental, it would be
  63    '304e' (0x33303465).  When the major version reaches 10, the letters
  64    A-Z will be used.  Assuming minor increments releases every 6
  65    months, we have to make a major increment every 50 years.  Assuming
  66    major increments releases every 5 years, we're ok for the next 155
  67    years -- good enough for me.
  68
  69    A record has a tag, length and variable amount of data.
  70
  71         record: header data
  72         header: int32:tag int32:length
  73         data: item*
  74
  75    Records are not nested, but there is a record hierarchy.  Tag
  76    numbers reflect this hierarchy.  Tags are unique across bbg and da
  77    files.  Some record types have a varying amount of data.  The LENGTH
  78    is usually used to determine how much data.  The tag value is split
  79    into 4 8-bit fields, one for each of four possible levels.  The
  80    most significant is allocated first.  Unused levels are zero.
  81    Active levels are odd-valued, so that the LSB of the level is one.
  82    A sub-level incorporates the values of its superlevels.  This
  83    formatting allows you to determine the tag heirarchy, without
  84    understanding the tags themselves, and is similar to the standard
  85    section numbering used in technical documents.  Level values
  86    [1..3f] are used for common tags, values [41..9f] for the graph
  87    file and [a1..ff] for the counter file.
  88
  89    The basic block graph file contains the following records
  90         bbg:  function-graph*
  91         function-graph: announce_function basic_blocks {arcs | lines}*
  92         announce_function: header string:name int32:checksum
  93         basic_block: header int32:flags*
  94         arcs: header int32:block_no arc*
  95         arc:  int32:dest_block int32:flags
  96         lines: header int32:block_no line*
  97                int32:0 string:NULL
  98         line:  int32:line_no | int32:0 string:filename
  99
 100    The BASIC_BLOCK record holds per-bb flags.  The number of blocks
 101    can be inferred from its data length.  There is one ARCS record per
 102    basic block.  The number of arcs from a bb is implicit from the
 103    data length.  It enumerates the destination bb and per-arc flags.
 104    There is one LINES record per basic block, it enumerates the source
 105    lines which belong to that basic block.  Source file names are
 106    introduced by a line number of 0, following lines are from the new
 107    source file.  The initial source file for the function is NULL, but
 108    the current source file should be remembered from one LINES record
 109    to the next.  The end of a block is indicated by an empty filename
 110    - this does not reset the current source file.  Note there is no
 111    ordering of the ARCS and LINES records: they may be in any order,
 112    interleaved in any manner.  The current filename follows the order
 113    the LINES records are stored in the file, *not* the ordering of the
 114    blocks they are for.
 115
 116    The data file contains the following records.
 117         da:   {function-data* summary:object summary:program*}*
 118         function-data:  announce_function arc_counts
 119         announce_function: header string:name int32:checksum
 120         arc_counts: header int64:count*
 121         summary: in32:checksum int32:runs int32:arcs int64:sum int64:max \
 122                 int64:max_sum int64:sum_max
 123
 124    The ANNOUNCE_FUNCTION record is the same as that in the BBG file.
 125    The ARC_COUNTS gives the counter values for those arcs that are
 126    instrumented.  The SUMMARY records give information about the whole
 127    object file and about the whole program.  The checksum is used for
 128    whole program summaries, and disambiguates different programs which
 129    include the same instrumented object file.  There may be several
 130    program summaries, each with a unique checksum.  The object
 131    summary's checkum is zero.  Note that the da file might contain
 132    information from several runs concatenated, or the data might be
 133    merged.
 134
 135    This file is included by both the compiler, gcov tools and the
 136    library.  The IN_LIBGCC2 define distinguishes these cases.  When
 137    IN_LIBGCC2 is nonzero, we're building libgcc2 for the target and
 138    know the compiler is (the just built) gcc.  Otherwise we're
 139    generating code for the host, and the compiler may or may not be
 140    gcc.  In this latter case, you must ensure that 'gcov_type' is
 141    typedefed to something suitable (unsigned HOST_WIDEST_INT is
 142    usually what you want).  */
 143
 144 #ifndef GCC_GCOV_IO_H
 145 #define GCC_GCOV_IO_H
 146
 147 #if IN_LIBGCC2
 148 #if LONG_TYPE_SIZE == GCOV_TYPE_SIZE
 149 typedef long gcov_type;
 150 #else
 151 typedef long long gcov_type;
 152 #endif
 153 #endif /* IN_LIBGCC2 */
 154
 155 /* File suffixes.  */
 156 #define GCOV_DATA_SUFFIX ".da"
 157 #define GCOV_GRAPH_SUFFIX ".bbg"
 158
 159 /* File magic.  */
 160 #define GCOV_DATA_MAGIC  0x67636f76 /* "gcov" */
 161 #define GCOV_GRAPH_MAGIC 0x67626267 /* "gbbg" */
 162
 163 /* gcov-iov.h is automatically generated by the makefile from
 164    version.c, it looks like
 165         #define GCOV_VERSION ((unsigned)0x89abcdef)
 166 */
 167 #include "gcov-iov.h"
 168
 169 /* The record tags.  Values [1..3f] are for tags which may be in either
 170    file.  Values [41..9f] for those in the bbg file and [a1..ff] for
 171    the data file.  */
 172
 173 #define GCOV_TAG_FUNCTION        ((unsigned)0x01000000)
 174 #define GCOV_TAG_BLOCKS          ((unsigned)0x01410000)
 175 #define GCOV_TAG_ARCS            ((unsigned)0x01430000)
 176 #define GCOV_TAG_LINES           ((unsigned)0x01450000)
 177 #define GCOV_TAG_ARC_COUNTS      ((unsigned)0x01a10000)
 178 #define GCOV_TAG_OBJECT_SUMMARY  ((unsigned)0xa1000000)
 179 #define GCOV_TAG_PROGRAM_SUMMARY ((unsigned)0xa3000000)
 180 #define GCOV_TAG_PLACEHOLDER_SUMMARY ((unsigned)0xa5000000)
 181 #define GCOV_TAG_INCORRECT_SUMMARY ((unsigned)0xa7000000)
 182
 183 /* The tag level mask has 1's in the position of the inner levels, &
 184    the lsb of the current level, and zero on the current and outer
 185    levels.  */
 186 #define GCOV_TAG_MASK(TAG) (((TAG) - 1) ^ (TAG))
 187
 188 /* Return nonzero if SUB is an immediate subtag of TAG.  */
 189 #define GCOV_TAG_IS_SUBTAG(TAG,SUB)                             \
 190         (GCOV_TAG_MASK (TAG) >> 8 == GCOV_TAG_MASK (SUB)        \
 191          && !(((SUB) ^ (TAG)) & ~GCOV_TAG_MASK(TAG)))
 192
 193 /* Return nonzero if SUB is at a sublevel to TAG.  */
 194 #define GCOV_TAG_IS_SUBLEVEL(TAG,SUB)                           \
 195         (GCOV_TAG_MASK (TAG) > GCOV_TAG_MASK (SUB))
 196
 197 /* Basic block flags.  */
 198 #define GCOV_BLOCK_UNEXPECTED   (1 << 0)
 199
 200 /* Arc flags.  */
 201 #define GCOV_ARC_ON_TREE        (1 << 0)
 202 #define GCOV_ARC_FAKE           (1 << 1)
 203 #define GCOV_ARC_FALLTHROUGH    (1 << 2)
 204
 205 /* Structured records.  */
 206
 207 /* Object & program summary record.  */
 208 struct gcov_summary
 209 {
 210   unsigned checksum;      /* checksum of program */
 211   unsigned runs;          /* number of program runs */
 212   unsigned arcs;          /* number of instrumented arcs */
 213   gcov_type arc_sum;      /* sum of all arc counters */
 214   gcov_type arc_max_one;  /* max counter on any one run */
 215   gcov_type arc_max_sum;  /* maximum arc_sum */
 216   gcov_type arc_sum_max;  /* sum of max_one */
 217 };
 218
 219 #if IN_LIBGCC2
 220 /* Structures embedded in coveraged program.  The structures generated
 221    by write_profile must match these.  */
 222
 223 /* Information about a single function.  */
 224 struct function_info
 225 {
 226   const char *name;             /* (mangled) name of function */
 227   unsigned checksum;            /* function checksum */
 228   unsigned n_arc_counts;        /* number of instrumented arcs */
 229 };
 230
 231 /* Information about a single object file.  */
 232 struct gcov_info
 233 {
 234   unsigned long version;        /* expected version number */
 235   struct gcov_info *next;       /* link to next, used by libgcc */
 236
 237   const char *filename;         /* output file name */
 238   long wkspc;                   /* libgcc workspace */
 239
 240   const struct function_info *functions; /* table of functions */
 241   unsigned n_functions;             /* number of functions */
 242
 243   gcov_type *arc_counts;        /* table of arc counts */
 244   unsigned n_arc_counts;        /* number of arc counts */
 245 };
 246
 247 /* Register a new object file module.  */
 248 extern void __gcov_init (struct gcov_info *);
 249
 250 /* Called before fork, to avoid double counting.  */
 251 extern void __gcov_flush (void);
 252
 253 #endif /* IN_LIBGCC2 */
 254
 255 /* Functions for reading and writing gcov files.  */
 256 static int gcov_write_unsigned PARAMS((FILE *, unsigned))
 257      ATTRIBUTE_UNUSED;
 258 static int gcov_write_counter PARAMS((FILE *, gcov_type))
 259      ATTRIBUTE_UNUSED;
 260 static int gcov_write_string PARAMS((FILE *, const char *, unsigned))
 261      ATTRIBUTE_UNUSED;
 262 static int gcov_read_unsigned PARAMS((FILE *, unsigned *))
 263      ATTRIBUTE_UNUSED;
 264 static int gcov_read_counter PARAMS((FILE *, gcov_type *))
 265      ATTRIBUTE_UNUSED;
 266 #if !IN_LIBGCC2
 267 static int gcov_read_string PARAMS((FILE *, char **, unsigned *))
 268      ATTRIBUTE_UNUSED;
 269 #endif
 270 static int gcov_read_summary PARAMS ((FILE *, struct gcov_summary *))
 271      ATTRIBUTE_UNUSED;
 272 #if IN_LIBGCC2
 273 static int gcov_write_summary PARAMS ((FILE *, unsigned,
 274                                        const struct gcov_summary *))
 275      ATTRIBUTE_UNUSED;
 276 #endif
 277 #define gcov_save_position(STREAM) \
 278         ftell (STREAM)
 279 #define gcov_reserve_length(STREAM) \
 280         (gcov_write_unsigned (STREAM, 0) ? 0 : ftell (STREAM) - 4)
 281 static int gcov_write_length PARAMS((FILE *, long))
 282      ATTRIBUTE_UNUSED;
 283 #define gcov_resync(STREAM, BASE, LENGTH) \
 284         fseek (STREAM, BASE + (long)LENGTH, SEEK_SET)
 285 #define gcov_skip(STREAM, LENGTH) \
 286         fseek (STREAM, LENGTH, SEEK_CUR)
 287 #define gcov_skip_string(STREAM, LENGTH) \
 288         fseek (STREAM, (LENGTH) + 4 - ((LENGTH) & 3), SEEK_CUR)
 289
 290
 291 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 292    file i/o error, or value error.  */
 293
 294 static int
 295 gcov_write_unsigned (file, value)
 296      FILE *file;
 297      unsigned value;
 298 {
 299   char buffer[4];
 300   unsigned ix;
 301
 302   for (ix = sizeof (buffer); ix--; )
 303     {
 304       buffer[ix] = value;
 305       value >>= 8;
 306     }
 307   return ((sizeof (value) > sizeof (buffer) && value)
 308           || fwrite (buffer, sizeof (buffer), 1, file) != 1);
 309 }
 310
 311 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 312    file i/o error, or value error.  Negative values are not checked
 313    here -- they are checked in gcov_read_counter.  */
 314
 315 static int
 316 gcov_write_counter (file, value)
 317      FILE *file;
 318      gcov_type value;
 319 {
 320   char buffer[8];
 321   unsigned ix;
 322
 323   for (ix = sizeof (buffer); ix--; )
 324     {
 325       buffer[ix] = value;
 326       value >>= 8;
 327     }
 328   return ((sizeof (value) > sizeof (buffer) && value != 0 && value != -1)
 329           || fwrite (buffer, sizeof (buffer), 1, file) != 1);
 330 }
 331
 332 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 333    file i/o error, or value error.  */
 334
 335 static int
 336 gcov_write_string (file, string, length)
 337      FILE *file;
 338      unsigned length;
 339      const char *string;
 340 {
 341   unsigned pad = 0;
 342
 343   if (string)
 344     return (gcov_write_unsigned (file, length)
 345             || fwrite (string, length, 1, file) != 1
 346             || fwrite (&pad, 4 - (length & 3), 1, file) != 1);
 347   else
 348     return gcov_write_unsigned (file, 0);
 349 }
 350
 351 /* Read *VALUE_P from coverage file FILE.  Return nonzero if failed
 352    due to file i/o error, or range error.  */
 353
 354 static int
 355 gcov_read_unsigned (file, value_p)
 356      FILE *file;
 357      unsigned *value_p;
 358 {
 359   unsigned value = 0;
 360   unsigned ix;
 361   unsigned char buffer[4];
 362
 363   if (fread (buffer, sizeof (buffer), 1, file) != 1)
 364     return 1;
 365   for (ix = sizeof (value); ix < sizeof (buffer); ix++)
 366     if (buffer[ix])
 367       return 1;
 368   for (ix = 0; ix != sizeof (buffer); ix++)
 369     {
 370       value <<= 8;
 371       value |= buffer[ix];
 372     }
 373   *value_p = value;
 374   return 0;
 375 }
 376
 377 /* Read *VALUE_P from coverage file FILE.  Return nonzero if failed
 378    due to file i/o error, or range error.  */
 379
 380 static int
 381 gcov_read_counter (file, value_p)
 382      FILE *file;
 383      gcov_type *value_p;
 384 {
 385   gcov_type value = 0;
 386   unsigned ix;
 387   unsigned char buffer[8];
 388
 389   if (fread (buffer, sizeof (buffer), 1, file) != 1)
 390     return 1;
 391   for (ix = sizeof (value); ix < sizeof (buffer); ix++)
 392     if (buffer[ix])
 393       return 1;
 394   for (ix = 0; ix != sizeof (buffer); ix++)
 395     {
 396       value <<= 8;
 397       value |= buffer[ix];
 398     }
 399
 400   *value_p = value;
 401   return value < 0;
 402 }
 403
 404 #if !IN_LIBGCC2
 405
 406 /* Read string from coverage file FILE.  Length is stored in *LENGTH_P
 407    (if non-null), a buffer is allocated and returned in *STRING_P.
 408    Return nonzero if failed due to file i/o error, or range
 409    error.  Uses xmalloc to allocate the string buffer.  */
 410
 411 static int
 412 gcov_read_string (file, string_p, length_p)
 413      FILE *file;
 414      char **string_p;
 415      unsigned *length_p;
 416 {
 417   unsigned length;
 418
 419   if (gcov_read_unsigned (file, &length))
 420     return 1;
 421
 422   if (length_p)
 423     *length_p = length;
 424   free (*string_p);
 425
 426   *string_p = NULL;
 427   if (!length)
 428     return 0;
 429
 430   length += 4 - (length & 3);
 431   *string_p = (char *) xmalloc (length);
 432
 433   return fread (*string_p, length, 1, file) != 1;
 434
 435 }
 436
 437 #endif /* !IN_LIBGCC2 */
 438
 439 /* Write a record length at PLACE.  The current file position is the
 440    end of the record, and is restored before returning.  Returns
 441    nonzero on failure.  */
 442
 443 static int
 444 gcov_write_length (file, place)
 445      FILE *file;
 446      long place;
 447 {
 448   long here = ftell (file);
 449   int result = (!place || fseek (file, place, SEEK_SET)
 450                 || gcov_write_unsigned (file, here - place - 4));
 451   if (fseek (file, here, SEEK_SET))
 452     result = 1;
 453   return result;
 454 }
 455
 456 #define GCOV_SUMMARY_LENGTH 44
 457 static int
 458 gcov_read_summary (da_file, summary)
 459      FILE *da_file;
 460      struct gcov_summary *summary;
 461 {
 462   return (gcov_read_unsigned (da_file, &summary->checksum)
 463           || gcov_read_unsigned (da_file, &summary->runs)
 464           || gcov_read_unsigned (da_file, &summary->arcs)
 465           || gcov_read_counter (da_file, &summary->arc_sum)
 466           || gcov_read_counter (da_file, &summary->arc_max_one)
 467           || gcov_read_counter (da_file, &summary->arc_max_sum)
 468           || gcov_read_counter (da_file, &summary->arc_sum_max));
 469 }
 470
 471 #if IN_LIBGCC2
 472 static int
 473 gcov_write_summary (da_file, tag, summary)
 474      FILE *da_file;
 475      unsigned tag;
 476      const struct gcov_summary *summary;
 477 {
 478   long base;
 479
 480   return (gcov_write_unsigned (da_file, tag)
 481           || !(base = gcov_reserve_length (da_file))
 482           || gcov_write_unsigned (da_file, summary->checksum)
 483           || gcov_write_unsigned (da_file, summary->runs)
 484           || gcov_write_unsigned (da_file, summary->arcs)
 485           || gcov_write_counter (da_file, summary->arc_sum)
 486           || gcov_write_counter (da_file, summary->arc_max_one)
 487           || gcov_write_counter (da_file, summary->arc_max_sum)
 488           || gcov_write_counter (da_file, summary->arc_sum_max)
 489           || gcov_write_length (da_file, base));
 490 }
 491 #endif
 492
 493 #endif /* GCC_GCOV_IO_H */