1 | /* File format for coverage information |
2 | Copyright (C) 1996-2017 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 files is |
52 | |
53 | file : int32:magic int32:version int32:stamp record* |
54 | |
55 | The magic ident is different for the notes and the data files. The |
56 | magic ident is used to determine the endianness of the file, when |
57 | reading. The version is the same for both files and is derived |
58 | from gcc's version number. The stamp value is used to synchronize |
59 | note and data files and to synchronize merging within a data |
60 | file. It need not be an absolute time stamp, merely a ticker that |
61 | increments fast enough and cycles slow enough to distinguish |
62 | different compile/run/compile cycles. |
63 | |
64 | Although the ident and version are formally 32 bit numbers, they |
65 | are derived from 4 character ASCII strings. The version number |
66 | consists of a two character major version number |
67 | (first digit starts from 'A' letter to not to clash with the older |
68 | numbering scheme), the single character minor version number, |
69 | and a single character indicating the status of the release. |
70 | That will be 'e' experimental, 'p' prerelease and 'r' for release. |
71 | Because, by good fortune, these are in alphabetical order, string |
72 | collating can be used to compare version strings. Be aware that |
73 | the 'e' designation will (naturally) be unstable and might be |
74 | incompatible with itself. For gcc 17.0 experimental, it would be |
75 | 'B70e' (0x42373065). As we currently do not release more than 5 minor |
76 | releases, the single character should be always fine. Major number |
77 | is currently changed roughly every year, which gives us space |
78 | for next 250 years (maximum allowed number would be 259.9). |
79 | |
80 | A record has a tag, length and variable amount of data. |
81 | |
82 | record: header data |
83 | header: int32:tag int32:length |
84 | data: item* |
85 | |
86 | Records are not nested, but there is a record hierarchy. Tag |
87 | numbers reflect this hierarchy. Tags are unique across note and |
88 | data files. Some record types have a varying amount of data. The |
89 | LENGTH is the number of 4bytes that follow and is usually used to |
90 | determine how much data. The tag value is split into 4 8-bit |
91 | fields, one for each of four possible levels. The most significant |
92 | is allocated first. Unused levels are zero. Active levels are |
93 | odd-valued, so that the LSB of the level is one. A sub-level |
94 | incorporates the values of its superlevels. This formatting allows |
95 | you to determine the tag hierarchy, without understanding the tags |
96 | themselves, and is similar to the standard section numbering used |
97 | in technical documents. Level values [1..3f] are used for common |
98 | tags, values [41..9f] for the notes file and [a1..ff] for the data |
99 | file. |
100 | |
101 | The notes file contains the following records |
102 | note: unit function-graph* |
103 | unit: header int32:checksum string:source |
104 | function-graph: announce_function basic_blocks {arcs | lines}* |
105 | announce_function: header int32:ident |
106 | int32:lineno_checksum int32:cfg_checksum |
107 | string:name string:source int32:lineno |
108 | basic_block: header int32:flags* |
109 | arcs: header int32:block_no arc* |
110 | arc: int32:dest_block int32:flags |
111 | lines: header int32:block_no line* |
112 | int32:0 string:NULL |
113 | line: int32:line_no | int32:0 string:filename |
114 | |
115 | The BASIC_BLOCK record holds per-bb flags. The number of blocks |
116 | can be inferred from its data length. There is one ARCS record per |
117 | basic block. The number of arcs from a bb is implicit from the |
118 | data length. It enumerates the destination bb and per-arc flags. |
119 | There is one LINES record per basic block, it enumerates the source |
120 | lines which belong to that basic block. Source file names are |
121 | introduced by a line number of 0, following lines are from the new |
122 | source file. The initial source file for the function is NULL, but |
123 | the current source file should be remembered from one LINES record |
124 | to the next. The end of a block is indicated by an empty filename |
125 | - this does not reset the current source file. Note there is no |
126 | ordering of the ARCS and LINES records: they may be in any order, |
127 | interleaved in any manner. The current filename follows the order |
128 | the LINES records are stored in the file, *not* the ordering of the |
129 | blocks they are for. |
130 | |
131 | The data file contains the following records. |
132 | data: {unit summary:object summary:program* function-data*}* |
133 | unit: header int32:checksum |
134 | function-data: announce_function present counts |
135 | announce_function: header int32:ident |
136 | int32:lineno_checksum int32:cfg_checksum |
137 | present: header int32:present |
138 | counts: header int64:count* |
139 | summary: int32:checksum {count-summary}GCOV_COUNTERS_SUMMABLE |
140 | count-summary: int32:num int32:runs int64:sum |
141 | int64:max int64:sum_max histogram |
142 | histogram: {int32:bitvector}8 histogram-buckets* |
143 | histogram-buckets: int32:num int64:min int64:sum |
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_LIBGOCV */ |
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) /* Obsolete */ |
241 | #define GCOV_TAG_PROGRAM_SUMMARY ((gcov_unsigned_t)0xa3000000) |
242 | #define GCOV_TAG_SUMMARY_LENGTH(NUM) \ |
243 | (1 + GCOV_COUNTERS_SUMMABLE * (10 + 3 * 2) + (NUM) * 5) |
244 | #define GCOV_TAG_AFDO_FILE_NAMES ((gcov_unsigned_t)0xaa000000) |
245 | #define GCOV_TAG_AFDO_FUNCTION ((gcov_unsigned_t)0xac000000) |
246 | #define GCOV_TAG_AFDO_WORKING_SET ((gcov_unsigned_t)0xaf000000) |
247 | |
248 | |
249 | /* Counters that are collected. */ |
250 | |
251 | #define DEF_GCOV_COUNTER(COUNTER, NAME, MERGE_FN) COUNTER, |
252 | enum { |
253 | #include "gcov-counter.def" |
254 | GCOV_COUNTERS |
255 | }; |
256 | #undef DEF_GCOV_COUNTER |
257 | |
258 | /* Counters which can be summaried. */ |
259 | #define GCOV_COUNTERS_SUMMABLE (GCOV_COUNTER_ARCS + 1) |
260 | |
261 | /* The first of counters used for value profiling. They must form a |
262 | consecutive interval and their order must match the order of |
263 | HIST_TYPEs in value-prof.h. */ |
264 | #define GCOV_FIRST_VALUE_COUNTER GCOV_COUNTERS_SUMMABLE |
265 | |
266 | /* The last of counters used for value profiling. */ |
267 | #define GCOV_LAST_VALUE_COUNTER (GCOV_COUNTERS - 1) |
268 | |
269 | /* Number of counters used for value profiling. */ |
270 | #define GCOV_N_VALUE_COUNTERS \ |
271 | (GCOV_LAST_VALUE_COUNTER - GCOV_FIRST_VALUE_COUNTER + 1) |
272 | |
273 | /* The number of hottest callees to be tracked. */ |
274 | #define GCOV_ICALL_TOPN_VAL 2 |
275 | |
276 | /* The number of counter entries per icall callsite. */ |
277 | #define GCOV_ICALL_TOPN_NCOUNTS (1 + GCOV_ICALL_TOPN_VAL * 4) |
278 | |
279 | /* Convert a counter index to a tag. */ |
280 | #define GCOV_TAG_FOR_COUNTER(COUNT) \ |
281 | (GCOV_TAG_COUNTER_BASE + ((gcov_unsigned_t)(COUNT) << 17)) |
282 | /* Convert a tag to a counter. */ |
283 | #define GCOV_COUNTER_FOR_TAG(TAG) \ |
284 | ((unsigned)(((TAG) - GCOV_TAG_COUNTER_BASE) >> 17)) |
285 | /* Check whether a tag is a counter tag. */ |
286 | #define GCOV_TAG_IS_COUNTER(TAG) \ |
287 | (!((TAG) & 0xFFFF) && GCOV_COUNTER_FOR_TAG (TAG) < GCOV_COUNTERS) |
288 | |
289 | /* The tag level mask has 1's in the position of the inner levels, & |
290 | the lsb of the current level, and zero on the current and outer |
291 | levels. */ |
292 | #define GCOV_TAG_MASK(TAG) (((TAG) - 1) ^ (TAG)) |
293 | |
294 | /* Return nonzero if SUB is an immediate subtag of TAG. */ |
295 | #define GCOV_TAG_IS_SUBTAG(TAG,SUB) \ |
296 | (GCOV_TAG_MASK (TAG) >> 8 == GCOV_TAG_MASK (SUB) \ |
297 | && !(((SUB) ^ (TAG)) & ~GCOV_TAG_MASK (TAG))) |
298 | |
299 | /* Return nonzero if SUB is at a sublevel to TAG. */ |
300 | #define GCOV_TAG_IS_SUBLEVEL(TAG,SUB) \ |
301 | (GCOV_TAG_MASK (TAG) > GCOV_TAG_MASK (SUB)) |
302 | |
303 | /* Basic block flags. */ |
304 | #define GCOV_BLOCK_UNEXPECTED (1 << 1) |
305 | |
306 | /* Arc flags. */ |
307 | #define GCOV_ARC_ON_TREE (1 << 0) |
308 | #define GCOV_ARC_FAKE (1 << 1) |
309 | #define GCOV_ARC_FALLTHROUGH (1 << 2) |
310 | |
311 | /* Structured records. */ |
312 | |
313 | /* Structure used for each bucket of the log2 histogram of counter values. */ |
314 | typedef struct |
315 | { |
316 | /* Number of counters whose profile count falls within the bucket. */ |
317 | gcov_unsigned_t num_counters; |
318 | /* Smallest profile count included in this bucket. */ |
319 | gcov_type min_value; |
320 | /* Cumulative value of the profile counts in this bucket. */ |
321 | gcov_type cum_value; |
322 | } gcov_bucket_type; |
323 | |
324 | /* For a log2 scale histogram with each range split into 4 |
325 | linear sub-ranges, there will be at most 64 (max gcov_type bit size) - 1 log2 |
326 | ranges since the lowest 2 log2 values share the lowest 4 linear |
327 | sub-range (values 0 - 3). This is 252 total entries (63*4). */ |
328 | |
329 | #define GCOV_HISTOGRAM_SIZE 252 |
330 | |
331 | /* How many unsigned ints are required to hold a bit vector of non-zero |
332 | histogram entries when the histogram is written to the gcov file. |
333 | This is essentially a ceiling divide by 32 bits. */ |
334 | #define GCOV_HISTOGRAM_BITVECTOR_SIZE (GCOV_HISTOGRAM_SIZE + 31) / 32 |
335 | |
336 | /* Cumulative counter data. */ |
337 | struct gcov_ctr_summary |
338 | { |
339 | gcov_unsigned_t num; /* number of counters. */ |
340 | gcov_unsigned_t runs; /* number of program runs */ |
341 | gcov_type sum_all; /* sum of all counters accumulated. */ |
342 | gcov_type run_max; /* maximum value on a single run. */ |
343 | gcov_type sum_max; /* sum of individual run max values. */ |
344 | gcov_bucket_type histogram[GCOV_HISTOGRAM_SIZE]; /* histogram of |
345 | counter values. */ |
346 | }; |
347 | |
348 | /* Object & program summary record. */ |
349 | struct gcov_summary |
350 | { |
351 | gcov_unsigned_t checksum; /* checksum of program */ |
352 | struct gcov_ctr_summary ctrs[GCOV_COUNTERS_SUMMABLE]; |
353 | }; |
354 | |
355 | #if !defined(inhibit_libc) |
356 | |
357 | /* Functions for reading and writing gcov files. In libgcov you can |
358 | open the file for reading then writing. Elsewhere you can open the |
359 | file either for reading or for writing. When reading a file you may |
360 | use the gcov_read_* functions, gcov_sync, gcov_position, & |
361 | gcov_error. When writing a file you may use the gcov_write |
362 | functions, gcov_seek & gcov_error. When a file is to be rewritten |
363 | you use the functions for reading, then gcov_rewrite then the |
364 | functions for writing. Your file may become corrupted if you break |
365 | these invariants. */ |
366 | |
367 | #if !IN_LIBGCOV |
368 | GCOV_LINKAGE int gcov_open (const char */*name*/, int /*direction*/); |
369 | GCOV_LINKAGE int gcov_magic (gcov_unsigned_t, gcov_unsigned_t); |
370 | #endif |
371 | |
372 | /* Available everywhere. */ |
373 | GCOV_LINKAGE int gcov_close (void) ATTRIBUTE_HIDDEN; |
374 | GCOV_LINKAGE gcov_unsigned_t gcov_read_unsigned (void) ATTRIBUTE_HIDDEN; |
375 | GCOV_LINKAGE gcov_type gcov_read_counter (void) ATTRIBUTE_HIDDEN; |
376 | GCOV_LINKAGE void gcov_read_summary (struct gcov_summary *) ATTRIBUTE_HIDDEN; |
377 | GCOV_LINKAGE const char *gcov_read_string (void); |
378 | GCOV_LINKAGE void gcov_sync (gcov_position_t /*base*/, |
379 | gcov_unsigned_t /*length */); |
380 | |
381 | #if !IN_GCOV |
382 | /* Available outside gcov */ |
383 | GCOV_LINKAGE void gcov_write_unsigned (gcov_unsigned_t) ATTRIBUTE_HIDDEN; |
384 | #endif |
385 | |
386 | #if !IN_GCOV && !IN_LIBGCOV |
387 | /* Available only in compiler */ |
388 | GCOV_LINKAGE unsigned gcov_histo_index (gcov_type value); |
389 | GCOV_LINKAGE void gcov_write_string (const char *); |
390 | GCOV_LINKAGE void gcov_write_filename (const char *); |
391 | GCOV_LINKAGE gcov_position_t gcov_write_tag (gcov_unsigned_t); |
392 | GCOV_LINKAGE void gcov_write_length (gcov_position_t /*position*/); |
393 | #endif |
394 | |
395 | #if IN_GCOV <= 0 && !IN_LIBGCOV |
396 | /* Available in gcov-dump and the compiler. */ |
397 | |
398 | /* Number of data points in the working set summary array. Using 128 |
399 | provides information for at least every 1% increment of the total |
400 | profile size. The last entry is hardwired to 99.9% of the total. */ |
401 | #define NUM_GCOV_WORKING_SETS 128 |
402 | |
403 | /* Working set size statistics for a given percentage of the entire |
404 | profile (sum_all from the counter summary). */ |
405 | typedef struct gcov_working_set_info |
406 | { |
407 | /* Number of hot counters included in this working set. */ |
408 | unsigned num_counters; |
409 | /* Smallest counter included in this working set. */ |
410 | gcov_type min_counter; |
411 | } gcov_working_set_t; |
412 | |
413 | GCOV_LINKAGE void compute_working_sets (const struct gcov_ctr_summary *summary, |
414 | gcov_working_set_t *gcov_working_sets); |
415 | #endif |
416 | |
417 | #if IN_GCOV > 0 |
418 | /* Available in gcov */ |
419 | GCOV_LINKAGE time_t gcov_time (void); |
420 | #endif |
421 | |
422 | #endif /* !inhibit_libc */ |
423 | |
424 | #endif /* GCC_GCOV_IO_H */ |
425 | |