vasilito
ff4ff35918
Red Bear OS is a full fork. All sources must be available from git clone with zero network access. Removed gitignore rules that excluded fetched source trees under recipes/*/source/, local/recipes/kde/*/source/, local/recipes/qt/*/source/, and vendor source trees. Build artifacts (target/, build/, source.tar, *.o, *.so) remain excluded. 127291 files added — kernel, relibc, base, bootloader, pkgar, all KDE/Qt frameworks, mesa, wayland, DRM drivers, and every other recipe source.
320 lines
12 KiB
Groff
320 lines
12 KiB
Groff
.\" -*- mode: troff; coding: utf-8 -*-
|
|
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45)
|
|
.\"
|
|
.\" 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-08-17 binutils-2.43.0 "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".
|