.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GCOV-TOOL 1"
.TH GCOV-TOOL 1 "2024-08-01" "gcc-14.2.0" "GNU"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gcov\-tool \- offline gcda profile processing tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
gcov-tool [\fB\-v\fR|\fB\-\-version\fR] [\fB\-h\fR|\fB\-\-help\fR]
.PP
gcov-tool merge [merge\-options] \fIdirectory1\fR \fIdirectory2\fR
     [\fB\-o\fR|\fB\-\-output\fR \fIdirectory\fR]
     [\fB\-v\fR|\fB\-\-verbose\fR]
     [\fB\-w\fR|\fB\-\-weight\fR \fIw1,w2\fR]
.PP
gcov-tool merge-stream [merge\-stream\-options] [\fIfile\fR]
     [\fB\-v\fR|\fB\-\-verbose\fR]
     [\fB\-w\fR|\fB\-\-weight\fR \fIw1,w2\fR]
.PP
gcov-tool rewrite [rewrite\-options] \fIdirectory\fR
     [\fB\-n\fR|\fB\-\-normalize\fR \fIlong_long_value\fR]
     [\fB\-o\fR|\fB\-\-output\fR \fIdirectory\fR]
     [\fB\-s\fR|\fB\-\-scale\fR \fIfloat_or_simple\-frac_value\fR]
     [\fB\-v\fR|\fB\-\-verbose\fR]
