yggdrasil/binutils-gdb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

gprofng: updated man pages and user guide

Browse Source 
This is a major update of all the man pages.  Bugs 30679 and 30895 are
addressed.  In addition to fixes for typos, the texts have been expanded
and clarified, and line lengths no longer extend beyond column 79.  In
case of gp-display-html, the new option syntax is documented. The user
guide has a new section on the gprofng GUI.

gprofng/ChangeLog
2023-11-28  Ruud van der Pas  <ruud.vanderpas@oracle.com>

	PR 30679
	PR 30895
	* doc/gp-archive.texi: Expand the description of the options.
	* doc/gp-collect-app.texi: Fix various typos and textual improvements.
	* doc/gp-display-html.texi: Cover the new GNU long option syntax.
	* doc/gp-display-src.texi: Fix various typos and textual improvements.
	* doc/gp-display-text.texi: Fix typos fixed and textual improvements.
	* doc/gp-macros.texi: Fix a bug in the vspace macro and add new macro.
	* doc/gprofng.texi: Cover the GPROFNG_SYSCONFDIR environment variable.
	* doc/gprofng_ug.texi: Fix various typos and textual improvements.
	* doc/version.texi: Adapt the date and version number.
This commit is contained in:
Vladimir Mezentsev 2023-11-27 12:32:09 -08:00
parent 35efddd5a1
commit 46c5675798
9 changed files with 636 additions and 269 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

260
gprofng/doc/gp-archive.texi
View File

@ -1,11 +1,11 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app man page.
@c This is the Texinfo source file for the gp-archive man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng archive
@setfilename gp-archive
@settitle Archive gprofng experiment data
@include gp-macros.texi
@end ifset
@ -54,7 +54,8 @@
@ManPageStart{NAME}
@c man begin NAME
gprofng archive - Archive gprofng experiment data
gp-archive - Archive the associated application binaries and sources for a
gprofng experiment
@c man end
@ManPageEnd{}
@ -81,9 +82,12 @@ gprofng archive - Archive gprofng experiment data
Archive the associated application binaries and source files in a gprofng
experiment to make it self contained and portable.
By default, the binaries are archived, but the application source files
are not archived. Use this tool to change this and afterwards archive
additional components.
By default, the binaries are archived as part of the data collection, but the
application source files are not archived. Use this tool to change this and
afterwards archive additional components.
This tool has to be executed on the same system where the profiling data was
recorded.
@c man end
@ManPageEnd{}
@ -111,34 +115,39 @@ Print the version number and exit.
Print usage information and exit.
@c -- @item --verbose @{on|off@}
@c -- @ifclear man
@c -- @IndexSubentry{Options, @code{--verbose}}
@c -- @end ifclear
@c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
@item -a @{off|on|ldobjects|src|usedldobjects|usedsrc@}
@item -a @{off | on | ldobjects | src | usedldobjects | used[src]@}
@ifclear man
@IndexSubentry{Options, @code{-a}}
@end ifclear
Specify archiving of binaries and other files. In addition to disable this
feature (off), or enable archiving off all loadobjects and sources (on),
the other op tions support a more refined selection.
feature (@samp{off}), or enable archiving of all loadobjects and sources
(@samp{on}), the other choices support a more refined selection.
All of these options enable archiving, but the keyword controls what exactly
is selected: all load objects (ldobjects), all source files (src), the
loadobjects asscoiated with a program counter (usedldobjects), or the source
files associated with a program counter (usedsrc).
The default is @samp{-a ldobjects}.
All of these choices enable archiving, but the keyword controls what exactly
is selected: all load objects (@samp{ldobjects}), all source files
(@samp{src}), the loadobjects associated with a program counter
(@samp{usedldobjects}), or the source files associated with a program counter
(@samp{used[src]}). The default is @samp{-a ldobjects}.
@item -n
@item -d @var{path}
@ifclear man
@IndexSubentry{Options, @code{-n}}
@IndexSubentry{Options, @code{-d}}
@end ifclear
Archive the named experiment only, not any of its descendants.
The @var{path} is the absolute path to a common archive, which is a
directory that contains archived files. If the directory does not
exist, then it will be created. Files are saved in the common archive
directory, and a symbolic link is created in the experiment archive.
@item -F
@ifclear man
@IndexSubentry{Options, @code{-F}}
@end ifclear
Force writing, or rewriting of .archive files. All archived files will be
removed and recreated, except if the @samp{-n} or @samp{-m} option is used,
or if the experiment is a subexperiment.
@item -m @var{regex}
@ifclear man
@ -148,32 +157,67 @@ Archive the named experiment only, not any of its descendants.
Archive only those source, object, and debug info files whose full path name
matches the given POSIX compliant @var{regex} regular expression.
@item -n
@ifclear man
@IndexSubentry{Options, @code{-n}}
@end ifclear
Archive the named experiment only, not any of its descendants.
@item -q
@ifclear man
@IndexSubentry{Options, @code{-q}}
@end ifclear
Do not write any warnings to stderr. Warnings are incorporated into the
.archive file in the experiment directory. They are shown in the output
of @command{gprofng display text}.
Do not write any warnings to @file{stderr}. Warnings are incorporated into
the .archive file in the experiment directory. They are shown in the output
of the @command{gprofng display text} command.
@item -F
@item -r @var{path}
@ifclear man
@IndexSubentry{Options, @code{-F}}
@IndexSubentry{Options, @code{-r}}
@end ifclear
Force writing or rewriting of the archive. This is ignored with the
@samp{-n} or @samp{-m} option, or if this is a subexperiment.
This option specifies the location of a common archive. The value is the
relative path to a common archive, which is a directory that contains
archived files.
If the directory does not exist, then it will be created. Files are saved
in the common archive directory, and a symbolic link is created in the
experiment archive.
@item -d @var{path}
@item -s @var{selection}
@ifclear man
@IndexSubentry{Options, @code{-d}}
@IndexSubentry{Options, @code{-s}}
@end ifclear
The @var{path} is the absolute path path to a common archive, which is a
directory that contains archived files. If the directory does not
exist, then it will be created. Files are saved in the common archive
directory, and a symbolic link is created in the experiment archive.
Specify archiving of source files. The allowed values for @var{selection} are:
@table @gcctabopt
@item no
Do not archive any source files.
@item all
Archive all source and object files that can be found.
@item used[src]
Archive source and object files for functions against which data was
recorded in the experiment, and that can be found.
@end table
By default, application source files are not archived into the experiment.
If the @samp{-s all}, or @samp{-s used} option is used, sources and object
files are archived.
These options also ensure that source files are available in the experiment,
even if the original source files have been modified, or are inaccessible
afterwards.
In case archive files cannot be found, use the @samp{addpath}, or
@samp{pathmap} command, or both, in an @file{.er.rc} file to specify the
location of the missing file(s).
@end table
@ -187,17 +231,130 @@ directory, and a symbolic link is created in the experiment archive.
@ManPageStart{NOTES}
@c man begin NOTES
Default archiving does not occur in case the application profiled terminates
prematurely, or if archiving is disabled when collecting the performance data.
In such cases, this tool can be used to afterwards archive the information,
but it has to be run on the same system where the profiling data was recorded.
@itemize @minus
@c ----------------------------------------------------------------------------
@item
Archiving of application binaries -
By default, binaries are archived automatically when an experiment is
created. However, archiving does not occur in one or more of the
following circumstances:
@itemize @bullet
@item
If the profiled application is terminated before it exits normally.
@item
If a running process is profiled.
@item
If archiving is explicitly disabled when profiling. For example by using
the @samp{-a off} option on @command{gprofng collect app}.
@end itemize
In these cases, @command{gprofng archive} must be run manually and on the same
machine where the profiling data was recorded.
Archiving of experiment data during the data collection process can be quite
expensive. Especially if the experiment has many descendant processes.
@ifclear man
@IndexSubentry{Options, @code{-a}}
@end ifclear
In such cases, a more efficient strategy is to use the @samp{-a off} option
when collecting the data. Once the collection has completed, the data can be
@ifclear man
@IndexSubentry{Options, @code{-s}}
@end ifclear
archived using the @samp{-s all} option. This saves all executables and
source files in the experiment.
If during the archiving there is an error message that an executable, or
@ifclear man
@IndexSubentry{Commands, @code{addpath}}
@end ifclear
source file cannot be found, the @samp{addpath} command to add the path
to the missing file(s) can be included in the @file{.er.rc} file.
After this command has been added, archive the experiment again. The
archiving archiving can be repeated as many times as necessary to archive all
files.
Archiving should be done on the same system as was used to collect the
experiment. If some files cannot be accessed from this system (e.g. sources
or object files), then additional archiving can be done using another system
that can access them. For example, the system where the application was built.
Some Java applications store shared objects in jar files. By default, such
shared objects are not automatically archived. To archive shared objects
contained in jar files, the addpath directive in an .er.rc file. The addpath
directive should give the path to the jar file, including the jar file itself.
The .er.rc file should be saved in the user home directory or parent of the
experiment directory.
contained in jar files, make sure to include the @samp{addpath} command in
an @file{.er.rc} file.
The @samp{addpath} command should give the path to the jar file, including
the jar file itself. The @file{.er.rc} file should be saved in the user home
directory, or experiment parent directory.
@item
Archiving of application sources -
By default, application source files are not archived in the experiment.
Execute the @command{gprofng archive} command with the @samp{-s all}, or
@samp{-s used} option on each experiment to store source files in the
experiment.
@item
Automatic archiving of application sources -
Environment variable @samp{GPROFNG_ARCHIVE} may be set to automatically
archive sources when the experiment has completed. This environment
variable can contain @samp{-s} and @samp{-m} arguments, as pairs of
argument and options, separated by one or more blanks.
@ifclear man
@IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE}}
@IndexSubentry{Options, @code{-a}}
@IndexSubentry{Options, @code{-m}}
@IndexSubentry{Options, @code{-s}}
@end ifclear
If more than one @samp{-s} argument appears on the command line, the
last one prevails. If @samp{-s} is both passed on the command line, and
set by the environment variable, the option from the environment variable
prevails.
Note that in case automatic source archiving during data collection has
been enabled using either the @samp{GPROFNG_ARCHIVE} variable, or the
@samp{-a src}, or @samp{-a usedsrc} option, it is recommended to confirm that
source files have been correctly resolved by executing the
@command{gprofng archive -s all}, or @command{gprofng archive -s used}
command.
@item
The @samp{-d} and @samp{-r} options are mutually exclusive.
@ifclear man
@IndexSubentry{Options, @code{-d}}
@IndexSubentry{Options, @code{-r}}
@end ifclear
@item
When using the @samp{-d} or @samp{-r} option, environment variable
@ifclear man
@IndexSubentry{Options, @code{-d}}
@IndexSubentry{Options, @code{-r}}
@IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE_COMMON_DIR}}
@end ifclear
@samp{GPROFNG_ARCHIVE_COMMON_DIR} can be used to specify the location of
the common archive. This can be very convenient when using a script to
profile applications.
@item
If more than one @samp{-s} option is given on the command line, or
specified in the environment variable, the specified option for all must
be the same. If not, @command{gprofng archive} exits with an error.
@item
This tool does not work on experiments recorded with earlier versions of
the tools. If invoked on such experiments, a warning is printed. Use the
version of @command{gprofng archive} from the same release with which the
experiment was recorded.
@end itemize
@c man end
@ManPageEnd{}
@ -206,10 +363,19 @@ experiment directory.
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@ManPageStart{SEE ALSO}
@c man begin SEEALSO
gprofng(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1), gp-display-text(1)
gprofng(1),
gp-collect-app(1),
gp-display-gui(1),
gp-display-html(1),
gp-display-src(1),
gp-display-text(1)
@iftex
@vspace{1}
@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the info
and gprofng programs are correctly installed, the command

