gcc/gcov-io.h

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