1GCOV-TOOL(1)                          GNU                         GCOV-TOOL(1)
2
3
4

NAME

6       gcov-tool - offline gcda profile processing tool
7

SYNOPSIS

9       gcov-tool [-v|--version] [-h|--help]
10
11       gcov-tool merge [merge-options] directory1 directory2
12            [-o|--output directory]
13            [-v|--verbose]
14            [-w|--weight w1,w2]
15
16       gcov-tool merge-stream [merge-stream-options] [file]
17            [-v|--verbose]
18            [-w|--weight w1,w2]
19
20       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
26       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

DESCRIPTION

35       gcov-tool is an offline tool to process gcc's gcda profile files.
36
37       Current gcov-tool supports the following functionalities:
38
39       *   merge two sets of profiles with weights.
40
41       *   read a stream of profiles with associated filenames and merge it
42           with a set of profiles with weights.
43
44       *   read one set of profile and rewrite profile contents. One can scale
45           or normalize the count values.
46
47       Examples of the use cases for this tool are:
48
49       *   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
53       *   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
58       *   Rewrite the profile after removing a subset of the gcda files,
59           while maintaining the consistency of the summary and the histogram.
60
61       *   It can also be used to debug or libgcov code as the tools shares
62           the majority code as the runtime library.
63
64       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
68       *   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
74       *   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
81       *   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

OPTIONS

86       -h
87       --help
88           Display help about using gcov-tool (on the standard output), and
89           exit without doing any further processing.
90
91       -v
92       --version
93           Display the gcov-tool version number (on the standard output), and
94           exit without doing any further processing.
95
96       merge
97           Merge two profile directories.
98
99           -o directory
100           --output directory
101               Set the output profile directory. Default output directory name
102               is merged_profile.
103
104           -v
105           --verbose
106               Set the verbose mode.
107
108           -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
113       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
120           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
124           -v
125           --verbose
126               Set the verbose mode.
127
128           -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
134       rewrite
135           Read the specified profile directory and rewrite to a new
136           directory.
137
138           -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
143           -o directory
144           --output directory
145               Set the output profile directory. Default output name is
146               rewrite_profile.
147
148           -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
154           -v
155           --verbose
156               Set the verbose mode.
157
158       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
167           -f
168           --function
169               Print function level overlap score.
170
171           -F
172           --fullname
173               Print full gcda filename.
174
175           -h
176           --hotonly
177               Only print info for hot objects/functions.
178
179           -o
180           --object
181               Print object level overlap score.
182
183           -t float
184           --hot_threshold <float>
185               Set the threshold for hot counter value.
186
187           -v
188           --verbose
189               Set the verbose mode.
190

SEE ALSO

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
198       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
206       (a) The FSF's Front-Cover Text is:
207
208            A GNU Manual
209
210       (b) The FSF's Back-Cover Text is:
211
212            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.
215
216
217
218gcc-13                            2023-12-05                      GCOV-TOOL(1)
Impressum