115
gprofng/doc/gp-collect-app.texi
View File

@ -5,7 +5,7 @@
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng collect app
@setfilename gp-collect-app
@settitle Collect performance data for the target application
@include gp-macros.texi
@end ifset
@ -54,7 +54,7 @@
@ManPageStart{NAME}
@c man begin NAME
gprofng collect app - Collect performance data for the target program
gp-collect-app - Collect performance data for the target program
@c man end
@ManPageEnd{}
@ -66,7 +66,8 @@ gprofng collect app - Collect performance data for the target program
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
@command{gprofng collect app} [@var{option(s)}] @var{target} [@var{option(s)}]
@command{gprofng collect app} [@var{option(s)}] @var{target}
[@var{target-option(s)}]
@c man end
@ManPageEnd{}
@ -79,7 +80,8 @@ gprofng collect app - Collect performance data for the target program
@c man begin DESCRIPTION
Collect performance data on the target program. In addition to Program Counter
(PC) sampling, hardware event counters and various tracing options are supported.
(PC) sampling, hardware event counters and various tracing options are
supported.
For example, this command collects performance data for an executable called
@samp{a.out} and stores the data collected in an experiment directory with
@ -115,28 +117,29 @@ Print the version number and exit.
Print usage information and exit.
@c -- @item --verbose @{on|off@}
@c -- @ifclear man
@c -- @IndexSubentry{Options, @code{--verbose}}
@c -- @end ifclear
@item -v, --verbose
@ifclear man
@IndexSubentry{Options, @code{-v}}
@IndexSubentry{Options, @code{--verbose}}
@end ifclear
@c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
By default, verbose mode is disabled. This option enables it.
@item -p @{off|on|lo|hi|@var{<value>}@}
@item -p @{off | on | lo[w] | hi[gh] | @var{<value>}@}
@ifclear man
@IndexSubentry{Options, @code{-p}}
@end ifclear
Disable (off) or enable (on) clock-profiling using a default sampling
granularity, or enable clock-profiling implicitly by setting the sampling
granularity (lo, hi, or a specific value in ms). By default, clock profiling
is enabled (@samp{-p on}).
Disable (@samp{off}) or enable (@samp{on}) clock profiling using a default
sampling granularity, or enable clock profiling implicitly by setting the
sampling granularity (@samp{lo[w]}, @samp{hi[gh]}, or a specific value in
ms). By default, clock profiling is enabled (@samp{-p on}).
@item -h @var{@{<ctr_def>...,<ctr_n_def>@}}
@item -h @var{<ctr_def>[,<ctr_def>]}
@ifclear man
@IndexSubentry{Options, @code{-h}}
@end ifclear
Enable hardware event counter profiling and select the counter(s).
Enable hardware event counter profiling and select one or more counter(s).
To see the supported counters on this system, use the @samp{-h} option
without other arguments.
@ -147,6 +150,7 @@ without other arguments.
Specify the name for the experiment directory. The name has to end with
@samp{.er} and may contain an absolute path (e.g. @file{/tmp/experiment.er}).
An existing experiment with the same name will not be overwritten.
@item -O @var{<exp_name>}
@ifclear man
@ -164,41 +168,46 @@ overwrites an existing experiment directory with the same name.
Add up to 10 comment strings to the experiment. These comments appear in the
notes section of the header and can be retrieved with the
@command{gprofng display text} command using the @samp{-header} option.
@ifclear man
@IndexSubentry{Options, @code{-header}}
@IndexSubentry{Commands, @code{-header}}
@end ifclear
@item -j @{on|off|@var{<path>}@}
@item -j @{on | off | @var{<path>}@}
@ifclear man
@IndexSubentry{Options, @code{-j}}
@end ifclear
Controls Java profiling when the target is a JVM machine. The allowed values of
this option are: enable (on), disable (off) Java profiling when the target
program is a JVM, or set @samp{<path>} to a non-default JVM.
The default is @samp{-j on}
Controls Java profiling when the target is a JVM machine. The allowed values
for this option are:
@table @gcctabopt
@item on
Record profiling data for the JVM machine, and recognize methods compiled by
the Java HotSpot virtual machine. Also record Java call stacks. The default
is @samp{-j on}.
the Java HotSpot virtual machine. Also record Java call stacks.
@item off
Does not record Java profiling data. Profiling data for native call stacks is
Do not record Java profiling data. Profiling data for native call stacks is
still recorded.
@item @var{<path>}
Records profiling data for the JVM, and use the JVM as installed in @var{<path>}.
Records profiling data for the JVM, and use the JVM as installed in
@var{<path>}.
@end table
@item -J @var{<jvm-options>}
The default is @samp{-j on}.
@item -J @var{<jvm-option(s)>}
@ifclear man
@IndexSubentry{Options, @code{-J}}
@end ifclear
Specifies additional options to be passed to the JVM used. The
@var{jvm-options} list must be enclosed in quotation marks if it contains more
than one option. The items in the list need to be separated by spaces or tab.
Specifies one or more additional options to be passed to the JVM used. The
@var{jvm-option(s)} list must be enclosed in quotation marks if it contains
more than one option. The items in the list need to be separated by spaces
or tabs.
Each item is passed as a separate option to the JVM. Note that this option
implies @samp{-j on}.
@ -211,11 +220,12 @@ Collects data for the specified duration. The duration can be a single number,
optionally followed by either @samp{m} to specify minutes, or @samp{s} to
specify seconds, which is the default.
The duration can also two numbers separated by minus (-) sign. If a single
number is given, data is collected from the start of the run until the given
time. If two numbers are given, data is collected from the first time to the
second. If the second time is zero, data is collected until the end of the
run. If two non-zero numbers are given, the first must be less than the second.
The duration can also consists of two numbers separated by a minus (@minus{})
sign. If a single number is given, data is collected from the start of the run
until the given time.
If two numbers are given, data is collected from the first time to the second.
In case the second time is zero, data is collected until the end of the run.
If two non-zero numbers are given, the first must be less than the second.
@item -n
@ifclear man
@ -243,8 +253,8 @@ enclose the @var{regex} in single quotes. The default is @samp{-F on}.
@end ifclear
Specify archiving of binaries and other files. In addition to disable this
feature (off), or enable archiving off all loadobjects and sources (on),
the other op tions support a more refined selection.
feature (@samp{off}), or enable archiving off all loadobjects and sources
(@samp{on}), the other options support a more refined selection.
All of these options enable archiving, but the keyword controls what exactly
is selected: all load objects (ldobjects), all source files (src), the
@ -257,9 +267,9 @@ The default is @samp{-a ldobjects}.
@IndexSubentry{Options, @code{-S}}
@end ifclear
Disable (off), or enable (on) periodic sampling of process-wide resource
utilization. By default, sampling occurs every second. Use the @var{<seconds>}
option to change this. The default is @samp{-S on}.
Disable (off), or enable (on) periodic sampling of process-wide
resource utilization. By default, sampling occurs every second. Use the
@var{<seconds>} option to change this. The default is @samp{-S on}.
@item -y @var{<signal>}[,r]
@ifclear man
@ -267,11 +277,11 @@ option to change this. The default is @samp{-S on}.
@end ifclear
Controls recording of data with the signal named @var{<signal>}, referred to
as the pause-resume signal. Whenever the given signal is delivered to the
as the pause-resume signal. Whenever the given signal is delivered to the
process, switch between paused (no data is recorded) and resumed (data is
recorded) states.
By default, data collection begins in the paused state. If the optional
By default, data collection begins in the paused state. If the optional
@samp{r} is given, data collection begins in the resumed state and data
collection begins immediately.
@ -283,8 +293,9 @@ not used by the target can be used.
@IndexSubentry{Options, @code{-l}}
@end ifclear
Specify a signal that will trigger a sample of process-wide resource utilization.
When the named @var{<signal>} is delivered to the process, a sample is recorded.
Specify a signal that will trigger a sample of process-wide resource
utilization. When the named @var{<signal>} is delivered to the process,
a sample is recorded.
The signal can be specified using the full name, without the initial
letters @code{SIG}, or the signal number. Note that the @command{kill}
@ -299,9 +310,10 @@ different.
@end ifclear
Enable synchronization wait tracing, where @var{<option>} is used to define the
specifics of the tracing (on, off, @var{<threshold>}, or all). The API is
specifics of the tracing (on, off, @var{<threshold>}, or all). The API is
selected through the setting for @var{<API>}: @samp{n} selects native/Pthreads,
@samp{j} selects Java, and @samp{nj} selects both. The default is @samp{-s off}.
@samp{j} selects Java, and @samp{nj} selects both. The default is
@samp{-s off}.
@item -H @{off|on@}
@ifclear man
@ -340,10 +352,19 @@ gprofng can provide more details, but this is not a requirement.
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@ManPageStart{SEE ALSO}
@c man begin SEEALSO
gprofng(1), gp-archive(1), gp-display-html(1), gp-display-src(1), gp-display-text(1)
gprofng(1),
gp-archive(1),
gp-display-gui(1),
gp-display-html(1),
gp-display-src(1),
gp-display-text(1)
@iftex
@vspace{1}
@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the

