| @c ---------------------------------------------------------------------------- |
| @c This is the Texinfo source file for the gprofng-display-text man page. |
| @c |
| @c Author: Ruud van der Pas |
| @c ---------------------------------------------------------------------------- |
| @ifset man |
| \input texinfo @c -*-texinfo-*- |
| @setfilename gprofng-display-text |
| @settitle Display the performance data in plain text format |
| @include gp-macros.texi |
| @end ifset |
| |
| @c ---------------------------------------------------------------------------- |
| @c This is from the man-pages(7) man page |
| @c |
| @c "The list below shows conventional or suggested sections. Most manual pages |
| @c should include at least the highlighted sections. Arrange a new manual |
| @c page so that sections are placed in the order shown in the list." |
| @c |
| @c NAME |
| @c SYNOPSIS |
| @c CONFIGURATION [Normally only in Section 4] |
| @c DESCRIPTION |
| @c OPTIONS [Normally only in Sections 1, 8] |
| @c EXIT STATUS [Normally only in Sections 1, 8] |
| @c RETURN VALUE [Normally only in Sections 2, 3] |
| @c ERRORS [Typically only in Sections 2, 3] |
| @c ENVIRONMENT |
| @c FILES |
| @c VERSIONS [Normally only in Sections 2, 3] |
| @c ATTRIBUTES [Normally only in Sections 2, 3] |
| @c CONFORMING TO |
| @c NOTES |
| @c BUGS |
| @c EXAMPLES |
| @c AUTHORS [Discouraged] |
| @c REPORTING BUGS [Not used in man-pages] |
| @c COPYRIGHT [Not used in man-pages] |
| @c SEE ALSO |
| @c |
| @c This is what the texi2pod.pl tool recognizes: |
| @c |
| @c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES |
| @c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) { |
| @c |
| @c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which |
| @c makes sense and adhered to for the other formats. |
| @c ---------------------------------------------------------------------------- |
| |
| @c ---------------------------------------------------------------------------- |
| @c NAME section |
| @c ---------------------------------------------------------------------------- |
| |
| @ManPageStart{NAME} |
| @c man begin NAME |
| |
| gp-display-text - Display the performance data in plain text format |
| |
| @c man end |
| @ManPageEnd{} |
| |
| @c ---------------------------------------------------------------------------- |
| @c SYNOPSIS section |
| @c ---------------------------------------------------------------------------- |
| |
| @ManPageStart{SYNOPSIS} |
| @c man begin SYNOPSIS |
| |
| @command{gprofng display text} [@var{option(s)}] [@var{commands}] |
| [-script @var{script-file}] @var{experiment(s)} |
| |
| @c man end |
| @ManPageEnd{} |
| |
| @c ---------------------------------------------------------------------------- |
| @c DESCRIPTION section |
| @c ---------------------------------------------------------------------------- |
| |
| @ManPageStart{DESCRIPTION} |
| @c man begin DESCRIPTION |
| |
| 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 |
| lists all the commands supported. |
| |
| Commands specified on the command line need to be prepended with the dash ('-') |
| symbol. |
| |
| In this example, a function overview will be shown, followed by the source |
| code listing of function @samp{my-func}, annotated with the |
| performance metrics that have been recorded during the data collection |
| and stored in experiment directory @samp{my-exp.er}: |
| |
| @smallexample |
| $ gprofng display text -functions -source my-func my-exp.er |
| @end smallexample |
| |
| Instead of, or in addition to, specifying these commands on the command line, |
| commands may also be included in a file called the @var{script-file}. |
| |
| 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. |
| |
| @c man end |
| @ManPageEnd{} |
| |
| @c ---------------------------------------------------------------------------- |
| @c OPTIONS section |
| @c ---------------------------------------------------------------------------- |
| |
| @ManPageStart{OPTIONS} |
| @c man begin OPTIONS |
| |
| @table @gcctabopt |
| |
| @item --version |
| @ifclear man |
| @IndexSubentry{Options, @code{--version}} |
| @end ifclear |
| |
| Print the version number and exit. |
| |
| @item --help |
| @ifclear man |
| @IndexSubentry{Options, @code{--help}} |
| @end ifclear |
| |
| Print usage information and exit. |
| |
| @item -script @var{script-file} |
| @ifclear man |
| @IndexSubentry{Options, @code{-script}} |
| @IndexSubentry{Commands, @code{script}} |
| @end ifclear |
| |
| Execute the commands stored in the script file. This feature may be combined |
| with commands specified at the command line. |
| |
| @end table |
| |
| @c man end |
| @ManPageEnd{} |
| |
| @c ---------------------------------------------------------------------------- |
| @c NOTES section |
| @c ---------------------------------------------------------------------------- |
| |
| @ManPageStart{NOTES} |
| @c man begin 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. |
| |
| @ifset man |
| There are many more commands. These are documented in the user guide. |
| @end ifset |
| |
| @table @code |
| |
| @item callers-callees |
| @ifclear man |
| @IndexSubentry{Options, @code{-callers-callees}} |
| @IndexSubentry{Commands, @code{callers-callees}} |
| @end ifclear |
| In a callers-callees panel, it is shown which function(s) call the target |
| function (the @emph{callers}) and what functions it is calling (the |
| @emph{callees}). |
| This command prints the callers-callees panel for each of the functions, |
| in the order specified by the function sort metric. |
| |
| @item calltree |
| @ifclear man |
| @IndexSubentry{Options, @code{-calltree}} |
| @IndexSubentry{Commands, @code{calltree}} |
| @end ifclear |
| Display the dynamic call graph from the experiment, showing the hierarchical |
| metrics at each level. |
| |
| @item compare @{on | off | delta | ratio@} |
| @ifclear man |
| @IndexSubentry{Options, @code{-compare}} |
| @IndexSubentry{Commands, @code{compare}} |
| @end ifclear |
| 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: |
| |
| @table @code |
| |
| @item on |
| For each experiment specified on the command line, print the values for |
| the metrics that have been activated for the experiment. |
| |
| @item off |
| Disable the comparison of experiments. This is the default. |
| |
| @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). |
| |
| @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). |
| |
| @end table |
| |
| @item disasm @var{function-name} |
| @ifclear man |
| @IndexSubentry{Options, @code{-disasm}} |
| @IndexSubentry{Commands, @code{disasm}} |
| @end ifclear |
| 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}] |
| @ifclear man |
| @IndexSubentry{Options, @code{-fsingle}} |
| @IndexSubentry{Commands, @code{fsingle}} |
| @end ifclear |
| Write a summary panel for the specified function. The optional parameter |
| @var{n} is needed for those cases where several functions have the same name. |
| |
| @item fsummary |
| @ifclear man |
| @IndexSubentry{Options, @code{-fsummary}} |
| @IndexSubentry{Commands, @code{fsummary}} |
| @end ifclear |
| Write a summary panel for each function in the function list. |
| |
| @item functions |
| @ifclear man |
| @IndexSubentry{Options, @code{-functions}} |
| @IndexSubentry{Commands, @code{functions}} |
| @end ifclear |
| Display a list of all functions executed. For each function the used metrics |
| (e.g. the CPU time) are shown. |
| |
| @item header |
| @ifclear man |
| @IndexSubentry{Options, @code{-header}} |
| @IndexSubentry{Commands, @code{header}} |
| @end ifclear |
| Shows several operational characteristics of the experiment(s) specified |
| on the command line. |
| |
| @item limit @var{n} |
| @ifclear man |
| @IndexSubentry{Options, @code{-limit}} |
| @IndexSubentry{Commands, @code{limit}} |
| @end ifclear |
| Limit the output to @var{n} lines. |
| |
| @item lines |
| @ifclear man |
| @IndexSubentry{Options, @code{-lines}} |
| @IndexSubentry{Commands, @code{lines}} |
| @end ifclear |
| Write a list of source lines and their metrics, ordered by the current |
| sort metric. |
| |
| @item metric_list |
| @ifclear man |
| @IndexSubentry{Options, @code{-metric_list}} |
| @IndexSubentry{Commands, @code{metric_list}} |
| @end ifclear |
| Display the currently selected metrics in the function view and a list |
| of all the metrics available for the target experiment(s). |
| |
| @item metrics @var{metric-spec} |
| @ifclear man |
| @IndexSubentry{Options, @code{-metrics}} |
| @IndexSubentry{Commands, @code{metrics}} |
| @end ifclear |
| Define the metrics to be displayed in the function and callers-callees |
| overviews. |
| |
| 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@}] |
| @ifclear man |
| @IndexSubentry{Options, @code{-name}} |
| @IndexSubentry{Commands, @code{name}} |
| @end ifclear |
| 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 @emph{soname} keyword. It can also be ommitted |
| (@emph{nosoname}), which is the default. |
| |
| 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 |
| 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}} |
| @IndexSubentry{Commands, @code{overview}} |
| @end ifclear |
| Shows a summary of the recorded performance data for the experiment(s) |
| specified on the command line. |
| |
| @item pcs |
| @ifclear man |
| @IndexSubentry{Options, @code{-pcs}} |
| @IndexSubentry{Commands, @code{pcs}} |
| @end ifclear |
| Write a list of program counters (PCs) and their metrics, ordered by |
| 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. |
| |
| @IndexSubentry{Sort, Reverse order} |
| The data can be sorted in reverse order by prepending the metric definition |
| with a minus (@samp{-}) sign. |
| |
| @noindent |
| For example @command{sort -e.totalcpu}. |
| |
| @IndexSubentry{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 @code{default} as |
| the key (@command{sort default}). |
| |
| @item source @var{function-name} |
| @ifclear man |
| @IndexSubentry{Options, @code{-source}} |
| @IndexSubentry{Commands, @code{source}} |
| @end ifclear |
| List the source code for the function specified, annotated with the metrics |
| used. |
| |
| @item viewmode @{user | expert | machine@} |
| @ifclear man |
| @IndexSubentry{Options, @code{-viewmode}} |
| @IndexSubentry{Commands, @code{viewmode}} |
| @end ifclear |
| This command is only relevant for Java programs. For all other languages |
| supported, the viewmode setting has no effect. |
| |
| The following options are supported: |
| |
| @table @code |
| |
| @item user |
| Show the Java call stacks for Java threads, but do not show housekeeping |
| threads. The function view includes a function called @samp{<JVM-System>}. |
| 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 @samp{<no Java callstack recorded>}. |
| |
| @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. |
| |
| @item machine |
| Show the actual native call stacks for all threads. This is the view mode |
| for C, C++, and Fortran. |
| |
| @end table |
| |
| @end table |
| |
| @c man end |
| @ManPageEnd{} |
| |
| @c ---------------------------------------------------------------------------- |
| @c SEEALSO section |
| @c ---------------------------------------------------------------------------- |
| |
| @ManPageStart{SEE ALSO} |
| @c man begin SEEALSO |
| |
| gprofng(1), |
| gprofng-archive(1), |
| gprofng-collect-app(1), |
| @c -- gprofng-display-gui(1), |
| gprofng-display-html(1), |
| gprofng-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 |
| command @command{info gprofng} should give access to this document. |
| |
| @c man end |
| @ManPageEnd{} |
| |
| @c ---------------------------------------------------------------------------- |
| @c COPYRIGHT section |
| @c ---------------------------------------------------------------------------- |
| |
| @ManPageStart{COPYRIGHT} |
| @c man begin COPYRIGHT |
| |
| Copyright @copyright{} 2022-2024 Free Software Foundation, Inc. |
| |
| 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''. |
| |
| @c man end |
| @ManPageEnd{} |
| |
| @c ---------------------------------------------------------------------------- |
| @c If this text is used for a man page, exit. Otherwise we need to continue. |
| @c ---------------------------------------------------------------------------- |
| |
| @ifset man |
| @bye |
| @end ifset |