]>
Commit | Line | Data |
---|---|---|
7adcbafe | 1 | @c Copyright (C) 2014-2022 Free Software Foundation, Inc. |
c77556a5 RX |
2 | @c This is part of the GCC manual. |
3 | @c For copying conditions, see the file gcc.texi. | |
4 | ||
5 | @ignore | |
6 | @c man begin COPYRIGHT | |
7adcbafe | 7 | Copyright @copyright{} 2014-2022 Free Software Foundation, Inc. |
c77556a5 RX |
8 | |
9 | Permission is granted to copy, distribute and/or modify this document | |
10 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
11 | any later version published by the Free Software Foundation; with the | |
12 | Invariant Sections being ``GNU General Public License'' and ``Funding | |
13 | Free Software'', the Front-Cover texts being (a) (see below), and with | |
14 | the Back-Cover Texts being (b) (see below). A copy of the license is | |
15 | included in the gfdl(7) man page. | |
16 | ||
17 | (a) The FSF's Front-Cover Text is: | |
18 | ||
19 | A GNU Manual | |
20 | ||
21 | (b) The FSF's Back-Cover Text is: | |
22 | ||
23 | You have freedom to copy and modify this GNU Manual, like GNU | |
24 | software. Copies published by the Free Software Foundation raise | |
25 | funds for GNU development. | |
26 | @c man end | |
27 | @c Set file name and title for the man page. | |
28 | @setfilename gcov-tool | |
29 | @settitle offline gcda profile processing tool | |
30 | @end ignore | |
31 | ||
32 | @node Gcov-tool | |
33 | @chapter @command{gcov-tool}---an Offline Gcda Profile Processing Tool | |
34 | ||
35 | @command{gcov-tool} is a tool you can use in conjunction with GCC to | |
36 | manipulate or process gcda profile files offline. | |
37 | ||
38 | @menu | |
39 | * Gcov-tool Intro:: Introduction to gcov-tool. | |
40 | * Invoking Gcov-tool:: How to use gcov-tool. | |
41 | @end menu | |
42 | ||
43 | @node Gcov-tool Intro | |
44 | @section Introduction to @command{gcov-tool} | |
45 | @c man begin DESCRIPTION | |
46 | ||
47 | @command{gcov-tool} is an offline tool to process gcc's gcda profile files. | |
48 | ||
49 | Current gcov-tool supports the following functionalities: | |
50 | ||
51 | @itemize @bullet | |
52 | @item | |
53 | merge two sets of profiles with weights. | |
54 | ||
55 | @item | |
56 | read one set of profile and rewrite profile contents. One can scale or | |
57 | normalize the count values. | |
58 | @end itemize | |
59 | ||
60 | Examples of the use cases for this tool are: | |
61 | @itemize @bullet | |
62 | @item | |
63 | Collect the profiles for different set of inputs, and use this tool to merge | |
64 | them. One can specify the weight to factor in the relative importance of | |
65 | each input. | |
66 | ||
67 | @item | |
68 | Rewrite the profile after removing a subset of the gcda files, while maintaining | |
69 | the consistency of the summary and the histogram. | |
70 | ||
71 | @item | |
72 | It can also be used to debug or libgcov code as the tools shares the majority | |
73 | code as the runtime library. | |
74 | @end itemize | |
75 | ||
76 | Note that for the merging operation, this profile generated offline may | |
77 | contain slight different values from the online merged profile. Here are | |
78 | a list of typical differences: | |
79 | ||
80 | @itemize @bullet | |
81 | @item | |
82 | histogram difference: This offline tool recomputes the histogram after merging | |
83 | the counters. The resulting histogram, therefore, is precise. The online | |
84 | merging does not have this capability -- the histogram is merged from two | |
85 | histograms and the result is an approximation. | |
86 | ||
87 | @item | |
88 | summary checksum difference: Summary checksum uses a CRC32 operation. The value | |
89 | depends on the link list order of gcov-info objects. This order is different in | |
90 | gcov-tool from that in the online merge. It's expected to have different | |
91 | summary checksums. It does not really matter as the compiler does not use this | |
92 | checksum anywhere. | |
93 | ||
94 | @item | |
95 | value profile counter values difference: Some counter values for value profile | |
96 | are runtime dependent, like heap addresses. It's normal to see some difference | |
97 | in these kind of counters. | |
98 | @end itemize | |
99 | ||
100 | @c man end | |
101 | ||
102 | @node Invoking Gcov-tool | |
103 | @section Invoking @command{gcov-tool} | |
104 | ||
105 | @smallexample | |
9b84e7a8 | 106 | gcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND @r{[}@var{sub_command-options}@r{]} @var{profile_dir} |
c77556a5 RX |
107 | @end smallexample |
108 | ||
109 | @command{gcov-tool} accepts the following options: | |
110 | ||
111 | @ignore | |
112 | @c man begin SYNOPSIS | |
113 | gcov-tool [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] | |
114 | ||
115 | gcov-tool merge [merge-options] @var{directory1} @var{directory2} | |
2f360676 | 116 | [@option{-o}|@option{--output} @var{directory}] |
c77556a5 | 117 | [@option{-v}|@option{--verbose}] |
c77556a5 RX |
118 | [@option{-w}|@option{--weight} @var{w1,w2}] |
119 | ||
120 | gcov-tool rewrite [rewrite-options] @var{directory} | |
2f360676 | 121 | [@option{-n}|@option{--normalize} @var{long_long_value}] |
c77556a5 RX |
122 | [@option{-o}|@option{--output} @var{directory}] |
123 | [@option{-s}|@option{--scale} @var{float_or_simple-frac_value}] | |
2f360676 | 124 | [@option{-v}|@option{--verbose}] |
9b84e7a8 RX |
125 | |
126 | gcov-tool overlap [overlap-options] @var{directory1} @var{directory2} | |
9b84e7a8 RX |
127 | [@option{-f}|@option{--function}] |
128 | [@option{-F}|@option{--fullname}] | |
2f360676 | 129 | [@option{-h}|@option{--hotonly}] |
9b84e7a8 RX |
130 | [@option{-o}|@option{--object}] |
131 | [@option{-t}|@option{--hot_threshold}] @var{float} | |
2f360676 | 132 | [@option{-v}|@option{--verbose}] |
9b84e7a8 | 133 | |
c77556a5 RX |
134 | @c man end |
135 | @c man begin SEEALSO | |
136 | gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for | |
137 | @file{gcc}. | |
138 | @c man end | |
139 | @end ignore | |
140 | ||
141 | @c man begin OPTIONS | |
142 | @table @gcctabopt | |
143 | @item -h | |
144 | @itemx --help | |
145 | Display help about using @command{gcov-tool} (on the standard output), and | |
146 | exit without doing any further processing. | |
147 | ||
148 | @item -v | |
149 | @itemx --version | |
150 | Display the @command{gcov-tool} version number (on the standard output), | |
151 | and exit without doing any further processing. | |
152 | ||
153 | @item merge | |
154 | Merge two profile directories. | |
c77556a5 | 155 | @table @gcctabopt |
c77556a5 RX |
156 | |
157 | @item -o @var{directory} | |
158 | @itemx --output @var{directory} | |
159 | Set the output profile directory. Default output directory name is | |
160 | @var{merged_profile}. | |
161 | ||
2f360676 ML |
162 | @item -v |
163 | @itemx --verbose | |
164 | Set the verbose mode. | |
165 | ||
c77556a5 RX |
166 | @item -w @var{w1},@var{w2} |
167 | @itemx --weight @var{w1},@var{w2} | |
168 | Set the merge weights of the @var{directory1} and @var{directory2}, | |
169 | respectively. The default weights are 1 for both. | |
170 | @end table | |
171 | ||
172 | @item rewrite | |
173 | Read the specified profile directory and rewrite to a new directory. | |
c77556a5 | 174 | @table @gcctabopt |
2f360676 ML |
175 | |
176 | @item -n @var{long_long_value} | |
177 | @itemx --normalize <long_long_value> | |
178 | Normalize the profile. The specified value is the max counter value | |
179 | in the new profile. | |
c77556a5 RX |
180 | |
181 | @item -o @var{directory} | |
182 | @itemx --output @var{directory} | |
183 | Set the output profile directory. Default output name is @var{rewrite_profile}. | |
184 | ||
185 | @item -s @var{float_or_simple-frac_value} | |
186 | @itemx --scale @var{float_or_simple-frac_value} | |
187 | Scale the profile counters. The specified value can be in floating point value, | |
188 | or simple fraction value form, such 1, 2, 2/3, and 5/3. | |
189 | ||
2f360676 ML |
190 | @item -v |
191 | @itemx --verbose | |
192 | Set the verbose mode. | |
9b84e7a8 RX |
193 | @end table |
194 | ||
195 | @item overlap | |
e0c8eebf | 196 | Compute the overlap score between the two specified profile directories. |
9b84e7a8 RX |
197 | The overlap score is computed based on the arc profiles. It is defined as |
198 | the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all), | |
199 | for all arc counter i, where p1_counter[i] and p2_counter[i] are two | |
200 | matched counters and p1_sum_all and p2_sum_all are the sum of counter | |
201 | values in profile 1 and profile 2, respectively. | |
202 | ||
203 | @table @gcctabopt | |
9b84e7a8 RX |
204 | @item -f |
205 | @itemx --function | |
206 | Print function level overlap score. | |
207 | ||
208 | @item -F | |
209 | @itemx --fullname | |
210 | Print full gcda filename. | |
211 | ||
2f360676 ML |
212 | @item -h |
213 | @itemx --hotonly | |
214 | Only print info for hot objects/functions. | |
215 | ||
9b84e7a8 RX |
216 | @item -o |
217 | @itemx --object | |
218 | Print object level overlap score. | |
219 | ||
220 | @item -t @var{float} | |
221 | @itemx --hot_threshold <float> | |
222 | Set the threshold for hot counter value. | |
2f360676 ML |
223 | |
224 | @item -v | |
225 | @itemx --verbose | |
226 | Set the verbose mode. | |
c77556a5 | 227 | @end table |
9b84e7a8 | 228 | |
c77556a5 RX |
229 | @end table |
230 | ||
231 | @c man end |