154
gprofng/doc/gp-display-html.texi
View File

@ -1,11 +1,11 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app man page.
@c This is the Texinfo source file for the gp-display-html man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng display html
@setfilename gp-display-html
@settitle Generate an HTML based directory structure to browse the profiles
@include gp-macros.texi
@end ifset
@ -54,7 +54,8 @@
@ManPageStart{NAME}
@c man begin NAME
gprofng display html - Generate an HTML based directory structure to browse the profiles
gp-display-html - Generate an HTML based directory structure to browse the
profiles
@c man end
@ManPageEnd{}
@ -107,85 +108,87 @@ Print the version number and exit.
Print usage information and exit.
@item --verbose @{on|off@}
@item --verbose
@ifclear man
@IndexSubentry{Options, @code{--verbose}}
@end ifclear
Enable (@samp{on}) or disable (@samp{off)} verbose mode.
The default is @samp{off}.
Enable verbose mode to show diagnostic messages about the processing of the
data. By default verbose mode is disabled.
@item --debug @{on|s|m|l|xl|off@}
@item -d @{on|s|m|l|xl|off@}
@item -d [@var{db-vol-size}], --debug[=@var{db-vol-size}]
@ifclear man
@IndexSubentry{Options, @code{-d}}
@IndexSubentry{Options, @code{--debug}}
@end ifclear
Control the printing of run time information to assist with troubleshooting,
or further development of this tool. The keyword is case insensitive.
A setting of @samp{on} gives a modest amount of information. The keywords
@samp{s}, @samp{m}, @samp{l}, and @samp{xl} give an increasing amount of
information, while @samp{off} disables the printing of debug information.
This is also the default.
Control the printing of run time debug information to assist with the
troubleshooting, or further development of this tool.
Note that currently @samp{on}, @samp{s}, @samp{m}, and @samp{l} are
equivalent. This is expected to change in future updates.
The @var{db-vol-size} parameter controls the output volume and is one from
the list @samp{s}, @samp{S}, @samp{m}, @samp{M}, @samp{l}, @samp{L}, @samp{xl},
or @samp{XL}. If @var{db-vol-size} is not set, a modest amount of information
is printed. This is equivalent to select @samp{s}, or @samp{S}. The volume
of data goes up as the size increases. Note that currently @samp{l/L} is
equivalent to @samp{xl/XL}, but this is expected to change in future updates.
By default debug mode is disabled.
@item ---highlight-percentage @var{value}
@item -hp @var{value}
@item --highlight-percentage=@var{value}
@ifclear man
@IndexSubentry{Options, @code{--highlight-percentage}}
@IndexSubentry{Options, @code{-hp}}
@end ifclear
Set a percentage value in the interval [0,100] to select and color code source
lines, as well as instructions, that are within this percentage of the maximum
metric value(s). The default is 90 (%).
metric value(s). The default is 90 (%). A value of zero disables this
feature.
A value of zero @samp{(-hp 0)} disables this feature.
@item --output @var{dirname}
@item -o @var{dirname}
@item -o @var{dirname}, --output=@var{dirname}
@ifclear man
@IndexSubentry{Options, @code{--output}}
@IndexSubentry{Options, @code{-o}}
@IndexSubentry{Options, @code{--output}}
@end ifclear
Use @var{dirname} as the directory name to store the HTML files in.
The default name is @samp{display.<n>.html} with @var{<n>} the first
positive integer number not in use. An existing directory with the
same name is not overwritten.
Use @var{dirname} as the directory name to store the results in. In
absence of this option, the default name is @samp{display.<n>.html}.
This directory is created in the current directory.
The number @var{<n>} is the first positive integer number not in use in
this naming scheme. An existing directory with the same name is not
overwritten.
In case the directory exists already, an error message is printed and
the tool terminates.
@item --overwrite @var{dirname}
@item -O @var{dirname}
@item -O @var{dirname}, --overwrite=@var{dirname}
@ifclear man
@IndexSubentry{Options, @code{--overwrite}}
@IndexSubentry{Options, @code{-O}}
@IndexSubentry{Options, @code{--overwrite}}
@end ifclear
Use @var{dirname} as the directory name to store the HTML files in.
Use @var{dirname} as the directory name to store the results in. In
absence of this option, the default name is @samp{display.<n>.html}.
This directory is created in the current directory.
The number @var{<n>} is the first positive integer number not in use in
this naming scheme. An existing directory with the same name is silently
overwritten.
@item --quiet @{on|off@}
@item -q @{on|off@}
@item -q, --quiet
@ifclear man
@IndexSubentry{Options, @code{--quiet}}
@IndexSubentry{Options, @code{-q}}
@IndexSubentry{Options, @code{--quiet}}
@end ifclear
Control the display of all warning, debug and verbose messages.
If set to @samp{on}, the settings for verbose, warnings and debug are ignored.
By default the quiet mode is disabled (@samp{-q off}).
Disable the display of all warning, debug, verbose and any other messages.
If enabled, the settings for verbose and debug are accepted, but ignored.
With this option, there is no screen output, other than errors. By default
quiet mode is disabled.
@item --warnings @{on|off@}
@item -w @{on|off@}
@item --nowarnings
@ifclear man
@IndexSubentry{Options, @code{--warnings}}
@IndexSubentry{Options, @code{-w}}
@IndexSubentry{Options, @code{--nowarnings}}
@end ifclear
Enable (@samp{on}), or disable (@samp{off}) run time warning messages from
the tool. By default these are enabled.
Disable the printing of warning messages on stdout. By default warning
messages are printed.
@end table
@ -199,11 +202,51 @@ the tool. By default these are enabled.
@ManPageStart{NOTES}
@c man begin NOTES
When setting a directory name for the HTML files to be stored in, make sure that
umask is set to the correct access permissions.
@itemize @minus
Regardless of the setting for the warning messages, any warnings are accessible
through the main @file{index.html} page.
@item
The options and values are case sensitive.
@item
In this release, the option syntax has changed to be more compliant with other
tools and commands.
The options that used to have an @samp{on} or @samp{off} value only, now act
as a switch. The option negates the default setting. For example, by
default, verbose mode is disabled. It is enabled by using the
@samp{--verbose} option.
The long options, those starting with @code{--}, that require a value, expect
the @code{=} sign between the option and the value.
While the previous syntax and choices are accepted still, we strongly
recommend to change the usage of the options according to the new syntax
and values. At some point, these legacy settings may no longer be accepted.
To assist with the transition, a warning message is shown if the legacy
syntax, or value, or both, are used.
@item
The @samp{-hp} option is still accepted, but it will be deprecated in a
future release. Use the @samp{--highlight-percentage} option instead.
@item
When setting a directory name for the HTML files to be stored in, make sure
that umask is set to the correct access permissions.
@item
Regardless of the setting for the warning messages, if there are warnings, they
are accessible through the main @file{index.html} page.
@item
The tool tries to accumulate as many warnings and errors as possible, before
taking action. In this way, it is easier to address multiple issues at
once. As a result of this approach, it may be that the messages do not show
immediately. In particular, warnings are shown towards the end of the
execution, but one or more errors will terminate execution before the
processing begins.
@end itemize
@c man end
@ManPageEnd{}
@ -212,10 +255,19 @@ through the main @file{index.html} page.
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@ManPageStart{SEE ALSO}
@c man begin SEEALSO
gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-src(1), gp-display-text(1)
gprofng(1),
gp-archive(1),
gp-collect-app(1),
gp-display-gui(1),
gp-display-src(1),
gp-display-text(1)
@iftex
@vspace{1}
@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the

