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 /* Since this file is used in both host and target files, and we don't
 254    include ansidecl.h in target files, provide some necessary macros.  */
 255 #ifndef PARAMS
 256 # define PARAMS(X) X
 257 #endif
 258 #ifndef ATTRIBUTE_UNUSED
 259 # define ATTRIBUTE_UNUSED __attribute__ ((__unused__))
 260 #endif
 261
 262 #endif /* IN_LIBGCC2 */
 263
 264 /* Functions for reading and writing gcov files.  */
 265 static int gcov_write_unsigned PARAMS((FILE *, unsigned))
 266      ATTRIBUTE_UNUSED;
 267 static int gcov_write_counter PARAMS((FILE *, gcov_type))
 268      ATTRIBUTE_UNUSED;
 269 static int gcov_write_string PARAMS((FILE *, const char *, unsigned))
 270      ATTRIBUTE_UNUSED;
 271 static int gcov_read_unsigned PARAMS((FILE *, unsigned *))
 272      ATTRIBUTE_UNUSED;
 273 static int gcov_read_counter PARAMS((FILE *, gcov_type *))
 274      ATTRIBUTE_UNUSED;
 275 #if !IN_LIBGCC2
 276 static int gcov_read_string PARAMS((FILE *, char **, unsigned *))
 277      ATTRIBUTE_UNUSED;
 278 #endif
 279 static int gcov_read_summary PARAMS ((FILE *, struct gcov_summary *))
 280      ATTRIBUTE_UNUSED;
 281 #if IN_LIBGCC2
 282 static int gcov_write_summary PARAMS ((FILE *, unsigned,
 283                                        const struct gcov_summary *))
 284      ATTRIBUTE_UNUSED;
 285 #endif
 286 #define gcov_save_position(STREAM) \
 287         ftell (STREAM)
 288 #define gcov_reserve_length(STREAM) \
 289         (gcov_write_unsigned (STREAM, 0) ? 0 : ftell (STREAM) - 4)
 290 static int gcov_write_length PARAMS((FILE *, long))
 291      ATTRIBUTE_UNUSED;
 292 #define gcov_resync(STREAM, BASE, LENGTH) \
 293         fseek (STREAM, BASE + (long)LENGTH, SEEK_SET)
 294 #define gcov_skip(STREAM, LENGTH) \
 295         fseek (STREAM, LENGTH, SEEK_CUR)
 296 #define gcov_skip_string(STREAM, LENGTH) \
 297         fseek (STREAM, (LENGTH) + 4 - ((LENGTH) & 3), SEEK_CUR)
 298
 299
 300 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 301    file i/o error, or value error.  */
 302
 303 static int
 304 gcov_write_unsigned (file, value)
 305      FILE *file;
 306      unsigned value;
 307 {
 308   char buffer[4];
 309   unsigned ix;
 310
 311   for (ix = sizeof (buffer); ix--; )
 312     {
 313       buffer[ix] = value;
 314       value >>= 8;
 315     }
 316   return ((sizeof (value) > sizeof (buffer) && value)
 317           || fwrite (buffer, sizeof (buffer), 1, file) != 1);
 318 }
 319
 320 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 321    file i/o error, or value error.  Negative values are not checked
 322    here -- they are checked in gcov_read_counter.  */
 323
 324 static int
 325 gcov_write_counter (file, value)
 326      FILE *file;
 327      gcov_type value;
 328 {
 329   char buffer[8];
 330   unsigned ix;
 331
 332   for (ix = sizeof (buffer); ix--; )
 333     {
 334       buffer[ix] = value;
 335       value >>= 8;
 336     }
 337   return ((sizeof (value) > sizeof (buffer) && value != 0 && value != -1)
 338           || fwrite (buffer, sizeof (buffer), 1, file) != 1);
 339 }
 340
 341 /* Write VALUE to coverage file FILE.  Return nonzero if failed due to
 342    file i/o error, or value error.  */
 343
 344 static int
 345 gcov_write_string (file, string, length)
 346      FILE *file;
 347      unsigned length;
 348      const char *string;
 349 {
 350   unsigned pad = 0;
 351
 352   if (string)
 353     return (gcov_write_unsigned (file, length)
 354             || fwrite (string, length, 1, file) != 1
 355             || fwrite (&pad, 4 - (length & 3), 1, file) != 1);
 356   else
 357     return gcov_write_unsigned (file, 0);
 358 }
 359
 360 /* Read *VALUE_P from coverage file FILE.  Return nonzero if failed
 361    due to file i/o error, or range error.  */
 362
 363 static int
 364 gcov_read_unsigned (file, value_p)
 365      FILE *file;
 366      unsigned *value_p;
 367 {
 368   unsigned value = 0;
 369   unsigned ix;
 370   unsigned char buffer[4];
 371
 372   if (fread (buffer, sizeof (buffer), 1, file) != 1)
 373     return 1;
 374   for (ix = sizeof (value); ix < sizeof (buffer); ix++)
 375     if (buffer[ix])
 376       return 1;
 377   for (ix = 0; ix != sizeof (buffer); ix++)
 378     {
 379       value <<= 8;
 380       value |= buffer[ix];
 381     }
 382   *value_p = value;
 383   return 0;
 384 }
 385
 386 /* Read *VALUE_P from coverage file FILE.  Return nonzero if failed
 387    due to file i/o error, or range error.  */
 388
 389 static int
 390 gcov_read_counter (file, value_p)
 391      FILE *file;
 392      gcov_type *value_p;
 393 {
 394   gcov_type value = 0;
 395   unsigned ix;
 396   unsigned char buffer[8];
 397
 398   if (fread (buffer, sizeof (buffer), 1, file) != 1)
 399     return 1;
 400   for (ix = sizeof (value); ix < sizeof (buffer); ix++)
 401     if (buffer[ix])
 402       return 1;
 403   for (ix = 0; ix != sizeof (buffer); ix++)
 404     {
 405       value <<= 8;
 406       value |= buffer[ix];
 407     }
 408
 409   *value_p = value;
 410   return value < 0;
 411 }
 412
 413 #if !IN_LIBGCC2
 414
 415 /* Read string from coverage file FILE.  Length is stored in *LENGTH_P
 416    (if non-null), a buffer is allocated and returned in *STRING_P.
 417    Return nonzero if failed due to file i/o error, or range
 418    error.  Uses xmalloc to allocate the string buffer.  */
 419
 420 static int
 421 gcov_read_string (file, string_p, length_p)
 422      FILE *file;
 423      char **string_p;
 424      unsigned *length_p;
 425 {
 426   unsigned length;
 427
 428   if (gcov_read_unsigned (file, &length))
 429     return 1;
 430
 431   if (length_p)
 432     *length_p = length;
 433   free (*string_p);
 434
 435   *string_p = NULL;
 436   if (!length)
 437     return 0;
 438
 439   length += 4 - (length & 3);
 440   *string_p = (char *) xmalloc (length);
 441
 442   return fread (*string_p, length, 1, file) != 1;
 443
 444 }
 445
 446 #endif /* !IN_LIBGCC2 */
 447
 448 /* Write a record length at PLACE.  The current file position is the
 449    end of the record, and is restored before returning.  Returns
 450    nonzero on failure.  */
 451
 452 static int
 453 gcov_write_length (file, place)
 454      FILE *file;
 455      long place;
 456 {
 457   long here = ftell (file);
 458   int result = (!place || fseek (file, place, SEEK_SET)
 459                 || gcov_write_unsigned (file, here - place - 4));
 460   if (fseek (file, here, SEEK_SET))
 461     result = 1;
 462   return result;
 463 }
 464
 465 #define GCOV_SUMMARY_LENGTH 44
 466 static int
 467 gcov_read_summary (da_file, summary)
 468      FILE *da_file;
 469      struct gcov_summary *summary;
 470 {
 471   return (gcov_read_unsigned (da_file, &summary->checksum)
 472           || gcov_read_unsigned (da_file, &summary->runs)
 473           || gcov_read_unsigned (da_file, &summary->arcs)
 474           || gcov_read_counter (da_file, &summary->arc_sum)
 475           || gcov_read_counter (da_file, &summary->arc_max_one)
 476           || gcov_read_counter (da_file, &summary->arc_max_sum)
 477           || gcov_read_counter (da_file, &summary->arc_sum_max));
 478 }
 479
 480 #if IN_LIBGCC2
 481 static int
 482 gcov_write_summary (da_file, tag, summary)
 483      FILE *da_file;
 484      unsigned tag;
 485      const struct gcov_summary *summary;
 486 {
 487   long base;
 488
 489   return (gcov_write_unsigned (da_file, tag)
 490           || !(base = gcov_reserve_length (da_file))
 491           || gcov_write_unsigned (da_file, summary->checksum)
 492           || gcov_write_unsigned (da_file, summary->runs)
 493           || gcov_write_unsigned (da_file, summary->arcs)
 494           || gcov_write_counter (da_file, summary->arc_sum)
 495           || gcov_write_counter (da_file, summary->arc_max_one)
 496           || gcov_write_counter (da_file, summary->arc_max_sum)
 497           || gcov_write_counter (da_file, summary->arc_sum_max)
 498           || gcov_write_length (da_file, base));
 499 }
 500 #endif
 501
 502 #endif /* GCC_GCOV_IO_H */