gprofng/doc/gp-display-text.texi

   1 @c ----------------------------------------------------------------------------
   2 @c This is the Texinfo source file for the gp-display-text man page.
   3 @c
   4 @c Author: Ruud van der Pas
   5 @c ----------------------------------------------------------------------------
   6 @ifset man
   7 \input texinfo @c -*-texinfo-*-
   8 @setfilename gp-display-text
   9 @settitle Display the performance data in plain text format
  10 @include gp-macros.texi
  11 @end ifset
  12
  13 @c ----------------------------------------------------------------------------
  14 @c This is from the man-pages(7) man page
  15 @c
  16 @c "The list below shows conventional or suggested sections.  Most manual pages
  17 @c  should include at least the highlighted sections.  Arrange a new manual
  18 @c  page so that sections are placed in the order shown in the list."
  19 @c
  20 @c              NAME
  21 @c              SYNOPSIS
  22 @c              CONFIGURATION    [Normally only in Section 4]
  23 @c              DESCRIPTION
  24 @c              OPTIONS          [Normally only in Sections 1, 8]
  25 @c              EXIT STATUS      [Normally only in Sections 1, 8]
  26 @c              RETURN VALUE     [Normally only in Sections 2, 3]
  27 @c              ERRORS           [Typically only in Sections 2, 3]
  28 @c              ENVIRONMENT
  29 @c              FILES
  30 @c              VERSIONS         [Normally only in Sections 2, 3]
  31 @c              ATTRIBUTES       [Normally only in Sections 2, 3]
  32 @c              CONFORMING TO
  33 @c              NOTES
  34 @c              BUGS
  35 @c              EXAMPLES
  36 @c              AUTHORS          [Discouraged]
  37 @c              REPORTING BUGS   [Not used in man-pages]
  38 @c              COPYRIGHT        [Not used in man-pages]
  39 @c              SEE ALSO
  40 @c
  41 @c This is what the texi2pod.pl tool recognizes:
  42 @c
  43 @c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
  44 @c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
  45 @c
  46 @c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
  47 @c makes sense and adhered to for the other formats.
  48 @c ----------------------------------------------------------------------------
  49
  50 @c ----------------------------------------------------------------------------
  51 @c NAME section
  52 @c ----------------------------------------------------------------------------
  53
  54 @ManPageStart{NAME}
  55 @c man begin NAME
  56
  57 gp-display-text - Display the performance data in plain text format
  58
  59 @c man end
  60 @ManPageEnd{}
  61
  62 @c ----------------------------------------------------------------------------
  63 @c SYNOPSIS section
  64 @c ----------------------------------------------------------------------------
  65
  66 @ManPageStart{SYNOPSIS}
  67 @c man begin SYNOPSIS
  68
  69 @command{gprofng display text} [@var{option(s)}] [@var{commands}]
  70 [-script @var{script-file}] @var{experiment(s)}
  71
  72 @c man end
  73 @ManPageEnd{}
  74
  75 @c ----------------------------------------------------------------------------
  76 @c DESCRIPTION section
  77 @c ----------------------------------------------------------------------------
  78
  79 @ManPageStart{DESCRIPTION}
  80 @c man begin DESCRIPTION
  81
  82 Print a plain text version of the various displays supported by gprofng.
  83
  84 The input consists of one or more experiment directories.  Through commands,
  85 the user controls the output.
  86
  87 There is a rich set of commands to control the display of the data.  The
  88 @samp{NOTES} section lists the most common ones.  The gprofng user guide
  89 lists all the commands supported.
  90
  91 Commands specified on the command line need to be prepended with the dash ('-')
  92 symbol.
  93
  94 In this example, a function overview will be shown, followed by the source
  95 code listing of function @samp{my-func}, annotated with the
  96 performance metrics that have been recorded during the data collection
  97 and stored in experiment directory @samp{my-exp.er}:
  98
  99 @smallexample
 100 $ gprofng display text -functions -source my-func my-exp.er
 101 @end smallexample
 102
 103 Instead of, or in addition to, specifying these commands on the command line,
 104 commands may also be included in a file called the @var{script-file}.
 105
 106 Note that the commands are processed and interpreted from left to right,
 107 @emph{so the order matters}.
 108
 109 If this tool is invoked without options, commands, or a script file, it
 110 starts in interpreter mode.  The user can then issue the commands
 111 interactively.  The session is terminated with the @command{exit} command in
 112 the interpreter.
 113
 114 @c man end
 115 @ManPageEnd{}
 116
 117 @c ----------------------------------------------------------------------------
 118 @c OPTIONS section
 119 @c ----------------------------------------------------------------------------
 120
 121 @ManPageStart{OPTIONS}
 122 @c man begin OPTIONS
 123
 124 @table @gcctabopt
 125
 126 @item --version
 127 @ifclear man
 128 @IndexSubentry{Options, @code{--version}}
 129 @end ifclear
 130
 131 Print the version number and exit.
 132
 133 @item --help
 134 @ifclear man
 135 @IndexSubentry{Options, @code{--help}}
 136 @end ifclear
 137
 138 Print usage information and exit.
 139
 140 @item -script @var{script-file}
 141 @ifclear man
 142 @IndexSubentry{Options,  @code{-script}}
 143 @IndexSubentry{Commands, @code{script}}
 144 @end ifclear
 145
 146 Execute the commands stored in the script file.  This feature may be combined
 147 with commands specified at the command line.
 148
 149 @end table
 150
 151 @c man end
 152 @ManPageEnd{}
 153
 154 @c ----------------------------------------------------------------------------
 155 @c NOTES section
 156 @c ----------------------------------------------------------------------------
 157
 158 @ManPageStart{NOTES}
 159 @c man begin NOTES
 160
 161 Many commands are supported.  Below, the more common ones are listed in
 162 mostly alphabetical order, because sometimes it is more logical to
 163 swap the order of two entries.
 164
 165 @ifset man
 166 There are many more commands.  These are documented in the user guide.
 167 @end ifset
 168
 169 @table @code
 170
 171 @item callers-callees
 172 @ifclear man
 173 @IndexSubentry{Options,  @code{-callers-callees}}
 174 @IndexSubentry{Commands, @code{callers-callees}}
 175 @end ifclear
 176 In a callers-callees panel, it is shown which function(s) call the target
 177 function (the @emph{callers}) and what functions it is calling (the
 178 @emph{callees}).
 179 This command prints the callers-callees panel for each of the functions,
 180 in the order specified by the function sort metric.
 181
 182 @item calltree
 183 @ifclear man
 184 @IndexSubentry{Options,  @code{-calltree}}
 185 @IndexSubentry{Commands, @code{calltree}}
 186 @end ifclear
 187 Display the dynamic call graph from the experiment, showing the hierarchical
 188 metrics at each level.
 189
 190 @item compare @{on | off | delta | ratio@}
 191 @ifclear man
 192 @IndexSubentry{Options,  @code{-compare}}
 193 @IndexSubentry{Commands, @code{compare}}
 194 @end ifclear
 195 By default, the results for multiple experiments are aggregated.  This
 196 command changes this to enable the comparison of experiments for certain
 197 views (e.g. the function view).  The first experiment specified is defined
 198 to be the reference.  The following options are supported:
 199
 200 @table @code
 201
 202 @item on
 203 For each experiment specified on the command line, print the values for
 204 the metrics that have been activated for the experiment.
 205
 206 @item off
 207 Disable the comparison of experiments.  This is the default.
 208
 209 @item delta
 210 Print the values for the reference experiment.  The results for the other
 211 experiments are shown as a delta relative to the reference (current-reference).
 212
 213 @item ratio
 214 Print the values for the reference experiment.  The results for the other
 215 experiments are shown as a ratio relative to the reference (current/reference).
 216
 217 @end table
 218
 219 @item disasm @var{function-name}
 220 @ifclear man
 221 @IndexSubentry{Options,  @code{-disasm}}
 222 @IndexSubentry{Commands, @code{disasm}}
 223 @end ifclear
 224 List the source code and instructions for the function specified.  The
 225 instructions are annotated with the metrics used.
 226
 227 @item fsingle @var{function-name} [@samp{n}]
 228 @ifclear man
 229 @IndexSubentry{Options,  @code{-fsingle}}
 230 @IndexSubentry{Commands, @code{fsingle}}
 231 @end ifclear
 232 Write a summary panel for the specified function.  The optional parameter
 233 @var{n} is needed for those cases where several functions have the same name.
 234
 235 @item fsummary
 236 @ifclear man
 237 @IndexSubentry{Options,  @code{-fsummary}}
 238 @IndexSubentry{Commands, @code{fsummary}}
 239 @end ifclear
 240 Write a summary panel for each function in the function list.
 241
 242 @item functions
 243 @ifclear man
 244 @IndexSubentry{Options,  @code{-functions}}
 245 @IndexSubentry{Commands, @code{functions}}
 246 @end ifclear
 247 Display a list of all functions executed.  For each function the used metrics
 248 (e.g. the CPU time) are shown.
 249
 250 @item header
 251 @ifclear man
 252 @IndexSubentry{Options,  @code{-header}}
 253 @IndexSubentry{Commands, @code{header}}
 254 @end ifclear
 255 Shows several operational characteristics of the experiment(s) specified
 256 on the command line.
 257
 258 @item limit @var{n}
 259 @ifclear man
 260 @IndexSubentry{Options,  @code{-limit}}
 261 @IndexSubentry{Commands, @code{limit}}
 262 @end ifclear
 263 Limit the output to @var{n} lines.
 264
 265 @item lines
 266 @ifclear man
 267 @IndexSubentry{Options,  @code{-lines}}
 268 @IndexSubentry{Commands, @code{lines}}
 269 @end ifclear
 270 Write a list of source lines and their metrics, ordered by the current
 271 sort metric.
 272
 273 @item metric_list
 274 @ifclear man
 275 @IndexSubentry{Options,  @code{-metric_list}}
 276 @IndexSubentry{Commands, @code{metric_list}}
 277 @end ifclear
 278 Display the currently selected metrics in the function view and a list
 279 of all the metrics available for the target experiment(s).
 280
 281 @item metrics @var{metric-spec}
 282 @ifclear man
 283 @IndexSubentry{Options,  @code{-metrics}}
 284 @IndexSubentry{Commands, @code{metrics}}
 285 @end ifclear
 286 Define the metrics to be displayed in the function and callers-callees
 287 overviews.
 288
 289 The @var{metric-spec} can either be the keyword @samp{default}
 290 to restore the default metrics selection, or a colon separated list
 291 with metrics.
 292
 293 @ifclear man
 294 @IndexSubentry{Hardware event counters, @code{hwc} metric}
 295 @end ifclear
 296 A special metric is @code{hwc}.  It automatically expands to the active
 297 set of hardware event counters used in the experiment(s).
 298
 299 @ifclear man
 300 @IndexSubentry{Hardware event counters, @code{IPC} metric}
 301 @IndexSubentry{Hardware event counters, @code{CPI} metric}
 302 @end ifclear
 303 If both instructions and clock cycles have been measured, the @code{CPI}
 304 and @code{IPC} metrics can be used to see the Clockcycles Per Instruction
 305 and Instructions Per Clockcyle values, respectively.
 306
 307 The gprofng user guide has more details how to define metrics.
 308
 309 @item name @{short | long | mangled@}[:@{soname | nosoname@}]
 310 @ifclear man
 311 @IndexSubentry{Options,  @code{-name}}
 312 @IndexSubentry{Commands, @code{name}}
 313 @end ifclear
 314 Specify whether to use the short, long, or mangled form of function names.
 315 Optionally, the load object that the function is part of can be included in
 316 the output by adding the @emph{soname} keyword.  It can also be ommitted
 317 (@emph{nosoname}), which is the default.
 318
 319 Whether there is an actual difference between these types of names depends
 320 on the language.
 321
 322 Note that there should be no (white)space to the left and right of the
 323 colon (@samp{:}).
 324
 325 This option should not be confused with the keyword @samp{name} in a
 326 metric definition, which is used to specify that the names of functions
 327 should be shown in the function overview.
 328
 329 @item overview
 330 @ifclear man
 331 @IndexSubentry{Options,  @code{-overview}}
 332 @IndexSubentry{Commands, @code{overview}}
 333 @end ifclear
 334 Shows a summary of the recorded performance data for the experiment(s)
 335 specified on the command line.
 336
 337 @item pcs
 338 @ifclear man
 339 @IndexSubentry{Options,  @code{-pcs}}
 340 @IndexSubentry{Commands, @code{pcs}}
 341 @end ifclear
 342 Write a list of program counters (PCs) and their metrics, ordered by
 343 the current sort metric.
 344
 345 @item sort @var{metric-spec}
 346 @ifclear man
 347 @IndexSubentry{Options,  @code{-sort}}
 348 @IndexSubentry{Commands, @code{sort}}
 349 @end ifclear
 350 Sort the function list on the @var{metric-spec} given.
 351
 352 @IndexSubentry{Sort, Reverse order}
 353 The data can be sorted in reverse order by prepending the metric definition
 354 with a minus (@samp{-}) sign.
 355
 356 @noindent
 357 For example @command{sort -e.totalcpu}.
 358
 359 @IndexSubentry{Sort, Reset to default}
 360 A default metric for the sort operation has been defined and since this is
 361 a persistent command, this default can be restored with @code{default} as
 362 the key (@command{sort default}).
 363
 364 @item source @var{function-name}
 365 @ifclear man
 366 @IndexSubentry{Options,  @code{-source}}
 367 @IndexSubentry{Commands, @code{source}}
 368 @end ifclear
 369 List the source code for the function specified, annotated with the metrics
 370 used.
 371
 372 @item viewmode @{user | expert | machine@}
 373 @ifclear man
 374 @IndexSubentry{Options,  @code{-viewmode}}
 375 @IndexSubentry{Commands, @code{viewmode}}
 376 @end ifclear
 377 This command is only relevant for Java programs.  For all other languages
 378 supported, the viewmode setting has no effect.
 379
 380 The following options are supported:
 381
 382 @table @code
 383
 384 @item user
 385 Show the Java call stacks for Java threads, but do not show housekeeping
 386 threads.  The function view includes a function called @samp{<JVM-System>}.
 387 This represents the aggregated time from non-Java threads.
 388 In case the JVM software does not report a Java call stack, time is reported
 389 against the function @samp{<no Java callstack recorded>}.
 390
 391 @item expert
 392 Show the Java call stacks for Java threads when the user Java code is executed,
 393 and machine call stacks when JVM code is executed, or when the JVM software
 394 does not report a Java call stack.  Show the machine call stacks for
 395 housekeeping threads.
 396
 397 @item machine
 398 Show the actual native call stacks for all threads.  This is the view mode
 399 for C, C++, and Fortran.
 400
 401 @end table
 402
 403 @end table
 404
 405 @c man end
 406 @ManPageEnd{}
 407
 408 @c ----------------------------------------------------------------------------
 409 @c SEEALSO section
 410 @c ----------------------------------------------------------------------------
 411
 412 @ManPageStart{SEE ALSO}
 413 @c man begin SEEALSO
 414
 415 gprofng(1),
 416 gp-archive(1),
 417 gp-collect-app(1),
 418 gp-display-gui(1),
 419 gp-display-html(1),
 420 gp-display-src(1)
 421
 422 @iftex
 423 @vspace{1}
 424 @end iftex
 425
 426 The user guide for gprofng is maintained as a Texinfo manual.  If the
 427 @command{info} and @command{gprofng} programs are correctly installed, the
 428 command @command{info gprofng} should give access to this document.
 429
 430 @c man end
 431 @ManPageEnd{}
 432
 433 @c ----------------------------------------------------------------------------
 434 @c COPYRIGHT section
 435 @c ----------------------------------------------------------------------------
 436
 437 @ManPageStart{COPYRIGHT}
 438 @c man begin COPYRIGHT
 439
 440 Copyright @copyright{} 2022-2024 Free Software Foundation, Inc.
 441
 442 Permission is granted to copy, distribute and/or modify this document
 443 under the terms of the GNU Free Documentation License, Version 1.3
 444 or any later version published by the Free Software Foundation;
 445 with no Invariant Sections, with no Front-Cover Texts, and with no
 446 Back-Cover Texts.  A copy of the license is included in the
 447 section entitled ``GNU Free Documentation License''.
 448
 449 @c man end
 450 @ManPageEnd{}
 451
 452 @c ----------------------------------------------------------------------------
 453 @c If this text is used for a man page, exit.  Otherwise we need to continue.
 454 @c ----------------------------------------------------------------------------
 455
 456 @ifset man
 457 @bye
 458 @end ifset