65
gprofng/doc/gp-display-src.texi
View File

@ -1,12 +1,12 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app man page.
@c This is the Texinfo source file for the gp-display-src man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng display src
@settitle Display the source code, optionally interleaved with the disassembly of the target object
@setfilename gp-display-src
@settitle Display source code and optionally disassembly of the target object
@include gp-macros.texi
@end ifset
@ -54,7 +54,8 @@
@ManPageStart{NAME}
@c man begin NAME
gprofng display src - Display the source code, optionally interleaved with the disassembly of the target object
gp-display-src - Display the source code, optionally interleaved with the
disassembly of the target object
@c man end
@ManPageEnd{}
@ -66,7 +67,7 @@ gprofng display src - Display the source code, optionally interleaved with the d
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
@command{gprofng display src} [@var{option(s)}] @var{target_file}
@command{gprofng display src} [@var{option(s)}] @var{target-file}
@c man end
@ManPageEnd{}
@ -78,12 +79,12 @@ gprofng display src - Display the source code, optionally interleaved with the d
@ManPageStart{DESCRIPTION}
@c man begin DESCRIPTION
Display the source code listing, or source code interleaved with disassembly code,
as extracted from the target file (an executable, shared object, object file, or a
Java .class file).
Display the source code listing, or source code interleaved with disassembly
code, as extracted from the target file (an executable, shared object, object
file, or a Java .class file).
For example, this command displays the source code and disassembly listing for a
function called @samp{mxv_core} that is part of object file @samp{mxv.o}:
For example, this command displays the source code and disassembly listing for
a function called @samp{mxv_core} that is part of object file @samp{mxv.o}:
@smallexample
$ gprofng display src -disasm mxv_core mxv.o
@ -96,10 +97,10 @@ use the following command:
$ gprofng display src -disasm all -1 mxv.o
@end smallexample
The @var{target_file} is the name of an executable, a shared object, an object
The @var{target-file} is the name of an executable, a shared object, an object
file (.o), or a Java .class file.
If no options are given, the source code listing of the @var{target_file}
If no options are given, the source code listing of the @var{target-file}
is shown. This is equivalent to @samp{-source all -1}. If this information
is not available, a message to this extent is printed.
@ -129,13 +130,6 @@ Print the version number and exit.
Print usage information and exit.
@c -- @item --verbose @{on|off@}
@c -- @ifclear man
@c -- @IndexSubentry{Options, @code{--verbose}}
@c -- @end ifclear
@c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
@item -functions
@ifclear man
@IndexSubentry{Options, @code{-functions}}
@ -148,29 +142,29 @@ List all the functions from the given object.
@IndexSubentry{Options, @code{-source}}
@IndexSubentry{Commands, @code{source}}
@end ifclear
Show the source code for @var{item} in @var{target_file}. The @var{tag}
Show the source code for @var{item} in @var{target-file}. The @var{tag}
is used to differentiate in case there are multiple occurences with the same
name.
See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
@item -disasm @var{item} @var{tag}
@ifclear man
@IndexSubentry{Options, @code{-disasm}}
@IndexSubentry{Commands, @code{disasm}}
@end ifclear
Include the disassembly in the source listing. The default listing does not
include the disassembly. If the source code is not available, show a listing
Include the disassembly in the source listing. The default listing does not
include the disassembly. If the source code is not available, show a listing
of the disassembly only.
See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
@item -outfile @var{filename}
@ifclear man
@IndexSubentry{Options, @code{-outfile}}
@IndexSubentry{Commands, @code{outfile}}
@end ifclear
Write results to file @var{filename}. A dash (-) writes to stdout. This is also
the default. Note that this option only affects those options included to the
right of this option.
Write results to file @var{filename}. A dash (@minus{}) writes to stdout.
This is also the default. Note that this option only affects those options
included to the right of the option.
@end table
@ -188,7 +182,7 @@ Use @var{item} to specify the name of a function, or of a source or object
file that was used to build the executable, or shared object.
The @var{tag} is an index used to determine which item is being referred
to when multiple functions have the same name. It is required, but will
to when multiple functions have the same name. It is required, but will
be ignored if not necessary to resolve the function.
The @var{item} may also be specified in the form @samp{function`file`}, in
@ -197,7 +191,7 @@ context of the named file will be used.
The special @var{item} and @var{tag} combination @samp{all -1}, is used to
indicate generating the source, or disassembly, for all functions in the
@var{target_file}.
@var{target-file}.
@c man end
@ManPageEnd{}
@ -206,10 +200,19 @@ indicate generating the source, or disassembly, for all functions in the
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@ManPageStart{SEE ALSO}
@c man begin SEEALSO
gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-html(1), gp-display-text(1)
gprofng(1),
gp-archive(1),
gp-collect-app(1),
gp-display-gui(1),
gp-display-html(1),
gp-display-text(1)
@iftex
@vspace{1}
@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the info
and gprofng programs are correctly installed, the command

