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