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 /* Structures embedded in coveraged program.  The structures generated
 220    by write_profile must match these.  */
 221
 222 /* Information about section of counters for a function.  */
 223 struct counter_section
 224 {
 225   unsigned tag;         /* Tag of the section.  */
 226   unsigned n_counters;  /* Number of counters in the section.  */
 227 };
 228
 229 #if IN_LIBGCC2
 230 /* Information about section of counters for an object file.  */
 231 struct counter_section_data
 232 {
 233   unsigned tag;         /* Tag of the section.  */
 234   unsigned n_counters;  /* Number of counters in the section.  */
 235   gcov_type *counters;  /* The data.  */
 236 };
 237
 238 /* Information about a single function.  */
 239 struct function_info
 240 {
 241   const char *name;             /* (mangled) name of function */
 242   unsigned checksum;            /* function checksum */
 243   unsigned n_counter_sections;  /* Number of types of counters */
 244   const struct counter_section *counter_sections;
 245                                 /* The section descriptions */
 246 };
 247
 248 /* Information about a single object file.  */
 249 struct gcov_info
 250 {
 251   unsigned long version;        /* expected version number */
 252   struct gcov_info *next;       /* link to next, used by libgcc */
 253
 254   const char *filename;         /* output file name */
 255   long wkspc;                   /* libgcc workspace */
 256
 257   unsigned n_functions;             /* number of functions */
 258   const struct function_info *functions; /* table of functions */
 259
 260   unsigned n_counter_sections;  /* Number of types of counters */
 261   const struct counter_section_data *counter_sections;
 262                                 /* The data to be put into the sections.  */
 263 };
 264
 265 /* Register a new object file module.  */
 266 extern void __gcov_init (struct gcov_info *);
 267
 268 /* Called before fork, to avoid double counting.  */
 269 extern void __gcov_flush (void);
 270
 271 /* Since this file is used in both host and target files, and we don't
 272    include ansidecl.h in target files, provide some necessary macros.  */
 273 #ifndef PARAMS
 274 # define PARAMS(X) X
 275 #endif
 276 #ifndef ATTRIBUTE_UNUSED
 277 # define ATTRIBUTE_UNUSED __attribute__ ((__unused__))
 278 #endif
 279
 280 #endif /* IN_LIBGCC2 */
 281
 282 /* Functions for reading and writing gcov files.  */
 283 static int gcov_write_unsigned PARAMS((FILE *, unsigned))
 284      ATTRIBUTE_UNUSED;
 285 static int gcov_write_counter PARAMS((FILE *, gcov_type))
 286      ATTRIBUTE_UNUSED;
 287 static int gcov_write_string PARAMS((FILE *, const char *, unsigned))
 288      ATTRIBUTE_UNUSED;
 289 static int gcov_read_unsigned PARAMS((FILE *, unsigned *))
 290      ATTRIBUTE_UNUSED;
 291 static int gcov_read_counter PARAMS((FILE *, gcov_type *))
 292      ATTRIBUTE_UNUSED;
 293 #if !IN_LIBGCC2
 294 static int gcov_read_string PARAMS((FILE *, char **, unsigned *))
 295      ATTRIBUTE_UNUSED;
 296 #endif
 297 static int gcov_read_summary PARAMS ((FILE *, struct gcov_summary *))
 298      ATTRIBUTE_UNUSED;
 299 #if IN_LIBGCC2
 300 static int gcov_write_summary PARAMS ((FILE *, unsigned,
 301                                        const struct gcov_summary *))
 302      ATTRIBUTE_UNUSED;
 303 #endif
 304 #define gcov_save_position(STREAM) \
 305         ftell (STREAM)
 306 #define gcov_reserve_length(STREAM) \
 307         (gcov_write_unsigned (STREAM, 0) ? 0 : ftell (STREAM) - 4)
 308 static int gcov_write_length PARAMS((FILE *, long))
 309      ATTRIBUTE_UNUSED;
 310 #define gcov_resync(STREAM, BASE, LENGTH) \
 311         fseek (STREAM, BASE + (long)LENGTH, SEEK_SET)
 312 #define gcov_skip(STREAM, LENGTH) \
 313         fseek (STREAM, LENGTH, SEEK_CUR)
 314 #define gcov_skip_string(STREAM, LENGTH) \
 315         fseek (STREAM, (LENGTH) + 4 - ((LENGTH) & 3), SEEK_CUR)
 316
 317
 318 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 319    file i/o error, or value error.  */
 320
 321 static int
 322 gcov_write_unsigned (file, value)
 323      FILE *file;
 324      unsigned value;
 325 {
 326   char buffer[4];
 327   unsigned ix;
 328
 329   for (ix = sizeof (buffer); ix--; )
 330     {
 331       buffer[ix] = value;
 332       value >>= 8;
 333     }
 334   return ((sizeof (value) > sizeof (buffer) && value)
 335           || fwrite (buffer, sizeof (buffer), 1, file) != 1);
 336 }
 337
 338 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 339    file i/o error, or value error.  Negative values are not checked
 340    here -- they are checked in gcov_read_counter.  */
 341
 342 static int
 343 gcov_write_counter (file, value)
 344      FILE *file;
 345      gcov_type value;
 346 {
 347   char buffer[8];
 348   unsigned ix;
 349
 350   for (ix = sizeof (buffer); ix--; )
 351     {
 352       buffer[ix] = value;
 353       value >>= 8;
 354     }
 355   return ((sizeof (value) > sizeof (buffer) && value != 0 && value != -1)
 356           || fwrite (buffer, sizeof (buffer), 1, file) != 1);
 357 }
 358
 359 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 360    file i/o error, or value error.  */
 361
 362 static int
 363 gcov_write_string (file, string, length)
 364      FILE *file;
 365      unsigned length;
 366      const char *string;
 367 {
 368   unsigned pad = 0;
 369
 370   if (string)
 371     return (gcov_write_unsigned (file, length)
 372             || fwrite (string, length, 1, file) != 1
 373             || fwrite (&pad, 4 - (length & 3), 1, file) != 1);
 374   else
 375     return gcov_write_unsigned (file, 0);
 376 }
 377
 378 /* Read *VALUE_P from coverage file FILE.  Return nonzero if failed
 379    due to file i/o error, or range error.  */
 380
 381 static int
 382 gcov_read_unsigned (file, value_p)
 383      FILE *file;
 384      unsigned *value_p;
 385 {
 386   unsigned value = 0;
 387   unsigned ix;
 388   unsigned char buffer[4];
 389
 390   if (fread (buffer, sizeof (buffer), 1, file) != 1)
 391     return 1;
 392   for (ix = sizeof (value); ix < sizeof (buffer); ix++)
 393     if (buffer[ix])
 394       return 1;
 395   for (ix = 0; ix != sizeof (buffer); ix++)
 396     {
 397       value <<= 8;
 398       value |= buffer[ix];
 399     }
 400   *value_p = value;
 401   return 0;
 402 }
 403
 404 /* Read *VALUE_P from coverage file FILE.  Return nonzero if failed
 405    due to file i/o error, or range error.  */
 406
 407 static int
 408 gcov_read_counter (file, value_p)
 409      FILE *file;
 410      gcov_type *value_p;
 411 {
 412   gcov_type value = 0;
 413   unsigned ix;
 414   unsigned char buffer[8];
 415
 416   if (fread (buffer, sizeof (buffer), 1, file) != 1)
 417     return 1;
 418   for (ix = sizeof (value); ix < sizeof (buffer); ix++)
 419     if (buffer[ix])
 420       return 1;
 421   for (ix = 0; ix != sizeof (buffer); ix++)
 422     {
 423       value <<= 8;
 424       value |= buffer[ix];
 425     }
 426
 427   *value_p = value;
 428   return value < 0;
 429 }
 430
 431 #if !IN_LIBGCC2
 432
 433 /* Read string from coverage file FILE.  Length is stored in *LENGTH_P
 434    (if non-null), a buffer is allocated and returned in *STRING_P.
 435    Return nonzero if failed due to file i/o error, or range
 436    error.  Uses xmalloc to allocate the string buffer.  */
 437
 438 static int
 439 gcov_read_string (file, string_p, length_p)
 440      FILE *file;
 441      char **string_p;
 442      unsigned *length_p;
 443 {
 444   unsigned length;
 445
 446   if (gcov_read_unsigned (file, &length))
 447     return 1;
 448
 449   if (length_p)
 450     *length_p = length;
 451   free (*string_p);
 452
 453   *string_p = NULL;
 454   if (!length)
 455     return 0;
 456
 457   length += 4 - (length & 3);
 458   *string_p = (char *) xmalloc (length);
 459
 460   return fread (*string_p, length, 1, file) != 1;
 461
 462 }
 463
 464 #endif /* !IN_LIBGCC2 */
 465
 466 /* Write a record length at PLACE.  The current file position is the
 467    end of the record, and is restored before returning.  Returns
 468    nonzero on failure.  */
 469
 470 static int
 471 gcov_write_length (file, place)
 472      FILE *file;
 473      long place;
 474 {
 475   long here = ftell (file);
 476   int result = (!place || fseek (file, place, SEEK_SET)
 477                 || gcov_write_unsigned (file, here - place - 4));
 478   if (fseek (file, here, SEEK_SET))
 479     result = 1;
 480   return result;
 481 }
 482
 483 #define GCOV_SUMMARY_LENGTH 44
 484 static int
 485 gcov_read_summary (da_file, summary)
 486      FILE *da_file;
 487      struct gcov_summary *summary;
 488 {
 489   return (gcov_read_unsigned (da_file, &summary->checksum)
 490           || gcov_read_unsigned (da_file, &summary->runs)
 491           || gcov_read_unsigned (da_file, &summary->arcs)
 492           || gcov_read_counter (da_file, &summary->arc_sum)
 493           || gcov_read_counter (da_file, &summary->arc_max_one)
 494           || gcov_read_counter (da_file, &summary->arc_max_sum)
 495           || gcov_read_counter (da_file, &summary->arc_sum_max));
 496 }
 497
 498 #if IN_LIBGCC2
 499 static int
 500 gcov_write_summary (da_file, tag, summary)
 501      FILE *da_file;
 502      unsigned tag;
 503      const struct gcov_summary *summary;
 504 {
 505   long base;
 506
 507   return (gcov_write_unsigned (da_file, tag)
 508           || !(base = gcov_reserve_length (da_file))
 509           || gcov_write_unsigned (da_file, summary->checksum)
 510           || gcov_write_unsigned (da_file, summary->runs)
 511           || gcov_write_unsigned (da_file, summary->arcs)
 512           || gcov_write_counter (da_file, summary->arc_sum)
 513           || gcov_write_counter (da_file, summary->arc_max_one)
 514           || gcov_write_counter (da_file, summary->arc_max_sum)
 515           || gcov_write_counter (da_file, summary->arc_sum_max)
 516           || gcov_write_length (da_file, base));
 517 }
 518 #endif
 519
 520 #endif /* GCC_GCOV_IO_H */