71
gprofng/doc/gp-display-text.texi
View File

@ -1,11 +1,11 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app man page.
@c This is the Texinfo source file for the gp-display-text man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng display text
@setfilename gp-display-text
@settitle Display the performance data in plain text format
@include gp-macros.texi
@end ifset
@ -54,7 +54,7 @@
@ManPageStart{NAME}
@c man begin NAME
gprofng display text - Display the performance data in plain text format
gp-display-text - Display the performance data in plain text format
@c man end
@ManPageEnd{}
@ -84,8 +84,8 @@ Print a plain text version of the various displays supported by gprofng.
The input consists of one or more experiment directories. Through commands,
the user controls the output.
There is a rich set of commands to control the display of the data. The
@samp{NOTES} section lists the most common ones. The gprofng user guide
There is a rich set of commands to control the display of the data. The
@samp{NOTES} section lists the most common ones. The gprofng user guide
lists all the commands supported.
Commands specified on the command line need to be prepended with the dash ('-')
@ -107,8 +107,9 @@ Note that the commands are processed and interpreted from left to right,
@emph{so the order matters}.
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 @command{exit} command in the interpreter.
starts in interpreter mode. The user can then issue the commands
interactively. The session is terminated with the @command{exit} command in
the interpreter.
@c man end
@ManPageEnd{}
@ -136,13 +137,6 @@ Print the version number and exit.
Print usage information and exit.
@c -- @item --verbose @{on|off@}
@c -- @ifclear man
@c -- @IndexSubentry{Options, @code{--verbose}}
@c -- @end ifclear
@c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
@item -script @var{script-file}
@ifclear man
@IndexSubentry{Options, @code{-script}}
@ -164,12 +158,12 @@ with commands specified at the command line.
@ManPageStart{NOTES}
@c man begin NOTES
Many commands are supported. Below, the more common ones are listed in
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.
@ifset man
There are many more commands. These are documented in the user guide.
There are many more commands. These are documented in the user guide.
@end ifset
@table @code
@ -198,7 +192,7 @@ metrics at each level.
@IndexSubentry{Options, @code{-compare}}
@IndexSubentry{Commands, @code{compare}}
@end ifclear
By default, the results for multiple experiments are aggregated. This
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:
@ -227,7 +221,7 @@ experiments are shown as a ratio relative to the reference (current/reference).
@IndexSubentry{Options, @code{-disasm}}
@IndexSubentry{Commands, @code{disasm}}
@end ifclear
List the source code and instructions for the function specified. The
List the source code and instructions for the function specified. The
instructions are annotated with the metrics used.
@item fsingle @var{function-name} [@samp{n}]
@ -251,7 +245,7 @@ Write a summary panel for each function in the function list.
@IndexSubentry{Commands, @code{functions}}
@end ifclear
Display a list of all functions executed. For each function the used metrics
(e.g. the CPU time) ar shown.
(e.g. the CPU time) are shown.
@item header
@ifclear man
@ -274,7 +268,7 @@ Limit the output to @var{n} lines.
@IndexSubentry{Commands, @code{lines}}
@end ifclear
Write a list of source lines and their metrics, ordered by the current
sort metric.
sort metric.
@item metric_list
@ifclear man
@ -296,6 +290,20 @@ The @var{metric-spec} can either be the keyword @samp{default}
to restore the default metrics selection, or a colon separated list
with metrics.
@ifclear man
@IndexSubentry{Hardware event counters, @code{hwc} metric}
@end ifclear
A special metric is @code{hwc}. It automatically expands to the active
set of hardware event counters used in the experiment(s).
@ifclear man
@IndexSubentry{Hardware event counters, @code{IPC} metric}
@IndexSubentry{Hardware event counters, @code{CPI} metric}
@end ifclear
If both instructions and clock cycles have been measured, the @code{CPI}
and @code{IPC} metrics can be used to see the Clockcycles Per Instruction
and Instructions Per Clockcyle values, respectively.
The gprofng user guide has more details how to define metrics.
@item name @{short | long | mangled@}[:@{soname | nosoname@}]
@ -311,9 +319,13 @@ the output by adding the @emph{soname} keyword. It can also be ommitted
Whether there is an actual difference between these types of names depends
on the language.
Note that there should be no (white)space to the left and right of the
Note that there should be no (white)space to the left and right of the
colon (@samp{:}).
This option should not be confused with the keyword @samp{name} in a
metric definition, which is used to specify that the names of functions
should be shown in the function overview.
@item overview
@ifclear man
@IndexSubentry{Options, @code{-overview}}
@ -328,14 +340,14 @@ specified on the command line.
@IndexSubentry{Commands, @code{pcs}}
@end ifclear
Write a list of program counters (PCs) and their metrics, ordered by
the current sort metric.
the current sort metric.
@item sort @var{metric-spec}
@ifclear man
@IndexSubentry{Options, @code{-sort}}
@IndexSubentry{Commands, @code{sort}}
@end ifclear
Sort the function list on the @var{metric-spec} given.
Sort the function list on the @var{metric-spec} given.
@IndexSubentry{Sort, Reverse order}
The data can be sorted in reverse order by prepending the metric definition
@ -397,10 +409,19 @@ for C, C++, and Fortran.
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@ManPageStart{SEE ALSO}
@c man begin SEEALSO
gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1)
gprofng(1),
gp-archive(1),
gp-collect-app(1),
gp-display-gui(1),
gp-display-html(1),
gp-display-src(1)
@iftex
@vspace{1}
@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the

