gcc/gcov-io.h

   1 /* File format for coverage information
   2    Copyright (C) 1996-2024 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 3, 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 Under Section 7 of GPL version 3, you are granted additional
  19 permissions described in the GCC Runtime Library Exception, version
  20 3.1, as published by the Free Software Foundation.
  21
  22 You should have received a copy of the GNU General Public License and
  23 a copy of the GCC Runtime Library Exception along with this program;
  24 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  25 <http://www.gnu.org/licenses/>.  */
  26
  27
  28 /* CAVEAT: Coverage information files should not be parsed directly,
  29    instead use `gcov --json-format`, which provides
  30    machine-readable coverage information.
  31
  32    Note that the following file format documentation might be outdated.
  33
  34    Coverage information is held in two files.  A notes file, which is
  35    generated by the compiler, and a data file, which is generated by
  36    the program under test.  Both files use a similar structure.  We do
  37    not attempt to make these files backwards compatible with previous
  38    versions, as you only need coverage information when developing a
  39    program.  We do hold version information, so that mismatches can be
  40    detected, and we use a format that allows tools to skip information
  41    they do not understand or are not interested in.
  42
  43    Numbers are recorded in the 32 bit unsigned binary form of the
  44    endianness of the machine generating the file. 64 bit numbers are
  45    stored as two 32 bit numbers, the low part first.
  46    The number of bytes is stored, followed by the
  47    string. Zero length and NULL strings are simply stored as a length
  48    of zero (they have no trailing NUL).
  49
  50         int32:  byte3 byte2 byte1 byte0 | byte0 byte1 byte2 byte3
  51         int64:  int32:low int32:high
  52         string: int32:0 | int32:length char* char:0
  53         item: int32 | int64 | string
  54
  55    The basic format of the notes file is
  56
  57         file : int32:magic int32:version int32:stamp int32:support_unexecuted_blocks record*
  58
  59    The basic format of the data file is
  60
  61         file : int32:magic int32:version int32:stamp record*
  62
  63    A filename header may be used to provide a filename for the data in
  64    a stream of data to support gcov in freestanding environments.  This
  65    header is used by the merge-stream subcommand of the gcov-tool.  The
  66    format of the filename header is
  67
  68         filename-header : int32:magic int32:version string
  69
  70    The magic ident is different for the notes and the data files as
  71    well as the filename header.  The magic ident is used to determine
  72    the endianness of the file, when reading.  The version is the same
  73    for both files and is derived from gcc's version number. The stamp
  74    value is used to synchronize note and data files and to synchronize
  75    merging within a data file. It need not be an absolute time stamp,
  76    merely a ticker that increments fast enough and cycles slow enough
  77    to distinguish different compile/run/compile cycles.
  78
  79    Although the ident and version are formally 32 bit numbers, they
  80    are derived from 4 character ASCII strings.  The version number
  81    consists of a two character major version number
  82    (first digit starts from 'A' letter to not to clash with the older
  83    numbering scheme), the single character minor version number,
  84    and a single character indicating the status of the release.
  85    That will be 'e' experimental, 'p' prerelease and 'r' for release.
  86    Because, by good fortune, these are in alphabetical order, string
  87    collating can be used to compare version strings.  Be aware that
  88    the 'e' designation will (naturally) be unstable and might be
  89    incompatible with itself.  For gcc 17.0 experimental, it would be
  90    'B70e' (0x42373065).  As we currently do not release more than 5 minor
  91    releases, the single character should be always fine.  Major number
  92    is currently changed roughly every year, which gives us space
  93    for next 250 years (maximum allowed number would be 259.9).
  94
  95    A record has a tag, length and variable amount of data.
  96
  97         record: header data
  98         header: int32:tag int32:length
  99         data: item*
 100
 101    Records are not nested, but there is a record hierarchy.  Tag
 102    numbers reflect this hierarchy.  Tags are unique across note and
 103    data files.  Some record types have a varying amount of data.  The
 104    LENGTH is the number of bytes that follow and is usually used to
 105    determine how much data.  The tag value is split into 4 8-bit
 106    fields, one for each of four possible levels.  The most significant
 107    is allocated first.  Unused levels are zero.  Active levels are
 108    odd-valued, so that the LSB of the level is one.  A sub-level
 109    incorporates the values of its superlevels.  This formatting allows
 110    you to determine the tag hierarchy, without understanding the tags
 111    themselves, and is similar to the standard section numbering used
 112    in technical documents.  Level values [1..3f] are used for common
 113    tags, values [41..9f] for the notes file and [a1..ff] for the data
 114    file.
 115
 116    The notes file contains the following records
 117         note: unit function-graph*
 118         unit: header int32:checksum string:source
 119         function-graph: announce_function basic_blocks {arcs | lines}*
 120         announce_function: header int32:ident
 121                 int32:lineno_checksum int32:cfg_checksum
 122                 string:name string:source int32:start_lineno int32:start_column int32:end_lineno
 123         basic_block: header int32:flags*
 124         arcs: header int32:block_no arc*
 125         arc:  int32:dest_block int32:flags
 126         lines: header int32:block_no line*
 127                int32:0 string:NULL
 128         line:  int32:line_no | int32:0 string:filename
 129
 130    The BASIC_BLOCK record holds per-bb flags.  The number of blocks
 131    can be inferred from its data length.  There is one ARCS record per
 132    basic block.  The number of arcs from a bb is implicit from the
 133    data length.  It enumerates the destination bb and per-arc flags.
 134    There is one LINES record per basic block, it enumerates the source
 135    lines which belong to that basic block.  Source file names are
 136    introduced by a line number of 0, following lines are from the new
 137    source file.  The initial source file for the function is NULL, but
 138    the current source file should be remembered from one LINES record
 139    to the next.  The end of a block is indicated by an empty filename
 140    - this does not reset the current source file.  Note there is no
 141    ordering of the ARCS and LINES records: they may be in any order,
 142    interleaved in any manner.  The current filename follows the order
 143    the LINES records are stored in the file, *not* the ordering of the
 144    blocks they are for.
 145
 146    The data file contains the following records.
 147         data: {unit summary:object function-data*}*
 148         unit: header int32:checksum
 149         function-data:  announce_function present counts
 150         announce_function: header int32:ident
 151                 int32:lineno_checksum int32:cfg_checksum
 152         present: header int32:present
 153         counts: header int64:count*
 154         summary: int32:checksum int32:runs int32:sum_max
 155
 156    The ANNOUNCE_FUNCTION record is the same as that in the note file,
 157    but without the source location.  The COUNTS gives the
 158    counter values for instrumented features.  The about the whole
 159    program.  The checksum is used for whole program summaries, and
 160    disambiguates different programs which include the same
 161    instrumented object file.  There may be several program summaries,
 162    each with a unique checksum.  The object summary's checksum is
 163    zero.  Note that the data file might contain information from
 164    several runs concatenated, or the data might be merged.
 165
 166    This file is included by both the compiler, gcov tools and the
 167    runtime support library libgcov. IN_LIBGCOV and IN_GCOV are used to
 168    distinguish which case is which.  If IN_LIBGCOV is nonzero,
 169    libgcov is being built. If IN_GCOV is nonzero, the gcov tools are
 170    being built. Otherwise the compiler is being built. IN_GCOV may be
 171    positive or negative. If positive, we are compiling a tool that
 172    requires additional functions (see the code for knowledge of what
 173    those functions are).  */
 174
 175 #ifndef GCC_GCOV_IO_H
 176 #define GCC_GCOV_IO_H
 177
 178 /* GCOV key-value pair linked list type.  */
 179
 180 struct gcov_kvp;
 181
 182 struct gcov_kvp
 183 {
 184   gcov_type value;
 185   gcov_type count;
 186   struct gcov_kvp *next;
 187 };
 188
 189 #ifndef IN_LIBGCOV
 190 /* About the host */
 191
 192 typedef unsigned gcov_unsigned_t;
 193 typedef unsigned gcov_position_t;
 194 /* gcov_type is typedef'd elsewhere for the compiler */
 195 #if IN_GCOV
 196 #define GCOV_LINKAGE static
 197 typedef int64_t gcov_type;
 198 typedef uint64_t gcov_type_unsigned;
 199 #if IN_GCOV > 0
 200 #include <sys/types.h>
 201 #endif
 202 #endif
 203
 204 #if defined (HOST_HAS_F_SETLKW)
 205 #define GCOV_LOCKED 1
 206 #else
 207 #define GCOV_LOCKED 0
 208 #endif
 209
 210 #if defined (HOST_HAS_LK_LOCK)
 211 #define GCOV_LOCKED_WITH_LOCKING 1
 212 #else
 213 #define GCOV_LOCKED_WITH_LOCKING 0
 214 #endif
 215
 216 #define ATTRIBUTE_HIDDEN
 217
 218 #endif /* !IN_LIBGCOV */
 219
 220 #ifndef GCOV_LINKAGE
 221 #define GCOV_LINKAGE extern
 222 #endif
 223
 224 #if IN_LIBGCOV
 225 #define gcov_nonruntime_assert(EXPR) ((void)(0 && (EXPR)))
 226 #else
 227 #define gcov_nonruntime_assert(EXPR) gcc_assert (EXPR)
 228 #define gcov_error(...) fatal_error (input_location, __VA_ARGS__)
 229 #endif
 230
 231 /* File suffixes.  */
 232 #define GCOV_DATA_SUFFIX ".gcda"
 233 #define GCOV_NOTE_SUFFIX ".gcno"
 234
 235 /* File magic. Must not be palindromes.  */
 236 #define GCOV_DATA_MAGIC ((gcov_unsigned_t)0x67636461) /* "gcda" */
 237 #define GCOV_NOTE_MAGIC ((gcov_unsigned_t)0x67636e6f) /* "gcno" */
 238 #define GCOV_FILENAME_MAGIC ((gcov_unsigned_t)0x6763666e) /* "gcfn" */
 239
 240 #include "version.h"
 241
 242 /* Convert a magic or version number to a 4 character string.  */
 243 #define GCOV_UNSIGNED2STRING(ARRAY,VALUE)       \
 244   ((ARRAY)[0] = (char)((VALUE) >> 24),          \
 245    (ARRAY)[1] = (char)((VALUE) >> 16),          \
 246    (ARRAY)[2] = (char)((VALUE) >> 8),           \
 247    (ARRAY)[3] = (char)((VALUE) >> 0))
 248
 249 /* The record tags.  Values [1..3f] are for tags which may be in either
 250    file.  Values [41..9f] for those in the note file and [a1..ff] for
 251    the data file.  The tag value zero is used as an explicit end of
 252    file marker -- it is not required to be present.
 253    All length values are in bytes.  */
 254
 255 #define GCOV_WORD_SIZE          4
 256
 257 #define GCOV_TAG_FUNCTION        ((gcov_unsigned_t)0x01000000)
 258 #define GCOV_TAG_FUNCTION_LENGTH (3 * GCOV_WORD_SIZE)
 259 #define GCOV_TAG_BLOCKS          ((gcov_unsigned_t)0x01410000)
 260 #define GCOV_TAG_BLOCKS_LENGTH(NUM) (NUM)
 261 #define GCOV_TAG_ARCS            ((gcov_unsigned_t)0x01430000)
 262 #define GCOV_TAG_ARCS_LENGTH(NUM)  (1 + (NUM) * 2 * GCOV_WORD_SIZE)
 263 #define GCOV_TAG_ARCS_NUM(LENGTH)  (((LENGTH / GCOV_WORD_SIZE) - 1) / 2)
 264 #define GCOV_TAG_CONDS             ((gcov_unsigned_t)0x01470000)
 265 #define GCOV_TAG_CONDS_LENGTH(NUM) ((NUM) * 2 * GCOV_WORD_SIZE)
 266 #define GCOV_TAG_CONDS_NUM(LENGTH) (((LENGTH) / GCOV_WORD_SIZE) / 2)
 267 #define GCOV_TAG_LINES           ((gcov_unsigned_t)0x01450000)
 268 #define GCOV_TAG_COUNTER_BASE    ((gcov_unsigned_t)0x01a10000)
 269 #define GCOV_TAG_COUNTER_LENGTH(NUM) ((NUM) * 2 * GCOV_WORD_SIZE)
 270 #define GCOV_TAG_COUNTER_NUM(LENGTH) ((LENGTH / GCOV_WORD_SIZE) / 2)
 271 #define GCOV_TAG_OBJECT_SUMMARY  ((gcov_unsigned_t)0xa1000000)
 272 #define GCOV_TAG_OBJECT_SUMMARY_LENGTH (2 * GCOV_WORD_SIZE)
 273 #define GCOV_TAG_PROGRAM_SUMMARY ((gcov_unsigned_t)0xa3000000) /* Obsolete */
 274 #define GCOV_TAG_AFDO_FILE_NAMES ((gcov_unsigned_t)0xaa000000)
 275 #define GCOV_TAG_AFDO_FUNCTION ((gcov_unsigned_t)0xac000000)
 276 #define GCOV_TAG_AFDO_WORKING_SET ((gcov_unsigned_t)0xaf000000)
 277
 278
 279 /* Counters that are collected.  */
 280
 281 #define DEF_GCOV_COUNTER(COUNTER, NAME, MERGE_FN) COUNTER,
 282 enum {
 283 #include "gcov-counter.def"
 284 GCOV_COUNTERS
 285 };
 286 #undef DEF_GCOV_COUNTER
 287
 288 /* The first of counters used for value profiling.  They must form a
 289    consecutive interval and their order must match the order of
 290    HIST_TYPEs in value-prof.h.  */
 291 #define GCOV_FIRST_VALUE_COUNTER GCOV_COUNTER_V_INTERVAL
 292
 293 /* The last of counters used for value profiling.  */
 294 #define GCOV_LAST_VALUE_COUNTER (GCOV_COUNTERS - 1)
 295
 296 /* Number of counters used for value profiling.  */
 297 #define GCOV_N_VALUE_COUNTERS \
 298   (GCOV_LAST_VALUE_COUNTER - GCOV_FIRST_VALUE_COUNTER + 1)
 299
 300 /* Number of top N counters when being in memory.  */
 301 #define GCOV_TOPN_MEM_COUNTERS 3
 302
 303 /* Number of top N counters in disk representation.  */
 304 #define GCOV_TOPN_DISK_COUNTERS 2
 305
 306 /* Maximum number of tracked TOP N value profiles.  */
 307 #define GCOV_TOPN_MAXIMUM_TRACKED_VALUES 32
 308
 309 /* Convert a counter index to a tag.  */
 310 #define GCOV_TAG_FOR_COUNTER(COUNT)                             \
 311         (GCOV_TAG_COUNTER_BASE + ((gcov_unsigned_t)(COUNT) << 17))
 312 /* Convert a tag to a counter.  */
 313 #define GCOV_COUNTER_FOR_TAG(TAG)                                       \
 314         ((unsigned)(((TAG) - GCOV_TAG_COUNTER_BASE) >> 17))
 315 /* Check whether a tag is a counter tag.  */
 316 #define GCOV_TAG_IS_COUNTER(TAG)                                \
 317         (!((TAG) & 0xFFFF) && GCOV_COUNTER_FOR_TAG (TAG) < GCOV_COUNTERS)
 318
 319 /* The tag level mask has 1's in the position of the inner levels, &
 320    the lsb of the current level, and zero on the current and outer
 321    levels.  */
 322 #define GCOV_TAG_MASK(TAG) (((TAG) - 1) ^ (TAG))
 323
 324 /* Return nonzero if SUB is an immediate subtag of TAG.  */
 325 #define GCOV_TAG_IS_SUBTAG(TAG,SUB)                             \
 326         (GCOV_TAG_MASK (TAG) >> 8 == GCOV_TAG_MASK (SUB)        \
 327          && !(((SUB) ^ (TAG)) & ~GCOV_TAG_MASK (TAG)))
 328
 329 /* Return nonzero if SUB is at a sublevel to TAG.  */
 330 #define GCOV_TAG_IS_SUBLEVEL(TAG,SUB)                           \
 331         (GCOV_TAG_MASK (TAG) > GCOV_TAG_MASK (SUB))
 332
 333 /* Basic block flags.  */
 334 #define GCOV_BLOCK_UNEXPECTED   (1 << 1)
 335
 336 /* Arc flags.  */
 337 #define GCOV_ARC_ON_TREE        (1 << 0)
 338 #define GCOV_ARC_FAKE           (1 << 1)
 339 #define GCOV_ARC_FALLTHROUGH    (1 << 2)
 340
 341 /* Object & program summary record.  */
 342
 343 struct gcov_summary
 344 {
 345   gcov_unsigned_t runs;         /* Number of program runs.  */
 346   gcov_type sum_max;            /* Sum of individual run max values.  */
 347 };
 348
 349 #if !defined(inhibit_libc)
 350
 351 /* Functions for reading and writing gcov files. In libgcov you can
 352    open the file for reading then writing. Elsewhere you can open the
 353    file either for reading or for writing. When reading a file you may
 354    use the gcov_read_* functions, gcov_sync, gcov_position, and
 355    gcov_error. When writing a file you may use the gcov_write*
 356    functions and gcov_error. When a file is to be rewritten
 357    you use the functions for reading, then gcov_rewrite then the
 358    functions for writing.  Your file may become corrupted if you break
 359    these invariants.  */
 360
 361 #if !IN_LIBGCOV || defined (IN_GCOV_TOOL)
 362 GCOV_LINKAGE int gcov_magic (gcov_unsigned_t, gcov_unsigned_t);
 363 #endif
 364
 365 /* Available everywhere.  */
 366 GCOV_LINKAGE int gcov_open (const char *, int) ATTRIBUTE_HIDDEN;
 367 GCOV_LINKAGE int gcov_close (void) ATTRIBUTE_HIDDEN;
 368 GCOV_LINKAGE gcov_unsigned_t gcov_read_unsigned (void) ATTRIBUTE_HIDDEN;
 369 GCOV_LINKAGE gcov_type gcov_read_counter (void) ATTRIBUTE_HIDDEN;
 370 GCOV_LINKAGE void gcov_read_summary (struct gcov_summary *) ATTRIBUTE_HIDDEN;
 371 GCOV_LINKAGE const char *gcov_read_string (void);
 372 GCOV_LINKAGE void gcov_sync (gcov_position_t /*base*/,
 373                              gcov_unsigned_t /*length */);
 374 char *mangle_path (char const *base);
 375
 376 #if !IN_GCOV
 377 /* Available outside gcov */
 378 GCOV_LINKAGE void gcov_write (const void *, unsigned) ATTRIBUTE_HIDDEN;
 379 GCOV_LINKAGE void gcov_write_unsigned (gcov_unsigned_t) ATTRIBUTE_HIDDEN;
 380 #endif
 381
 382 #if !IN_GCOV && !IN_LIBGCOV
 383 /* Available only in compiler */
 384 GCOV_LINKAGE void gcov_write_string (const char *);
 385 GCOV_LINKAGE void gcov_write_filename (const char *);
 386 GCOV_LINKAGE gcov_position_t gcov_write_tag (gcov_unsigned_t);
 387 GCOV_LINKAGE void gcov_write_length (gcov_position_t /*position*/);
 388 #endif
 389
 390 #if IN_GCOV > 0
 391 /* Available in gcov */
 392 GCOV_LINKAGE time_t gcov_time (void);
 393 #endif
 394
 395 #endif /* !inhibit_libc  */
 396
 397 #endif /* GCC_GCOV_IO_H */