| 1 |
@c Copyright (C) 2014-2022 Free Software Foundation, Inc. |
| 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 |
| 7 |
Copyright @copyright{} 2014-2022 Free Software Foundation, Inc. |
| 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 |
| 106 |
gcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND @r{[}@var{sub_command-options}@r{]} @var{profile_dir} |
| 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{-o}|@option{--output} @var{directory}] |
| 117 |
[@option{-v}|@option{--verbose}] |
| 118 |
[@option{-w}|@option{--weight} @var{w1,w2}] |
| 119 |
|
| 120 |
gcov-tool rewrite [rewrite-options] @var{directory} |
| 121 |
[@option{-n}|@option{--normalize} @var{long_long_value}] |
| 122 |
[@option{-o}|@option{--output} @var{directory}] |
| 123 |
[@option{-s}|@option{--scale} @var{float_or_simple-frac_value}] |
| 124 |
[@option{-v}|@option{--verbose}] |
| 125 |
|
| 126 |
gcov-tool overlap [overlap-options] @var{directory1} @var{directory2} |
| 127 |
[@option{-f}|@option{--function}] |
| 128 |
[@option{-F}|@option{--fullname}] |
| 129 |
[@option{-h}|@option{--hotonly}] |
| 130 |
[@option{-o}|@option{--object}] |
| 131 |
[@option{-t}|@option{--hot_threshold}] @var{float} |
| 132 |
[@option{-v}|@option{--verbose}] |
| 133 |
|
| 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 |
@table @gcctabopt |
| 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 |
|
| 162 |
@item -v |
| 163 |
@itemx --verbose |
| 164 |
Set the verbose mode. |
| 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 |
@table @gcctabopt |
| 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. |
| 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 |
|
| 190 |
@item -v |
| 191 |
@itemx --verbose |
| 192 |
Set the verbose mode. |
| 193 |
@end table |
| 194 |
|
| 195 |
@item overlap |
| 196 |
Compute 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 -f |
| 205 |
@itemx --function |
| 206 |
Print function level overlap score. |
| 207 |
|
| 208 |
@item -F |
| 209 |
@itemx --fullname |
| 210 |
Print full gcda filename. |
| 211 |
|
| 212 |
@item -h |
| 213 |
@itemx --hotonly |
| 214 |
Only print info for hot objects/functions. |
| 215 |
|
| 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. |
| 223 |
|
| 224 |
@item -v |
| 225 |
@itemx --verbose |
| 226 |
Set the verbose mode. |
| 227 |
@end table |
| 228 |
|
| 229 |
@end table |
| 230 |
|
| 231 |
@c man end |