6
gprofng/doc/gp-macros.texi
View File

@ -23,6 +23,10 @@
@command{gprofng archive}
@end macro
@macro GUI{}
@command{gprofng display gui}
@end macro
@macro Driver{}
@command{gprofng}
@end macro
@ -41,7 +45,9 @@ gprofng
@end macro
@macro vspace {lines}
@iftex
@sp \lines\
@end iftex
@end macro
@c -- For some reason ending this macro with @noindent does not work out well.

114
gprofng/doc/gprofng.texi
View File

@ -74,7 +74,8 @@ gprofng - The driver for the gprofng application profiling tool
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
@command{gprofng} [@var{option(s)}] @var{action} [@var{qualifier}] [@var{option(s)}] @var{target} [@var{options}]
@command{gprofng} [@var{option(s)}] @var{action} [@var{qualifier}]
[@var{option(s)}] @var{target} [@var{options}]
@c man end
@ManPageEnd{}
@ -86,17 +87,17 @@ gprofng - The driver for the gprofng application profiling tool
@ManPageStart{DESCRIPTION}
@c man begin DESCRIPTION
This is the driver for the gprofng tools suite to gather and analyze performance
data.
This is the driver for the gprofng tools suite to gather and analyze
performance data.
The driver executes the @var{action} specified. An example of an action is
@samp{collect} to collect performance data. Depending on the action, a
The driver executes the @var{action} specified. An example of an action is
@samp{collect} to collect performance data. Depending on the action, a
@var{qualifier} may be needed to further define the command.
The last item is the @var{target} that the command applies to.
There are three places where options are supported. The driver supports
options. These can be found below. The @var{action}, possibly in combination
with the @var{qualifier} also supports options. A description of these can be
with the @var{qualifier} also supports options. A description of these can be
found in the man page for the command. Any options needed to execute the
target command should follow the target name.
@ -108,12 +109,12 @@ the following command may be used:
$ gprofng collect app -o mydata.er a.out -t 2
@end smallexample
In this example, the action is @samp{collect}, the qualifier is @samp{app}, the single
argument to the command is @code{-o mydata.er} and the target is @command{a.out}.
The target command is invoked with the @samp{-t 2} option.
In this example, the action is @samp{collect}, the qualifier is @samp{app},
the single argument to the command is @code{-o mydata.er} and the target is
@command{a.out}. The target command is invoked with the @samp{-t 2} option.
If gprofng is executed without any additional option, action, or target, a usage
overview is printed.
If gprofng is executed without any additional option, action, or target, a
usage overview is printed.
@c man end
@ManPageEnd{}
@ -144,9 +145,9 @@ Print usage information and exit.
@c man end
@ManPageEnd{}
@c -----------------------------------------------------------------------------
@c ----------------------------------------------------------------------------
@c ENVIRONMENT SECTION
@c -----------------------------------------------------------------------------
@c ----------------------------------------------------------------------------
@ManPageStart{ENVIRONMENT}
@c man begin ENVIRONMENT
@ -156,45 +157,94 @@ The following environment variables are supported:
@table @samp
@item @env{GPROFNG_MAX_CALL_STACK_DEPTH}
@ifclear man
@cindex Environment variables
@end ifclear
Set the depth of the call stack (default is 256).
@item @env{GPROFNG_USE_JAVA_OPTIONS}
@ifclear man
@cindex Environment variables
@end ifclear
May be set when profiling a C/C++ application that uses dlopen() to execute
Java code.
@c -- deferred @item @env{GPROFNG_SSH_REMOTE_DISPLAY}
@c -- deferred Use this variable to define the ssh command executed by the remote display tool.
@c -- deferred Use this variable to define the ssh command executed by the
@c -- remote display tool.
@c -- deferred @item @env{GPROFNG_SKIP_VALIDATION}
@c -- deferred Set this variable to disable checking hardware, system, and Java versions.
@c -- deferred Set this variable to disable checking hardware, system, and
@c -- Java versions.
@item @env{GPROFNG_ALLOW_CORE_DUMP}
@ifclear man
@cindex Environment variables
@end ifclear
Set this variable to allow a core file to be generated; otherwise an error
report is created on /tmp.
report is created on @samp{/tmp}.
@item @env{GPROFNG_ARCHIVE}
@ifclear man
@cindex Environment variables
Use this variable to define the settings for automatic archiving upon experiment
recording completion.
@end ifclear
Use this variable to define the settings for automatic archiving upon
experiment recording completion.
@item @env{GPROFNG_ARCHIVE_COMMON_DIR}
@ifclear man
@cindex Environment variables
@end ifclear
Set this variable to the location of the common archive.
@item @env{GPROFNG_JAVA_MAX_CALL_STACK_DEPTH}
@ifclear man
@cindex Environment variables
@end ifclear
Set the depth of the Java call stack; the default is 256; set to 0 to disable
capturing of call stacks.
@item @env{GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH}
@ifclear man
@cindex Environment variables
@end ifclear
Set the depth of the Java native call stack; the default is 256; set to 0 to
disable capturing of call stacks (JNI and assembly call stacks are not
captured).
@item @env{GPROFNG_SYSCONFDIR}
@ifclear man
@cindex Environment variables
@end ifclear
Set the path to the @file{gprofng.rc} configuration file. By default, this
file is placed in the @file{etc} subdirectory of the binutils installation
directory. In case an RPM has been used for the installation, this file is
in directory @file{/etc}.
When building and installing from the source, the user can set the path
to this configuration file to a non-default location. If this is the case,
the user may set the @code{GPROFNG_SYSCONFDIR} environment variable to point
to this location.
Otherwise, the @command{gp-display-text}, @command{gp-display-src}, and
@command{gp-archive} tools cannot find this file.
@end table
@c man end
@ -208,10 +258,14 @@ captured).
@c man begin NOTES
The gprofng driver supports the following commands.
@vspace{1}
@c The man pages for the commands below can be viewed using the command name with "gprofng" replaced by "gp" and the spaces replaced by a dash ("-"). For example the man page
@c name for "gprofng collect app" is "gp-collect-app".
@iftex
@vspace{1}
@end iftex
@c The man pages for the commands below can be viewed using the command name
@c with "gprofng" replaced by "gp" and the spaces replaced by a dash ("-").
@c For example the man page name for "gprofng collect app" is "gp-collect-app".
@i{Collect performance data:}
@ -232,6 +286,10 @@ Display the performance data in ASCII format.
@item gprofng display html
Generate an HTML file from one or more experiments.
@item gprofng display gui
Start the GUI. Note that this tool is not available by default and needs to
be installed seperately.
@end table
@i{Miscellaneous commands:}
@ -257,13 +315,21 @@ use the driver.
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@ManPageStart{SEE ALSO}
@c man begin SEEALSO
gp-archive(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1),
gp-archive(1),
gp-collect-app(1),
gp-display-gui(1),
gp-display-html(1),
gp-display-src(1),
gp-display-text(1)
Each gprofng command also supports the @option{--help} option. This lists the
@iftex
@vspace{1}
@end iftex
Each gprofng command also supports the @option{--help} option. This lists the
options and a short description for each option.
For example this displays the options supported on the

