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 57gp-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 82Print a plain text version of the various displays supported by gprofng. 83 84The input consists of one or more experiment directories. Through commands, 85the user controls the output. 86 87There 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 89lists all the commands supported. 90 91Commands specified on the command line need to be prepended with the dash ('-') 92symbol. 93 94In this example, a function overview will be shown, followed by the source 95code listing of function @samp{my-func}, annotated with the 96performance metrics that have been recorded during the data collection 97and 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 103Instead of, or in addition to, specifying these commands on the command line, 104commands may also be included in a file called the @var{script-file}. 105 106Note that the commands are processed and interpreted from left to right, 107@emph{so the order matters}. 108 109If this tool is invoked without options, commands, or a script file, it 110starts in interpreter mode. The user can then issue the commands 111interactively. The session is terminated with the @command{exit} command in 112the 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 131Print the version number and exit. 132 133@item --help 134@ifclear man 135@IndexSubentry{Options, @code{--help}} 136@end ifclear 137 138Print 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 146Execute the commands stored in the script file. This feature may be combined 147with 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 161Many commands are supported. Below, the more common ones are listed in 162mostly alphabetical order, because sometimes it is more logical to 163swap the order of two entries. 164 165@ifset man 166There 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 176In a callers-callees panel, it is shown which function(s) call the target 177function (the @emph{callers}) and what functions it is calling (the 178@emph{callees}). 179This command prints the callers-callees panel for each of the functions, 180in 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 187Display the dynamic call graph from the experiment, showing the hierarchical 188metrics 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 195By default, the results for multiple experiments are aggregated. This 196command changes this to enable the comparison of experiments for certain 197views (e.g. the function view). The first experiment specified is defined 198to be the reference. The following options are supported: 199 200@table @code 201 202@item on 203For each experiment specified on the command line, print the values for 204the metrics that have been activated for the experiment. 205 206@item off 207Disable the comparison of experiments. This is the default. 208 209@item delta 210Print the values for the reference experiment. The results for the other 211experiments are shown as a delta relative to the reference (current-reference). 212 213@item ratio 214Print the values for the reference experiment. The results for the other 215experiments 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 224List the source code and instructions for the function specified. The 225instructions 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 232Write 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 240Write 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 247Display 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 255Shows several operational characteristics of the experiment(s) specified 256on 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 263Limit 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 270Write a list of source lines and their metrics, ordered by the current 271sort metric. 272 273@item metric_list 274@ifclear man 275@IndexSubentry{Options, @code{-metric_list}} 276@IndexSubentry{Commands, @code{metric_list}} 277@end ifclear 278Display the currently selected metrics in the function view and a list 279of 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 286Define the metrics to be displayed in the function and callers-callees 287overviews. 288 289The @var{metric-spec} can either be the keyword @samp{default} 290to restore the default metrics selection, or a colon separated list 291with metrics. 292 293@ifclear man 294@IndexSubentry{Hardware event counters, @code{hwc} metric} 295@end ifclear 296A special metric is @code{hwc}. It automatically expands to the active 297set 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 303If both instructions and clock cycles have been measured, the @code{CPI} 304and @code{IPC} metrics can be used to see the Clockcycles Per Instruction 305and Instructions Per Clockcyle values, respectively. 306 307The 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 314Specify whether to use the short, long, or mangled form of function names. 315Optionally, the load object that the function is part of can be included in 316the output by adding the @emph{soname} keyword. It can also be ommitted 317(@emph{nosoname}), which is the default. 318 319Whether there is an actual difference between these types of names depends 320on the language. 321 322Note that there should be no (white)space to the left and right of the 323colon (@samp{:}). 324 325This option should not be confused with the keyword @samp{name} in a 326metric definition, which is used to specify that the names of functions 327should 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 334Shows a summary of the recorded performance data for the experiment(s) 335specified on the command line. 336 337@item pcs 338@ifclear man 339@IndexSubentry{Options, @code{-pcs}} 340@IndexSubentry{Commands, @code{pcs}} 341@end ifclear 342Write a list of program counters (PCs) and their metrics, ordered by 343the 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 350Sort the function list on the @var{metric-spec} given. 351 352@IndexSubentry{Sort, Reverse order} 353The data can be sorted in reverse order by prepending the metric definition 354with a minus (@samp{-}) sign. 355 356@noindent 357For example @command{sort -e.totalcpu}. 358 359@IndexSubentry{Sort, Reset to default} 360A default metric for the sort operation has been defined and since this is 361a persistent command, this default can be restored with @code{default} as 362the 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 369List the source code for the function specified, annotated with the metrics 370used. 371 372@item viewmode @{user | expert | machine@} 373@ifclear man 374@IndexSubentry{Options, @code{-viewmode}} 375@IndexSubentry{Commands, @code{viewmode}} 376@end ifclear 377This command is only relevant for Java programs. For all other languages 378supported, the viewmode setting has no effect. 379 380The following options are supported: 381 382@table @code 383 384@item user 385Show the Java call stacks for Java threads, but do not show housekeeping 386threads. The function view includes a function called @samp{<JVM-System>}. 387This represents the aggregated time from non-Java threads. 388In case the JVM software does not report a Java call stack, time is reported 389against the function @samp{<no Java callstack recorded>}. 390 391@item expert 392Show the Java call stacks for Java threads when the user Java code is executed, 393and machine call stacks when JVM code is executed, or when the JVM software 394does not report a Java call stack. Show the machine call stacks for 395housekeeping threads. 396 397@item machine 398Show the actual native call stacks for all threads. This is the view mode 399for 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 415gprofng(1), 416gp-archive(1), 417gp-collect-app(1), 418gp-display-gui(1), 419gp-display-html(1), 420gp-display-src(1) 421 422@iftex 423@vspace{1} 424@end iftex 425 426The user guide for gprofng is maintained as a Texinfo manual. If the 427@command{info} and @command{gprofng} programs are correctly installed, the 428command @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 440Copyright @copyright{} 2022-2024 Free Software Foundation, Inc. 441 442Permission is granted to copy, distribute and/or modify this document 443under the terms of the GNU Free Documentation License, Version 1.3 444or any later version published by the Free Software Foundation; 445with no Invariant Sections, with no Front-Cover Texts, and with no 446Back-Cover Texts. A copy of the license is included in the 447section 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 459