232 lines
6.8 KiB
Plaintext
232 lines
6.8 KiB
Plaintext
@c Copyright (C) 2014-2020 Free Software Foundation, Inc.
|
|
@c This is part of the GCC manual.
|
|
@c For copying conditions, see the file gcc.texi.
|
|
|
|
@ignore
|
|
@c man begin COPYRIGHT
|
|
Copyright @copyright{} 2014-2020 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being ``GNU General Public License'' and ``Funding
|
|
Free Software'', the Front-Cover texts being (a) (see below), and with
|
|
the Back-Cover Texts being (b) (see below). A copy of the license is
|
|
included in the gfdl(7) man page.
|
|
|
|
(a) The FSF's Front-Cover Text is:
|
|
|
|
A GNU Manual
|
|
|
|
(b) The FSF's Back-Cover Text is:
|
|
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
|
software. Copies published by the Free Software Foundation raise
|
|
funds for GNU development.
|
|
@c man end
|
|
@c Set file name and title for the man page.
|
|
@setfilename gcov-tool
|
|
@settitle offline gcda profile processing tool
|
|
@end ignore
|
|
|
|
@node Gcov-tool
|
|
@chapter @command{gcov-tool}---an Offline Gcda Profile Processing Tool
|
|
|
|
@command{gcov-tool} is a tool you can use in conjunction with GCC to
|
|
manipulate or process gcda profile files offline.
|
|
|
|
@menu
|
|
* Gcov-tool Intro:: Introduction to gcov-tool.
|
|
* Invoking Gcov-tool:: How to use gcov-tool.
|
|
@end menu
|
|
|
|
@node Gcov-tool Intro
|
|
@section Introduction to @command{gcov-tool}
|
|
@c man begin DESCRIPTION
|
|
|
|
@command{gcov-tool} is an offline tool to process gcc's gcda profile files.
|
|
|
|
Current gcov-tool supports the following functionalities:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
merge two sets of profiles with weights.
|
|
|
|
@item
|
|
read one set of profile and rewrite profile contents. One can scale or
|
|
normalize the count values.
|
|
@end itemize
|
|
|
|
Examples of the use cases for this tool are:
|
|
@itemize @bullet
|
|
@item
|
|
Collect the profiles for different set of inputs, and use this tool to merge
|
|
them. One can specify the weight to factor in the relative importance of
|
|
each input.
|
|
|
|
@item
|
|
Rewrite the profile after removing a subset of the gcda files, while maintaining
|
|
the consistency of the summary and the histogram.
|
|
|
|
@item
|
|
It can also be used to debug or libgcov code as the tools shares the majority
|
|
code as the runtime library.
|
|
@end itemize
|
|
|
|
Note that for the merging operation, this profile generated offline may
|
|
contain slight different values from the online merged profile. Here are
|
|
a list of typical differences:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
histogram difference: This offline tool recomputes the histogram after merging
|
|
the counters. The resulting histogram, therefore, is precise. The online
|
|
merging does not have this capability -- the histogram is merged from two
|
|
histograms and the result is an approximation.
|
|
|
|
@item
|
|
summary checksum difference: Summary checksum uses a CRC32 operation. The value
|
|
depends on the link list order of gcov-info objects. This order is different in
|
|
gcov-tool from that in the online merge. It's expected to have different
|
|
summary checksums. It does not really matter as the compiler does not use this
|
|
checksum anywhere.
|
|
|
|
@item
|
|
value profile counter values difference: Some counter values for value profile
|
|
are runtime dependent, like heap addresses. It's normal to see some difference
|
|
in these kind of counters.
|
|
@end itemize
|
|
|
|
@c man end
|
|
|
|
@node Invoking Gcov-tool
|
|
@section Invoking @command{gcov-tool}
|
|
|
|
@smallexample
|
|
gcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND @r{[}@var{sub_command-options}@r{]} @var{profile_dir}
|
|
@end smallexample
|
|
|
|
@command{gcov-tool} accepts the following options:
|
|
|
|
@ignore
|
|
@c man begin SYNOPSIS
|
|
gcov-tool [@option{-v}|@option{--version}] [@option{-h}|@option{--help}]
|
|
|
|
gcov-tool merge [merge-options] @var{directory1} @var{directory2}
|
|
[@option{-o}|@option{--output} @var{directory}]
|
|
[@option{-v}|@option{--verbose}]
|
|
[@option{-w}|@option{--weight} @var{w1,w2}]
|
|
|
|
gcov-tool rewrite [rewrite-options] @var{directory}
|
|
[@option{-n}|@option{--normalize} @var{long_long_value}]
|
|
[@option{-o}|@option{--output} @var{directory}]
|
|
[@option{-s}|@option{--scale} @var{float_or_simple-frac_value}]
|
|
[@option{-v}|@option{--verbose}]
|
|
|
|
gcov-tool overlap [overlap-options] @var{directory1} @var{directory2}
|
|
[@option{-f}|@option{--function}]
|
|
[@option{-F}|@option{--fullname}]
|
|
[@option{-h}|@option{--hotonly}]
|
|
[@option{-o}|@option{--object}]
|
|
[@option{-t}|@option{--hot_threshold}] @var{float}
|
|
[@option{-v}|@option{--verbose}]
|
|
|
|
@c man end
|
|
@c man begin SEEALSO
|
|
gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for
|
|
@file{gcc}.
|
|
@c man end
|
|
@end ignore
|
|
|
|
@c man begin OPTIONS
|
|
@table @gcctabopt
|
|
@item -h
|
|
@itemx --help
|
|
Display help about using @command{gcov-tool} (on the standard output), and
|
|
exit without doing any further processing.
|
|
|
|
@item -v
|
|
@itemx --version
|
|
Display the @command{gcov-tool} version number (on the standard output),
|
|
and exit without doing any further processing.
|
|
|
|
@item merge
|
|
Merge two profile directories.
|
|
@table @gcctabopt
|
|
|
|
@item -o @var{directory}
|
|
@itemx --output @var{directory}
|
|
Set the output profile directory. Default output directory name is
|
|
@var{merged_profile}.
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
Set the verbose mode.
|
|
|
|
@item -w @var{w1},@var{w2}
|
|
@itemx --weight @var{w1},@var{w2}
|
|
Set the merge weights of the @var{directory1} and @var{directory2},
|
|
respectively. The default weights are 1 for both.
|
|
@end table
|
|
|
|
@item rewrite
|
|
Read the specified profile directory and rewrite to a new directory.
|
|
@table @gcctabopt
|
|
|
|
@item -n @var{long_long_value}
|
|
@itemx --normalize <long_long_value>
|
|
Normalize the profile. The specified value is the max counter value
|
|
in the new profile.
|
|
|
|
@item -o @var{directory}
|
|
@itemx --output @var{directory}
|
|
Set the output profile directory. Default output name is @var{rewrite_profile}.
|
|
|
|
@item -s @var{float_or_simple-frac_value}
|
|
@itemx --scale @var{float_or_simple-frac_value}
|
|
Scale the profile counters. The specified value can be in floating point value,
|
|
or simple fraction value form, such 1, 2, 2/3, and 5/3.
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
Set the verbose mode.
|
|
@end table
|
|
|
|
@item overlap
|
|
Compute the overlap score between the two specified profile directories.
|
|
The overlap score is computed based on the arc profiles. It is defined as
|
|
the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all),
|
|
for all arc counter i, where p1_counter[i] and p2_counter[i] are two
|
|
matched counters and p1_sum_all and p2_sum_all are the sum of counter
|
|
values in profile 1 and profile 2, respectively.
|
|
|
|
@table @gcctabopt
|
|
@item -f
|
|
@itemx --function
|
|
Print function level overlap score.
|
|
|
|
@item -F
|
|
@itemx --fullname
|
|
Print full gcda filename.
|
|
|
|
@item -h
|
|
@itemx --hotonly
|
|
Only print info for hot objects/functions.
|
|
|
|
@item -o
|
|
@itemx --object
|
|
Print object level overlap score.
|
|
|
|
@item -t @var{float}
|
|
@itemx --hot_threshold <float>
|
|
Set the threshold for hot counter value.
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
Set the verbose mode.
|
|
@end table
|
|
|
|
@end table
|
|
|
|
@c man end
|