114
gprofng/doc/gprofng_ug.texi
View File

@ -93,16 +93,16 @@ section entitled ``GNU Free Documentation License.''
@c * Archive Experiment Data:: Archive an experiment.
@menu
* Introduction:: About this manual.
* Overview:: A brief overview of @ProductName{}.
* A Mini Tutorial:: A short tutorial covering the key features.
* The gprofng Tools:: An overview of the tools supported.
* Performance Data Collection:: Record the performance information.
* View the Performance Information:: Different ways to view the data.
* Terminology:: Concepts and terminology explained.
* Other Document Formats:: Create this document in other formats.
* The gprofng Man Pages:: The gprofng man pages.
* Index:: The index.
* Introduction:: About this manual.
* Overview:: A brief overview of @ProductName{}.
* A Mini Tutorial:: A short tutorial covering the key features.
* The gprofng Tools:: An overview of the tools supported.
* Performance Data Collection:: Record the performance information.
* View the Performance Information:: Different ways to view the data.
* Terminology:: Concepts and terminology explained.
* Other Document Formats:: Create this document in other formats.
* The gprofng Man Pages:: The gprofng man pages.
* Index:: The index.
@detailmenu
@ -131,6 +131,14 @@ The gprofng Tools
* Filters:: Filters.
* Supported Environment Variables:: The supported environment variables.
Performance Data Collection
* The @command{gprofng collect app} Tool:: Collect application performance data.
View the Performance Information
* The @command{gprofng display text} Tool:: View the performance data in plain text.
Terminology
* The Program Counter:: What is a Program Counter?
@ -139,17 +147,17 @@ Terminology
* The Viewmode:: Select the way call stacks are presented.
* The Selection List:: How to define a selection.
* Load Objects and Functions:: The components in an application.
* The Concept of a CPU in @ProductName{}:: The definition of a CPU.
* The Concept of a CPU in gprofng:: The definition of a CPU.
* Hardware Event Counters Explained:: What are event counters?
* apath:: Our generic definition of a path.
The gprofng Man Pages
* gprofng collect app:: The man page for gprofng collect app.
* gprofng display text:: The man page for gprofng display text.
* gprofng display src:: The man page for gprofng display src.
* gprofng display html:: The man page for gprofng display html.
* gprofng archive:: The man page for gprofng archive.
* Man page for @command{gprofng collect app}:: The man page for gprofng collect app.
* Man page for @command{gprofng display text}:: The man page for gprofng display text.
* Man page for @command{gprofng display html}:: The man page for gprofng display html.
* Man page for @command{gprofng display src}:: The man page for gprofng display src.
* Man page for @command{gprofng archive}:: The man page for gprofng archive.
@c -- Index
@ -1899,7 +1907,7 @@ referred to as
Similar to the commands for the threads, there are several commands related
to the usage of the cores, or @emph{CPUs} as they are called in @ToolName{}
(@xref{The Concept of a CPU in @ProductName{}}).
(@xref{The Concept of a CPU in gprofng}).
@IndexSubentry{Options, @code{-cpu_list}}
@IndexSubentry{Commands, @code{cpu_list}}
@ -2615,7 +2623,8 @@ portable in case we would like to repeat this experiment on another processor.
@IndexSubentry{Hardware event counters, @code{hwc} metric}
This is where the special @code{hwc} metric comes very handy. It
automatically expands to the active set of events used.
automatically expands to the active set of hardware event counters used
in the experiment(s).
With this, it is very easy to display the event counter values. Note that
although the regular clock based profiling was enabled, we only want to see
@ -3205,25 +3214,47 @@ the results.
@item @DisplayText{}
@IndexSubentry{@code{gprofng}, @code{display text}}
Generates performance reports in ASCII format. Commandline
options, and/or commands in a script file are used to control the contents
and lay-out of the generated report(s).
@item @DisplayHTML{}
@IndexSubentry{@code{gprofng}, @code{display html}}
Takes one or more experiment directories and generates a directory with
HTML files. Starting from the index.html file, the performance data
may be examined in a browser.
@item @DisplaySRC{}
@IndexSubentry{@code{gprofng}, @code{display src}}
Displays the source code, interleaved with the disassembled instructions.
@item @Archive{}
@IndexSubentry{@code{gprofng}, @code{archive}}
Archives an experiment directory by (optionally) including source code and
object files, as well as the shared libraries that have been used.
@item @GUI{}
@IndexSubentry{@code{gprofng}, @code{display gui}}
This is an optional component that can be installed in addition to the
command line gprofng tools listed above. It supports the graphical
analysis of one or more experiments that have been created using
@CollectApp{}.
The GUI part of @ProductName{} is a GNU project. This is the link to the
@url{https://savannah.gnu.org/projects/gprofng-gui, gprofng GUI page}.
This page contains more information (e.g. how to clone the repo).
There is also a
@url{https://ftp.gnu.org/gnu/gprofng-gui, tar file distribution directory}
with tar files that include everything that is needed to build and install
the GUI code. Various versions are available here.
Be aware that in order to build and use the gprofng GUI, Java needs to be
installed first. The minimum Java version required is Java 8.
@end table
@c -- A new section -----------------------------------------------------------
@ -3232,13 +3263,14 @@ object files, as well as the shared libraries that have been used.
@c ----------------------------------------------------------------------------
The @file{gprofng.rc}
@cindex gprofng.rc
file is used to define default settings for the @DisplayText{} and
@DisplaySRC{} tools, but the user can override these defaults through local
configuration files.
file is used to define default settings for the @DisplayText{}, @Archive{},
and @DisplaySRC{} tools, but the user can override these defaults through
local configuration settings when building and installing from the source
code..
There are three files that are checked when the tool starts up. The first
file has pre-defined settings and comes with the installation, but through
a hidden file called @file{.gprofng.rc}, the user can (re)define the defaults:
a hidden file called @file{.gprofng.rc}, the user can (re)define the defaults.
These are the locations and files that are checked upon starting the above
mentioned tools:
@ -3247,7 +3279,7 @@ mentioned tools:
@item
The system-wide filename is called @file{gprofng.rc} and is located in
the top level @file{/etc} directory.
the @file{/etc} subdirectory in case an RPM was used for the installation..
If @ProductName{} has been built from the source, this file is in
subdirectory @file{etc} in the top level installation directory.
@ -3256,7 +3288,7 @@ subdirectory @file{etc} in the top level installation directory.
The user's home directory may have a hidden file called @file{.gprofng.rc}.
@item
The directory where @DisplayText{} (or @DisplaySRC{}) is invoked from may
The directory where @DisplayText{} (or @DisplaySRC{}) is invoked from, may
have a hidden file called @file{.gprofng.rc}.
@end enumerate
@ -3439,7 +3471,7 @@ For a list of all the predefined filters see @ref{Predefined Filters}.
Various environment variables are supported. We refer to the man page for
gprofng(1) for an overview and description
(@xref{Man page for gprofng}).
(@xref{Man page for @command{gprofng}}).
@c -- A new chapter -----------------------------------------------------------
@node Performance Data Collection
@ -3456,8 +3488,8 @@ used to store the relevant information and forms the basis for a subsequent
analysis with one of the viewing tools.
@c -- A new section -----------------------------------------------------------
@node The @CollectApp{} command
@section The @CollectApp{} command
@node The @command{gprofng collect app} Tool
@section The @command{gprofng collect app} Tool
@c ----------------------------------------------------------------------------
This is the command to collect the performance information for the target
@ -3483,8 +3515,8 @@ directories are available. In this chapter, these will all be covered in
detail.
@c -- A new section -----------------------------------------------------------
@node The @code{gprofng display text} Tool
@section The @code{gprofng display text} Tool
@node The @command{gprofng display text} Tool
@section The @command{gprofng display text} Tool
@c ----------------------------------------------------------------------------
This tool displays the performance information in ASCII format. It supports
@ -3518,8 +3550,8 @@ or command, occurs multiple times, the rightmost setting is selected.
@c ----------------------------------------------------------------------------
The most commonly used commands are documented in the man page for this tool
(@xref{gprofng display text}). In this section we list and describe all other
commands that are supported.
(@xref{Man page for @command{gprofng display text}}). In this section we list
and describe all other commands that are supported.
@c -- A new sub subsection ----------------------------------------------------
@node Commands that List Experiment Details
@ -4124,8 +4156,8 @@ Most of the functions correspond directly to the source model of the program, bu
there are exceptions. This topic is however outside of the scope of this guide.
@c ----------------------------------------------------------------------------
@node The Concept of a CPU in @ProductName{}
@section The Concept of a CPU in @ProductName{}
@node The Concept of a CPU in gprofng
@section The Concept of a CPU in gprofng
@c ----------------------------------------------------------------------------
@cindex CPU
@ -4333,15 +4365,15 @@ in the make file in the @code{<my-build-dir/gprofng/doc} directory.
@end itemize
@c -- An appendix -------------------------------------------------------------
@node The @ProductName{} Man Pages
@appendix The @ProductName{} Man Pages
@node The gprofng Man Pages
@appendix The gprofng Man Pages
@c ----------------------------------------------------------------------------
In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@c @node gprofng driver
@node Man page for gprofng
@node Man page for @command{gprofng}
@section Man page for @command{gprofng}
@c ----------------------------------------------------------------------------
@ -4349,7 +4381,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
@node gprofng collect app
@node Man page for @command{gprofng collect app}
@section Man page for @command{gprofng collect app}
@c ----------------------------------------------------------------------------
@ -4357,7 +4389,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
@node gprofng display text
@node Man page for @command{gprofng display text}
@section Man page for @command{gprofng display text}
@c ----------------------------------------------------------------------------
@ -4365,7 +4397,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
@node gprofng display html
@node Man page for @command{gprofng display html}
@section Man page for @command{gprofng display html}
@c ----------------------------------------------------------------------------
@ -4373,7 +4405,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
@node gprofng display src
@node Man page for @command{gprofng display src}
@section Man page for @command{gprofng display src}
@c ----------------------------------------------------------------------------
@ -4381,7 +4413,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
@node gprofng archive
@node Man page for @command{gprofng archive}
@section Man page for @command{gprofng archive}
@c ----------------------------------------------------------------------------

6
gprofng/doc/version.texi
View File

@ -1,4 +1,4 @@
@set UPDATED 4 September 2023
@set UPDATED-MONTH September 2023
@set UPDATED 28 November 2023
@set UPDATED-MONTH November 2023
@set EDITION 2.41.50
@set VERSION 2.41.50
@set VERSION 2.2