1*ec02198aSmrg@c Copyright (C) 2014-2020 Free Software Foundation, Inc. 210d565efSmrg@c This is part of the GCC manual. 310d565efSmrg@c For copying conditions, see the file gcc.texi. 410d565efSmrg 510d565efSmrg@ignore 610d565efSmrg@c man begin COPYRIGHT 7*ec02198aSmrgCopyright @copyright{} 2014-2020 Free Software Foundation, Inc. 810d565efSmrg 910d565efSmrgPermission is granted to copy, distribute and/or modify this document 1010d565efSmrgunder the terms of the GNU Free Documentation License, Version 1.3 or 1110d565efSmrgany later version published by the Free Software Foundation; with the 1210d565efSmrgInvariant Sections being ``GNU General Public License'' and ``Funding 1310d565efSmrgFree Software'', the Front-Cover texts being (a) (see below), and with 1410d565efSmrgthe Back-Cover Texts being (b) (see below). A copy of the license is 1510d565efSmrgincluded in the gfdl(7) man page. 1610d565efSmrg 1710d565efSmrg(a) The FSF's Front-Cover Text is: 1810d565efSmrg 1910d565efSmrg A GNU Manual 2010d565efSmrg 2110d565efSmrg(b) The FSF's Back-Cover Text is: 2210d565efSmrg 2310d565efSmrg You have freedom to copy and modify this GNU Manual, like GNU 2410d565efSmrg software. Copies published by the Free Software Foundation raise 2510d565efSmrg funds for GNU development. 2610d565efSmrg@c man end 2710d565efSmrg@c Set file name and title for the man page. 2810d565efSmrg@setfilename gcov-tool 2910d565efSmrg@settitle offline gcda profile processing tool 3010d565efSmrg@end ignore 3110d565efSmrg 3210d565efSmrg@node Gcov-tool 3310d565efSmrg@chapter @command{gcov-tool}---an Offline Gcda Profile Processing Tool 3410d565efSmrg 3510d565efSmrg@command{gcov-tool} is a tool you can use in conjunction with GCC to 3610d565efSmrgmanipulate or process gcda profile files offline. 3710d565efSmrg 3810d565efSmrg@menu 3910d565efSmrg* Gcov-tool Intro:: Introduction to gcov-tool. 4010d565efSmrg* Invoking Gcov-tool:: How to use gcov-tool. 4110d565efSmrg@end menu 4210d565efSmrg 4310d565efSmrg@node Gcov-tool Intro 4410d565efSmrg@section Introduction to @command{gcov-tool} 4510d565efSmrg@c man begin DESCRIPTION 4610d565efSmrg 4710d565efSmrg@command{gcov-tool} is an offline tool to process gcc's gcda profile files. 4810d565efSmrg 4910d565efSmrgCurrent gcov-tool supports the following functionalities: 5010d565efSmrg 5110d565efSmrg@itemize @bullet 5210d565efSmrg@item 5310d565efSmrgmerge two sets of profiles with weights. 5410d565efSmrg 5510d565efSmrg@item 5610d565efSmrgread one set of profile and rewrite profile contents. One can scale or 5710d565efSmrgnormalize the count values. 5810d565efSmrg@end itemize 5910d565efSmrg 6010d565efSmrgExamples of the use cases for this tool are: 6110d565efSmrg@itemize @bullet 6210d565efSmrg@item 6310d565efSmrgCollect the profiles for different set of inputs, and use this tool to merge 6410d565efSmrgthem. One can specify the weight to factor in the relative importance of 6510d565efSmrgeach input. 6610d565efSmrg 6710d565efSmrg@item 6810d565efSmrgRewrite the profile after removing a subset of the gcda files, while maintaining 6910d565efSmrgthe consistency of the summary and the histogram. 7010d565efSmrg 7110d565efSmrg@item 7210d565efSmrgIt can also be used to debug or libgcov code as the tools shares the majority 7310d565efSmrgcode as the runtime library. 7410d565efSmrg@end itemize 7510d565efSmrg 7610d565efSmrgNote that for the merging operation, this profile generated offline may 7710d565efSmrgcontain slight different values from the online merged profile. Here are 7810d565efSmrga list of typical differences: 7910d565efSmrg 8010d565efSmrg@itemize @bullet 8110d565efSmrg@item 8210d565efSmrghistogram difference: This offline tool recomputes the histogram after merging 8310d565efSmrgthe counters. The resulting histogram, therefore, is precise. The online 8410d565efSmrgmerging does not have this capability -- the histogram is merged from two 8510d565efSmrghistograms and the result is an approximation. 8610d565efSmrg 8710d565efSmrg@item 8810d565efSmrgsummary checksum difference: Summary checksum uses a CRC32 operation. The value 8910d565efSmrgdepends on the link list order of gcov-info objects. This order is different in 9010d565efSmrggcov-tool from that in the online merge. It's expected to have different 9110d565efSmrgsummary checksums. It does not really matter as the compiler does not use this 9210d565efSmrgchecksum anywhere. 9310d565efSmrg 9410d565efSmrg@item 9510d565efSmrgvalue profile counter values difference: Some counter values for value profile 9610d565efSmrgare runtime dependent, like heap addresses. It's normal to see some difference 9710d565efSmrgin these kind of counters. 9810d565efSmrg@end itemize 9910d565efSmrg 10010d565efSmrg@c man end 10110d565efSmrg 10210d565efSmrg@node Invoking Gcov-tool 10310d565efSmrg@section Invoking @command{gcov-tool} 10410d565efSmrg 10510d565efSmrg@smallexample 10610d565efSmrggcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND @r{[}@var{sub_command-options}@r{]} @var{profile_dir} 10710d565efSmrg@end smallexample 10810d565efSmrg 10910d565efSmrg@command{gcov-tool} accepts the following options: 11010d565efSmrg 11110d565efSmrg@ignore 11210d565efSmrg@c man begin SYNOPSIS 11310d565efSmrggcov-tool [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] 11410d565efSmrg 11510d565efSmrggcov-tool merge [merge-options] @var{directory1} @var{directory2} 11610d565efSmrg [@option{-o}|@option{--output} @var{directory}] 11710d565efSmrg [@option{-v}|@option{--verbose}] 11810d565efSmrg [@option{-w}|@option{--weight} @var{w1,w2}] 11910d565efSmrg 12010d565efSmrggcov-tool rewrite [rewrite-options] @var{directory} 12110d565efSmrg [@option{-n}|@option{--normalize} @var{long_long_value}] 12210d565efSmrg [@option{-o}|@option{--output} @var{directory}] 12310d565efSmrg [@option{-s}|@option{--scale} @var{float_or_simple-frac_value}] 12410d565efSmrg [@option{-v}|@option{--verbose}] 12510d565efSmrg 12610d565efSmrggcov-tool overlap [overlap-options] @var{directory1} @var{directory2} 12710d565efSmrg [@option{-f}|@option{--function}] 12810d565efSmrg [@option{-F}|@option{--fullname}] 12910d565efSmrg [@option{-h}|@option{--hotonly}] 13010d565efSmrg [@option{-o}|@option{--object}] 13110d565efSmrg [@option{-t}|@option{--hot_threshold}] @var{float} 13210d565efSmrg [@option{-v}|@option{--verbose}] 13310d565efSmrg 13410d565efSmrg@c man end 13510d565efSmrg@c man begin SEEALSO 13610d565efSmrggpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for 13710d565efSmrg@file{gcc}. 13810d565efSmrg@c man end 13910d565efSmrg@end ignore 14010d565efSmrg 14110d565efSmrg@c man begin OPTIONS 14210d565efSmrg@table @gcctabopt 14310d565efSmrg@item -h 14410d565efSmrg@itemx --help 14510d565efSmrgDisplay help about using @command{gcov-tool} (on the standard output), and 14610d565efSmrgexit without doing any further processing. 14710d565efSmrg 14810d565efSmrg@item -v 14910d565efSmrg@itemx --version 15010d565efSmrgDisplay the @command{gcov-tool} version number (on the standard output), 15110d565efSmrgand exit without doing any further processing. 15210d565efSmrg 15310d565efSmrg@item merge 15410d565efSmrgMerge two profile directories. 15510d565efSmrg@table @gcctabopt 15610d565efSmrg 15710d565efSmrg@item -o @var{directory} 15810d565efSmrg@itemx --output @var{directory} 15910d565efSmrgSet the output profile directory. Default output directory name is 16010d565efSmrg@var{merged_profile}. 16110d565efSmrg 16210d565efSmrg@item -v 16310d565efSmrg@itemx --verbose 16410d565efSmrgSet the verbose mode. 16510d565efSmrg 16610d565efSmrg@item -w @var{w1},@var{w2} 16710d565efSmrg@itemx --weight @var{w1},@var{w2} 16810d565efSmrgSet the merge weights of the @var{directory1} and @var{directory2}, 16910d565efSmrgrespectively. The default weights are 1 for both. 17010d565efSmrg@end table 17110d565efSmrg 17210d565efSmrg@item rewrite 17310d565efSmrgRead the specified profile directory and rewrite to a new directory. 17410d565efSmrg@table @gcctabopt 17510d565efSmrg 17610d565efSmrg@item -n @var{long_long_value} 17710d565efSmrg@itemx --normalize <long_long_value> 17810d565efSmrgNormalize the profile. The specified value is the max counter value 17910d565efSmrgin the new profile. 18010d565efSmrg 18110d565efSmrg@item -o @var{directory} 18210d565efSmrg@itemx --output @var{directory} 18310d565efSmrgSet the output profile directory. Default output name is @var{rewrite_profile}. 18410d565efSmrg 18510d565efSmrg@item -s @var{float_or_simple-frac_value} 18610d565efSmrg@itemx --scale @var{float_or_simple-frac_value} 18710d565efSmrgScale the profile counters. The specified value can be in floating point value, 18810d565efSmrgor simple fraction value form, such 1, 2, 2/3, and 5/3. 18910d565efSmrg 19010d565efSmrg@item -v 19110d565efSmrg@itemx --verbose 19210d565efSmrgSet the verbose mode. 19310d565efSmrg@end table 19410d565efSmrg 19510d565efSmrg@item overlap 19610d565efSmrgCompute the overlap score between the two specified profile directories. 19710d565efSmrgThe overlap score is computed based on the arc profiles. It is defined as 19810d565efSmrgthe sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all), 19910d565efSmrgfor all arc counter i, where p1_counter[i] and p2_counter[i] are two 20010d565efSmrgmatched counters and p1_sum_all and p2_sum_all are the sum of counter 20110d565efSmrgvalues in profile 1 and profile 2, respectively. 20210d565efSmrg 20310d565efSmrg@table @gcctabopt 20410d565efSmrg@item -f 20510d565efSmrg@itemx --function 20610d565efSmrgPrint function level overlap score. 20710d565efSmrg 20810d565efSmrg@item -F 20910d565efSmrg@itemx --fullname 21010d565efSmrgPrint full gcda filename. 21110d565efSmrg 21210d565efSmrg@item -h 21310d565efSmrg@itemx --hotonly 21410d565efSmrgOnly print info for hot objects/functions. 21510d565efSmrg 21610d565efSmrg@item -o 21710d565efSmrg@itemx --object 21810d565efSmrgPrint object level overlap score. 21910d565efSmrg 22010d565efSmrg@item -t @var{float} 22110d565efSmrg@itemx --hot_threshold <float> 22210d565efSmrgSet the threshold for hot counter value. 22310d565efSmrg 22410d565efSmrg@item -v 22510d565efSmrg@itemx --verbose 22610d565efSmrgSet the verbose mode. 22710d565efSmrg@end table 22810d565efSmrg 22910d565efSmrg@end table 23010d565efSmrg 23110d565efSmrg@c man end 232