1@c Copyright (C) 2014-2021 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 7Copyright @copyright{} 2014-2021 Free Software Foundation, Inc. 8 9Permission is granted to copy, distribute and/or modify this document 10under the terms of the GNU Free Documentation License, Version 1.3 or 11any later version published by the Free Software Foundation; with the 12Invariant Sections being ``GNU General Public License'' and ``Funding 13Free Software'', the Front-Cover texts being (a) (see below), and with 14the Back-Cover Texts being (b) (see below). A copy of the license is 15included 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 36manipulate 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 49Current gcov-tool supports the following functionalities: 50 51@itemize @bullet 52@item 53merge two sets of profiles with weights. 54 55@item 56read one set of profile and rewrite profile contents. One can scale or 57normalize the count values. 58@end itemize 59 60Examples of the use cases for this tool are: 61@itemize @bullet 62@item 63Collect the profiles for different set of inputs, and use this tool to merge 64them. One can specify the weight to factor in the relative importance of 65each input. 66 67@item 68Rewrite the profile after removing a subset of the gcda files, while maintaining 69the consistency of the summary and the histogram. 70 71@item 72It can also be used to debug or libgcov code as the tools shares the majority 73code as the runtime library. 74@end itemize 75 76Note that for the merging operation, this profile generated offline may 77contain slight different values from the online merged profile. Here are 78a list of typical differences: 79 80@itemize @bullet 81@item 82histogram difference: This offline tool recomputes the histogram after merging 83the counters. The resulting histogram, therefore, is precise. The online 84merging does not have this capability -- the histogram is merged from two 85histograms and the result is an approximation. 86 87@item 88summary checksum difference: Summary checksum uses a CRC32 operation. The value 89depends on the link list order of gcov-info objects. This order is different in 90gcov-tool from that in the online merge. It's expected to have different 91summary checksums. It does not really matter as the compiler does not use this 92checksum anywhere. 93 94@item 95value profile counter values difference: Some counter values for value profile 96are runtime dependent, like heap addresses. It's normal to see some difference 97in 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 106gcov-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 113gcov-tool [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] 114 115gcov-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 120gcov-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 126gcov-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 136gpl(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 145Display help about using @command{gcov-tool} (on the standard output), and 146exit without doing any further processing. 147 148@item -v 149@itemx --version 150Display the @command{gcov-tool} version number (on the standard output), 151and exit without doing any further processing. 152 153@item merge 154Merge two profile directories. 155@table @gcctabopt 156 157@item -o @var{directory} 158@itemx --output @var{directory} 159Set the output profile directory. Default output directory name is 160@var{merged_profile}. 161 162@item -v 163@itemx --verbose 164Set the verbose mode. 165 166@item -w @var{w1},@var{w2} 167@itemx --weight @var{w1},@var{w2} 168Set the merge weights of the @var{directory1} and @var{directory2}, 169respectively. The default weights are 1 for both. 170@end table 171 172@item rewrite 173Read 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> 178Normalize the profile. The specified value is the max counter value 179in the new profile. 180 181@item -o @var{directory} 182@itemx --output @var{directory} 183Set 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} 187Scale the profile counters. The specified value can be in floating point value, 188or simple fraction value form, such 1, 2, 2/3, and 5/3. 189 190@item -v 191@itemx --verbose 192Set the verbose mode. 193@end table 194 195@item overlap 196Compute the overlap score between the two specified profile directories. 197The overlap score is computed based on the arc profiles. It is defined as 198the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all), 199for all arc counter i, where p1_counter[i] and p2_counter[i] are two 200matched counters and p1_sum_all and p2_sum_all are the sum of counter 201values in profile 1 and profile 2, respectively. 202 203@table @gcctabopt 204@item -f 205@itemx --function 206Print function level overlap score. 207 208@item -F 209@itemx --fullname 210Print full gcda filename. 211 212@item -h 213@itemx --hotonly 214Only print info for hot objects/functions. 215 216@item -o 217@itemx --object 218Print object level overlap score. 219 220@item -t @var{float} 221@itemx --hot_threshold <float> 222Set the threshold for hot counter value. 223 224@item -v 225@itemx --verbose 226Set the verbose mode. 227@end table 228 229@end table 230 231@c man end 232