.PP
gcov-tool overlap [overlap\-options] \fIdirectory1\fR \fIdirectory2\fR
     [\fB\-f\fR|\fB\-\-function\fR]
     [\fB\-F\fR|\fB\-\-fullname\fR]
     [\fB\-h\fR|\fB\-\-hotonly\fR]
     [\fB\-o\fR|\fB\-\-object\fR]
     [\fB\-t\fR|\fB\-\-hot_threshold\fR] \fIfloat\fR
     [\fB\-v\fR|\fB\-\-verbose\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBgcov-tool\fR is an offline tool to process gcc's gcda profile files.
.PP
Current gcov-tool supports the following functionalities:
.IP "*" 4
merge two sets of profiles with weights.
.IP "*" 4
read a stream of profiles with associated filenames and merge it with a set of
profiles with weights.
.IP "*" 4
read one set of profile and rewrite profile contents. One can scale or
normalize the count values.
.PP
Examples of the use cases for this tool are:
.IP "*" 4
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.
.IP "*" 4
Collect profiles from target systems without a filesystem (freestanding
environments).  Merge the collected profiles with associated profiles
present on the host system.  One can specify the weight to factor in the
relative importance of each input.
.IP "*" 4
Rewrite the profile after removing a subset of the gcda files, while maintaining
the consistency of the summary and the histogram.
.IP "*" 4
It can also be used to debug or libgcov code as the tools shares the majority
code as the runtime library.
.PP
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:
.IP "*" 4
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.
.IP "*" 4
summary checksum difference: Summary checksum uses a \s-1CRC32\s0 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.
.IP "*" 4
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.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Display help about using \fBgcov-tool\fR (on the standard output), and
exit without doing any further processing.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display the \fBgcov-tool\fR version number (on the standard output),
and exit without doing any further processing.
.IP "\fBmerge\fR" 4
.IX Item "merge"
Merge two profile directories.
.RS 4
.IP "\fB\-o\fR \fIdirectory\fR" 4
.IX Item "-o directory"
.PD 0
.IP "\fB\-\-output\fR \fIdirectory\fR" 4
.IX Item "--output directory"
.PD
Set the output profile directory. Default output directory name is
\&\fImerged_profile\fR.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.IP "\fB\-w\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "-w w1,w2"
.PD 0
.IP "\fB\-\-weight\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "--weight w1,w2"
.PD
Set the merge weights of the \fIdirectory1\fR and \fIdirectory2\fR,
respectively. The default weights are 1 for both.
.RE
.RS 4
.RE
.IP "\fBmerge-stream\fR" 4
.IX Item "merge-stream"
Collect profiles with associated filenames from a \fIgcfn\fR and \fIgcda\fR
data stream.  Read the stream from the file specified by \fIfile\fR or from
\&\fIstdin\fR.  Merge the profiles with associated profiles in the host
filesystem.  Apply the optional weights while merging profiles.
.Sp
For the generation of a \fIgcfn\fR and \fIgcda\fR data stream on the target
system, please have a look at the \f(CW\*(C`_\|_gcov_filename_to_gcfn()\*(C'\fR and
\&\f(CW\*(C`_\|_gcov_info_to_gcda()\*(C'\fR functions declared in \f(CW\*(C`#include <gcov.h>\*(C'\fR.
.RS 4
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.IP "\fB\-w\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "-w w1,w2"
.PD 0
.IP "\fB\-\-weight\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "--weight w1,w2"
.PD
Set the merge weights of the profiles from the \fIgcfn\fR and \fIgcda\fR data
stream and the associated profiles in the host filesystem, respectively.  The
default weights are 1 for both.
.RE
.RS 4
.RE
.IP "\fBrewrite\fR" 4
.IX Item "rewrite"
Read the specified profile directory and rewrite to a new directory.
.RS 4
.IP "\fB\-n\fR \fIlong_long_value\fR" 4
.IX Item "-n long_long_value"
.PD 0
.IP "\fB\-\-normalize <long_long_value>\fR" 4
.IX Item "--normalize <long_long_value>"
.PD
Normalize the profile. The specified value is the max counter value
in the new profile.
.IP "\fB\-o\fR \fIdirectory\fR" 4
.IX Item "-o directory"
.PD 0
.IP "\fB\-\-output\fR \fIdirectory\fR" 4
.IX Item "--output directory"
.PD
Set the output profile directory. Default output name is \fIrewrite_profile\fR.
.IP "\fB\-s\fR \fIfloat_or_simple\-frac_value\fR" 4
.IX Item "-s float_or_simple-frac_value"
.PD 0
.IP "\fB\-\-scale\fR \fIfloat_or_simple\-frac_value\fR" 4
.IX Item "--scale float_or_simple-frac_value"
.PD
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.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.RE
.RS 4
.RE
.IP "\fBoverlap\fR" 4
.IX 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.
.RS 4
.IP "\fB\-f\fR" 4
.IX Item "-f"
.PD 0
.IP "\fB\-\-function\fR" 4
.IX Item "--function"
.PD
Print function level overlap score.
.IP "\fB\-F\fR" 4
.IX Item "-F"
.PD 0
.IP "\fB\-\-fullname\fR" 4
.IX Item "--fullname"
.PD
Print full gcda filename.
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-hotonly\fR" 4
.IX Item "--hotonly"
.PD
Only print info for hot objects/functions.
.IP "\fB\-o\fR" 4
.IX Item "-o"
.PD 0
.IP "\fB\-\-object\fR" 4
.IX Item "--object"
.PD
Print object level overlap score.
.IP "\fB\-t\fR \fIfloat\fR" 4
.IX Item "-t float"
.PD 0
.IP "\fB\-\-hot_threshold <float>\fR" 4
.IX Item "--hot_threshold <float>"
.PD
Set the threshold for hot counter value.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgpl\fR\|(7), \fBgfdl\fR\|(7), \fBfsf\-funding\fR\|(7), \fBgcc\fR\|(1), \fBgcov\fR\|(1) and the Info entry for
\&\fIgcc\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2014\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being \*(L"\s-1GNU\s0 General Public License\*(R" and \*(L"Funding
Free Software\*(R", 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 \fBgfdl\fR\|(7) man page.
.PP
(a) The \s-1FSF\s0's Front-Cover Text is:
.PP
.Vb 1
\&     A GNU Manual
.Ve
.PP
(b) The \s-1FSF\s0's Back-Cover Text is:
.PP
.Vb 3
\&     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.
.Ve