diff options
Diffstat (limited to 'upstream/debian-unstable/man1/gp-display-text.1')
| -rw-r--r-- | upstream/debian-unstable/man1/gp-display-text.1 | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/gp-display-text.1 b/upstream/debian-unstable/man1/gp-display-text.1 new file mode 100644 index 00000000..54cf84c4 --- /dev/null +++ b/upstream/debian-unstable/man1/gp-display-text.1 @@ -0,0 +1,319 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. 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 +.\" ======================================================================== +.\" +.IX Title "GP-DISPLAY-TEXT.1 1" +.TH GP-DISPLAY-TEXT.1 1 2024-02-21 binutils-2.42 "User Commands" +.\" 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 +gp\-display\-text \- Display the performance data in plain text format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +\&\fBgprofng display text\fR [\fIoption(s)\fR] [\fIcommands\fR] +[\-script \fIscript-file\fR] \fIexperiment(s)\fR +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Print a plain text version of the various displays supported by gprofng. +.PP +The input consists of one or more experiment directories. Through commands, +the user controls the output. +.PP +There is a rich set of commands to control the display of the data. The +\&\fBNOTES\fR section lists the most common ones. The gprofng user guide +lists all the commands supported. +.PP +Commands specified on the command line need to be prepended with the dash ('\-') +symbol. +.PP +In this example, a function overview will be shown, followed by the source +code listing of function \fBmy-func\fR, annotated with the +performance metrics that have been recorded during the data collection +and stored in experiment directory \fBmy\-exp.er\fR: +.PP +.Vb 1 +\& $ gprofng display text \-functions \-source my\-func my\-exp.er +.Ve +.PP +Instead of, or in addition to, specifying these commands on the command line, +commands may also be included in a file called the \fIscript-file\fR. +.PP +Note that the commands are processed and interpreted from left to right, +\&\fIso the order matters\fR. +.PP +If this tool is invoked without options, commands, or a script file, it +starts in interpreter mode. The user can then issue the commands +interactively. The session is terminated with the \fBexit\fR command in +the interpreter. +.SH OPTIONS +.IX Header "OPTIONS" +.IP \fB\-\-version\fR 4 +.IX Item "--version" +Print the version number and exit. +.IP \fB\-\-help\fR 4 +.IX Item "--help" +Print usage information and exit. +.IP "\fB\-script\fR \fIscript-file\fR" 4 +.IX Item "-script script-file" +Execute the commands stored in the script file. This feature may be combined +with commands specified at the command line. +.SH NOTES +.IX Header "NOTES" +Many commands are supported. Below, the more common ones are listed in +mostly alphabetical order, because sometimes it is more logical to +swap the order of two entries. +.PP +There are many more commands. These are documented in the user guide. +.ie n .IP """callers\-callees""" 4 +.el .IP \f(CWcallers\-callees\fR 4 +.IX Item "callers-callees" +In a callers-callees panel, it is shown which function(s) call the target +function (the \fIcallers\fR) and what functions it is calling (the +\&\fIcallees\fR). +This command prints the callers-callees panel for each of the functions, +in the order specified by the function sort metric. +.ie n .IP """calltree""" 4 +.el .IP \f(CWcalltree\fR 4 +.IX Item "calltree" +Display the dynamic call graph from the experiment, showing the hierarchical +metrics at each level. +.ie n .IP """compare {on | off | delta | ratio}""" 4 +.el .IP "\f(CWcompare {on | off | delta | ratio}\fR" 4 +.IX Item "compare {on | off | delta | ratio}" +By default, the results for multiple experiments are aggregated. This +command changes this to enable the comparison of experiments for certain +views (e.g. the function view). The first experiment specified is defined +to be the reference. The following options are supported: +.RS 4 +.ie n .IP """on""" 4 +.el .IP \f(CWon\fR 4 +.IX Item "on" +For each experiment specified on the command line, print the values for +the metrics that have been activated for the experiment. +.ie n .IP """off""" 4 +.el .IP \f(CWoff\fR 4 +.IX Item "off" +Disable the comparison of experiments. This is the default. +.ie n .IP """delta""" 4 +.el .IP \f(CWdelta\fR 4 +.IX Item "delta" +Print the values for the reference experiment. The results for the other +experiments are shown as a delta relative to the reference (current-reference). +.ie n .IP """ratio""" 4 +.el .IP \f(CWratio\fR 4 +.IX Item "ratio" +Print the values for the reference experiment. The results for the other +experiments are shown as a ratio relative to the reference (current/reference). +.RE +.RS 4 +.RE +.ie n .IP """disasm \fIfunction\-name\fR""" 4 +.el .IP "\f(CWdisasm \fR\f(CIfunction\-name\fR\f(CW\fR" 4 +.IX Item "disasm function-name" +List the source code and instructions for the function specified. The +instructions are annotated with the metrics used. +.ie n .IP """fsingle \fIfunction\-name\fR [\fBn\fR]""" 4 +.el .IP "\f(CWfsingle \fR\f(CIfunction\-name\fR\f(CW [\fR\f(CBn\fR\f(CW]\fR" 4 +.IX Item "fsingle function-name [n]" +Write a summary panel for the specified function. The optional parameter +\&\fIn\fR is needed for those cases where several functions have the same name. +.ie n .IP """fsummary""" 4 +.el .IP \f(CWfsummary\fR 4 +.IX Item "fsummary" +Write a summary panel for each function in the function list. +.ie n .IP """functions""" 4 +.el .IP \f(CWfunctions\fR 4 +.IX Item "functions" +Display a list of all functions executed. For each function the used metrics +(e.g. the CPU time) are shown. +.ie n .IP """header""" 4 +.el .IP \f(CWheader\fR 4 +.IX Item "header" +Shows several operational characteristics of the experiment(s) specified +on the command line. +.ie n .IP """limit \fIn\fR""" 4 +.el .IP "\f(CWlimit \fR\f(CIn\fR\f(CW\fR" 4 +.IX Item "limit n" +Limit the output to \fIn\fR lines. +.ie n .IP """lines""" 4 +.el .IP \f(CWlines\fR 4 +.IX Item "lines" +Write a list of source lines and their metrics, ordered by the current +sort metric. +.ie n .IP """metric_list""" 4 +.el .IP \f(CWmetric_list\fR 4 +.IX Item "metric_list" +Display the currently selected metrics in the function view and a list +of all the metrics available for the target experiment(s). +.ie n .IP """metrics \fImetric\-spec\fR""" 4 +.el .IP "\f(CWmetrics \fR\f(CImetric\-spec\fR\f(CW\fR" 4 +.IX Item "metrics metric-spec" +Define the metrics to be displayed in the function and callers-callees +overviews. +.Sp +The \fImetric-spec\fR can either be the keyword \fBdefault\fR +to restore the default metrics selection, or a colon separated list +with metrics. +.Sp +A special metric is \f(CW\*(C`hwc\*(C'\fR. It automatically expands to the active +set of hardware event counters used in the experiment(s). +.Sp +If both instructions and clock cycles have been measured, the \f(CW\*(C`CPI\*(C'\fR +and \f(CW\*(C`IPC\*(C'\fR metrics can be used to see the Clockcycles Per Instruction +and Instructions Per Clockcyle values, respectively. +.Sp +The gprofng user guide has more details how to define metrics. +.ie n .IP """name {short | long | mangled}[:{soname | nosoname}]""" 4 +.el .IP "\f(CWname {short | long | mangled}[:{soname | nosoname}]\fR" 4 +.IX Item "name {short | long | mangled}[:{soname | nosoname}]" +Specify whether to use the short, long, or mangled form of function names. +Optionally, the load object that the function is part of can be included in +the output by adding the \fIsoname\fR keyword. It can also be ommitted +(\fInosoname\fR), which is the default. +.Sp +Whether there is an actual difference between these types of names depends +on the language. +.Sp +Note that there should be no (white)space to the left and right of the +colon (\fB:\fR). +.Sp +This option should not be confused with the keyword \fBname\fR in a +metric definition, which is used to specify that the names of functions +should be shown in the function overview. +.ie n .IP """overview""" 4 +.el .IP \f(CWoverview\fR 4 +.IX Item "overview" +Shows a summary of the recorded performance data for the experiment(s) +specified on the command line. +.ie n .IP """pcs""" 4 +.el .IP \f(CWpcs\fR 4 +.IX Item "pcs" +Write a list of program counters (PCs) and their metrics, ordered by +the current sort metric. +.ie n .IP """sort \fImetric\-spec\fR""" 4 +.el .IP "\f(CWsort \fR\f(CImetric\-spec\fR\f(CW\fR" 4 +.IX Item "sort metric-spec" +Sort the function list on the \fImetric-spec\fR given. +.Sp +\&\f(CW@IndexSubentry\fR{Sort, Reverse order} +The data can be sorted in reverse order by prepending the metric definition +with a minus (\fB\-\fR) sign. +.Sp +For example \fBsort \-e.totalcpu\fR. +.Sp +\&\f(CW@IndexSubentry\fR{Sort, Reset to default} +A default metric for the sort operation has been defined and since this is +a persistent command, this default can be restored with \f(CW\*(C`default\*(C'\fR as +the key (\fBsort default\fR). +.ie n .IP """source \fIfunction\-name\fR""" 4 +.el .IP "\f(CWsource \fR\f(CIfunction\-name\fR\f(CW\fR" 4 +.IX Item "source function-name" +List the source code for the function specified, annotated with the metrics +used. +.ie n .IP """viewmode {user | expert | machine}""" 4 +.el .IP "\f(CWviewmode {user | expert | machine}\fR" 4 +.IX Item "viewmode {user | expert | machine}" +This command is only relevant for Java programs. For all other languages +supported, the viewmode setting has no effect. +.Sp +The following options are supported: +.RS 4 +.ie n .IP """user""" 4 +.el .IP \f(CWuser\fR 4 +.IX Item "user" +Show the Java call stacks for Java threads, but do not show housekeeping +threads. The function view includes a function called \fB<JVM\-System>\fR. +This represents the aggregated time from non-Java threads. +In case the JVM software does not report a Java call stack, time is reported +against the function \fB<no Java callstack recorded>\fR. +.ie n .IP """expert""" 4 +.el .IP \f(CWexpert\fR 4 +.IX Item "expert" +Show the Java call stacks for Java threads when the user Java code is executed, +and machine call stacks when JVM code is executed, or when the JVM software +does not report a Java call stack. Show the machine call stacks for +housekeeping threads. +.ie n .IP """machine""" 4 +.el .IP \f(CWmachine\fR 4 +.IX Item "machine" +Show the actual native call stacks for all threads. This is the view mode +for C, C++, and Fortran. +.RE +.RS 4 +.RE +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBgprofng\fR\|(1), +\&\fBgp\-archive\fR\|(1), +\&\fBgp\-collect\-app\fR\|(1), +\&\fBgp\-display\-gui\fR\|(1), +\&\fBgp\-display\-html\fR\|(1), +\&\fBgp\-display\-src\fR\|(1) +.PP +The user guide for gprofng is maintained as a Texinfo manual. If the +\&\fBinfo\fR and \fBgprofng\fR programs are correctly installed, the +command \fBinfo gprofng\fR should give access to this document. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 2022\-2024 Free Software Foundation, Inc. +.PP +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 no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". |