]>
Commit | Line | Data |
---|---|---|
f1717362 | 1 | @c Copyright (C) 2014-2016 Free Software Foundation, Inc. |
e76f6040 | 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 | |
f1717362 | 7 | Copyright @copyright{} 2014-2016 Free Software Foundation, Inc. |
e76f6040 | 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 | |
26054e0b | 106 | gcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND @r{[}@var{sub_command-options}@r{]} @var{profile_dir} |
e76f6040 | 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} | |
116 | [@option{-v}|@option{--verbose}] | |
117 | [@option{-o}|@option{ --output} @var{directory}] | |
118 | [@option{-w}|@option{--weight} @var{w1,w2}] | |
119 | ||
120 | gcov-tool rewrite [rewrite-options] @var{directory} | |
121 | [@option{-v}|@option{--verbose}] | |
122 | [@option{-o}|@option{--output} @var{directory}] | |
123 | [@option{-s}|@option{--scale} @var{float_or_simple-frac_value}] | |
124 | [@option{-n}|@option{--normalize} @var{long_long_value}] | |
26054e0b | 125 | |
126 | gcov-tool overlap [overlap-options] @var{directory1} @var{directory2} | |
127 | [@option{-v}|@option{--verbose}] | |
128 | [@option{-h}|@option{--hotonly}] | |
129 | [@option{-f}|@option{--function}] | |
130 | [@option{-F}|@option{--fullname}] | |
131 | [@option{-o}|@option{--object}] | |
132 | [@option{-t}|@option{--hot_threshold}] @var{float} | |
133 | ||
e76f6040 | 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. | |
155 | ||
156 | @table @gcctabopt | |
157 | @item -v | |
158 | @itemx --verbose | |
159 | Set the verbose mode. | |
160 | ||
161 | @item -o @var{directory} | |
162 | @itemx --output @var{directory} | |
163 | Set the output profile directory. Default output directory name is | |
164 | @var{merged_profile}. | |
165 | ||
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. | |
174 | ||
175 | @table @gcctabopt | |
176 | @item -v | |
177 | @itemx --verbose | |
178 | Set the verbose mode. | |
179 | ||
180 | @item -o @var{directory} | |
181 | @itemx --output @var{directory} | |
182 | Set the output profile directory. Default output name is @var{rewrite_profile}. | |
183 | ||
184 | @item -s @var{float_or_simple-frac_value} | |
185 | @itemx --scale @var{float_or_simple-frac_value} | |
186 | Scale the profile counters. The specified value can be in floating point value, | |
187 | or simple fraction value form, such 1, 2, 2/3, and 5/3. | |
188 | ||
189 | @item -n @var{long_long_value} | |
190 | @itemx --normalize <long_long_value> | |
191 | Normalize the profile. The specified value is the max counter value | |
192 | in the new profile. | |
26054e0b | 193 | @end table |
194 | ||
195 | @item overlap | |
196 | Computer the overlap score between the two specified profile directories. | |
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 | |
204 | @item -v | |
205 | @itemx --verbose | |
206 | Set the verbose mode. | |
207 | ||
208 | @item -h | |
209 | @itemx --hotonly | |
210 | Only print info for hot objects/functions. | |
e76f6040 | 211 | |
26054e0b | 212 | @item -f |
213 | @itemx --function | |
214 | Print function level overlap score. | |
215 | ||
216 | @item -F | |
217 | @itemx --fullname | |
218 | Print full gcda filename. | |
219 | ||
220 | @item -o | |
221 | @itemx --object | |
222 | Print object level overlap score. | |
223 | ||
224 | @item -t @var{float} | |
225 | @itemx --hot_threshold <float> | |
226 | Set the threshold for hot counter value. | |
e76f6040 | 227 | @end table |
26054e0b | 228 | |
e76f6040 | 229 | @end table |
230 | ||
231 | @c man end |