gcc/doc/gcov-tool.texi

   1 @c Copyright (C) 2014-2024 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-2024 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 a stream of profiles with associated filenames and merge it with a set of
  57 profiles with weights.
  58
  59 @item
  60 read one set of profile and rewrite profile contents. One can scale or
  61 normalize the count values.
  62 @end itemize
  63
  64 Examples of the use cases for this tool are:
  65 @itemize @bullet
  66 @item
  67 Collect the profiles for different set of inputs, and use this tool to merge
  68 them. One can specify the weight to factor in the relative importance of
  69 each input.
  70
  71 @item
  72 Collect profiles from target systems without a filesystem (freestanding
  73 environments).  Merge the collected profiles with associated profiles
  74 present on the host system.  One can specify the weight to factor in the
  75 relative importance of each input.
  76
  77 @item
  78 Rewrite the profile after removing a subset of the gcda files, while maintaining
  79 the consistency of the summary and the histogram.
  80
  81 @item
  82 It can also be used to debug or libgcov code as the tools shares the majority
  83 code as the runtime library.
  84 @end itemize
  85
  86 Note that for the merging operation, this profile generated offline may
  87 contain slight different values from the online merged profile. Here are
  88 a list of typical differences:
  89
  90 @itemize @bullet
  91 @item
  92 histogram difference: This offline tool recomputes the histogram after merging
  93 the counters. The resulting histogram, therefore, is precise. The online
  94 merging does not have this capability -- the histogram is merged from two
  95 histograms and the result is an approximation.
  96
  97 @item
  98 summary checksum difference: Summary checksum uses a CRC32 operation. The value
  99 depends on the link list order of gcov-info objects. This order is different in
 100 gcov-tool from that in the online merge. It's expected to have different
 101 summary checksums. It does not really matter as the compiler does not use this
 102 checksum anywhere.
 103
 104 @item
 105 value profile counter values difference: Some counter values for value profile
 106 are runtime dependent, like heap addresses. It's normal to see some difference
 107 in these kind of counters.
 108 @end itemize
 109
 110 @c man end
 111
 112 @node Invoking Gcov-tool
 113 @section Invoking @command{gcov-tool}
 114
 115 @smallexample
 116 gcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND @r{[}@var{sub_command-options}@r{]} @var{profile_dir}
 117 @end smallexample
 118
 119 @command{gcov-tool} accepts the following options:
 120
 121 @ignore
 122 @c man begin SYNOPSIS
 123 gcov-tool [@option{-v}|@option{--version}] [@option{-h}|@option{--help}]
 124
 125 gcov-tool merge [merge-options] @var{directory1} @var{directory2}
 126      [@option{-o}|@option{--output} @var{directory}]
 127      [@option{-v}|@option{--verbose}]
 128      [@option{-w}|@option{--weight} @var{w1,w2}]
 129
 130 gcov-tool merge-stream [merge-stream-options] [@var{file}]
 131      [@option{-v}|@option{--verbose}]
 132      [@option{-w}|@option{--weight} @var{w1,w2}]
 133
 134 gcov-tool rewrite [rewrite-options] @var{directory}
 135      [@option{-n}|@option{--normalize} @var{long_long_value}]
 136      [@option{-o}|@option{--output} @var{directory}]
 137      [@option{-s}|@option{--scale} @var{float_or_simple-frac_value}]
 138      [@option{-v}|@option{--verbose}]
 139
 140 gcov-tool overlap [overlap-options] @var{directory1} @var{directory2}
 141      [@option{-f}|@option{--function}]
 142      [@option{-F}|@option{--fullname}]
 143      [@option{-h}|@option{--hotonly}]
 144      [@option{-o}|@option{--object}]
 145      [@option{-t}|@option{--hot_threshold}] @var{float}
 146      [@option{-v}|@option{--verbose}]
 147
 148 @c man end
 149 @c man begin SEEALSO
 150 gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for
 151 @file{gcc}.
 152 @c man end
 153 @end ignore
 154
 155 @c man begin OPTIONS
 156 @table @gcctabopt
 157 @item -h
 158 @itemx --help
 159 Display help about using @command{gcov-tool} (on the standard output), and
 160 exit without doing any further processing.
 161
 162 @item -v
 163 @itemx --version
 164 Display the @command{gcov-tool} version number (on the standard output),
 165 and exit without doing any further processing.
 166
 167 @item merge
 168 Merge two profile directories.
 169 @table @gcctabopt
 170
 171 @item -o @var{directory}
 172 @itemx --output @var{directory}
 173 Set the output profile directory. Default output directory name is
 174 @var{merged_profile}.
 175
 176 @item -v
 177 @itemx --verbose
 178 Set the verbose mode.
 179
 180 @item -w @var{w1},@var{w2}
 181 @itemx --weight @var{w1},@var{w2}
 182 Set the merge weights of the @var{directory1} and @var{directory2},
 183 respectively. The default weights are 1 for both.
 184 @end table
 185
 186 @item merge-stream
 187 Collect profiles with associated filenames from a @emph{gcfn} and @emph{gcda}
 188 data stream.  Read the stream from the file specified by @var{file} or from
 189 @file{stdin}.  Merge the profiles with associated profiles in the host
 190 filesystem.  Apply the optional weights while merging profiles.
 191
 192 For the generation of a @emph{gcfn} and @emph{gcda} data stream on the target
 193 system, please have a look at the @code{__gcov_filename_to_gcfn()} and
 194 @code{__gcov_info_to_gcda()} functions declared in @code{#include <gcov.h>}.
 195 @table @gcctabopt
 196
 197 @item -v
 198 @itemx --verbose
 199 Set the verbose mode.
 200
 201 @item -w @var{w1},@var{w2}
 202 @itemx --weight @var{w1},@var{w2}
 203 Set the merge weights of the profiles from the @emph{gcfn} and @emph{gcda} data
 204 stream and the associated profiles in the host filesystem, respectively.  The
 205 default weights are 1 for both.
 206 @end table
 207
 208 @item rewrite
 209 Read the specified profile directory and rewrite to a new directory.
 210 @table @gcctabopt
 211
 212 @item -n @var{long_long_value}
 213 @itemx --normalize <long_long_value>
 214 Normalize the profile. The specified value is the max counter value
 215 in the new profile.
 216
 217 @item -o @var{directory}
 218 @itemx --output @var{directory}
 219 Set the output profile directory. Default output name is @var{rewrite_profile}.
 220
 221 @item -s @var{float_or_simple-frac_value}
 222 @itemx --scale @var{float_or_simple-frac_value}
 223 Scale the profile counters. The specified value can be in floating point value,
 224 or simple fraction value form, such 1, 2, 2/3, and 5/3.
 225
 226 @item -v
 227 @itemx --verbose
 228 Set the verbose mode.
 229 @end table
 230
 231 @item overlap
 232 Compute the overlap score between the two specified profile directories.
 233 The overlap score is computed based on the arc profiles. It is defined as
 234 the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all),
 235 for all arc counter i, where p1_counter[i] and p2_counter[i] are two
 236 matched counters and p1_sum_all and p2_sum_all are the sum of counter
 237 values in profile 1 and profile 2, respectively.
 238
 239 @table @gcctabopt
 240 @item -f
 241 @itemx --function
 242 Print function level overlap score.
 243
 244 @item -F
 245 @itemx --fullname
 246 Print full gcda filename.
 247
 248 @item -h
 249 @itemx --hotonly
 250 Only print info for hot objects/functions.
 251
 252 @item -o
 253 @itemx --object
 254 Print object level overlap score.
 255
 256 @item -t @var{float}
 257 @itemx --hot_threshold <float>
 258 Set the threshold for hot counter value.
 259
 260 @item -v
 261 @itemx --verbose
 262 Set the verbose mode.
 263 @end table
 264
 265 @end table
 266
 267 @c man end