1GCOV-TOOL(1) GNU GCOV-TOOL(1)
2
6 gcov-tool - offline gcda profile processing tool
7
9 gcov-tool [-v|--version] [-h|--help]
10 gcov-tool merge [merge-options] directory1 directory2
12 [-o|--output directory]
13 [-v|--verbose]
14 [-w|--weight w1,w2]
15 gcov-tool merge-stream [merge-stream-options] [file]
17 [-v|--verbose]
18 [-w|--weight w1,w2]
19 gcov-tool rewrite [rewrite-options] directory
21 [-n|--normalize long_long_value]
22 [-o|--output directory]
23 [-s|--scale float_or_simple-frac_value]
24 [-v|--verbose]
25 gcov-tool overlap [overlap-options] directory1 directory2
27 [-f|--function]
28 [-F|--fullname]
29 [-h|--hotonly]
30 [-o|--object]
31 [-t|--hot_threshold] float
32 [-v|--verbose]
33
35 gcov-tool is an offline tool to process gcc's gcda profile files.
36 Current gcov-tool supports the following functionalities:
38 * merge two sets of profiles with weights.
40 * read a stream of profiles with associated filenames and merge it
42 with a set of profiles with weights.
43 * read one set of profile and rewrite profile contents. One can scale
45 or normalize the count values.
46 Examples of the use cases for this tool are:
48 * Collect the profiles for different set of inputs, and use this tool
50 to merge them. One can specify the weight to factor in the relative
51 importance of each input.
52 * Collect profiles from target systems without a filesystem
54 (freestanding environments). Merge the collected profiles with
55 associated profiles present on the host system. One can specify
56 the weight to factor in the relative importance of each input.
57 * Rewrite the profile after removing a subset of the gcda files,
59 while maintaining the consistency of the summary and the histogram.
60 * It can also be used to debug or libgcov code as the tools shares
62 the majority code as the runtime library.
63 Note that for the merging operation, this profile generated offline may
65 contain slight different values from the online merged profile. Here
66 are a list of typical differences:
67 * histogram difference: This offline tool recomputes the histogram
69 after merging the counters. The resulting histogram, therefore, is
70 precise. The online merging does not have this capability -- the
71 histogram is merged from two histograms and the result is an
72 approximation.
73 * summary checksum difference: Summary checksum uses a CRC32
75 operation. The value depends on the link list order of gcov-info
76 objects. This order is different in gcov-tool from that in the
77 online merge. It's expected to have different summary checksums. It
78 does not really matter as the compiler does not use this checksum
79 anywhere.
80 * value profile counter values difference: Some counter values for
82 value profile are runtime dependent, like heap addresses. It's
83 normal to see some difference in these kind of counters.
84
86 -h
87 --help
88 Display help about using gcov-tool (on the standard output), and
89 exit without doing any further processing.
90 -v
92 --version
93 Display the gcov-tool version number (on the standard output), and
94 exit without doing any further processing.
95 merge
97 Merge two profile directories.
98 -o directory
100 --output directory
101 Set the output profile directory. Default output directory name
102 is merged_profile.
103 -v
105 --verbose
106 Set the verbose mode.
107 -w w1,w2
109 --weight w1,w2
110 Set the merge weights of the directory1 and directory2,
111 respectively. The default weights are 1 for both.
112 merge-stream
114 Collect profiles with associated filenames from a gcfn and gcda
115 data stream. Read the stream from the file specified by file or
116 from stdin. Merge the profiles with associated profiles in the
117 host filesystem. Apply the optional weights while merging
118 profiles.
119 For the generation of a gcfn and gcda data stream on the target
121 system, please have a look at the "__gcov_filename_to_gcfn()" and
122 "__gcov_info_to_gcda()" functions declared in "#include <gcov.h>".
123 -v
125 --verbose
126 Set the verbose mode.
127 -w w1,w2
129 --weight w1,w2
130 Set the merge weights of the profiles from the gcfn and gcda
131 data stream and the associated profiles in the host filesystem,
132 respectively. The default weights are 1 for both.
133 rewrite
135 Read the specified profile directory and rewrite to a new
136 directory.
137 -n long_long_value
139 --normalize <long_long_value>
140 Normalize the profile. The specified value is the max counter
141 value in the new profile.
142 -o directory
144 --output directory
145 Set the output profile directory. Default output name is
146 rewrite_profile.
147 -s float_or_simple-frac_value
149 --scale float_or_simple-frac_value
150 Scale the profile counters. The specified value can be in
151 floating point value, or simple fraction value form, such 1, 2,
152 2/3, and 5/3.
153 -v
155 --verbose
156 Set the verbose mode.
157 overlap
159 Compute the overlap score between the two specified profile
160 directories. The overlap score is computed based on the arc
161 profiles. It is defined as the sum of min (p1_counter[i] /
162 p1_sum_all, p2_counter[i] / p2_sum_all), for all arc counter i,
163 where p1_counter[i] and p2_counter[i] are two matched counters and
164 p1_sum_all and p2_sum_all are the sum of counter values in profile
165 1 and profile 2, respectively.
166 -f
168 --function
169 Print function level overlap score.
170 -F
172 --fullname
173 Print full gcda filename.
174 -h
176 --hotonly
177 Only print info for hot objects/functions.
178 -o
180 --object
181 Print object level overlap score.
182 -t float
184 --hot_threshold <float>
185 Set the threshold for hot counter value.
186 -v
188 --verbose
189 Set the verbose mode.
190
192 gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for
193 gcc.
194
196 Copyright (c) 2014-2023 Free Software Foundation, Inc.
197 Permission is granted to copy, distribute and/or modify this document
199 under the terms of the GNU Free Documentation License, Version 1.3 or
200 any later version published by the Free Software Foundation; with the
201 Invariant Sections being "GNU General Public License" and "Funding Free
202 Software", the Front-Cover texts being (a) (see below), and with the
203 Back-Cover Texts being (b) (see below). A copy of the license is
204 included in the gfdl(7) man page.
205 (a) The FSF's Front-Cover Text is:
207 A GNU Manual
209 (b) The FSF's Back-Cover Text is:
211 You have freedom to copy and modify this GNU Manual, like GNU
213 software. Copies published by the Free Software Foundation raise
214 funds for GNU development.
215gcc-13 2023-12-05 GCOV-TOOL(1)